Spawn/Grow/Bond/Absorb Workflow Guide

This guide covers the visitor workflow for deriving, syncing, bonding, and merging code from CMN spores.

1. Ownership Philosophy

CMN has a unique ownership model:

Once you spawn a spore, it becomes your own project.

Concept	Traditional Git	CMN
Fork	Copy to your account, maintain link	Spawn and own - no “fork” concept
Pull	Update from origin (you don’t own it)	Sync with spawn source (you choose to follow)
Push	Send changes to remote	Release under your domain

2. Commands Overview

Command	Purpose	When to Use
`spawn`	Derive from verified source with full history	Start developing your version
`bond`	Fetch all bonds to `.cmn/bonds/`	After spawn, after adding dependencies
`grow`	Sync updates from `spawned_from` source	Following source releases
`absorb`	Merge changes from any spore	Cherry-pick features from forks/siblings

3. Spawn - Derive from Source

hypha spawn cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2
cd my-spore

Archive Source Workflow (Default)

Verify spore signature against domain’s public key
Download and extract archive to target directory
If --vcs git: initialize git repository with initial commit
Add spawn reference to spore.core.json

Git Source Workflow

Used with --dist git:

Verify spore signature against domain’s public key
Clone git repository to cache: ~/.cache/cmn/hypha/{domain}/repos/{root_commit}/
Checkout verified ref to target directory
If --vcs git: keep .git and set up remotes; otherwise remove .git
Add spawn reference to spore.core.json

After Spawn

Without --vcs:

my-spore/
├── src/
└── spore.core.json    ← Contains spawn reference

With --vcs git:

my-spore/
├── src/
├── spore.core.json    ← Contains spawn reference
└── .git/

spore.core.json with spawn reference:

{
  "id": "my-spore",
  "name": "My Spore",
  "bonds": [
    {
      "uri": "cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2",
      "relation": "spawned_from"
    }
  ]
}

Note: domain is intentionally omitted after spawn. Set it when ready to release:

hypha hatch --domain mydomain.com

4. Grow - Sync with Spawn Source

When the spawn source releases a new version:

cd my-spore
hypha grow

Two-Phase Grow (Git Sources)

Phase 1: Update cache bare repo (network operations):

Read spawn reference from spore.core.json
Fetch latest mycelium, find new spore hash
Verify signature
Verify repository identity (root_commit must match)
Git fetch to cache bare repo

Phase 2: Merge into working directory (local operations):

Backup spore.core.json
git fetch spawn
git merge spawn/main --no-commit
Restore spore.core.json
Update spawn reference hash
Auto-commit if no conflicts

Conflict Resolution

$ hypha grow

{
  "code": "error",
  "error": "Automatic merge failed. Fix conflicts and commit.",
  "trace": {
    "error_code": "MERGE_CONFLICT"
  }
}

# Resolve manually:
vim src/main.rs
git add src/main.rs
git commit -m "merge upstream"

Archive Source Grow

For spores spawned from archives:

# 1. Commit local changes first
git add .
git commit -m "my changes"

# 2. Grow from archive source
hypha grow
# Files are replaced with new upstream version
# spore.core.json is preserved

# 3. Review changes
git diff
git status

# 4. Accept or revert
git add . && git commit -m "Grow from upstream"

5. Bond - Fetch Bonds

Bond reads spore.core.json bonds and fetches tasted-safe referenced spores to .cmn/bonds/. It excludes spawned_from (handled by grow) and absorbed_from (historical — the merge is already done):

cd my-spore
hypha bond

What Hypha Does

Read all bonds from spore.core.json
For each bond: check taste verdict (must be tasted)
Fetch tasted-safe spores to .cmn/bonds/{id-or-hash}/ (uses id when present)
Write bonds.json index mapping dir names to hashes, URIs, relations, and names

Directory Structure

my-spore/
├── src/
├── spore.core.json
└── .cmn/                    ← gitignored
    └── bonds/
        ├── bonds.json       ← index of all bonds
        ├── signing-lib/       ← depends_on (id="signing-lib")
        │   ├── spore.json
        │   └── content/
        └── b3.8cQnH4xPm.../   ← follows (no id — hash used)
            ├── spore.json
            └── content/

Build Integration

For depends_on bonds, use bonds.json to look up the dir name and set up build system paths pointing to .cmn/bonds/{id-or-hash}/content/:

# Cargo.toml
[dependencies]
parsing_lib = { path = ".cmn/bonds/signing-lib/content" }

// package.json
{ "dependencies": { "parsing-lib": "file:.cmn/bonds/signing-lib/content" } }

When to Bond

Scenario	Command
After spawn	`hypha spawn <uri> --bond` or `hypha bond`
After grow	`hypha grow --bond` or `hypha bond`
After absorb added new `depends_on`	`hypha bond`
After editing spore.core.json bonds	`hypha bond`
Clean up orphaned bonds	`hypha bond --clean`

Taste Gate

Every bonded spore must be individually tasted as safe before bond places it in your working directory. No shortcuts — trusting one spore from a domain does not extend to other spores on that domain.

# Taste each reference first
hypha taste cmn://pub.com/b3.8cQnH4xPmZ2vLkJdRt7wNbA9sF3eYgU1hK6pXq5
hypha taste cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2

# Then bond-fetch
hypha bond

6. Absorb - AI-Assisted Merge

Unlike grow (which syncs from spawned_from), absorb prepares code from any spore(s) for AI-assisted merging:

# Single source
hypha absorb cmn://other.com/b3.8cQnH4xPmZ2vLkJdRt7wNbA9sF3eYgU1hK6pXq5

# Multiple sources
hypha absorb cmn://spawn-a.com/... cmn://spawn-b.com/...

# Auto-discover from lineage
hypha absorb --lineage --synapse https://synapse.example.com

What Hypha Does

Fetch and verify each target spore signature
Extract code to .cmn/absorb/{hash}/
Generate .cmn/absorb/ABSORB.md with structured prompt

Directory Structure

.cmn/absorb/
├── ABSORB.md                    # AI prompt (main entry point)
├── b3.3yMR7vZQ9.../             # Source 1
│   ├── spore.json               # Full spore manifest
│   └── content/                 # Extracted source code
├── b3.3yMR7vZQ9....report.md   # AI-generated report
└── b3.8cQnH4xPm.../             # Source 2
    ├── spore.json
    └── content/

AI Workflow Phases

Analyze Each Source - Create detailed report per source
Cross-Source Analysis - Detect overlaps and conflicts
Merge Plan - Propose plan, wait for user approval
Execute Merge - Apply approved changes
Update Bonds - Add absorbed_from entries to spore.core.json
Cleanup - Remove .cmn/absorb/

Usage with AI

"Read .cmn/absorb/ABSORB.md and help me absorb these changes"

Key Differences from Grow

Aspect	grow	absorb
Source	`spawned_from` reference only	Any spore URI(s)
Count	Single source	Multiple sources supported
Execution	Hypha performs git merge	AI agent handles merge
Workflow	Automatic	Phased with user decisions
Relation	Updates `spawned_from` hash	Adds `absorbed_from` entries

7. Evolution Tracking

Query the evolution network via Synapse:

# Who did this spore come from?
hypha ancestors cmn://... --synapse https://synapse.example.com

# Who forked/evolved this spore?
hypha lineage cmn://... --synapse https://synapse.example.com

8. Releasing Your Version

After modifying a spawned spore:

# 1. Set up your own domain (one-time)
hypha mycelium root --domain mydomain.com

# 2. Update spore.core.json
hypha hatch --domain mydomain.com --intent "Added my feature"

# 3. Replicate non-self bonds to your domain (recommended)
hypha replicate --bonds --domain mydomain.com

# 4. Release under your domain
hypha release --domain mydomain.com

# Result: Two independent spores exist
# cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2   (original)
# cmn://mydomain.com/b3.8cQnH4xPmZ2vLkJdRt7wNbA9sF3eYgU1hK6pXq5   (yours)
# Plus: all bonds replicated on mydomain.com

Replicate Convention

Publishers SHOULD replicate all bonds that point to other domains before releasing. This ensures visitors can reach all bonded spores from your domain alone.

# Replicate a single spore
hypha replicate cmn://other.com/b3.8cQnH4xPmZ2vLkJdRt7wNbA9sF3eYgU1hK6pXq5 --domain mydomain.com

# Replicate all non-self bonds and update spore.core.json URIs
hypha replicate --bonds --domain mydomain.com

A replicate is an exact copy (same hash, same core). The original authorship is preserved in core.domain — your domain only re-signs the capsule.

9. Local Cache Structure

~/.cache/cmn/hypha/
└── {domain}/
    ├── mycelium/
    │   ├── cmn.json            # Domain entry point cache (includes public key)
    │   ├── mycelium.json      # Full mycelium manifest
    │   └── status.json        # Fetch status
    │
    ├── spore/
    │   └── {hash}/            # Downloaded spore
    │       ├── spore.json
    │       └── content/
    │
    └── repos/                 # Git repository cache
        └── {root_commit}/     # Identified by first commit SHA
            └── .git/          # Bare repository (verified)

Why root_commit as identifier:

Stable: Never changes, even with new commits
Unique: Each repository has unique first commit
Secure: Verifiable to confirm same repository

10. Bond Types

Relation	Description	Grow	Bond
`spawned_from`	Source derived from	Syncs to latest	Excluded (handled by grow)
`absorbed_from`	Source merged into this	—	Excluded (historical)
`depends_on`	Runtime/build dependency	—	Fetched to `.cmn/bonds/` (build system uses this)
`follows`	Convention/standard adhered to	—	Fetched to `.cmn/bonds/`
`implements`	Spec/interface implemented	—	Fetched to `.cmn/bonds/`
`inspired_by`	Inspiration	—	Fetched to `.cmn/bonds/`
`related_to`	General relationship	—	Fetched to `.cmn/bonds/`

Each bond has uri (required), relation (required), and optional reason (explains why this bond exists). See §2.4 Bond Types for details.

11. Complete Workflow Diagram

┌─────────────────────────────────────────────────────────────────┐
│                     PUBLISHER (cmn.dev)                          │
│                                                                  │
│   develop → release → publish                                    │
│                           │                                      │
│                           ▼                                      │
│            cmn://cmn.dev/b3.3yMR7vZQ9hL2x...               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                │ hypha taste → hypha spawn
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                           VISITOR                                │
│                                                                  │
│   ~/projects/my-spore/                                          │
│   ├── src/                                                      │
│   ├── spore.core.json  (spawn reference + user's metadata)      │
│   ├── .git/                                                     │
│   └── .cmn/bonds/      (bonds)                                  │
│                           │                                      │
│                           │ hypha bond (fetch tasted bonds) │
│                           │ develop & commit locally             │
│                           ▼                                      │
│   hypha grow [--bond]                                            │
│   ├── Phase 1: fetch to cache (network, verify)                 │
│   └── Phase 2: git merge (local, preserve spore.core.json)      │
│                           │                                      │
│                           │ ready to publish your version        │
│                           ▼                                      │
│   hypha release --domain mydomain.com                                  │
│                           │                                      │
│                           ▼                                      │
│                   cmn://mydomain.com/b3.8cQnH4xPm...       │
└─────────────────────────────────────────────────────────────────┘