create-holon 0.1.6 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-holon",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "type": "module",
   "description": "Scaffold a Nomos domain package: the starter domain + compile config + live e2e. `npm create githolon my-app`.",
   "license": "SEE LICENSE IN LICENSE.md",

package/template/README.md

@@ -61,9 +61,11 @@ The starter is the tutorial; this is the exact path from guestbook to your own l
    ```js
    export default { name: "<pkg>", domains: [{ key: "<pkg>", modules: ["./domains/<yours>.ts"] }] };
    ```
-   **Naming convention:** make `<pkg>` ONE lowercase word (`potluck`, `studygroup`).
-   It becomes the generated symbols verbatim: `build/<pkg>.client.ts` exporting
-   `<pkg>Client(holon)` and `<PKG>_DOMAIN_HASH`.
+   **Naming convention: there isn't one.** `<pkg>` can be whatever you'd actually
+   call it — `potluck`, `tool-library`, `study_group`, even `Tool Library`.
+   Artifact filenames keep your name verbatim (`build/<pkg>.client.ts`); the
+   generated symbols normalize it for you (`toolLibraryClient(holon)`,
+   `TOOL_LIBRARY_DOMAIN_HASH`).
 3. **Compile and read what you built:**
    ```bash
    npx githolon compile && cat build/<pkg>.summary.txt
@@ -77,8 +79,27 @@ The starter is the tutorial; this is the exact path from guestbook to your own l
 
 Then deploy it for real: `npx githolon login --agent && npx githolon ws create <ws> && npx githolon deploy <ws>`.
 
+## Docs — in the box
+
+`docs/` travels with you — offline, like everything else here. Five short
+pages, each under a screen and a half:
+
+1. [The mental model](./docs/01-mental-model.md) — holons, content-addressed
+   law, custody-not-truth, admission, no server authority.
+2. [Authoring law](./docs/02-authoring.md) — aggregates, field kinds, the
+   merge-driver table, plan ops (`addToSet` vs `set`), determinism rules,
+   declared reads (query/count/derived/sum).
+3. [The client](./docs/03-client.md) — `connect`, the generated client
+   contract, `sync` semantics (`admission: null` is normal), watches, dead
+   letters, the two-clientId concurrency proof.
+4. [Nomos Cloud](./docs/04-cloud.md) — both deploy lanes, `login --agent`
+   identity, retirement + data retention per the license, DLQ retry, quotas.
+5. [Superpowers](./docs/05-superpowers.md) — mint a holon locally, the upload
+   birth, byte-identical wasm everywhere, the enforced-offline proof.
+
 ## What's here
 
+- `docs/` — the five pages above; the offline reference.
 - `domains/guestbook.ts` — the starter domain (the law): one aggregate, two
   directives, a declared query, a derived field, a count. Rename it, reshape
   it, or add domains with `npx githolon generate domain <name>`.
@@ -94,7 +115,9 @@ Then deploy it for real: `npx githolon login --agent && npx githolon ws create <
 ## Authoring rules (the engine enforces these)
 
 - A directive's plan is a PURE function of `(payload, ports)` — timestamps ride
-  in the payload as ISO strings; no `Date.now()` / `Math.random()`.
+  in the payload as ISO strings; no `Date.now()` / `Math.random()`. You rarely
+  stamp one by hand: payload fields named `…At` are auto-filled with ISO now()
+  by the generated client when you omit them (an explicit value always wins).
 - `create(Agg)` mints ids — `.creates` payloads never carry one.
 - Merge drivers are the law: `Lww`, `AddWins`, `MapOf(Lww)`.
 

package/template/docs/01-mental-model.md

@@ -0,0 +1,57 @@
+# The mental model
+
+Five ideas. Everything else in this scaffold is a consequence of them.
+
+## Holons
+
+A holon is the runtime: kernel + SQLite projection + an embedded deterministic
+JS engine, compiled into ONE `wasm32-wasip1` artifact. Every peer — the cloud
+edge, your laptop, a browser tab, the e2e test — runs the SAME bytes. That is
+why results agree: not because peers trust each other, but because they cannot
+diverge. There is no "server build" and "client build". There is one build.
+
+## Law
+
+Your domain — aggregates + directives in `domains/*.ts` — compiles to a
+package whose sha256 IS its identity (`policy:{hash}`). Law is
+content-addressed: a workspace doesn't run "version 3 of guestbook", it runs
+`policy:ab12…`, and the generated client carries that exact hash baked in.
+A write is judged against the hash it was authored under. No ambient config,
+no environment drift — if the bytes differ, it is different law.
+
+## Custody, not truth
+
+The ledger is a git repo. Git stores and transports the chain; it does not
+vouch for it. Every holon re-verifies everything it replays: contiguity,
+admission of every intent, plans re-run and byte-compared. So possession of
+the repo confers nothing — a chain is valid because it verifies, wherever it
+sits. This is why `git clone` of your workspace works with stock git, and why
+a chain minted on your laptop is exactly as good as one minted in the cloud.
+
+## Admission
+
+Clients author OFFLINE under the pulled law, then push to an untrusted
+`session/<clientId>` branch. The edge holon re-admits each intent — validates
+the payload, re-runs the plan, byte-compares the result — before merging to
+`main`. Verification, never trust: `refs/heads/main` is written only through
+that gate. A rejected intent is dead-lettered on both sides, never lost
+(see [03-client.md](./03-client.md)).
+
+## No server authority
+
+No holon outranks another. The cloud edge is custody plus a convenient
+always-on peer — its verdicts are re-derivable by anyone with the chain and
+the wasm. That's the point of Path B in the README: mint a ledger locally,
+verify it locally, push it, and watch the cloud re-derive your exact verdict
+before serving anything. Authority lives in the git, not in a hostname.
+
+## What this buys you
+
+- Offline is the normal case, not a degraded mode. Writes, queries, counts,
+  derived fields all run locally; sync is reconciliation, not submission.
+- Merges are law, not luck: every field declares its merge driver, so
+  concurrent edits resolve the same way on every peer
+  (see [02-authoring.md](./02-authoring.md)).
+- The audit trail is `git log`. Every commit is an intent envelope.
+
+Next: [02-authoring.md](./02-authoring.md) — what you actually write.

package/template/docs/02-authoring.md

@@ -0,0 +1,76 @@
+# Authoring law
+
+You write exactly TWO things: aggregates and directives. Never apply/fold/
+merge code — the kernel owns folding; your directive PLANS ops and the sealed
+engine replays them deterministically on every peer. Declared reads (query,
+count, derived, sum) are auto-discovered from your module's exports by shape.
+`domains/guestbook.ts` demonstrates every pattern below; reshape it.
+
+## Aggregates: typed fields, each tagged a merge driver
+
+```ts
+export const Book = aggregate("Book", {
+  title: t.string().merge(Lww),
+  tags:  t.set(t.string()).merge(AddWins),
+  notes: t.map(t.string()).merge(MapOf(Lww)),
+});
+```
+
+Field kinds: `t.string()` · `t.int()` · `t.enum([...] as const)` (typos squeal
+at compile time) · `t.set(t.string())` · `t.map(inner)` · `t.json()` /
+`t.jsonObject()` (JSON-string leaf; `jsonObject` asserts an object and reads
+back structured) · `t.ref(Agg)` (an id-valued reference) ·
+`t.hasMany(Child).via("parent")` (the virtual read side of a child's ref —
+nothing stored on the parent). Add `.optional()` where absence is legal.
+
+## Merge drivers ARE the conflict policy
+
+| driver | concurrent writes to the same field… |
+|---|---|
+| `Lww` | last write wins (by the intent's HLC timestamp) |
+| `AddWins` | sets union — concurrent adds ALL survive |
+| `MapOf(Lww)` | per-key LWW — concurrent writers to different keys commute |
+| `Conflict` | refuse to merge (fail-closed; the default if you tag nothing) |
+
+You choose the policy per field, at authoring time. Nobody writes merge code
+at 2am during an incident — the kernel applies the declared driver, the same
+way on every peer.
+
+## Directives: a zod payload → a pure plan
+
+```ts
+export const addBook = directive("addBook").creates(Book)
+  .payload(z.object({ title: z.string(), addedAt: z.string() }))
+  .plan((p) => { create(Book).set("title", p.title); return []; });
+```
+
+Plan ops: `set` (scalars/refs) · `addToSet` (the ONLY additive write to an
+AddWins set — `set()` on a set field would overwrite the union and is REFUSED
+at the type level and at runtime) · `setEntry` (one map key) · `strike`
+(retract). `.creates(Agg)` mints the id — payloads never carry one;
+`.mutates(Agg)` takes the instance id in the payload.
+
+## Determinism or death
+
+A plan is a PURE function of its payload. No `Date.now()`, no
+`Math.random()`, no I/O — the sandbox traps them. Timestamps ride IN the
+payload as ISO strings, stamped by the caller. Why so strict: every peer
+re-runs your plan and byte-compares the result; one nondeterministic call and
+admission fails everywhere, forever.
+
+## Declared reads — name them, never scan
+
+- `query("booksByShelf").key("shelf").returns(Book)` — an indexed probe.
+- `count("booksPerShelf").of(Book).by("shelf")` — a maintained O(1) tally.
+- `sum("stockValue", "price").of(Book).by("shelf")` — count's numeric sibling:
+  a maintained running total of an int field; `.where(p => …)` filters, `.by`
+  groups. Never a `SUM(*)` scan.
+- `derived("isLong").of(Book).returns(z.boolean()).as((b) => …)` — a PURE
+  engine-projected read field. Lives only in the read model, never in the
+  ledger, so it is always re-derivable.
+
+Export each at top level; `githolon compile` routes them into the read
+manifest so they work at the edge AND in clients. After a compile, read
+`build/<pkg>.summary.txt` — it describes exactly what you built.
+
+Next: [03-client.md](./03-client.md) — driving it from an app.

package/template/docs/03-client.md

@@ -0,0 +1,78 @@
+# The client
+
+`test/e2e.mts` IS the tutorial — every claim below runs live in it. This page
+is the map.
+
+## connect()
+
+```ts
+import { connect } from "@githolon/client";
+import { guestbookClient } from "../build/guestbook.client.ts";
+
+const holon = await connect({ cloud, workspace, clientId });
+const app = guestbookClient(holon);
+```
+
+`connect` pulls the wasm, the workspace manifests, and the ledger, then runs
+the byte-identical holon LOCALLY. `clientId` names your session branch
+(`session/<clientId>`) — one per writer. Everything after connect works
+offline; the e2e proves it by trapping `fetch` while it authors and queries.
+
+## The generated client contract
+
+`githolon compile` emits `build/<pkg>.client.ts`: a typed method per directive
+(payload types from the SAME zod the engine validates), a read-model interface
+per aggregate (every field optional — partial folds are normal), typed
+accessors per declared query/count/sum, by-id read and watch helpers, and the
+deployed law's content hash baked in. Zero imports — it binds structurally to
+`connect()`'s holon. If the cloud's law hash differs from the client's, you
+compiled different bytes; recompile rather than wonder.
+
+The raw surface stays underneath: `holon.dispatch(...)`, `holon.query(id,
+params)`, `holon.queryById(id)`, `holon.count(id, group)`, `holon.sum(id,
+group)`. Hover anything in your editor — `@githolon/client` ships full types
+and the semantics live in the doc comments.
+
+## sync()
+
+```ts
+const s = await holon.sync({ admit: true });
+```
+
+One call: push unpushed intents to your session branch, ask the edge to judge
+now, pull canonical main, rebase-replay anything still unacked (intent-id
+deduped — nothing ever double-folds). `s.admission` is `null` when there was
+nothing to push — normal, not an error. Without `{admit: true}` a push still
+lands within ~2s: the edge self-schedules admission. `holon.pull()` converges
+in place on demand; no reconnects, ever.
+
+## watch
+
+`app.watch<Agg>ById(id, (rows) => …)` is a LOCAL reactive read — it fires on
+local folds and on pulls. Render from watches; treat sync as background
+reconciliation, not as the read path.
+
+## Dead letters — refused work is never lost
+
+A DOMAIN rejection (the law couldn't admit it — e.g. its domain isn't deployed
+yet) parks the FULL intent on both sides: `holon.deadLetters()` locally
+(durable — it rides `holon.export()`/restore) and the workspace DLQ in the
+cloud. Ship a law fix through the deploy lane, then `holon.retryDeadLetter(id)`
+— the user's work lands on main. `discardDeadLetter(id)` is the app's explicit
+choice; nothing is silently dropped. Obvious attacks (session-lane law
+intents) are dropped, never queued.
+
+## Two writers, no coordination
+
+The canonical concurrency demo (e2e step 9): two `connect()`s with DIFFERENT
+clientIds tag the same entry offline, blind to each other. Both sync; the
+AddWins union keeps every add. No locks, no "last writer wins the whole
+record", no merge code — the field's declared driver did it
+(see [02-authoring.md](./02-authoring.md)).
+
+## Persistence
+
+`holon.export()` → bytes; `connect({ restoreFrom: bytes })` restores. Pending
+un-synced writes survive an app reload and still sync.
+
+Next: [04-cloud.md](./04-cloud.md) — workspaces, identity, quotas.

package/template/docs/04-cloud.md

@@ -0,0 +1,78 @@
+# Nomos Cloud
+
+The cloud (`https://nomos.captainapp.co.uk`) hosts edge holons, one per
+workspace, ledgered in git. It is custody plus an always-on peer — not an
+authority (see [01-mental-model.md](./01-mental-model.md)). Everything the
+CLI does, curl and stock git can do; `npx githolon --help` lists every lane.
+
+## Identity first
+
+```bash
+npx githolon login --agent
+```
+
+One command, no browser, no signup form: a VERIFIED self-onboarded identity,
+linkable to a full account later. Every birth needs a principal — no
+anonymous nodes — so log in before creating anything. `githolon whoami` shows
+the principal births will ride; sessions auto-refresh from
+`~/.holon/credentials.json`.
+
+## Two deploy lanes, one destination
+
+**Path A — deploy your law** (the cloud births the workspace):
+
+```bash
+npx githolon ws create <ws>   # birth; the ONE-TIME workspaceSecret is saved to ~/.holon
+npx githolon deploy <ws>      # POST build/<pkg>.deploy.json with the stored secret
+```
+
+**Path B — the upload birth** (you birth it, the cloud verifies):
+
+```bash
+npx githolon ledger init holon
+cd holon && npx githolon git remote <ws> && git push nomos main
+```
+
+Both end in the same place — all holons are equal in authority; the chain
+proves itself either way ([05-superpowers.md](./05-superpowers.md) walks B).
+
+## Ownership
+
+The workspace secret gates LAW (deploys, retirement, secret rotation). End-user
+apps carry NO secret: reads and session pushes are open, judged by edge
+admission; the session lane structurally refuses control-plane intents. So law
+only ever enters through the secret-gated deploy. Lose the secret? It was
+shown once — `githolon secret rotate` with the current one, or ask the
+operator. Never embed it in an app.
+
+## Dead-letter retry — the operator's unjam
+
+Domain-rejected intents land in the workspace DLQ with full provenance
+(`GET /v1/workspaces/<ws>/dead-letters`, owner-keyed). Ship the law fix via
+the deploy lane, then `POST /v1/workspaces/<ws>/dead-letters/retry?id=` (or
+client-side `retryDeadLetter(id)`). The refused work — somebody's actual
+writes — lands on main. DELETE discards, explicitly.
+
+## Retirement and data retention
+
+```bash
+npx githolon ws retire <ws>
+```
+
+Owner-gated. The workspace stops counting toward your quota; deploys and
+session pushes refuse; reads keep serving. The data is NOT deleted: this is a
+pre-release and the license says so plainly — workspace data (ledgers, law,
+intents) is retained and may be examined to evaluate the product. Don't put
+anything in a pre-release workspace you wouldn't want the builders to read.
+Need something truly expunged? jack@captainapp.co.uk.
+
+## Quotas — law-state, not host config
+
+The limits are themselves law (a `CloudPolicy` record in the root workspace):
+**50 live workspaces** per principal, **1 GiB** cumulative pushed bytes per
+workspace ledger, push 30/min, admit 10/min per workspace. Refusals on the
+git lane answer with a pkt-line `ERR`, so stock git prints the reason. Hitting
+a limit is a quota REQUEST, not a wall: an admin grants an allowance and a
+fresh grant unjams immediately. Ask: jack@captainapp.co.uk.
+
+Next: [05-superpowers.md](./05-superpowers.md) — what only this stack can do.

package/template/docs/05-superpowers.md

@@ -0,0 +1,66 @@
+# Superpowers
+
+Things this stack does that a client-server stack structurally cannot. Each
+one is e2e-proven, not aspirational.
+
+## Mint a real holon locally
+
+```bash
+npx githolon ledger init holon    # genesis + your compiled law, under YOUR identity
+npx githolon ledger verify holon  # re-assert any time
+```
+
+`ledger init` builds a brand-new GitHolon ledger on your machine: genesis (the
+nomos controller), then your law, every intent stamped `installedBy: <your
+identity>` — and verifies the chain with the SAME byte-identical wasm gate the
+cloud runs. This is not a mock or a dev server. It is a holon, born valid,
+and you can assert that yourself, offline, before any network exists.
+
+## The upload birth — the cloud re-derives YOUR verdict
+
+```bash
+cd holon
+npx githolon git remote <ws>   # wires the remote + credential helper, mints the owner secret
+git push nomos main            # stock git; the credential helper answers the 401
+```
+
+Pushing `refs/heads/main` to an unborn workspace births it FROM YOUR REPO. The
+cloud replay-verifies the whole chain from genesis — contiguity, every intent
+re-admitted against the state folded from the chain prefix, every plan re-run
+and byte-compared — and re-derives your exact local verdict: same head, same
+plans. Valid ⇒ custody adopts your head BYTE-IDENTICAL (no re-seal), and
+sha256 of your push password becomes the owner credential. Invalid ⇒ archived
+under `refs/heads/refused/`, the workspace stays unborn, the verdict rides
+`githolon ws status <ws>`. The pushed bytes buy nothing; the chain proves
+itself. The git holon executes — and thus validates — itself.
+
+Why this matters: deployment is `git push`, the audit trail is `git log`, and
+"does the cloud agree with my machine?" is a checkable equation, not a hope.
+
+## Byte-identical wasm everywhere
+
+One `wasm32-wasip1` artifact runs in the cloud edge, the heavy container tier,
+your browser, your terminal, and the e2e. The same law, the same fold, the
+same admission gate — so a verdict computed anywhere is the verdict
+everywhere. The e2e's final convergence check (local head == canonical main)
+is only meaningful because both sides ran the same bytes.
+
+## Offline is enforced, not narrated
+
+`npm run e2e` doesn't claim offline-first — it traps `fetch` to THROW while it
+authors a write, routes a declared query, folds a mutate, projects a derived
+field, and reads a count, all locally. If any "local" path touched the
+network, the test fails. Then it restores fetch, syncs, and the cloud answers
+the same query. That trap is the honest definition of local-first: the network
+is for reconciliation only.
+
+## What to do with all this
+
+- Demo without wifi. Author, query, watch — then sync when it's back.
+- Treat the cloud as replaceable custody. Your ledger clones with stock git;
+  a holon minted from it locally verifies without asking anyone.
+- Audit by reading. Every commit is an intent envelope; `git log` in `holon/`
+  is the complete, verifiable history of the workspace.
+
+Back to the [README](../README.md) — or start reshaping
+`domains/guestbook.ts` ([02-authoring.md](./02-authoring.md)).

package/template/domains/guestbook.ts

@@ -12,8 +12,8 @@
  *   * a DERIVED read field (engine-projected, PURE fn of the folded fields);
  *   * a COUNT (a maintained tally, grouped by a field).
  */
-import { z } from "zod";
 import {
+  z,
   aggregate,
   t,
   Lww,

package/template/package.json

@@ -10,12 +10,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@githolon/dsl": "^0.1.0",
-    "@githolon/client": "^0.1.0",
+    "@githolon/dsl": "^0.2.0",
+    "@githolon/client": "^0.2.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "githolon": "^0.1.2",
+    "githolon": "^0.2.0",
     "@types/node": "^25.9.2",
     "tsx": "^4.19.2",
     "typescript": "^5.6.3"

package/template/test/e2e.mts

@@ -6,6 +6,8 @@
 //   TYPED declared query routes LOCALLY → sync + edge admission → the CLOUD's
 //   declared query returns the entry.
 //
+// docs/03-client.md explains every call here.
+//
 // Run from this directory AFTER `npx nomos-compile`:  npx tsx test/e2e.mts
 import { readFileSync } from "node:fs";
 import { connect } from "@githolon/client";
@@ -70,11 +72,14 @@ if (!(entries.length === 1 && entries[0]!.data.message === "hello from the edge
 const entryId = entries[0]!.id;
 ok(`typed declared query routes — entriesByAuthor → ${entryId} (mood: ${entries[0]!.data.mood})`);
 
-// 5. typed mutate + typed by-id read (SetEntry map-put folds locally)
-await app.reactToEntry({ entryId, reactor: "bob", reaction: "love", reactedAt: new Date().toISOString() });
+// 5. typed mutate + typed by-id read (SetEntry map-put folds locally).
+//    `reactedAt` is OMITTED — the generated client auto-stamps `…At` payload fields
+//    with ISO now() at dispatch (caller-side, so the plan stays pure).
+await app.reactToEntry({ entryId, reactor: "bob", reaction: "love" });
 const after = await app.guestbookEntryById(entryId);
 if (after[0]!.data.reactions?.bob !== "love") fail(`typed mutate/read: ${JSON.stringify(after)}`);
-ok("typed mutate folds — reactions map shows bob → love locally");
+if (!/^\d{4}-\d{2}-\d{2}T/.test(after[0]!.data.updatedAt ?? "")) fail(`auto-stamped reactedAt did not fold into updatedAt: ${JSON.stringify(after[0]!.data)}`);
+ok("typed mutate folds — reactions map shows bob → love locally (reactedAt auto-stamped by the client)");
 
 // 5b. DERIVED read field: the engine projects moodEmoji from the law's pure fn
 if (after[0]!.data.moodEmoji !== "🤩") fail(`derived moodEmoji not projected locally: ${JSON.stringify(after[0]!.data)}`);
@@ -88,8 +93,9 @@ ok("declared count maintained locally — entriesPerMood('delighted') = 1");
 globalThis.fetch = realFetch;
 ok("offline proof ENFORCED — fetch was trapped: local write/query/mutate/count touched no network");
 
-// 6. sync: push the session branch + edge admission merges to main
-const s = await holon.sync({ admit: true });
+// 6. sync: push the session branch + edge admission merges to main.
+//    Bare sync() IS the whole loop — admit defaults to true.
+const s = await holon.sync();
 if (!s.admission?.ok) fail(`sync/admit: ${JSON.stringify(s)}`);
 const admitted = (s.admission.sessions || []).flatMap((x: { admitted?: unknown[] }) => x.admitted || []);
 if (admitted.length < 2) fail(`edge admitted ${admitted.length} intent(s), expected 2: ${JSON.stringify(s.admission)}`);
@@ -117,8 +123,8 @@ const taggerA = await connect({ cloud: CLOUD, workspace: WS, clientId: "tagger-a
 const taggerB = await connect({ cloud: CLOUD, workspace: WS, clientId: "tagger-b" });
 await guestbookClient(taggerA).tagEntry({ entryId, tags: ["vegan"] });
 await guestbookClient(taggerB).tagEntry({ entryId, tags: ["gluten-free"] });
-await taggerA.sync({ admit: true });
-await taggerB.sync({ admit: true });
+await taggerA.sync();
+await taggerB.sync();
 d = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/aggregates/${encodeURIComponent(entryId)}`)).json();
 const mergedTags: string[] = d.rows?.[0]?.data?.tags ?? [];
 if (!(mergedTags.includes("vegan") && mergedTags.includes("gluten-free"))) fail(`AddWins union lost an add: ${JSON.stringify(mergedTags)}`);
@@ -133,4 +139,53 @@ const remoteMain = (refsAdv.match(/([0-9a-f]{40}) refs\/heads\/main/) || [])[1];
 if (head !== remoteMain) fail(`not converged in place: local ${head?.slice(0, 10)} vs main ${remoteMain?.slice(0, 10)}`);
 ok("converged in place — local head == canonical main, no reconnect");
 
-console.log(`\nALL GREEN — typed client: compile → deploy → connect → typed write/query/mutate/derive/count → admit → converge → cloud reads (${WS})`);
+// 11. WATCH — the local reactive read: watchById polls the LOCAL projection and fires
+//     the callback whenever the row changes (purely local — no network, no server push
+//     to wait on). A typed mutate lands; the watcher sees it.
+const watched: Record<string, unknown>[] = [];
+const stopWatch = holon.watchById(entryId, (rows) => { watched.push(rows[0]?.data ?? {}); }, { intervalMs: 50 });
+await app.reactToEntry({ entryId, reactor: "carol", reaction: "wow" });
+const sawReaction = async () => {
+  for (let i = 0; i < 100; i++) {
+    if (watched.some((dd) => (dd.reactions as Record<string, unknown> | undefined)?.carol === "wow")) return true;
+    await new Promise((res) => setTimeout(res, 50));
+  }
+  return false;
+};
+if (!(await sawReaction())) fail(`watchById never observed carol's reaction: ${JSON.stringify(watched.at(-1))}`);
+stopWatch(); // the returned stop() ends the polling — no leaked timers
+ok("watchById fires on change — typed mutate observed reactively (carol → wow), watcher stopped");
+await holon.sync(); // ride carol's reaction to main so the ledger ends converged
+
+// 12. DEAD-LETTER QUEUE — refused work is NEVER lost. The honest jam: a user's client
+//     on a FRESH workspace installs a domain LOCALLY (offline-first — the edge has no
+//     such law) and does real work under it. On sync the edge cannot certify that law:
+//     a DOMAIN rejection PARKS the intent — full provenance, durable, rides
+//     export()/restore — it does not vanish. (A directive whose domain isn't in YOUR
+//     law refuses at dispatch time, loudly — only committed-then-refused work parks.)
+const WS2 = WS + "-dlq";
+d = await (await fetch(`${CLOUD}/v1/workspaces/${WS2}`, { method: "POST", headers: { "x-nomos-principal": "nomos-e2e-suite" } })).json();
+if (!d.ok) fail(`create DLQ workspace: ${JSON.stringify(d)}`);
+const jammed = await connect({ cloud: CLOUD, workspace: WS2, clientId: "jammed-user" });
+await jammed.dispatch("nomos", "installDomain", {
+  domainHash: GUESTBOOK_DOMAIN_HASH, packageUsda: deploy.packageUsda, installedBy: "local-user",
+  authorityScope: "workspace/root", dependencies: [], finalizers: [],
+}, { domainHash: d.controller.domainHash });
+await guestbookClient(jammed).signGuestbook({ author: "marta", message: "work I refuse to lose", mood: "happy", signedAt: new Date().toISOString() });
+const js = await jammed.sync();
+if (!(js.converged?.deadLettered ?? []).length) fail(`tenant write did not dead-letter: ${JSON.stringify(js.converged)}`);
+const dlq = await jammed.deadLetters();
+if (!(dlq.length === 1 && dlq[0]!.domain === "guestbook" && dlq[0]!.directiveId === "signGuestbook" && dlq[0]!.source === "edge")) {
+  fail(`DLQ provenance wrong: ${JSON.stringify(dlq)}`);
+}
+ok(`dead letter parked with provenance — ${dlq[0]!.domain}/${dlq[0]!.directiveId} refused by ${dlq[0]!.source}, work NOT lost`);
+// THE RETRY LANE (not run here — see test/dlq.e2e.mjs in the nomos2 repo for the full
+// unjam): the domain dev deploys the law fix (`POST /v1/workspaces/:ws/domains`, secret-
+// gated), then `retryDeadLetter(id)` — or the owner's `POST /dead-letters/retry` — lands
+// the parked write on main. Here the app makes the OTHER explicit choice:
+const dropped = await jammed.discardDeadLetter(dlq[0]!.id ?? dlq[0]!.oid);
+if (!(dropped.ok && dropped.removed === 1)) fail(`discard: ${JSON.stringify(dropped)}`);
+if ((await jammed.deadLetters()).length !== 0) fail("DLQ not drained after discard");
+ok("discardDeadLetter drains the queue — the APP's explicit choice, never the runtime's");
+
+console.log(`\nALL GREEN — typed client: compile → deploy → connect → typed write/query/mutate/derive/count → admit → converge → watch → dead-letter custody → cloud reads (${WS})`);