create-githolon 0.5.1 → 0.7.0

package/index.mjs

@@ -55,9 +55,16 @@ cpSync(TEMPLATE, targetDir, { recursive: true });
 // and the scaffold restores the dot.
 renameSync(path.join(targetDir, "gitignore"), path.join(targetDir, ".gitignore"));
 
-for (const f of ["package.json", "README.md"]) {
+// Parameterize the scaffold to the app name. The generated typed client + its baked
+// hash const are NAMED off the package name (`__APP_NAME__`): the artifact filename
+// keeps the raw name (build/<app>.client.ts), the hash SYMBOL normalizes it to
+// UPPER_SNAKE (the same transform `githolon compile` uses — see codegen_ts.ts). The
+// client FACTORY (`todoClient`) is named off the DOMAIN key, which stays `todo`.
+const appHash = `${appName.replace(/[-\s]+/g, "_").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase()}_DOMAIN_HASH`;
+const subst = (s) => s.replaceAll("__APP_NAME__", appName).replaceAll("__APP_HASH__", appHash);
+for (const f of ["package.json", "README.md", "nomos.package.mjs", "domains/todo.ts", "test/e2e.mts"]) {
   const p = path.join(targetDir, f);
-  writeFileSync(p, readFileSync(p, "utf8").replaceAll("__APP_NAME__", appName), "utf8");
+  if (existsSync(p)) writeFileSync(p, subst(readFileSync(p, "utf8")), "utf8");
 }
 
 const git = (cmd) => spawnSync("git", cmd, { cwd: targetDir, stdio: "ignore" }).status === 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.5.1",
+  "version": "0.7.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

@@ -24,7 +24,7 @@ real workspace afterwards.
 
 ```bash
 npx githolon ws create <ws>   # births a fresh workspace on your identity; SAVES its one-time secret to ~/.holon
-npx githolon deploy <ws>      # POSTs build/guestbook.deploy.json with the stored secret
+npx githolon deploy <ws>      # POSTs build/__APP_NAME__.deploy.json with the stored secret
 npm run e2e                # the full loop, live: offline write → sync → admission → cloud query
 ```
 
@@ -55,14 +55,14 @@ git just works against the cloud.)
 
 ## Make it YOURS — the five-minute walkthrough
 
-The starter is the tutorial; this is the exact path from guestbook to your own law.
+The starter is the tutorial; this is the exact path from the todo list to your own law.
 
 1. **Rename the law file** and reshape it:
-   `git mv domains/guestbook.ts domains/<yours>.ts` — keep the patterns
-   (aggregate fields each tagged a merge driver; an optional DECLARED INVARIANT
-   on the aggregate — the guestbook's max-10-tags rule shows the shape, judged
-   post-fold at the one gate with a typed refusal; directives = zod payload →
-   pure plan; `addToSet` for AddWins sets — `set()` on a set field is refused).
+   `git mv domains/todo.ts domains/<yours>.ts` — keep the patterns
+   (aggregate fields each tagged a merge driver — `Lww` scalar, `AddWins` set;
+   directives = zod payload → pure plan; `addToSet` for AddWins sets — `set()` on
+   a set field is refused; `done` is a 2-value Lww enum because there is no
+   `t.bool()`; sharing is one native Zanzibar tuple via `writeTuple`).
 2. **Point the compile config at it** — `nomos.package.mjs`:
    ```js
    export default { name: "<pkg>", domains: [{ key: "<pkg>", modules: ["./domains/<yours>.ts"] }] };
@@ -83,13 +83,15 @@ The starter is the tutorial; this is the exact path from guestbook to your own l
    reference until it's clean.
 5. **Prove it live:** `npm run e2e` — your law deploys to a throwaway workspace,
    an offline write syncs through admission, the cloud answers your declared
-   query and count, and two blind clients prove the AddWins merge.
+   query and count, and one native sharing tuple is recorded. (Prove it OFFLINE
+   first with `npx githolon proof` — the generated proof on a local holon, no
+   cloud.)
 
 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. Six short
+`docs/` travels with you — offline, like everything else here. Seven short
 pages, each under a screen and a half:
 
 1. [The mental model](./docs/01-mental-model.md) — holons, content-addressed
@@ -107,18 +109,22 @@ pages, each under a screen and a half:
 6. [Evolving law](./docs/06-law-evolution.md) — what's safe to change once
    real data exists (add freely; rename/retype honestly), the era rule, and
    the one trap: old clients after a breaking upgrade.
+7. [Security](./docs/07-security.md) — private aggregates (`requires(cap)` +
+   grant/revoke, the holon gates its own reads) and operator-blind E2E
+   encrypted fields (`.encrypted()`, the key handshake, `githolon decrypt`).
 
 ## What's here
 
-- `docs/` — the six 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>`.
+- `docs/` — the seven pages above; the offline reference.
+- `domains/todo.ts` — the starter domain (the law): a shared, offline-first todo
+  list — two aggregates, the directives, a declared query, a where-filtered count,
+  and one native Zanzibar sharing tuple. Rename it, reshape it, or add domains
+  with `npx githolon generate domain <name>`.
 - `nomos.package.mjs` — the compile config (module list per domain key; reads
   are auto-discovered from exports).
-- `build/guestbook.client.ts` — GENERATED typed TS client (payload types from
+- `build/__APP_NAME__.client.ts` — GENERATED typed TS client (payload types from
   the engine's zod, read models from the field kinds, the law hash baked in).
-- `build/guestbook.proof.mts` — GENERATED runnable proof, synthesized from your
+- `build/__APP_NAME__.proof.mts` — GENERATED runnable proof, synthesized from your
   own directives/queries/counts on every compile; `npx githolon proof` runs it.
 - `test/e2e.mts` — proves compile → deploy → typed offline write/query →
   edge admission → cloud declared query, against the live cloud.

package/template/docs/02-authoring.md

@@ -4,7 +4,7 @@ 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 the core patterns below; reshape it.
+`domains/todo.ts` demonstrates the core patterns below; reshape it.
 
 ## Aggregates: typed fields, each tagged a merge driver
 

package/template/docs/03-client.md

@@ -7,10 +7,10 @@ is the map.
 
 ```ts
 import { connect } from "@githolon/client";
-import { guestbookClient } from "../build/guestbook.client.ts";
+import { todoClient } from "../build/<app>.client.ts";
 
 const holon = await connect({ cloud, workspace, clientId });
-const app = guestbookClient(holon);
+const app = todoClient(holon);
 ```
 
 `connect` pulls the wasm, the workspace manifests, and the ledger, then runs

package/template/docs/05-superpowers.md

@@ -63,4 +63,4 @@ is for reconciliation only.
   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)).
+`domains/todo.ts` ([02-authoring.md](./02-authoring.md)).

package/template/docs/07-security.md

@@ -0,0 +1,176 @@
+# Security: private reads & operator-blind encryption
+
+Two opt-in layers, both e2e-proven, both **era-ruled** — a domain that uses
+neither pays nothing, and a chain sealed before these features replays
+byte-identically forever. You add them field by field; nothing else changes.
+
+The throughline: **the githolon enforces its own access**. Not the host, not a
+server's `if (user.canRead)` — the same byte-identical wasm gate every peer runs.
+A read you aren't entitled to is refused by the holon itself, on every replica.
+
+## Layer 1 — private aggregates: the holon gates its own reads
+
+Make a type private and a read touching it is served only to a principal the
+workspace **granted** the capability. `role ≡ cap` in v1 — the role you grant is
+the cap a read requires.
+
+```ts
+import {
+  aggregate, t, Lww, requires, userPermissionAggregate, grant, revoke, directive, query, z,
+} from "@githolon/dsl";
+
+// PUBLIC — anyone reads (the control: privacy must not change how public serves).
+export const Announcement = aggregate("Announcement", { text: t.string().merge(Lww) });
+
+// PRIVATE — a read of Note needs the `readNote` cap.
+export const Note = aggregate("Note",
+  { owner: t.string().merge(Lww), body: t.string().merge(Lww) },
+  { visibility: requires("readNote") });
+
+// The framework permission aggregate — EXPORT it, so grants fold into THIS chain
+// (the bindings the read gate reads). Forgetting this is the #1 mistake.
+export const UserPermission = userPermissionAggregate;
+
+// The owner bestows the cap on a reader. Authored through the secret-gated
+// `/author` lane (or `githolon author`) — only the owner can grant.
+export const grantReader = directive("grantReader").ensures(UserPermission)
+  .payload(z.object({ principal: z.string(), grantedBy: z.string(), grantedAt: z.string() }))
+  .plan((p) => grant({
+    userId: p.principal, scope: ["workspace", "notes"], role: "readNote",
+    grantedBy: p.grantedBy, grantedAt: p.grantedAt,
+  }));
+
+// Revoke flips that same binding to status:revoked (forward-only, remove-wins).
+export const revokeReader = directive("revokeReader").ensures(UserPermission)
+  .payload(z.object({
+    principal: z.string(), grantedBy: z.string(), grantedAt: z.string(),
+    revokedBy: z.string(), revokedAt: z.string(),
+  }))
+  .plan((p) => revoke({
+    userId: p.principal, scope: ["workspace", "notes"], role: "readNote",
+    grantedBy: p.grantedBy, grantedAt: p.grantedAt, revokedBy: p.revokedBy, revokedAt: p.revokedAt,
+  }));
+
+export const notesByOwner = query("notesByOwner").key("owner").returns(Note); // inherits the gate
+```
+
+How it behaves:
+
+- **Who decides.** The read gate runs in the wasm against the workspace's own
+  folded role-bindings — never the host. Every peer (the cloud edge included)
+  re-derives the same verdict.
+- **Two grains.** *Granular* reads (`query`, `queryById`) need the **specific**
+  cap. *Bulk* reads — cloning `main`, `snapshot`, `count`, `sum` — need **any**
+  declared cap and reveal everything (pulling `main` hands over the whole ledger;
+  that's the deal). A fully public workspace clones openly, as before.
+- **Who you are.** A read carries the principal (an `x-nomos-auth` token, verified;
+  or the transitional `x-nomos-principal`). No principal ⇒ a private read is
+  refused, fail-closed.
+- **Revocation is honest.** Remove-wins: a revoked principal can never be
+  re-granted by a replayed grant. The post-revoke read re-derives authority from
+  the maintained projection — cost scales with the number of *identities*, not
+  your data volume (revoking one reader over 10k private records stays fast).
+
+The owner grants through the secret-gated lane; your end-user app carries **no
+secret** — its writes are judged by edge admission, and it simply can't author a
+grant. Authority enters only through the owner.
+
+## Layer 2 — encrypted fields: operator-blind, end-to-end
+
+Mark a field `.encrypted()` and its value is sealed **on the client** before it
+ever reaches the cloud. The operator stores and serves ciphertext; only a
+key-holder can read it. This is RFC 9420-style group keys mapped onto the ledger:
+per-scope keys, distributed as on-chain wrapped-key events, revocation as
+forward-only key rotation.
+
+```ts
+import {
+  aggregate, t, Lww, requires, directive, create, query, z,
+  userPermissionAggregate, grant,
+  KeyScope, WrappedKey, advanceKeyEpoch, wrapKey, wrappedKeysByRecipient,
+} from "@githolon/dsl";
+
+export const Note = aggregate("Note",
+  { owner: t.string().merge(Lww), body: t.string().merge(Lww).encrypted() }, // body is E2E-encrypted
+  { visibility: requires("readNote") }); // .encrypted() REQUIRES a private aggregate (the cap is the scope)
+
+export const UserPermission = userPermissionAggregate;
+export const KS = KeyScope;            // the per-scope key head     — export so it folds
+export const WK = WrappedKey;          // the on-chain wrapped keys  — export so it folds
+export const advanceEpoch = advanceKeyEpoch; // the key rotation     — export so it routes
+export const wrap1 = wrapKey;
+export const wraps = wrappedKeysByRecipient;
+
+export const writeNote = directive("writeNote").creates(Note)
+  .payload(z.object({ owner: z.string(), body: z.string() })) // `body` is the PRE-SEALED envelope
+  .plan((p) => { create(Note).set("owner", p.owner).set("body", p.body); return []; });
+
+export const grantReader = directive("grantReader").ensures(UserPermission)
+  .payload(z.object({ principal: z.string(), grantedBy: z.string(), grantedAt: z.string() }))
+  .plan((p) => grant({ userId: p.principal, scope: ["workspace", "w"], role: "readNote",
+                       grantedBy: p.grantedBy, grantedAt: p.grantedAt }));
+
+export const notesByOwner = query("notesByOwner").key("owner").returns(Note);
+```
+
+`.encrypted()` is only legal on a **private** (`requires(cap)`) aggregate — the
+cap *is* the encryption scope — and only on an **Lww-class** field (the value is
+a ciphertext envelope replaced wholesale). `githolon compile` refuses otherwise,
+naming the fix.
+
+### The handshake (operator-blind)
+
+The cloud never sees a key or a plaintext. The dance:
+
+1. **The reader makes a device key.** An X25519 keypair (`cryptoKeygen`); the
+   secret stays on the device, the public key is published.
+2. **The owner grants the cap** (`grantReader`) — opens the read gate *and* adds
+   the reader to the scope's key roster.
+3. **The owner advances the epoch** (`advanceKeyEpoch`), wrapping the scope key
+   to every member's public key (computed client-side, `cryptoWrapKey`). The
+   fan-out gate verifies the wraps cover exactly the surviving roster — no missing
+   member (lost access), no extra (a leak).
+4. **The author seals the field** — resolve the `(type, field)` stable ids from
+   the law, `crypto_seal_field` with the scope key → an envelope, write the
+   envelope as the field value.
+5. **The reader unwraps and reads** — `cryptoUnwrapKey` with the device secret
+   recovers the scope key; inject it on the read and the field comes back
+   decrypted. Without the key it stays an opaque envelope.
+
+A standalone proof of the whole loop ships as a dev tool:
+
+```bash
+githolon decrypt <ws> --as <principal> --secret <b64> --query notesByOwner
+```
+
+It clones the ledger, unwraps that principal's scope keys from the on-chain
+wrapped keys, and runs the query **decrypted** — the operator-blind ledger is
+plaintext only to a key-holder, and this proves it as that holder.
+
+### What to keep in mind
+
+- **Revocation is forward-only.** Removing a reader advances the epoch and
+  re-wraps to the survivors; old ciphertext is *not* re-encrypted. A removed
+  member can still read what they were already shown — "no new reads" is the only
+  honest semantic over an append-only log.
+- **Metadata is public.** Who is a member, how many, ciphertext sizes, write
+  timing, and any plaintext field you `count` / `sum` / index *by* — all visible.
+  Encrypt the secret value, not the thing you group by.
+- **Renames are safe.** The envelope carries the field's stable id, so renaming
+  an encrypted field (or its aggregate) keeps old ciphertext decryptable under the
+  new label. A true removal or retype still needs the evolve-gate dispositions
+  (see `06-law-evolution.md`).
+- **Never write plaintext into an encrypted field.** The gate refuses anything
+  that isn't a valid envelope sealed to the declared slot.
+- **Ergonomics today.** The generated client types the payloads but does not yet
+  seal/unwrap for you — drive the seal and the key injection through the holon's
+  crypto ops (the reference flow is small; ask if you want a helper wired into the
+  generated client).
+
+## Defense in depth, not a panic button
+
+Per-scope keys mean a client only ever *holds* keys for scopes it may read — so
+leaking your own authorized view is harmless, and holding a key for data you were
+never granted simply can't happen. A device keystore (non-extractable WebCrypto on
+web, the OS keystore on native) is real hardening on top, but the load-bearing
+guarantee is the key scoping, not the enclave.

package/template/domains/todo.ts

@@ -0,0 +1,85 @@
+/**
+ * __APP_NAME__ — a shared, offline-first todo list. The smallest domain that shows the
+ * magic: two people edit the SAME list while BOTH offline, blind to each other, and
+ * converge byte-identically when they sync — because the merge is the LAW (kernel-folded
+ * CRDT), not the app's job. You write only aggregates + directives; the engine does the
+ * rest. Rename it, add fields, add directives — it's yours from the first byte.
+ */
+import {
+  z, aggregate, t, Lww, AddWins, directive, create, instance, set, addToSet,
+  query, count, writeTuple, RelationTuple, relateSubject, relationTuplesByObject,
+} from "@githolon/dsl";
+
+// A todo is open or done. (There is no t.bool() — model a flag as a 2-value Lww enum.)
+const DONE = ["open", "done"] as const;
+
+// ── what we store ─────────────────────────────────────────────────────────────
+export const TodoList = aggregate("TodoList", {
+  title: t.string().merge(Lww), // last writer wins
+});
+
+export const Todo = aggregate("Todo", {
+  listId: t.string().merge(Lww),       // which list this todo is on (the query key)
+  text: t.string().merge(Lww),         // last writer wins
+  done: t.enum(DONE).merge(Lww),       // last writer wins
+  tags: t.set(t.string()).merge(AddWins), // concurrent taggers UNION — nobody's tag is lost
+});
+
+// Re-export the framework's Zanzibar tuple aggregate so its events fold into THIS
+// chain. relateSubject (an `.ensures(RelationTuple)` directive) is what marks the
+// tuple an ensured type, which shareList's tuple write below needs.
+export { RelationTuple, relateSubject };
+
+// ── what people do (directives PLAN ops; the sealed engine replays them) ────────
+export const createList = directive("createList")
+  .creates(TodoList) // Nomos MINTS the id — callers never supply one
+  .payload(z.object({ title: z.string().min(1) }))
+  .plan((p) => { create(TodoList).set("title", p.title); return []; });
+
+export const addTodo = directive("addTodo")
+  .creates(Todo)
+  .payload(z.object({ listId: z.string().min(1), text: z.string().min(1) }))
+  .plan((p) => {
+    create(Todo).set("listId", p.listId).set("text", p.text).set("done", "open");
+    return [];
+  });
+
+export const renameTodo = directive("renameTodo")
+  .mutates(Todo)
+  .payload(z.object({ todoId: z.string(), text: z.string().min(1) }))
+  .plan((p) => [set(instance(Todo, p.todoId), "text", p.text)]);
+
+// The caller decides open↔done and rides it IN the payload (a plan is pure — no clock,
+// no random). Concurrent toggles are Lww: the later HLC wins, and both peers converge.
+export const toggleTodo = directive("toggleTodo")
+  .mutates(Todo)
+  .payload(z.object({ todoId: z.string(), done: z.enum(DONE) }))
+  .plan((p) => [set(instance(Todo, p.todoId), "done", p.done)]);
+
+// addToSet is the ONLY additive write to an AddWins set (set() would overwrite).
+export const tagTodo = directive("tagTodo")
+  .mutates(Todo)
+  .payload(z.object({ todoId: z.string(), tags: z.array(z.string()).min(1) }))
+  .plan((p) => [addToSet(instance(Todo, p.todoId), "tags", p.tags)]);
+
+// Sharing = ONE native Zanzibar tuple: TodoList:<id>#<role>@user:<user>.
+export const shareList = directive("shareList")
+  .ensures(RelationTuple)
+  .payload(z.object({
+    listId: z.string().min(1), userId: z.string().min(1),
+    role: z.enum(["editor", "viewer"]), sharedBy: z.string().min(1), sharedAt: z.string(),
+  }))
+  .plan((p) => writeTuple({
+    object: `TodoList:${p.listId}`, relation: p.role, subject: `user:${p.userId}`,
+    grantedBy: p.sharedBy, grantedAt: p.sharedAt,
+  }));
+
+// ── what people read (auto-discovered by shape; routed to every peer) ───────────
+export const todosByList = query("todosByList").key("listId").returns(Todo);
+
+// An O(1) maintained tally: how many todos are still open, per list.
+export const openTodosByList = count("openTodosByList")
+  .of(Todo).where((p) => p.field("done").eq("open")).by("listId");
+
+// The raw sharing tuples for a list — the audit surface (re-exported so it routes here).
+export { relationTuplesByObject };

package/template/nomos.package.mjs

@@ -1,9 +1,10 @@
-// The holon-compile config: one package, one domain, one module file.
-// Read-side declarations (queries/counts/...) are auto-discovered from the
-// module's exports by shape — nothing to wire here.
+// The githolon-compile config: one package, one domain, one module file.
+// Read-side declarations (the query + the count) are auto-discovered from the
+// module's exports by shape — nothing to wire here. The framework RelationTuple
+// aggregate + its relationTuplesByObject query are pulled in by todo.ts's re-exports.
 // Building a Flutter app too? Add `dart: true` for the typed Dart frontend
 // (build/dart/) alongside the TS client.
 export default {
-  name: "guestbook",
-  domains: [{ key: "guestbook", modules: ["./domains/guestbook.ts"] }],
+  name: "__APP_NAME__",
+  domains: [{ key: "todo", modules: ["./domains/todo.ts"] }],
 };

package/template/test/e2e.mts

@@ -1,23 +1,25 @@
-// E2E: the FULL friend loop against a LIVE Nomos Cloud, driven through the
-// GENERATED TYPED CLIENT (`build/guestbook.client.ts` — emitted by nomos-compile):
+// E2E: the FULL loop against a LIVE Nomos Cloud, driven through the GENERATED TYPED
+// CLIENT (`build/__APP_NAME__.client.ts` — emitted by githolon compile):
 //
 //   compile → create workspace → deploy (package + manifest overlay, ONE POST) →
-//   web client connects → TYPED dispatch signGuestbook LOCALLY (offline write) →
-//   TYPED declared query routes LOCALLY → sync + edge admission → the CLOUD's
-//   declared query returns the entry.
+//   web client connects → TYPED createList + addTodo LOCALLY (offline writes) →
+//   sync + edge admission → the CLOUD's declared query + count return the work.
 //
 // The docs travel with you, offline: docs/01-mental-model.md first, then
 // docs/03-client.md explains every call here. This file is the NARRATED
-// walkthrough you reshape by hand; its GENERATED sibling — build/<name>.proof.mts,
+// walkthrough you reshape by hand; its GENERATED sibling — build/__APP_NAME__.proof.mts,
 // emitted by every compile from your own law — needs no rewriting: `githolon proof`.
 //
-// Run from this directory AFTER `npx nomos-compile`:  npx tsx test/e2e.mts
+// The OFFLINE convergence proof (two peers, blind edits, byte-identical sync, no cloud)
+// lives in test/convergence.local.mjs:  node test/convergence.local.mjs
+//
+// Run from this directory AFTER `npx githolon compile`:  npx tsx test/e2e.mts
 import { readFileSync } from "node:fs";
 import { connect } from "@githolon/client";
-import { guestbookClient, GUESTBOOK_DOMAIN_HASH } from "../build/guestbook.client.ts";
+import { todoClient, __APP_HASH__ } from "../build/__APP_NAME__.client.ts";
 
 const CLOUD = (process.env.NOMOS_CLOUD || "https://nomos.captainapp.co.uk").replace(/\/+$/, "");
-const WS = process.env.NOMOS_WS || "gb-e2e-" + Math.random().toString(36).slice(2, 8);
+const WS = process.env.NOMOS_WS || "todo-e2e-" + Math.random().toString(36).slice(2, 8);
 
 // explicit annotation on the const so TS's never-call narrowing applies after fail(...)
 // IDENTITY NOTE: this proof uses the bare x-nomos-principal lane so the test is
@@ -26,169 +28,87 @@ const WS = process.env.NOMOS_WS || "gb-e2e-" + Math.random().toString(36).slice(
 const fail: (m: string) => never = (m) => { console.error("✗ " + m); process.exit(1); };
 const ok = (m: string) => console.log("✓ " + m);
 
-const deploy = JSON.parse(readFileSync(new URL("../build/guestbook.deploy.json", import.meta.url), "utf8"));
+const deploy = JSON.parse(readFileSync(new URL("../build/__APP_NAME__.deploy.json", import.meta.url), "utf8"));
 
-// 1. create the workspace (capture the ONE-TIME secret) + deploy WITH the secret
+// 1. create the workspace (capture the ONE-TIME secret)
 let r = await fetch(`${CLOUD}/v1/workspaces/${WS}`, { method: "POST", headers: { "x-nomos-principal": "nomos-e2e-suite" } });
 let d = await r.json();
 if (!d.ok) fail(`create workspace: ${JSON.stringify(d)}`);
 const SECRET: string = d.workspaceSecret;
 if (!SECRET?.startsWith("nws_v1_")) fail(`no workspaceSecret returned: ${JSON.stringify(d)}`);
-ok(`workspace ${WS} created — controller ${d.controller.domainHash.slice(0, 12)}…, secret ${SECRET.slice(0, 10)}…`);
+ok(`workspace ${WS} created — controller ${d.controller.domainHash.slice(0, 12)}…`);
 
 // ownership: a deploy WITHOUT the secret must be refused
 r = await fetch(`${CLOUD}/v1/workspaces/${WS}/domains`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(deploy) });
 if (r.status !== 401) fail(`unauthenticated deploy was not refused (got ${r.status})`);
 ok("ownership — deploy without the workspace secret refused (401)");
 
+// deploy WITH the secret. The generated client's baked hash IS the deployed law's hash.
 r = await fetch(`${CLOUD}/v1/workspaces/${WS}/domains`, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${SECRET}` }, body: JSON.stringify(deploy) });
 d = await r.json();
 if (!d.ok || d.installation?.[0]?.data?.["status.phase"] !== "Active") fail(`deploy: ${JSON.stringify(d)}`);
-// The generated client's baked hash IS the deployed law's content hash — same compile.
-if (d.domainHash !== GUESTBOOK_DOMAIN_HASH) fail(`deploy hash ${d.domainHash} != generated client's ${GUESTBOOK_DOMAIN_HASH}`);
-ok(`guestbook deployed Active — ${GUESTBOOK_DOMAIN_HASH.slice(0, 12)}… (baked into the typed client)`);
+if (d.domainHash !== __APP_HASH__) fail(`deploy hash ${d.domainHash} != generated client's ${__APP_HASH__}`);
+ok(`law deployed Active — ${__APP_HASH__.slice(0, 12)}… (baked into the typed client)`);
 
-// 2. connect + bind the TYPED client (zero-import generated file, structural holon)
-const holon = await connect({ cloud: CLOUD, workspace: WS, clientId: "guest-1" });
-const app = guestbookClient(holon);
+// 2. connect a web client (pulls wasm + manifests + ledger) and bind the typed surface
+const holon = await connect({ cloud: CLOUD, workspace: WS, clientId: "owner-1" });
+const app = todoClient(holon);
 ok(`web client connected — typed client bound (replica ${holon.replica.slice(0, 6)}…)`);
 
-let rows = await holon.queryById(`domain-installation:${GUESTBOOK_DOMAIN_HASH}`);
-if (!(rows.length && rows[0].data["status.phase"] === "Active")) fail("local replay: guestbook not Active locally");
-ok("local replay — guestbook law Active in the local projection");
-
-// 3. LOCAL-FIRST write through the TYPED surface: payload shape + enum are compile-checked
-const signedAt = new Date().toISOString();
-// THE OFFLINE PROOF IS ENFORCED, not narrated: while we author/query/count
-// LOCALLY, fetch THROWS — if any "local" path touched the network, this test fails.
+// 3. LOCAL-FIRST writes — ENFORCED offline (fetch is trapped; any network touch fails).
 const realFetch = globalThis.fetch;
 globalThis.fetch = (() => { throw new Error("OFFLINE PROOF VIOLATED: local authoring touched the network"); }) as typeof fetch;
 
-await app.signGuestbook({ author: "ada", message: "hello from the edge of the network", mood: "delighted", signedAt, tags: ["first-entry"] });
-ok("typed dispatch signGuestbook — offline write under the pulled law");
-
-// 4. the TYPED declared query routes LOCALLY; rows come back as Row<GuestbookEntryData>[]
-const entries = await app.entriesByAuthor({ author: "ada" });
-if (!(entries.length === 1 && entries[0]!.data.message === "hello from the edge of the network")) {
-  fail(`local typed query: ${JSON.stringify(entries)}`);
-}
-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).
-//    `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)}`);
-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)}`);
-ok("derived field projects locally — moodEmoji 🤩 (engine-computed, never in the ledger)");
-
-// 5c. DECLARED COUNT: the maintained O(1) tally, typed accessor, local projection
-const localCount = await app.entriesPerMood("delighted");
-if (localCount !== 1) fail(`local declared count: ${localCount}`);
-ok("declared count maintained locally — entriesPerMood('delighted') = 1");
+// A directive returns the new local HEAD (a string). Aggregate ids are MINTED by the
+// engine — read them back from the declared query. `addTodo.listId` is a plain string
+// the app chooses (the grouping key), so we don't need createList's minted id to wire
+// todos to a list — we just key both on the same `listId`.
+const listId = "list-launch-plan";
+await app.createList({ title: "Launch plan" });
+await app.addTodo({ listId, text: "Draft the deck" });
+await app.addTodo({ listId, text: "Book the venue" });
+ok("typed offline writes — createList + 2 addTodo, under the pulled law");
+
+// the TYPED declared query routes LOCALLY; minted Todo ids come back on the rows
+const seeded = await app.todosByList({ listId });
+if (seeded.length !== 2) fail(`local query: expected 2 todos, got ${seeded.length}`);
+const t1 = seeded.find((row) => row.data.text === "Draft the deck")!.id;
+await app.toggleTodo({ todoId: t1, done: "done" });          // Lww enum — open ↔ done
+await app.tagTodo({ todoId: t1, tags: ["urgent", "q3"] });   // AddWins set
+ok(`read back a minted Todo id (${t1.slice(0, 16)}…) → toggled done + tagged`);
+
+const localOpen = await app.openTodosByList(listId);
+if (localOpen !== 1) fail(`local count: expected 1 open, got ${localOpen}`);
+ok("local reads route — todosByList = 2, openTodosByList = 1 (2 todos − 1 done), no network");
 
 globalThis.fetch = realFetch;
-ok("offline proof ENFORCED — fetch was trapped: local write/query/mutate/count touched no network");
+ok("offline proof ENFORCED — fetch was trapped: local write/query/count touched no network");
 
-// 6. sync: push the session branch + edge admission merges to main.
-//    Bare sync() IS the whole loop — admit defaults to true.
+// 4. sync: push the session branch → edge admission merges to canonical main
 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)}`);
-ok(`synced — edge admission merged ${admitted.length} intents to main`);
-
-// 7. the CLOUD's declared query (read-manifest overlay, edge projection) returns the entry
-d = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/query?queryId=entriesByAuthor&params=${encodeURIComponent(JSON.stringify({ author: "ada" }))}`)).json();
-if (!(d.ok && d.rows.length === 1 && d.rows[0].data.reactions?.bob === "love")) {
-  fail(`cloud declared query: ${JSON.stringify(d)}`);
-}
-ok("cloud declared query returns the admitted entry WITH the admitted reaction — full loop closed");
-
-// 8. the EDGE projects the derived field + maintains the count too (same wasm, same law)
-d = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/aggregates/${encodeURIComponent(entryId)}`)).json();
-if (d.rows?.[0]?.data?.moodEmoji !== "🤩") fail(`edge derived projection: ${JSON.stringify(d.rows?.[0]?.data)}`);
-ok("derived field projects at the edge — moodEmoji 🤩");
-d = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/counts/entriesPerMood?group=delighted`)).json();
+ok("synced — session branch admitted onto canonical main");
+
+// 5. the CLOUD answers the declared query + the maintained count from canonical main
+d = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/query?queryId=todosByList&params=${encodeURIComponent(JSON.stringify({ listId }))}`)).json();
+if (!(d.ok && d.rows.length === 2)) fail(`cloud query: ${JSON.stringify(d)}`);
+ok("cloud query — todosByList returned both todos from canonical main");
+d = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/counts/openTodosByList?group=${encodeURIComponent(listId)}`)).json();
 if (!(d.ok && d.count === 1)) fail(`cloud count: ${JSON.stringify(d)}`);
-ok("cloud count endpoint — entriesPerMood[delighted] = 1 (O(1) maintained read)");
-
-// 9. CONCURRENCY — the canonical AddWins demo: two writers = two connect()s with
-//    DIFFERENT clientIds; each tags the same entry OFFLINE, blind to the other;
-//    admission merges both and the AddWins union keeps every add.
-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();
-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)}`);
-ok(`concurrent tags from two offline clients ALL survive the merge — [${[...mergedTags].sort().join(", ")}]`);
-
-// 10. CONVERGENCE: the ORIGINAL instance adopts canonical main — including the two
-//     taggers' admitted writes — inside a pull; no reconnect, no rebuild.
-await holon.pull();
-const head = await holon.head();
-const refsAdv = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/git/info/refs?service=git-upload-pack`)).text();
-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");
-
-// 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})`);
+ok("cloud count — openTodosByList = 1 (the where-filtered O(1) tally, maintained)");
+
+// 6. SHARING — one native Zanzibar tuple. Author it through the owner's secret-gated
+//    /author lane, then read it back from the cloud's audit query.
+r = await fetch(`${CLOUD}/v1/workspaces/${WS}/author`, {
+  method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${SECRET}` },
+  body: JSON.stringify({ domain: "todo", directiveId: "shareList", payload: {
+    listId, userId: "bob", role: "editor", sharedBy: "owner-1", sharedAt: new Date().toISOString() } }),
+});
+d = await r.json();
+if (!d.ok) fail(`shareList author: ${JSON.stringify(d)}`);
+d = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/query?queryId=relationTuplesByObject&params=${encodeURIComponent(JSON.stringify({ object: `TodoList:${listId}` }))}`)).json();
+const editor = (d.rows ?? []).find((u: { data: { relation: string } }) => u.data.relation === "editor");
+if (editor?.data?.subjects?.["user:bob"]?.status !== "active") fail(`sharing tuple not recorded: ${JSON.stringify(d)}`);
+ok("sharing — TodoList#editor@user:bob recorded as a native relation tuple (active)");
+
+console.log(`\nALL GREEN — typed client: compile → deploy → connect → typed offline writes → query/count → admit → cloud reads → native sharing (${WS})`);

package/template/domains/guestbook.ts

@@ -1,164 +0,0 @@
-/**
- * guestbook — the smallest complete Nomos tenant domain, written the only way a
- * domain is ever written: aggregates + directives on `@githolon/dsl`. No apply/fold/
- * merge code — the kernel owns folding; the directive plans ops, the sealed engine
- * replays them deterministically on every peer.
- *
- * What it shows:
- *   * an aggregate with Lww scalars, an AddWins set, and a MapOf(Lww) map;
- *   * a `.creates` directive (Nomos mints the aggregate id — never the caller);
- *   * a `.mutates` directive bound to an existing instance;
- *   * a declared, indexed read query (auto-discovered by `nomos-compile`);
- *   * a DERIVED read field (engine-projected, PURE fn of the folded fields);
- *   * a COUNT (a maintained tally, grouped by a field).
- */
-import {
-  z,
-  aggregate,
-  t,
-  Lww,
-  AddWins,
-  MapOf,
-  directive,
-  create,
-  instance,
-  set,
-  setEntry,
-  addToSet,
-  query,
-  derived,
-  count,
-  type DerivedDecl,
-  type CountDecl,
-} from "@githolon/dsl";
-
-// --- vocabulary ---------------------------------------------------------------
-
-export const ENTRY_MOODS = ["delighted", "happy", "neutral", "grumpy"] as const;
-
-// --- aggregate ----------------------------------------------------------------
-
-/** An entry may carry at most this many tags — the declared invariant's honest rule. */
-export const MAX_TAGS = 10;
-
-/**
- * One guestbook entry. The wire type `GuestbookEntry` is what readers key on.
- *
- * THE DECLARED AGGREGATE INVARIANT (#41 — declared invariants are REAL law): an
- * entry holds AT MOST {@link MAX_TAGS} tags. The kernel judges the POST-FOLD
- * snapshot at the ONE admission gate on every peer — a write that would leave
- * an entry over the limit refuses TYPED (`tags-exceed-limit:10`), offline and
- * on the edge alike. AddWins still merges concurrent adds; the invariant
- * bounds what any single admitted write may leave behind.
- */
-export const GuestbookEntry = aggregate(
-  "GuestbookEntry",
-  {
-    author: t.string().merge(Lww),
-    message: t.string().merge(Lww),
-    mood: t.enum(ENTRY_MOODS).merge(Lww),
-    signedAt: t.string().merge(Lww), // ISO-8601, caller-stamped
-    updatedAt: t.string().merge(Lww), // ISO-8601
-    /** Free-form additive tags — concurrent adds commute (AddWins). */
-    tags: t.set(t.string()).merge(AddWins),
-    /** Reactions keyed by reactor — per-key Lww, concurrent reactors commute. */
-    reactions: t.map(t.string()).merge(MapOf(Lww)),
-  },
-  {
-    invariant: (snap) => {
-      const tags = snap["tags"];
-      const n = Array.isArray(tags) ? tags.length : 0;
-      return n > MAX_TAGS ? { reject: `tags-exceed-limit:${MAX_TAGS}` } : { accept: true };
-    },
-  },
-);
-
-// --- directives ---------------------------------------------------------------
-
-/** Sign the guestbook: creates an entry (Nomos mints the id). */
-export const signGuestbook = directive("signGuestbook")
-  .creates(GuestbookEntry)
-  .payload(
-    z.object({
-      author: z.string().min(1),
-      message: z.string().min(1),
-      mood: z.enum(ENTRY_MOODS),
-      signedAt: z.string(), // ISO-8601
-      tags: z.array(z.string()).optional(),
-    }),
-  )
-  .plan((p) => {
-    const entry = create(GuestbookEntry);
-    entry
-      .set("author", p.author)
-      .set("message", p.message)
-      .set("mood", p.mood)
-      .set("signedAt", p.signedAt)
-      .set("updatedAt", p.signedAt);
-    for (const tag of p.tags ?? []) entry.add("tags", tag);
-    return [];
-  });
-
-/**
- * Tag an entry — the ADDITIVE set write. Two people tagging the SAME entry at
- * the SAME time both win: AddWins unions the adds, nothing is lost. (addToSet
- * is the ONLY additive write to an AddWins set — set() would overwrite, and is
- * refused at both the type level and runtime.)
- */
-export const tagEntry = directive("tagEntry")
-  .mutates(GuestbookEntry)
-  .payload(z.object({ entryId: z.string(), tags: z.array(z.string()).min(1) }))
-  .plan((p) => [addToSet(instance(GuestbookEntry, p.entryId), "tags", p.tags)]);
-
-/** React to an entry: a map-PUT at the reactor's key (concurrent reactors commute). */
-export const reactToEntry = directive("reactToEntry")
-  .mutates(GuestbookEntry)
-  .payload(
-    z.object({
-      entryId: z.string(),
-      reactor: z.string().min(1),
-      reaction: z.string().min(1),
-      reactedAt: z.string(), // ISO-8601
-    }),
-  )
-  .plan((p) => {
-    const entry = instance(GuestbookEntry, p.entryId);
-    return [
-      setEntry(entry, "reactions", p.reactor, p.reaction),
-      set(entry, "updatedAt", p.reactedAt),
-    ];
-  });
-
-// --- declared read queries (auto-discovered by nomos-compile) -------------------
-
-/** All entries by one author — an indexed probe, not a scan. */
-export const entriesByAuthor = query("entriesByAuthor").key("author").returns(GuestbookEntry);
-
-// --- derived read fields (engine-projected, PURE; NEVER stamped into the ledger) ---
-
-/** The mood → emoji rendering table — verbatim the {@link ENTRY_MOODS} vocabulary. */
-export const MOOD_EMOJI: Record<(typeof ENTRY_MOODS)[number], string> = {
-  delighted: "🤩",
-  happy: "😊",
-  neutral: "🙂",
-  grumpy: "😠",
-};
-
-/**
- * `GuestbookEntry.moodEmoji` — an ENGINE-PROJECTED DERIVED read field: a PURE fn of the
- * entry's folded `mood` (the {@link MOOD_EMOJI} table lookup; `"❔"` while `mood` is
- * still unfolded — partial folds are normal). Computed BY THE ENGINE during the
- * read-model projection and stored ONLY in the read model — never stamped into a kernel
- * op/event, so the ledger stays pure user-intents and the value is always re-derivable.
- * Exported INDIVIDUALLY at top level: both the engine bundle and `nomos-compile`
- * auto-discover it from the module exports by shape ({id, of, returns, fn}).
- */
-export const moodEmoji: DerivedDecl = derived("moodEmoji")
-  .of(GuestbookEntry)
-  .returns(z.string())
-  .as((a) => MOOD_EMOJI[a.mood as (typeof ENTRY_MOODS)[number]] ?? "❔");
-
-// --- counts (maintained tallies — O(1) reads, never a scan) ----------------------
-
-/** How many entries per mood — one maintained counter per distinct `mood` value. */
-export const entriesPerMood: CountDecl = count("entriesPerMood").of(GuestbookEntry).by("mood");