create-githolon 0.99.0 → 0.100.0

package/template/docs/04-cloud.md

@@ -1,78 +0,0 @@
-# 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
-
-**Deploy your law** (the cloud births the workspace by its parent's offer-effect):
-
-```bash
-npx githolon ws create <ws>   # birth; NO secret is minted — ownership is a law fact in the chain
-npx githolon deploy <ws>      # POST build/<pkg>.deploy.json, authenticated as your principal
-```
-
-A workspace is born ONLY by its PARENT authoring its birth (an offer-effect that records the
-child in the parent's own chain). There is no "push a repo to create a workspace" — pushing
-`refs/heads/main` to an unborn name is refused. You sync your work by pushing session branches
-(`refs/heads/session/<client-id>`) to an EXISTING workspace; child workspaces you author offline
-(e.g. an estate under a home in local custody) materialize on the cloud when you sync the parent.
-
-## Ownership
-
-There is no host secret. Ownership is a LAW FACT bound IN THE CHAIN — the principal the parent's
-birth records as the owner (e.g. `HomeOwner.principal`). Born-ness derives from custody (the ledger
-has a `main`); `/boot` returns no secret. DEPLOY write-authority is judged by the
-KERNEL at the offer gate — you authenticate as a principal the law grants deploy
-authority (`x-nomos-auth`, or transitionally `x-nomos-principal`), not a Bearer
-secret. End-user apps carry no credential: reads and session pushes are open,
-judged by edge admission; the session lane structurally refuses control-plane
-intents. So law only ever enters through a deploy the kernel authorizes. There is
-nothing host-side to rotate (`/rotate-secret` is retired, 410); to re-own, re-birth
-via the upload lane with a new push password — or ask the operator.
-
-## Dead-letter retry — the operator's unjam
-
-Domain-rejected intents land in the workspace DLQ with full provenance
-(`GET /v2/workspaces/<ws>/dead-letters`, owner-keyed). Ship the law fix via
-the deploy lane, then `POST /v2/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

@@ -1,69 +0,0 @@
-# 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.
-
-## Offline birth — the parent births the child, the cloud re-derives it on sync
-
-A workspace is born ONLY by its PARENT authoring its birth. You don't push a repo to create a
-workspace; you author the birth on a parent you hold, and the child materializes when the parent
-syncs (or when you offer the birth to the parent's edge online). A home you hold in local custody
-can birth an estate OFFLINE — no network — and the cloud materializes that estate, byte-identical,
-the moment the home syncs:
-
-```bash
-cd holon
-npx githolon git remote <ws>              # wire the remote + credential helper for THIS workspace
-git push nomos refs/heads/session/<id>    # sync your writes (incl. any births you authored) to the edge
-```
-
-The cloud replay-verifies every synced intent — contiguity, each 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. A birth intent's consequence is the child, materialized in
-cloud custody with an immutable `nomos-birth-record` on the parent (so the whole tree is walkable
-from root — no orphans). Pushing `refs/heads/main` to an unborn name is REFUSED: the pushed bytes
-buy nothing; a workspace comes to exist through its parent's law, not a push.
-
-Why this matters: authorship is `git log`, "does the cloud agree with my machine?" is a checkable
-equation, and every workspace's parentage is a verifiable ledger fact — no host says what exists.
-
-## 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/todo.ts` ([02-authoring.md](./02-authoring.md)).

package/template/docs/06-law-evolution.md

@@ -1,166 +0,0 @@
-# Evolving law
-
-Your domain will change after real data exists. This page is the honest map of
-what each change actually does — every claim below is asserted by a passing
-test against the real wasm (`bench/scale/law_evolution.test.mjs` in the nomos2
-repo, "the proof" hereafter), not aspiration.
-
-First, the mental model: **you never modify a domain — you install a new law
-beside the old one.** Law is content-addressed (`sha256(package bytes)` IS the
-identity), so editing `domains/*.ts` and recompiling yields a NEW hash. Deploying
-it is the same `githolon deploy <ws>` / `POST /domains` you already used; the old
-law stays installed and Active on the chain. Recompile, and the regenerated
-typed client bakes the new hash — shipping it moves your writers to the new law.
-
-**The era rule** (your history is safe): every sealed intent is judged by the
-law that governed it at its position in the chain — old intents replay and
-verify under THEIR law, forever. Upgrading never invalidates history. *(Proof:
-the three-era chain cold-verifies green end to end; also
-`bench/scale/invariant_era.test.mjs`.)*
-
-## The capability map
-
-| change | verdict | what really happens |
-|---|---|---|
-| add a field | **safe** | old rows simply lack it (every read-model field is optional) |
-| add a directive | **safe** | works on old rows the moment the new law installs |
-| add an aggregate / a domain | **safe** | the same deploy lane; nothing existing moves |
-| widen a payload (new optional zod key) | **safe** | old clients' payloads still validate |
-| deprecate a field (keep it, stop writing) | **safe** | old rows keep reading it |
-| rename a field / an aggregate | **safe — framework-handled** | names are labels; identity is the compiler-minted STABLE ID. Rename the declaration, recompile (commit `nomos.stable-ids.json` — the lockfile carries identity), deploy: the evolve gate admits silently and old rows READ THE NEW NAME automatically. No migration, no backfill |
-| remove a field / an aggregate | **refused typed, then disposed** | the upgrade refuses naming the stable id; redeploy with `dispositions: { retired: ["<sid>"] }` in the deploy JSON to acknowledge the true removal |
-| retype a field in place | **refused typed — prefer a new field** | the upgrade refuses (same stable id, new kind); `dispositions: { retyped: { "<sid>": "why" } }` admits it, but old rows keep their authored type → mixed-type reads. A NEW field is almost always better |
-| narrow/change a payload or plan old clients still dispatch | **refused typed** | the old trap is closed: a divergent old-hash write gets a typed era refusal at the gate (never a silently poisoned chain) — see below |
-| read on the write path (`read()` in a plan) | **safe — when declared** | declare each query on the directive (`.reads(theQuery)`); the read is served live at author, captured onto the intent, replayed at verify, and CAS-checked at every gate (a stale premise is a typed read-conflict refusal) |
-| automatic migration of old VALUES (rescale on read) | **not yet** | the upcaster hatch exists in the gate but ships inert; renames no longer need it (stable ids) |
-| rewrite what old intents meant | **never** | history is sealed and self-verifying — that is the point |
-
-## Recipes
-
-### Add a field, add a directive (the free moves)
-
-Add the field to the aggregate (`.optional()` if your `.creates` doesn't always
-set it), add the directive, recompile, deploy, ship the regenerated client.
-Old rows read fine without the field, and the new directive mutates old rows
-immediately. *(Proof: era-1 `alpha` gains `mood` via the era-2 `setMood`.)*
-
-### Deprecate — don't delete
-
-To retire a field or directive, KEEP its declaration and stop using it. Removing
-a field's declaration orphans it from reads (see rename, next) even though the
-data stays in the chain. Removing a directive breaks any client still
-dispatching it. Deletion buys you nothing — law size is not data size.
-
-### Rename a field or aggregate (framework-handled)
-
-Names are LABELS; identity is the STABLE ID the compiler mints at first
-appearance and carries across compiles via `nomos.stable-ids.json` — **commit
-that lockfile** (it is how a rename keeps its identity across machines and
-clean clones). The flow:
-
-1. Rename the declaration in `domains/*.ts`.
-2. Recompile — the summary prints `INFERRED RENAME geoPos -> pos (stable id
-   … carried)`. If you meant a removal + an unrelated addition instead, split
-   the edit into two compiles (or answer the evolve gate, below).
-3. Deploy. The evolve gate diffs old vs new law BY STABLE ID: a rename is the
-   same id with a new label — **it admits silently**, and the projection folds
-   via the stable id, so old rows READ THE NEW NAME immediately. Nothing on
-   the chain changes (history stays append-only); no client backfill exists
-   anymore. *(Proof: the era-1 row reads `pos` the moment v2 installs.)*
-
-### Remove a field (the evolve gate asks)
-
-Deleting a declaration makes its stable id DISAPPEAR — the deploy is refused
-typed, naming the id and the remedies. If it is a true removal, redeploy with
-the disposition (an in-history fact on the upgrade intent):
-
-```jsonc
-// add to build/<name>.deploy.json before POSTing (or via curl --data)
-"dispositions": { "retired": ["<the sid from the refusal>"] }
-```
-
-If it was actually a rename the compiler could not infer (no lockfile, or an
-ambiguous edit), recompile with the lockfile present — or declare
-`"dispositions": { "rebinds": { "<newSid>": "<oldSid>" } }`.
-
-### Retype in place (refused; prefer a new field)
-
-Same field name, new kind (`t.string()` → `t.int()`) is the SAME stable id
-with a different kind — the deploy refuses typed. You may acknowledge it with
-`"dispositions": { "retyped": { "<sid>": "grid index supersedes lat-long" } }`,
-but rows keep their AUTHORED type, so reads go mixed-type across eras and a
-typed client's read model lies for old rows. A NEW field (new identity) is
-almost always the better move. *(Proof: the era-2 string `pos` row reads back
-as a string under the disposed era-3 int schema, beside an int row.)*
-
-### Read on the write path (captured reads)
-
-A plan that must read to decide declares the query on its directive and calls
-`read()`:
-
-```ts
-export const auditShelf = directive("auditShelf")
-  .creates(Audit)
-  .payload(z.object({ shelf: z.string().min(1), auditedAt: z.string().min(1) }))
-  .plan((p) => {
-    const rows = read(entriesByShelf, { shelf: p.shelf }) as unknown[];
-    create(Audit).set("shelf", p.shelf).set("seen", rows.length).set("auditedAt", p.auditedAt);
-    return [];
-  })
-  .reads(entriesByShelf);   // ← the declaration that makes nomos.read lawful
-```
-
-The read is served LIVE from the committed pre-write state at author, captured
-onto the intent (its premise becomes part of its truth), replayed at verify,
-and RE-DERIVED at every gate: if the rows moved between your author and the
-edge admission (a concurrent writer), the write is a **typed read-conflict
-refusal** — the chain is the compare-and-swap register; re-read and
-re-dispatch. Undeclared `read()` refuses at compile. Reads are same-workspace
-and size-bounded by law. *(Proof: `bench/scale/captured_reads.test.mjs`.)*
-
-### Old clients after a breaking change (the trap, now closed)
-
-After you deploy v2, a client still authoring under v1's hash is judged by the
-**era gate**: the gate resolves the LATEST install for the domain and re-runs
-the write's plan under it (the same judgment every cold replay — upload birth,
-deep-verify, any fresh peer — passes at that position):
-
-- if the new law re-derives the SAME bytes for that write (you didn't touch
-  that directive), it admits and verifies green everywhere — *(proof: the
-  unchanged `tagSite` under the old hash)*;
-- if the new law re-derives DIFFERENTLY (changed payload schema or plan), the
-  write is a **typed era refusal** naming both law versions — it can no longer
-  admit silently and poison the chain. At the author door the write stays in
-  the client's hands; on the cloud sync lane the full intent parks in the
-  dead-letter queue on both sides (work is never lost) — deploy a compatible
-  law (or ship the regenerated client) and retry. *(Proof: the divergent
-  old-hash write — typed refusal at the author door AND at edge admission; the
-  chain stays cold-green.)*
-
-The discipline is still: **don't change the meaning of a directive old clients
-still dispatch** — the era gate turns the mistake from a silent ledger poison
-into a visible, recoverable refusal, but your users' offline writes will jam
-in the DLQ until you ship the fix. Either evolve additively (new directive
-names, widened payloads), or retire/redeploy all writers before deploying the
-breaking law. The generated client makes the move atomic per app release — the
-law hash is baked in at compile time.
-
-### Dispatching ahead of the deploy
-
-A write under a law hash the workspace hasn't installed is a typed refusal
-(`no-active-installation`) at the gate — and on the cloud sync lane the full
-intent parks in the dead-letter queue on both sides, then replays with
-`retryDeadLetter` once the law is deployed (see [04-cloud.md](./04-cloud.md)).
-Deploy first, then ship the client.
-
-### Sharded workspaces
-
-On a sharded (coordinator + shards) workspace you deploy ONCE, to the coordinator:
-the cloud fans the same deploy into every open shard
-(`/deploy-from-coordinator`, idempotent per package hash). Proven live in
-`cloud/web-client/test/heavy_coordinator.e2e.mjs`.
-
-Back to the [README](../README.md) — or the deep dive:
-`architecture/law_evolution.md` in the nomos2 repo (the substrate mechanics:
-stable identifiers, the evolve gate, the sid-lineage fold, and the still-inert
-upcaster surface for true value migrations).

package/template/docs/07-security.md

@@ -1,195 +0,0 @@
-# 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 gateway offer lane
-// (`POST /v2/workspaces/<ws>/grantReader`, authenticated as the owning principal) —
-// write-authority is kernel-judged at the offer gate; there is no host secret.
-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.
-- **⚠️ A private workspace needs its OWN verifier (`setAuthProvider`).** The token is
-  verified **against the workspace's own law-declared AuthProvider** — every workspace
-  verifies for itself; there is no global verifier, and **a child does NOT inherit its
-  parent's AuthProvider**. If a private workspace has **no** AuthProvider, a presented
-  `x-nomos-auth` token cannot be verified and the read falls back to the **unverified**
-  bare `x-nomos-principal` claim — i.e. anyone who *claims* to be the owner is served.
-  So a workspace that holds private (`requires(cap)`) or `.encrypted()` data **must**
-  `setAuthProvider` for itself (issuer + JWKS/keys + audience), authored by a principal
-  the workspace's law authorizes. This is true for **every** private workspace — a
-  platform, and each home/space/project born under it. Births do **not** seed it for you:
-  the birth recipe installs law + seats the owner, but the AuthProvider is a separate
-  `setAuthProvider` the new workspace's owner authors (you can copy the parent's config).
-  Refusals are typed — a 403 on a bulk read (`/pack`, `/snapshot`, clone) names the
-  premise (`no-authprovider-verifier` / `token-verification-failed` / `no-principal-presented`
-  / `principal-lacks-workspace-read-cap`), the resolved principal, the required cap, and
-  the workspace's issuer — so the app can tell "token expired" from "not granted."
-- **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 gateway offer lane, authenticated as the owning
-principal (write-authority is kernel-judged at the offer gate — no host secret);
-your end-user app carries **no** credential — its writes are judged by edge
-admission, and it simply can't author a grant. Authority enters only through a
-principal the law authorizes.
-
-## 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/docs/08-births.md

@@ -1,66 +0,0 @@
-# Birth: give a business thing its own life
-
-Use `birth(Aggregate, spec)` when a business thing should be independently durable, portable, and
-recoverable. Describe the business facts once; Nomos owns the workspace, identity proof, provenance,
-persistence, and recovery beneath it.
-
-```ts
-import { Lww, aggregate, birth, t, z } from "@githolon/dsl";
-
-export const Project = aggregate("Project", {
-  reference: t.string().merge(Lww),
-  name: t.string().merge(Lww),
-  country: t.string().merge(Lww),
-});
-
-export const project = birth(Project, {
-  payload: z.object({
-    reference: z.string().min(1),
-    name: z.string().min(1),
-    country: z.string().length(2),
-  }),
-  key: (facts) => facts.reference,
-  plan: (project, facts) => project
-    .set("reference", facts.reference)
-    .set("name", facts.name)
-    .set("country", facts.country),
-});
-```
-
-The generated client has one birth method:
-
-```ts
-const born = await app.birth({
-  reference: "PROJECT-001",
-  name: "Foundry retrofit",
-  country: "GB",
-});
-```
-
-`born` is the typed reference to the business root. The call returns only after the birth is committed
-locally and persistence has been requested from the bound Nomos session.
-
-That is the tenant contract. Do not create a birth directive, construct a child address, assemble setup
-steps, or expose framework hashes in application code. Those are framework implementation details.
-
-## One root per domain
-
-A domain declares at most one business birth. This keeps the generated method unambiguous and makes the
-born aggregate the stable root of its workspace. Model other records beneath that root using ordinary
-aggregates and directives.
-
-## Prove it locally
-
-```bash
-npx githolon compile
-npx githolon proof
-```
-
-The offline proof drives the real kernel. It checks that the child installs its law in-chain, authors the
-business root, verifies its full history, packs its custody, discards the resident copy, reopens from that
-custody, verifies again, and can still read the root.
-
-## Framework compatibility
-
-The lower-level recipe APIs still exist for Nomos' built-in workspace laws and for older packages. They
-are not the tenant authoring surface. New business domains use `birth(Aggregate, spec)`.

package/template/docs/09-attested-reads.md

@@ -1,87 +0,0 @@
-# 09 — Attested cross-workspace reads (slice B)
-
-Your law can gate a write on a FACT IN ANOTHER WORKSPACE — without ever trusting the host,
-and without any peer opening the foreign chain at replay. The source's kernel SIGNS the
-answer; your law declares whose signature it trusts; every door (author, edge admission,
-`verify_chain` forever) re-verifies the signed envelope.
-
-## Declare the trust edge in law
-
-```ts
-import { z, directive, read, trustSource, foreignQuery } from "@githolon/dsl";
-
-const platformPolicy = foreignQuery("platformPolicy"); // the SOURCE's declared query, by id
-
-// module level — the trust boundary IS law (rides the domainHash):
-export const platformTrust = trustSource("acme-platform", {
-  genesis: "9d1c…",            // the source's genesis oid (its true identity — names are routing)
-  keyHashes: ["41aa…"],        // sha256 of the source's read-attestor public key(s)
-  maxAgeMs: 86_400_000,        // how stale an envelope may be vs the intent's own clock
-  minSourceEpoch: "birth",
-  monotone: true,              // refuse an answer older than one this chain already saw
-});
-
-export const enrollDevice = directive("enrollDevice")
-  .creates(HomeDevice)
-  .payload(z.object({ device: z.string() }))
-  .readsFrom("acme-platform", platformPolicy)   // the declared foreign read
-  .plan((p) => {
-    const rows = read(platformPolicy, { scope: "homes" }, { from: "acme-platform" });
-    if (rows[0]?.data?.enrollmentOpen !== "true") throw new Error("enrollment closed");
-    create(HomeDevice).set("device", p.device);
-    return [];
-  });
-```
-
-## Who fetches the evidence? THE AUTHOR — never the host
-
-The host never initiates a fetch (that would be orchestration — host-purge doctrine). Three
-lanes, in precedence order:
-
-1. **Carried** — the offer already contains `attestations: [{queryId, result, attestation}]`.
-   The gate judges the carried envelope; nothing ever replaces it.
-2. **Colocated (kernel-internal)** — when the source workspace is mounted in the SAME engine
-   instance (the container pool colocates workspaces), the engine plane serves + signs the
-   read in-kernel and injects it. Zero HTTP. The envelope is byte-identical to the HTTP lane —
-   colocation is invisible to the gate.
-3. **Client-carried (`?attest=1`)** — otherwise the CLIENT pre-fetches from the source's open
-   read lane and carries the envelope on the offer.
-
-## `@githolon/client` does the dance for you
-
-```ts
-const holon = await connect({ cloud, workspace, clientId,
-  attestedSources: { "acme-platform": "https://nomos.captainapp.co.uk" } }); // optional override
-await holon.dispatch("home", "enrollDevice", { device: "d-1" });
-// → the kernel refuses TYPED naming the missing read; the client fetches
-//   GET <sourceCloud>/v2/workspaces/acme-platform/platformPolicy?scope=homes&attest=1
-//   injects the signed envelope, retries — automatically.
-```
-
-**Offline:** if the source is unreachable, the offer FAILS with the named
-`attested-read-unreachable` error. There is NO stale fallback — a plan without its live
-premise cannot author. Retry when the source is reachable. You can also pre-fetch ahead of
-time (`holon.fetchAttestedRead(from, queryId, args)`) and pass
-`dispatch(..., { attestations: [entry] })`.
-
-## The two-step dance for THIN clients (raw HTTP, no SDK)
-
-1. `POST /v2/workspaces/<ws>/<directiveId>` with your payload. If the law declares foreign
-   reads and your body carries no matching attestation, you get **422** with:
-   `attested-read-unreachable: read('<queryId>', {from: '<source>'}) args={…} has no injected
-   attestation — pre-fetch it from the source's open read lane (?attest=1 …)`.
-2. `GET /v2/workspaces/<source>/<queryId>?<args>&attest=1` → `{ok, rows, attestation}` —
-   the source KERNEL signed it; the host relayed opaque bytes. Retry the POST with
-   `"attestations": [{"queryId": "<queryId>", "result": <rows>, "attestation": <attestation>}]`
-   in the body (it rides beside your payload fields, not inside them).
-
-No server fills this in for you — the refusal is the kernel INSTRUCTING you what evidence to
-carry. That is the design, not a limitation: the author carries the premise; every replayer
-verifies the signature forever, offline.
-
-## What the gate checks (every door, every peer, forever)
-
-declared edge ✓ → key hash ∈ your law's pins ∧ genesis matches ∧ signature verifies over the
-result ✓ → size bounds ✓ → freshness (`maxAgeMs` vs the intent's frozen clock, `minSourceEpoch`,
-the `monotone` frontier) ✓ → the plan re-runs with the replayed capture and byte-compares.
-A forged/tampered/stale/wrong-key envelope is a TYPED refusal. No peer ever contacts the source.