Foundations

def content_hash(obj: JsonValue) -> str:
    """Canonical SHA-256 ID for any JSON-serializable value.

    Canonical form: json.dumps with sort_keys=True, separators=(",",":"),
    ensure_ascii=True, UTF-8 encoded — then SHA-256.
    Returns "sha256:<64-hex>" (always 71 chars).
    """

def blob_id(data: bytes) -> str:
    """SHA-256 of raw bytes. Same "sha256:<64-hex>" format."""

  refs/heads/dev  ──►  CommitRecord (sha256:9e21b8...)
                            │  parent_commit_id
                            ▼
                       CommitRecord (sha256:3f8a1c...)
                            │  snapshot_id
                            ▼
                       SnapshotRecord (sha256:04ee5e...)
                            │  manifest
                       ┌────┼────────────┐
                       ▼    ▼            ▼
                     Blob  Blob  ...  Blob
                    (sha256:a1b2c3...)  (sha256:d4e5f6...)

@dataclass
class CommitRecord:
    # Core identity
    commit_id:          str           # sha256:<64-hex>
    branch:             str
    snapshot_id:        str           # sha256:<64-hex>
    message:            str
    committed_at:       datetime.datetime

    # Graph edges
    parent_commit_id:   str | None    # None for genesis commits
    parent2_commit_id:  str | None    # Set for merge commits (two-parent)

    # Authorship
    author:             str           # handle
    metadata:           dict

    # Structured delta (populated by domain plugin's diff())
    structured_delta:   StructuredDelta | None

    # Semantic versioning
    sem_ver_bump:       Literal["none", "patch", "minor", "major"]
    breaking_changes:   list[str]

    # Agent provenance — all empty strings for human commits
    agent_id:           str           # e.g. "claude-code"
    model_id:           str           # e.g. "claude-sonnet-4-6"
    toolchain_id:       str
    prompt_hash:        str           # sha256 of system prompt

    # Ed25519 signature
    signature:          str           # "ed25519:<base64url>"
    signer_public_key:  str           # "ed25519:<base64url>"
    signer_key_id:      str           # fingerprint of signing key

    # Labels, review metadata
    reviewed_by:        list[str]
    test_runs:          int
    labels:             list[str]
    status:             str
    notes:              list[str]
    score:              float | None

# Agent commit — full provenance chain
muse commit -m "feat: add rate limiting" \
  --agent-id claude-code \
  --model-id claude-sonnet-4-6 \
  --sign

# Human commit — no provenance flags
muse commit -m "chore: update config"

{
  "commit_id":         "sha256:6ab243df7bdb...",
  "branch":            "dev",
  "snapshot_id":       "sha256:04ee5ecd07ec...",
  "message":           "feat: add rate limiting",
  "committed_at":      "2026-04-21T23:00:00Z",
  "parent_commit_id":  "sha256:4c9e7959...",
  "parent2_commit_id": null,
  "author":            "gabriel",
  "agent_id":          "claude-code",
  "model_id":          "claude-sonnet-4-6",
  "signature":         "ed25519:AAAA...",
  "signer_public_key": "ed25519:BBBB...",
  "sem_ver_bump":      "minor",
  "labels":            ["reviewed"],
  "score":             0.94
}

@dataclass
class SnapshotRecord:
    snapshot_id:    str               # sha256:<64-hex>
    manifest:       dict[str, str]    # path → "sha256:<64-hex>"
    directories:    list[str]         # explicit empty directories
    created_at:     datetime.datetime
    note:           str
    schema_version: int

{
  "schema_version": 1,
  "snapshot_id": "sha256:04ee5ecd...",
  "manifest": {
    "musehub/main.py":                  "sha256:a1b2c3...",
    "musehub/graph/dag.py":             "sha256:d4e5f6...",
    "musehub/graph/push_validator.py":  "sha256:7890ab..."
  },
  "directories": [],
  "created_at": "2026-04-21T23:00:00Z",
  "note": ""
}

# Create and switch in one command, with intent metadata
muse checkout -b task/rate-limiting \
  --intent "implement token bucket rate limiter" \
  --resumable

# Work, stage, commit
muse code add src/rate_limiter.py
muse commit -m "feat: token bucket rate limiter" \
  --agent-id claude-code --model-id claude-sonnet-4-6 --sign

# Merge back
muse checkout dev
muse merge task/rate-limiting     # three-way, harmony auto-resolves known conflicts
muse branch -d task/rate-limiting
muse push local dev

[
  {
    "name":       "task/rate-limiting",
    "current":    false,
    "intent":     "implement token bucket rate limiter",
    "resumable":  true,
    "created_by": "claude-code",
    "commit_id":  "sha256:6ab243..."
  }
]

muse code add src/rate_limiter.py

muse commit -m "feat: token bucket rate limiter" \
  --agent-id claude-code --model-id claude-sonnet-4-6 --sign

muse push local task/rate-limiting

muse pull local task/rate-limiting

muse log --json

muse read --json --manifest

muse diff --staged

[global]
patterns = [
    ".DS_Store",
    "Thumbs.db",
    "*.tmp",
    "*.swp",
]

[domain.code]
patterns = [
    "__pycache__/",
    "*.pyc",
    ".venv/",
    "dist/",
    "build/",
    "*.egg-info/",
    "node_modules/",
]

# [force_track]
# Exact repo-relative paths to track even if they match a secrets pattern.
# paths = [
#     "deploy/local-tls/localhost.key",
# ]

[force_track]
paths = [
    "deploy/local-tls/localhost.key",
    "deploy/local-tls/localhost.crt",
]

python3 -c "import msgpack,json,sys; d=msgpack.unpackb(open(sys.argv[1],'rb').read(),raw=False); print(json.dumps(d,indent=2))" \
  .muse/objects/sha256/9e/21b8a4f273…

.muse/
├── repo.json                       # repo_id, domain, owner, created_at
├── HEAD                            # "refs/heads/dev" (symbolic ref)
├── refs/
│   └── heads/
│       ├── main                    # "sha256:<64-hex>\n"
│       └── dev                     # "sha256:<64-hex>\n"
├── objects/
│   └── sha256/
│       └── ab/                     # first 2 hex chars (sharding)
│           └── <62-hex>           # commits, snapshots, and blobs — unified store
├── coordination/                   # multi-agent symbol reservations
│   ├── reservations/
│   ├── intents/
│   ├── releases/
│   └── heartbeats/
├── harmony/                        # conflict resolution memory
│   ├── patterns/
│   ├── policies/
│   └── audit/
└── agent.md                        # repo-specific agent rules

/data/repos/<owner>/<slug>/
├── objects/
│   └── sha256/                     # algorithm namespace (mldsa65/ slots in here)
│       └── ab/                     # 2-char hex shard
│           └── <62-hex>           # raw blob — same layout as .muse/objects/
└── refs/
    └── heads/
        ├── main                    # "sha256:<64-hex>" — same format as client
        └── dev

{
  "branch":                    "dev",
  "head_commit":               "sha256:abc...",
  "upstream":                  null,          // tracking remote name, or null
  "ahead":                     null,          // commits ahead of remote; null when no upstream
  "behind":                    null,          // commits behind remote; null when no upstream
  "clean":                     true,          // true only when no staged, unstaged, or untracked files
  "dirty":                     false,         // always NOT clean
  "total_changes":             0,             // tracked-file changes (added+modified+deleted+renamed)
  "untracked_count":           0,             // len(untracked); nonzero when dirty but total_changes==0
  "added":                     [],            // flat union of staged + unstaged
  "modified":                  [],
  "deleted":                   [],
  "renamed":                   {},            // old_path → new_path map
  "staged": {
    "added": [], "modified": [], "deleted": []
  },
  "unstaged": {
    "added": [], "modified": [], "deleted": [], "renamed": {}
  },
  "untracked":                 [],            // on-disk but not tracked; presence makes clean=false
  "conflict_paths":            [],
  "merge_in_progress":         false,
  "merge_from":                null,          // branch being merged; null when no merge
  "conflict_count":            0,
  "checkout_interrupted":      false,
  "checkout_target":           null
}

class WireMPack(BaseModel):
    commits:      list[WireCommit]    # CommitRecord dicts
    snapshots:    list[WireSnapshot]  # SnapshotRecord dicts
    objects:      list[WireObject]   # raw blob bytes
    branch_heads: dict[str, str]      # branch → commit_id

class WireObject(BaseModel):
    object_id: str
    content:   bytes                  # raw; no base64
    path:      str = ""
    encoding:  str = "raw"           # "raw" | "zlib" | "delta+zlib"
    base_id:   str | None             # set for delta-encoded objects

1.  Verify MSign Authorization header (Ed25519, ±30s replay window)
2.  Resolve repo — owner + slug → repo_id + repo_root (/data/repos/<owner>/<slug>/)
3.  Confirm pusher has write access
4.  Negotiate have/want — hub checks object existence on disk, not in DB
5.  Validate mpack schema + ID format (sha256:<hex>, ≥32 chars)
6.  Enforce push limits (max 10k commits, 1k objects, 38 MB/object)
7.  Persist objects → /data/repos/<owner>/<slug>/objects/sha256/<2-hex>/<62-hex> (atomic)
8.  Persist snapshots → musehub_snapshots (DB cache)
9.  Persist commits → musehub_commits (DB cache)
10. Advance branch pointer → refs/heads/<branch> on disk (atomic rename), then musehub_branches (cache)
11. Update repo.pushed_at timestamp
12. Upsert reachability index (musehub_object_refs)

# Push dev branch to the local hub
muse push local dev

# Push to staging
muse push staging dev

# Pull from remote
muse pull local dev

# Check configured remotes
muse remote --json