create-githolon 0.2.2 → 0.3.0

package/package.json

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

@@ -87,7 +87,7 @@ Then deploy it for real: `npx githolon login --agent && npx githolon ws create <
 
 ## Docs — in the box
 
-`docs/` travels with you — offline, like everything else here. Five short
+`docs/` travels with you — offline, like everything else here. Six short
 pages, each under a screen and a half:
 
 1. [The mental model](./docs/01-mental-model.md) — holons, content-addressed
@@ -102,10 +102,13 @@ pages, each under a screen and a half:
    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.
+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.
 
 ## What's here
 
-- `docs/` — the five pages above; the offline reference.
+- `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>`.

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

@@ -0,0 +1,116 @@
+# 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 | **honest, manual** | NO migration — old rows keep the old name, new rows the new; backfill is client-driven |
+| retype a field in place | **don't** | rows keep their authored type → mixed-type reads; typed clients break on old rows |
+| narrow/change a payload or plan old clients still dispatch | **the trap** | old-hash writes still ADMIT but the chain stops cold-verifying — see below |
+| automatic migration of old events (true rename/rescale on read) | **not yet** | the upcaster hatch exists in the gate but ships inert; specced in `architecture/law_evolution.md` |
+| 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 (what really happens)
+
+A rename is a remove + an add. The proof shows exactly this:
+
+- era-1 rows KEEP their value under the OLD name in reads (the old install is
+  still that field's latest declaring install) — orphaned name, not lost data;
+- the NEW name is ABSENT on era-1 rows: **nothing migrates**;
+- new-law rows carry only the new name — reads are SPLIT across two names.
+
+The safe sequence, if you must rename:
+
+1. Add the new field (keep the old one declared).
+2. New law's directives write the new field; deploy; ship the new client.
+3. **Backfill client-side**: read each old row, dispatch the new-law mutate
+   with the old value. *(Proof: the backfill lands `pos`; `geoPos` remains as
+   residue — history is append-only.)*
+4. Treat the old field as deprecated (recipe above). Reads that matter use the
+   new name only.
+
+### Never retype in place
+
+Same field name, new kind (`t.string()` → `t.int()`) compiles and verifies —
+and gives you rows of BOTH types under one field name, era by era. A typed
+client's read model is then wrong for old rows. Use a NEW field name and the
+rename recipe. *(Proof: the era-2 string `pos` row reads back as a string under
+the era-3 int schema, beside an int row.)*
+
+### The one real trap: old clients after a breaking change
+
+After you deploy v2, a client still authoring under v1's hash is NOT refused —
+v1 is still an Active install, so its writes admit at the gate. But the chain
+is re-judged on every cold replay (upload birth, deep-verify, any fresh peer)
+by the LATEST law at each position, which re-runs each plan and byte-compares:
+
+- if the new law re-derives the SAME bytes for that write (you didn't touch
+  that directive), it verifies green — *(proof: the unchanged `tagSite`)*;
+- if the new law re-derives DIFFERENTLY (changed payload schema or plan), the
+  write **admits silently and the chain stops cold-verifying** — an upload of
+  that ledger is refused. *(Proof: the divergent old-hash write — local verify
+  green, cold verify typed refusal.)*
+
+So the discipline is: **never change the meaning of a directive old clients
+still dispatch.** 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 estates
+
+On a sharded (coordinator + shards) estate 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 +
+the specced upcaster surface for true migrations).