musehub/templates/musehub/pages/docs_muse_foundations.html · gabriel/musehub

<span class="tok-num">3</span> objects (<span class="tok-str">1</span> blob, <span class="tok-str">1</span> snapshot, <span class="tok-str">1</span> commit)

502

503

<span class="tok-str">✓</span> sha256:c8d5e1f0… <span class="tok-cmt">snapshot 1.1 kB</span>

504

<span class="tok-str">✓</span> sha256:9e21b8a4… <span class="tok-cmt">commit 0.8 kB</span>

505

branch task/rate-limiting → sha256:9e21b8a4…

506

<span class="tok-str">✔</span> pushed in 142 ms</pre>

</div>

<p>

The hub stores all three objects, verifies the Ed25519 signature, and advances

511

the branch pointer in a single transaction.

</p>

<p>

A second agent (or a second machine) pulls the branch. Muse fetches only the

517

objects it doesn't already have — content-addressability makes deduplication

trivial.

</p>

</div>

<pre><code>muse pull local task/rate-limiting</code></pre>

526

</div>

527

528

<pre>Fetching task/rate-limiting from local

529

<span class="tok-num">3</span> new objects

530

531

<span class="tok-str">✓</span> sha256:c8d5e1f0… <span class="tok-cmt">snapshot</span>

532

<span class="tok-str">✓</span> sha256:9e21b8a4… <span class="tok-cmt">commit</span>

533

branch task/rate-limiting → sha256:9e21b8a4…

534

<span class="tok-str">✔</span> fast-forward, working tree updated</pre>

</div>

<p>

Because every ID is derived from content, the pull output IDs are byte-for-byte

539

identical to the push output. There is no translation, no rebase, no rewriting —

540

the same objects are present on both sides.

541

</p>

542

543

<h3 class="devdocs-subsection-title"><a href="#round-trip-log">Inspecting the result</a></h3>

</div>

</div>

<pre>{

<span class="tok-key">"truncated"</span>: <span class="tok-num">false</span>,

554

<span class="tok-key">"commits"</span>: [

555

{

556

<span class="tok-key">"commit_id"</span>: <span class="tok-str">"sha256:9e21b8a4f273…"</span>,

557

<span class="tok-key">"message"</span>: <span class="tok-str">"feat: token bucket rate limiter"</span>,

558

<span class="tok-key">"committed_at"</span>: <span class="tok-str">"2026-04-30T18:22:04Z"</span>,

559

<span class="tok-key">"author"</span>: <span class="tok-str">"gabriel"</span>,

560

<span class="tok-key">"agent_id"</span>: <span class="tok-str">"claude-code"</span>,

561

<span class="tok-key">"model_id"</span>: <span class="tok-str">"claude-sonnet-4-6"</span>,

562

<span class="tok-key">"parent_commit_id"</span>:<span class="tok-str">"sha256:4c9e7959…"</span>,

563

<span class="tok-key">"snapshot_id"</span>: <span class="tok-str">"sha256:c8d5e1f0…"</span>

564

},

565

<span class="tok-cmt">…earlier commits…</span>

]

}</pre>

</div>

</div>

<pre><code>muse read --json --manifest</code></pre>

</div>

<pre>{

<span class="tok-key">"commit_id"</span>: <span class="tok-str">"sha256:9e21b8a4f273…"</span>,

579

<span class="tok-key">"snapshot_id"</span>: <span class="tok-str">"sha256:c8d5e1f09ab3…"</span>,

580

<span class="tok-key">"files_added"</span>: [<span class="tok-str">"src/rate_limiter.py"</span>],

581

<span class="tok-key">"files_modified"</span>:[],

582

<span class="tok-key">"files_removed"</span>: [],

583

<span class="tok-key">"manifest"</span>: {

584

<span class="tok-key">"src/rate_limiter.py"</span>: <span class="tok-str">"sha256:f3a7b92c4de1…"</span>,

585

<span class="tok-key">"src/main.py"</span>: <span class="tok-str">"sha256:a1b2c3d4e5f6…"</span>,

586

<span class="tok-key">"src/config.py"</span>: <span class="tok-str">"sha256:789abc012def…"</span>

}

}</pre>

</div>

</div>

<pre><code>muse diff --staged</code></pre>

596

</div>

597

598

<pre><span class="tok-str">+++ src/rate_limiter.py</span> <span class="tok-cmt">(new file, sha256:f3a7b92c…)</span>

599

<span class="tok-str">+</span> class TokenBucket:

600

<span class="tok-str">+</span> def __init__(self, rate: float, burst: int) -> None:

601

<span class="tok-str">+</span> self.rate = rate

602

<span class="tok-str">+</span> self.burst = burst

603

<span class="tok-str">+</span> self._tokens = burst

604

<span class="tok-str">+</span> self._last = time.monotonic()

605

606

<span class="tok-str">+</span> def consume(self, n: int = 1) -> bool:

</div>

</section>

{# ── .museignore ──────────────────────────────────────────────────────────── #}

612

613

<h2 class="devdocs-section-title"><a href="#museignore">.museignore</a></h2>

614

615

<p>

616

<code>.museignore</code> is a <strong>TOML</strong> file that tells Muse which

617

files to exclude from tracking. It has three section types:

</p>

<thead><tr><th>Section</th><th>Applied when</th></tr></thead>

622

<tbody>

623

<tr><td><code>[global]</code></td><td>All domains, always</td></tr>

624

<tr><td><code>[domain.<name>]</code></td><td>Only when the active domain is <code><name></code></td></tr>

625

<tr><td><code>[force_track]</code></td><td>Whitelist — exact paths that bypass all ignore rules</td></tr>

</tbody>

</table>

<span class="devdocs-code-label">.museignore</span>

</div>

<pre><code>[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.

655

# paths = [

656

# "deploy/local-tls/localhost.key",

# ]</code></pre>

</div>

<h3 class="devdocs-subsection-title"><a href="#museignore-patterns">Pattern syntax</a></h3>

661

662

663

<thead><tr><th>Pattern</th><th>Matches</th></tr></thead>

664

<tbody>

665

<tr><td><code>*.pyc</code></td><td>Any <code>.pyc</code> file at any depth</td></tr>

666

<tr><td><code>__pycache__/</code></td><td>Any directory named <code>__pycache__</code> (trailing <code>/</code> = directory)</td></tr>

667

<tr><td><code>/dist/</code></td><td>Only <code>dist/</code> at the repo root (leading <code>/</code> = anchored)</td></tr>

668

<tr><td><code>!important.tmp</code></td><td>Un-ignore a previously matched path (leading <code>!</code> = negate)</td></tr>

669

<tr><td><code>src/*.min.js</code></td><td>Minified JS files directly inside <code>src/</code> (<code>*</code> excludes <code>/</code>)</td></tr>

670

<tr><td><code>tests/fixtures/**</code></td><td>All contents of <code>tests/fixtures/</code> recursively (<code>**</code> includes <code>/</code>)</td></tr>

</tbody>

</table>

<p>

Patterns are evaluated in order — global first, then domain-specific. The

676

<strong>last matching rule wins</strong>, mirroring gitignore semantics.

677

</p>

678

679

<h3 class="devdocs-subsection-title"><a href="#museignore-force-track">[force_track] — override the secrets blocklist</a></h3>

680

681

<p>

682

Muse automatically blocks certain file types from tracking (e.g. <code>*.key</code>,

683

<code>*.pem</code>, <code>.env</code>). The <code>[force_track]</code> section

684

lists <strong>exact repo-relative paths</strong> (no globs) that must be tracked

685

regardless. Use it for dev infrastructure that would otherwise be blocked.

</p>

<span class="devdocs-code-label">.museignore — force_track</span>

692

</div>

693

<pre><code>[force_track]

694

paths = [

695

"deploy/local-tls/localhost.key",

696

"deploy/local-tls/localhost.crt",

]</code></pre>

</div>

<div>

<code>muse check-ignore <path> --json</code> tells you whether a given path

704

is ignored and which rule matched. Use it when <code>muse status</code> shows

705

a file as untracked and you want to understand why.

</div>

</div>

</section>

{# ── Serialization ─────────────────────────────────────────────────────── #}

711

712

<h2 class="devdocs-section-title"><a href="#serialization">Serialization</a></h2>

713

714

<p>

715

Commits and snapshots are serialized with <strong>msgpack</strong>, not JSON.

716

On real-world code repositories, msgpack is 3–6× faster to encode and decode,

717

and produces smaller files. The coordination bus uses JSON (infrequent, small

718

payloads) and the MCP wire uses JSON for tool calls, but the core object store

719

is msgpack throughout.

</p>

<thead><tr><th>Data</th><th>Format</th><th>Reason</th></tr></thead>

724

<tbody>

725

<tr><td>Commits / snapshots</td><td>msgpack</td><td>3–6× faster; binary-safe for blob content</td></tr>

726

<tr><td>Objects (blobs)</td><td>raw bytes</td><td>No encoding overhead</td></tr>

727

<tr><td>Coordination records</td><td>JSON</td><td>Infrequent; human-readable debugging</td></tr>

728

<tr><td>Harmony patterns</td><td>JSON</td><td>Infrequent; inspectable</td></tr>

729

<tr><td>Wire push (HTTP)</td><td>msgpack</td><td><code>application/x-msgpack</code></td></tr>

730

<tr><td>MCP tool calls</td><td>JSON</td><td>MCP protocol requirement</td></tr>

</tbody>

</table>

<h3 class="devdocs-subsection-title"><a href="#msgpack-example">msgpack CommitRecord — decoded</a></h3>

735

<p>

736

Commits are stored as msgpack binary files. The JSON below is the decoded

737

equivalent — every field in the msgpack maps 1:1 to the CommitRecord dataclass.

738

The <code>sha256:</code> prefix is stored as a plain string; it is never

stripped.

</p>

</div>

<pre><code>python3 -c <span class="tok-str">"import msgpack,json,sys; d=msgpack.unpackb(open(sys.argv[1],'rb').read(),raw=False); print(json.dumps(d,indent=2))"</span> \

747

.muse/objects/sha256/9e/21b8a4f273…</code></pre>

</div>

<pre>{

<span class="tok-key">"commit_id"</span>: <span class="tok-str">"sha256:9e21b8a4f273…"</span>,

752

<span class="tok-key">"repo_id"</span>: <span class="tok-str">"sha256:0000genesis…"</span>,

753

<span class="tok-key">"branch"</span>: <span class="tok-str">"task/rate-limiting"</span>,

754

<span class="tok-key">"snapshot_id"</span>: <span class="tok-str">"sha256:c8d5e1f09ab3…"</span>,

755

<span class="tok-key">"message"</span>: <span class="tok-str">"feat: token bucket rate limiter"</span>,

756

<span class="tok-key">"committed_at"</span>: <span class="tok-str">"2026-04-30T18:22:04Z"</span>,

757

<span class="tok-key">"parent_commit_id"</span>: <span class="tok-str">"sha256:4c9e7959…"</span>,

758

<span class="tok-key">"parent2_commit_id"</span>: null,

759

<span class="tok-key">"author"</span>: <span class="tok-str">"gabriel"</span>,

760

<span class="tok-key">"agent_id"</span>: <span class="tok-str">"claude-code"</span>,

761

<span class="tok-key">"model_id"</span>: <span class="tok-str">"claude-sonnet-4-6"</span>,

762

<span class="tok-key">"toolchain_id"</span>: <span class="tok-str">""</span>,

763

<span class="tok-key">"prompt_hash"</span>: <span class="tok-str">""</span>,

764

<span class="tok-key">"signature"</span>: <span class="tok-str">"ed25519:AAAA…"</span>,

765

<span class="tok-key">"signer_public_key"</span>: <span class="tok-str">"ed25519:BBBB…"</span>,

766

<span class="tok-key">"signer_key_id"</span>: <span class="tok-str">"sha256:CCCC…"</span>,

767

<span class="tok-key">"sem_ver_bump"</span>: <span class="tok-str">"minor"</span>,

768

<span class="tok-key">"breaking_changes"</span>: [],

769

<span class="tok-key">"structured_delta"</span>: null,

770

<span class="tok-key">"reviewed_by"</span>: [],

771

<span class="tok-key">"test_runs"</span>: <span class="tok-num">0</span>,

772

<span class="tok-key">"labels"</span>: [],

773

<span class="tok-key">"status"</span>: <span class="tok-str">""</span>,

774

<span class="tok-key">"notes"</span>: [],

775

<span class="tok-key">"score"</span>: null,

776

<span class="tok-key">"format_version"</span>: <span class="tok-num">8</span>

}</pre>

</div>

<h3 class="devdocs-subsection-title"><a href="#limits">Size limits</a></h3>

781

782

<thead><tr><th>Limit</th><th>Value</th><th>Notes</th></tr></thead>

783

<tbody>

784

<tr><td>Max commits per push</td><td>10,000</td><td>Rejected at wire layer</td></tr>

785

<tr><td>Max objects per push</td><td>1,000</td><td>Larger batches use presigned URLs</td></tr>

786

<tr><td>Max object size (inline)</td><td>38 MB</td><td>Above this: presigned upload</td></tr>

787

<tr><td>Max msgpack file</td><td>64 MiB</td><td>Per commit or snapshot file</td></tr>

788

<tr><td>Max blob in mpack</td><td>256 MiB</td><td>MPack format limit</td></tr>

789

<tr><td>Max string (msgpack)</td><td>1 MiB</td><td>Any single string value</td></tr>

790

<tr><td>Max collection entries</td><td>1M</td><td>Array or map</td></tr>

</tbody>

</table>

</section>

{# ── On-disk layout ────────────────────────────────────────────────────── #}

796

797

<h2 class="devdocs-section-title"><a href="#on-disk">On-disk layout</a></h2>

798

799

<p>

800

Every Muse repo is a directory containing a <code>.muse/</code> subdirectory.

801

There is no index file, no packed-refs, no reflog by default — just the

802

flat object store and a handful of ref files.

</p>

<span class="devdocs-code-label">.muse/ directory tree</span>

809

</div>

810

<pre><code>.muse/

811

├── repo.json <span class="tok-cmt"># repo_id, domain, owner, created_at</span>

812

├── HEAD <span class="tok-cmt"># "refs/heads/dev" (symbolic ref)</span>

813

├── refs/

814

│ └── heads/

815

│ ├── main <span class="tok-cmt"># "sha256:<64-hex>\n"</span>

816

│ └── dev <span class="tok-cmt"># "sha256:<64-hex>\n"</span>

817

├── objects/

818

│ └── sha256/

819

│ └── ab/ <span class="tok-cmt"># first 2 hex chars (sharding)</span>

820

│ └── <62-hex> <span class="tok-cmt"># commits, snapshots, and blobs — unified store</span>

821

├── coordination/ <span class="tok-cmt"># multi-agent symbol reservations</span>

│ ├── reservations/

│ ├── intents/

│ ├── releases/

│ └── heartbeats/

├── harmony/ <span class="tok-cmt"># conflict resolution memory</span>

│ ├── patterns/

│ ├── policies/

│ └── audit/

└── agent.md <span class="tok-cmt"># repo-specific agent rules</span></code></pre>

</div>

<p>

The two-level sharding on objects (<code>sha256/ab/<62-hex></code>) keeps

835

directory sizes bounded: at one million objects, each shard directory

836

holds ~3,900 files on average — well within filesystem limits on all

major platforms.

</p>

<h3 class="devdocs-subsection-title"><a href="#on-disk-server">MuseHub server store</a></h3>

841

842

<p>

843

The MuseHub server uses the <strong>same on-disk format</strong> per repo under

844

<code>/data/repos/</code>. Object IDs, shard directories, and ref files are

845

byte-for-byte compatible with the client store — a blob stored by a push and

846

a blob stored locally are indistinguishable at the byte level.

847

The database holds only metadata caches and the collaboration layer;

848

authoritative repo state is always on disk.

</p>

<span class="devdocs-code-label">Server-side per-repo tree</span>

855

</div>

856

<pre><code>/data/repos/<owner>/<slug>/

857

├── objects/

858

│ └── sha256/ <span class="tok-cmt"># algorithm namespace (mldsa65/ slots in here)</span>

859

│ └── ab/ <span class="tok-cmt"># 2-char hex shard</span>

860

│ └── <62-hex> <span class="tok-cmt"># raw blob — same layout as .muse/objects/</span>

861

└── refs/

862

└── heads/

863

├── main <span class="tok-cmt"># "sha256:<64-hex>" — same format as client</span>

└── dev</code></pre>

</div>

<thead><tr><th>DB table</th><th>Role</th></tr></thead>

869

<tbody>

870

<tr><td><code>musehub_commits</code></td><td>Cache — fast graph queries, search, API listing</td></tr>

871

<tr><td><code>musehub_snapshots</code></td><td>Cache — fast manifest lookups</td></tr>

872

<tr><td><code>musehub_branches</code></td><td>Cache — fast branch listing; disk ref is authoritative</td></tr>

873

<tr><td><code>musehub_repos</code></td><td>Canonical — repo metadata, visibility, owner</td></tr>

874

<tr><td><code>musehub_identities</code> / <code>musehub_auth_keys</code></td><td>Canonical — identity and auth</td></tr>

875

<tr><td><code>musehub_issues</code> / <code>musehub_proposals</code></td><td>Canonical — collaboration layer</td></tr>

876

<tr><td><code>musehub_objects</code></td><td>Canonical — <code>storage_uri</code> + <code>size_bytes</code> index for fetch path resolution</td></tr>

</tbody>

</table>

<div>

Push negotiation checks object existence directly on disk — never in the DB.

884

This means force-resign, migration, or partial push failures cannot corrupt

885

the have/want walk. If the DB cache drifts from disk,

886

<code>GET /repos/{owner}/{repo}/branches/{name}/repair</code> heals it.

</div>

</div>

</section>

{# ── CLI reference ────────────────────────────────────────────────────── #}

892

893

<h2 class="devdocs-section-title"><a href="#cli">CLI reference</a></h2>

894

895

<p>

896

Every command accepts <code>--json</code>. The <code>--json</code> output is the

897

stable machine contract; the default terminal output is for humans and is not

898

versioned. Use <code>muse -C ~/path/to/repo <cmd></code> when your working

899

directory differs from the target repo.

900

</p>

901

902

<h3 class="devdocs-subsection-title"><a href="#cli-basics">Core workflow</a></h3>

903

904

905

<thead><tr><th>Task</th><th>Command</th></tr></thead>

906

<tbody>

907

<tr><td>Initialise repo</td><td><code>muse init [--domain code|midi|identity]</code></td></tr>

908

<tr><td>Working-tree status</td><td><code>muse status --json</code></td></tr>

909

<tr><td>Stage files</td><td><code>muse code add <path></code> / <code>muse code add .</code></td></tr>

910

<tr><td>Unstage</td><td><code>muse code reset <path></code></td></tr>

911

<tr><td>Delete + stage deletion</td><td><code>muse rm <path></code></td></tr>

912

<tr><td>Commit</td><td><code>muse commit -m "msg" [--agent-id X --model-id Y --sign]</code></td></tr>

913

<tr><td>History</td><td><code>muse log --json</code></td></tr>

914

<tr><td>Inspect commit</td><td><code>muse read --json [--manifest]</code></td></tr>

915

<tr><td>Diff working tree</td><td><code>muse diff</code> / <code>muse diff --staged</code></td></tr>

916

917

<tr><td>List branches</td><td><code>muse branch --json</code></td></tr>

918

<tr><td>Switch / create branch</td><td><code>muse checkout [-b] <branch> [--intent "..." --resumable]</code></td></tr>

919

<tr><td>Three-way merge</td><td><code>muse merge <branch></code></td></tr>

920

<tr><td>Dry-run merge</td><td><code>muse merge --dry-run <branch> --json</code></td></tr>

921

<tr><td>Shelf (stash)</td><td><code>muse shelf save [-m "msg"]</code> / <code>muse shelf pop</code></td></tr>

922

<tr><td>Tag</td><td><code>muse tag add "label" [<ref>]</code></td></tr>

923

<tr><td>Release</td><td><code>muse release add <semver></code></td></tr>

</tbody>

</table>

<div>

<code>muse code add .</code> stages new files, modifications, <em>and</em>

931

deletions of already-tracked files — equivalent to <code>git add -u && git add .</code>

932

combined. To remove a file from tracking without deleting it from disk,

933

use <code>muse rm --cached <path></code>.

</div>

</div>

<h3 class="devdocs-subsection-title"><a href="#cli-json-shape">muse status --json shape</a></h3>

938

939

<p>

940

The status JSON schema is always identical regardless of domain or staging state.

941

All keys are always present — no <code>dict.get</code> guards needed.

</p>

</div>

<pre><code>{

<span class="tok-key">"branch"</span>: <span class="tok-str">"dev"</span>,

950

<span class="tok-key">"head_commit"</span>: <span class="tok-str">"sha256:abc..."</span>,

951

<span class="tok-key">"upstream"</span>: null, <span class="tok-cmt">// tracking remote name, or null</span>

952

<span class="tok-key">"ahead"</span>: null, <span class="tok-cmt">// commits ahead of remote; null when no upstream</span>

953

<span class="tok-key">"behind"</span>: null, <span class="tok-cmt">// commits behind remote; null when no upstream</span>

954

<span class="tok-key">"clean"</span>: <span class="tok-num">true</span>, <span class="tok-cmt">// true only when no staged, unstaged, or untracked files</span>

955

<span class="tok-key">"dirty"</span>: <span class="tok-num">false</span>, <span class="tok-cmt">// always NOT clean</span>

956

<span class="tok-key">"total_changes"</span>: <span class="tok-num">0</span>, <span class="tok-cmt">// tracked-file changes (added+modified+deleted+renamed)</span>

957

<span class="tok-key">"untracked_count"</span>: <span class="tok-num">0</span>, <span class="tok-cmt">// len(untracked); nonzero when dirty but total_changes==0</span>

958

<span class="tok-key">"added"</span>: [], <span class="tok-cmt">// flat union of staged + unstaged</span>

959

<span class="tok-key">"modified"</span>: [],

960

<span class="tok-key">"deleted"</span>: [],

961

<span class="tok-key">"renamed"</span>: {}, <span class="tok-cmt">// old_path → new_path map</span>

962

<span class="tok-key">"staged"</span>: {

963

<span class="tok-key">"added"</span>: [], <span class="tok-key">"modified"</span>: [], <span class="tok-key">"deleted"</span>: []

964

},

965

<span class="tok-key">"unstaged"</span>: {

966

<span class="tok-key">"added"</span>: [], <span class="tok-key">"modified"</span>: [], <span class="tok-key">"deleted"</span>: [], <span class="tok-key">"renamed"</span>: {}

967

},

968

<span class="tok-key">"untracked"</span>: [], <span class="tok-cmt">// on-disk but not tracked; presence makes clean=false</span>

969

<span class="tok-key">"conflict_paths"</span>: [],

970

<span class="tok-key">"merge_in_progress"</span>: <span class="tok-num">false</span>,

971

<span class="tok-key">"merge_from"</span>: null, <span class="tok-cmt">// branch being merged; null when no merge</span>

972

<span class="tok-key">"conflict_count"</span>: <span class="tok-num">0</span>,

973

<span class="tok-key">"checkout_interrupted"</span>: <span class="tok-num">false</span>,

974

<span class="tok-key">"checkout_target"</span>: null

}</code></pre>

</div>

</section>

{# ── Push / pull ──────────────────────────────────────────────────────── #}

<p>

Push sends a <code>WireMPack</code> — a compact envelope containing every

985

commit, snapshot, and object the remote doesn't already have — over

986

<code>application/x-msgpack</code> to <code>POST /{owner}/{slug}/push</code>.

987

The hub validates the mpack, stores objects atomically, and advances the

988

branch pointer in a single transaction. Pull is the reverse: the client

989

fetches an mpack from the hub and integrates it locally.

</p>

<span class="devdocs-code-lang">python</span>

995

<span class="devdocs-code-label">WireMPack shape (musehub.models.wire)</span>

996

</div>

997

<pre><code><span class="tok-kw">class</span> <span class="tok-type">WireMPack</span>(BaseModel):

998

commits: list[<span class="tok-type">WireCommit</span>] <span class="tok-cmt"># CommitRecord dicts</span>

999

snapshots: list[<span class="tok-type">WireSnapshot</span>] <span class="tok-cmt"># SnapshotRecord dicts</span>

1000

objects: list[<span class="tok-type">WireObject</span>] <span class="tok-cmt"># raw blob bytes</span>

1001

branch_heads: dict[str, str] <span class="tok-cmt"># branch → commit_id</span>

1002

1003

<span class="tok-kw">class</span> <span class="tok-type">WireObject</span>(BaseModel):

1004

object_id: str

1005

content: bytes <span class="tok-cmt"># raw; no base64</span>

1006

path: str = <span class="tok-str">""</span>

1007

encoding: str = <span class="tok-str">"raw"</span> <span class="tok-cmt"># "raw" | "zlib" | "delta+zlib"</span>

1008

base_id: str | None <span class="tok-cmt"># set for delta-encoded objects</span></code></pre>

</div>

<p>The hub validates a push in this order before persisting anything:</p>

</div>

<pre><code>1. Verify MSign Authorization header (Ed25519, ±30s replay window)

1020

2. Resolve repo — owner + slug → repo_id + repo_root (/data/repos/<owner>/<slug>/)

1021

3. Confirm pusher has write access

1022

4. Negotiate have/want — hub checks object existence on disk, not in DB

1023

5. Validate mpack schema + ID format (<span class="tok-acc">sha256:</span><hex>, ≥32 chars)

1024

6. Enforce push limits (max 10k commits, 1k objects, 38 MB/object)

1025

7. Persist objects → /data/repos/<owner>/<slug>/objects/sha256/<2-hex>/<62-hex> (atomic)

1026

8. Persist snapshots → musehub_snapshots (DB cache)

1027

9. Persist commits → musehub_commits (DB cache)

1028

10. Advance branch pointer → refs/heads/<branch> on disk (atomic rename), then musehub_branches (cache)

1029

11. Update repo.pushed_at timestamp

1030

12. Upsert reachability index (musehub_object_refs)</code></pre>

</div>

</div>

<pre><code><span class="tok-cmt"># Push dev branch to the local hub</span>

1038

muse push local dev

1039

1040

<span class="tok-cmt"># Push to staging</span>

1041

muse push staging dev

1042

1043

<span class="tok-cmt"># Pull from remote</span>

1044

muse pull local dev

1045

1046

<span class="tok-cmt"># Check configured remotes</span>

1047

muse remote --json</code></pre>

</div>

<div>

Push returns 404 ("Repository not found on remote") if the repo hasn't

1054

been created on the hub yet. Create it first via

1055

<code>muse hub repo create --name <name> --json</code>, then retry.

</div>

</div>

</section>

{# ── Phase nav ────────────────────────────────────────────────────────── #}

Phase 00: Getting Started

1065

</a>

1066

1067

Phase 02: Cryptographic Identity

</a>

</nav>

</article>

</div>

</div>

{% endblock %}