root / MUSE_WORK_ORDER.md
13799 bytes
# Muse work order: peer record and block exchange, isomorphic core
## Goal
The self-hosting MVP in `SPEC.md` is done: `sh test/self-host.sh` passes at
`590ded7`, covering all four acceptance cases (two generations, interruption
before selection, fetch of a new commit, corrupt-block rejection). Nodes
currently move source between each other only through Git clone bootstrap.
This work order is the first item SPEC defers after the MVP: peer record and
block exchange. A node must be able to sync signed ANProto records and AndFS
blocks directly from another node, verify them, and serve the same history —
without a Git clone in between.
Standing constraint from Ev: keep ANBot isomorphic. The core must run in the
browser as well as in Node. Browser peers sync, verify, and hold records and
blocks; they do not need to materialize Git repositories or serve Git HTTP.
## Standing constraints
- The ANProto envelope stays byte-identical: `author`, `contentHash`,
`payload`, `proof`, `signature`, and `id` are computed exactly as SPEC
defines them. Records published by the current code must keep verifying
under the new code.
- Selection is the publication commit point. Verify records and blocks
durably before changing the selection. An interruption before selection
leaves the previous update usable and may leave unselected records or
blocks behind.
- Sync is per-interest: follow the head of the repository you care about,
walk back until you reach records you already have, then stop. No
whole-network scan and no whole-network hash.
- No new dependencies unless there is no platform built-in that does the
job. WebCrypto, `fetch`, OPFS, and IndexedDB are built-ins.
- Git materialization (`git` CLI, bundles, `fsck`, `git http-backend`) and
Git HTTP serving stay Node-only.
- Commit changes locally. Push to a remote only when explicitly requested.
- For changes to publication, storage, or Git serving, run
`sh test/self-host.sh` from a clean, committed checkout and record the
commit the test exercised.
## 1. Isomorphic core split
Split the platform-free logic out of `storage.mjs` into core module(s) that
import nothing Node-only.
- [x] Core covers: envelope signing and verification, AndFS chunking and
manifest validation, record container validation, duplicate-member
rejection. Git-specific update content rules stay in `repository.mjs`.
No `node:` imports, no `Buffer`, no `process`, no `fs`.
- [x] Crypto moves from sync `node:crypto` to async WebCrypto
(`globalThis.crypto.subtle`) for SHA-256 and Ed25519, following the
pattern already used in the muse-wiredove-adapter's `an.js`. Core
functions become async throughout; callers adapt.
- [x] Key handling keeps PEM/PKCS8 identity files: keys are imported into
WebCrypto on load and new keys are exported back to PEM. No migration
and no re-keying: existing identities keep their author and
repository ID, and already-published records keep verifying.
- [x] Regression check: records and bundles published by the `590ded7`
code verify and recover under the new core, byte for byte.
(`test/core-compat.sh` checks both directions against `6432db8`,
the last pre-core commit.)
- [x] Add an import check to the tests: core files must not import `node:*`
or reference Node-only globals. (`test/core-imports.sh`.)
## 2. Store interface
Put a small async store interface behind record, block, and selection
storage. The core talks to the interface; each platform provides one.
- [x] Interface: get/put records by ID, get/put blocks by hash, read/write
the selection. Puts are durable before they return, on each platform
to the extent that platform allows. (`store.mjs` documents the
interface; `test/store.sh` runs conformance checks.)
- [x] Node implementation keeps current filesystem semantics: fsync,
atomic link/rename install, directory sync. (`createFsStore` in
`storage.mjs`, same on-disk layout; `writeRecord`, `readRecord`,
`storeBundle`, and `recoverBundle` run on it.)
- [x] Browser implementation: OPFS first, IndexedDB fallback. Document the
durability limits honestly (no fsync in a browser) and keep the
verify-then-select rule. (`store-browser.mjs`; the browser harness
in section 5 exercises both backends.)
- [x] In-memory store for tests (precedent: `memoryStore` in Wiredove's
`vendor/andfs/stores.js`). (`memoryStore` in `store.mjs`.)
## 3. Sync endpoints (Node server)
Extend `serve` with read-only sync endpoints next to the Git endpoints.
Reuse the existing verification on the serve path.
- [x] `GET /gossip/poll?since=<cursor>` returns records after the cursor,
paginated, in arrival order, shaped like the Wiredove relay poll.
Define the cursor as an opaque server sequence and document it.
(Cursor is Base64url JSON `[payloadTimestamp, recordId]`; order is
(timestamp, id); page size 100; `nextSince` is null at the end.)
- [x] `GET /blocks/<hash>` returns manifest or chunk bytes by hash.
(Hash verified before serving; immutable cache headers.)
- [x] Endpoints are read-only. They serve only records and blocks the node
holds; they never accept unverified data. (Poll skips unverified
records with a log line; both endpoints carry
`Access-Control-Allow-Origin: *` for browser peers.)
## 4. Pull client (isomorphic, `fetch`-based)
A sync client that runs unchanged in Node and in the browser.
- [x] Pull records since the cursor. Verify the envelope and content of
each record before storing it. Deduplicate by record ID; re-pulling
the same cursor is a no-op. (`sync.mjs`; no cursor is persisted —
every pull starts from the beginning and deduplicates.)
- [x] For each `git-update` record, fetch the manifest and any missing
chunks. Verify the manifest structure, each chunk hash and length,
and the reconstructed size before use.
- [x] Advance the selection only after the bundle verifies: on Node,
through the existing materialize path (bundle verify, connectivity,
no prerequisites, exact branch and commit); in the browser, verify
manifest and chunks and hold the bundle bytes. (Node hook:
`verifySelection`; default hook: `reassembleBundle`.)
- [x] Per repository: follow the selected head and stop at records already
held. Partial failure leaves unselected records or blocks behind and
never advances the selection on unverified data. (Chain links via a
new optional `previous` field on `git-update` records; records
without it are chain roots. Serving now verifies against the
repository's publisher key, not the local identity, so synced
records serve.)
- [x] Reject corrupt or tampered records and blocks with the same rules
`storage.mjs` applies today. Never store unverified bytes under a
verified ID.
## 5. Tests and browser proof
- [x] Extend `test/self-host.sh`: node B syncs from node A through peer
exchange with no Git clone, then serves the same commit over Git.
A development commit on B propagates through sync and `fetch`.
Interruption before selection during sync leaves the previous
commit cloneable; retry selects the new tip. Corrupt records and
blocks offered over sync are rejected.
(Deviation: the coverage lives in `test/sync.sh` instead of
extending `test/self-host.sh`, keeping the clone-bootstrap test
focused. Interruption before selection is covered by deterministic
failure injection — a tamper shim, `test/sync-shim.mjs`, offers a
corrupt record and a corrupt block — rather than a timed kill, so
the test cannot race. The development commit propagates from A to B
through sync, matching acceptance case 2.)
- [x] Browser harness: a static page importing the core modules, run in a
real browser, exercising sign/verify, an AndFS round-trip, and a
pull against a local node. Record how to run it in `README.md`.
(`test/browser/harness.html` + `test/browser.sh`, run in headless
Chromium; also exercises both browser store backends.)
- [x] The existing self-host test stays green throughout. Record the
commit each test run exercised. (Battery results per section are
recorded in the handoff below.)
## 6. Docs
- [x] Update `SPEC.md` with the peer exchange section: endpoints, cursor
semantics, and the browser peer's verification-only role.
(Also documents the optional `previous` field and serving against
the repository publisher key.)
- [x] Update `README.md` with sync commands and browser notes.
(Sync commands, browser-peer notes with honest durability limits,
harness instructions, and the new test commands.)
- [x] Update `AGENTS.md` if new standing rules emerge.
(Serve-by-publisher-key, stores as dumb byte holders, sync and
browser test commands.)
- [x] At handoff, record the source commit and the exact start, publish,
sync, clone, and fetch commands with their observed results, as
SPEC's acceptance section requires. (Handoff below.)
## Non-goals
- Git materialization in the browser (isomorphic-git or similar). A later
decision, not needed for this milestone.
- Push, gossip, or WebRTC/Trystero transport. HTTP pull first; it works in
the browser today with no new dependencies.
- Social records, historical adapters, and multi-publisher import. They
follow this milestone, per SPEC.
- Multi-repository serving and ambiguous-prefix rules beyond what the MVP
already documents.
- Any ingest endpoint that stores data before verifying it.
## Open decisions
- Cursor semantics for the poll endpoint: resolved — Base64url JSON
`[payloadTimestamp, recordId]` from verified records, ordered by
(timestamp, id). No server-side index; correct across restarts.
- Browser store default: resolved — OPFS first, IndexedDB fallback where
OPFS is unavailable (`createBrowserStore` in `store-browser.mjs`).
- Existing node identity migration: resolved — PEM identities are imported
into WebCrypto on load; no conversion on disk and no re-keying, so new
publications keep the same repository ID.
## Acceptance
1. Node B syncs from node A through peer exchange alone, serves the synced
commit over ordinary Git, and a clone from B matches the published
commit and history.
2. A new commit published on A reaches B through sync, and `fetch` from B
at the same URL shows it with its ancestry intact.
3. Interruption before selection during sync leaves the previous commit
cloneable; retry selects the new tip.
4. Corrupt or tampered records and blocks offered over sync are rejected,
and the previous selection keeps serving.
5. The core modules import and run in a real browser with no Node-only
imports, and the browser harness passes.
6. `sh test/self-host.sh` passes from a clean, committed checkout, and the
handoff record names the commit and commands with observed results.
## Handoff
Source commit: `94cce07` (sections 2–5; section 6 is docs-only on top of
it). The commands below are the exact sequence `test/sync.sh` executes,
with scratch directories shown as `a`, `b`, `source`, and `clone`, and
ports 18795 (A), 18796 (B), and 18797 (shim). Observed results are from
the battery run at `94cce07` on 2026-11-16.
Start node A and publish v1:
```sh
git init -q -b main source
git -C source commit -q -m v1
node anbot.mjs publish --data a --source source --branch main --port 18795
node anbot.mjs serve --data a --port 18795
```
Sync node B with no Git clone, then clone from B:
```sh
node anbot.mjs sync --data b --url http://127.0.0.1:18795
node anbot.mjs serve --data b --port 18796
git clone "$(cat urlb)" clone
```
Observed: the clone's HEAD was
`f364d75035951a70df13ebc94e3734357a450bf6`, the published v1 commit.
Publish v2 on A, sync B, fetch from B:
```sh
git -C source commit -q -m v2
node anbot.mjs publish --data a --source source --branch main --port 18795
node anbot.mjs sync --data b --url http://127.0.0.1:18795
git -C clone fetch -q origin
```
Observed: `origin/main` was
`106e0bc1d5478ed4e87aa1bf5a90a47808d299db`, with v1 as its ancestor.
Offer a corrupt record over sync, then verify the previous selection
still serves after a restart with the cache deleted:
```sh
node test/sync-shim.mjs --upstream http://127.0.0.1:18795 --port 18797 --mode tamper-record
node anbot.mjs sync --data b --url http://127.0.0.1:18797
```
Observed: sync exited nonzero; the shim logged a tampered record; a
fresh clone from restarted B still got v2.
Publish v3 on A, offer a corrupt block over sync, then retry directly:
```sh
git -C source commit -q -m v3
node anbot.mjs publish --data a --source source --branch main --port 18795
node test/sync-shim.mjs --upstream http://127.0.0.1:18795 --port 18797 --mode tamper-block
node anbot.mjs sync --data b --url http://127.0.0.1:18797
node anbot.mjs sync --data b --url http://127.0.0.1:18795
git -C clone fetch -q origin
```
Observed: the tampered sync failed with `Corrupt AndFS block` and a
fresh clone still got v2; after the direct retry, `origin/main` was
`b7f6a70b4cb7b481aaab56ae1e52b245c2cb9bc3`, with v2 as its ancestor.
Full battery at `94cce07`, all green: `test/self-host.sh` (two
generations and interruption, clone got
`d4afb2cc87f369c0adf8bc3c68f0d2bfdc5a495d`), `test/push.sh` (published
`83f4eb64d88b8c12aebb97a2a4ea2cb1d845ff0c`), `test/webui.sh` (served
`4c8b6c2b71364878d65f2083b56406be1cb0320a`), `test/core-imports.sh`,
`test/core-compat.sh` (both directions at
`d61d2ac2268de16b058d60153cbc3f605ee0f7c4`), `test/store.sh`,
`test/sync.sh`, and `test/browser.sh` (harness at
`66e7aeef4baf17fc625e4847735be95137ad95c9`).