create-githolon 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.4.0",
+  "version": "0.5.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/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 every pattern below; reshape it.
+`domains/guestbook.ts` demonstrates the core patterns below; reshape it.
 
 ## Aggregates: typed fields, each tagged a merge driver
 
@@ -48,7 +48,90 @@ 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.
+`.mutates(Agg)` takes the instance id in the payload; `.ensures(Agg)` upserts
+at a DETERMINISTIC id (next section).
+
+## Upserts: `.ensures` — create-or-amend at a deterministic id
+
+When the CALLER owns the identity (a reading keyed `probe:day`, a config row
+keyed by name), mark the directive `.ensures(Agg)` and address the instance
+with an id DERIVED FROM THE PAYLOAD — never minted, never guessed:
+
+```ts
+export const recordReading = directive("recordReading").ensures(Reading)
+  .payload(z.object({ probe: z.string(), day: z.string(), value: z.number().int() }))
+  .plan((p) => {
+    const r = instance(Reading, `reading:${p.probe}:${p.day}`);
+    return [set(r, "probe", p.probe), set(r, "day", p.day), set(r, "value", p.value)];
+  });
+```
+
+The first dispatch creates the row; a re-dispatch folds onto it IN PLACE under
+the field merge drivers (Lww: a re-submission of the same value is a no-op, a
+corrected value replaces it). That makes the write IDEMPOTENT — any host can
+re-submit without double-counting. Collectors, crons, and retry loops live on
+this.
+
+## "Singletons" — minted record + natural-key query, NEVER a fixed row id
+
+A common instinct is to model a one-of-a-kind record (a platform, a config, a
+tenant) with a FIXED aggregate id — `create(Platform)` then address it forever
+at `"the-platform"`. **The gate refuses this.** Every `create()` mints a
+kernel id (`<TypeTag>_<uuidv7>`) and `check_create_ids` rejects a hand-written
+id typed (`NotMinted`). Identity is minted; names are data.
+
+So a singleton is **a minted record carrying its natural key as a FIELD, plus an
+indexed query to find it by that key:**
+
+```ts
+export const Platform = aggregate("Platform", {
+  platformId: t.string().merge(Lww),   // the natural key — a FIELD, not the row id
+  namespace: t.string().merge(Lww),
+  // … the rest of the platform's state
+});
+
+export const registerPlatform = directive("registerPlatform").creates(Platform)
+  .payload(z.object({ platformId: z.string().min(1), namespace: z.string().min(1) }))
+  .plan((p) => { create(Platform).set("platformId", p.platformId).set("namespace", p.namespace); return []; });
+//  ^ NO id in the payload — Nomos MINTS it. The typed client mints-when-omitted.
+
+export const platformByPlatformId = query("platformByPlatformId").key("platformId").returns(Platform);
+//  ^ "the singleton" is read by its natural key, O(1) — never by a guessed row id.
+```
+
+The same pattern is how you model `namespaceId`, `providerId`, a config record
+keyed by `name` — each a minted row + a `…By<NaturalKey>` query. If you truly
+want create-or-amend semantics at a caller-owned key (and the natural key IS the
+identity), use `.ensures` above instead — that lane DELIBERATELY addresses a
+derived id and is the ONLY way a non-minted id is lawful.
+
+### Multi-aggregate ensures: `withMarker`
+
+A directive's marker covers its OWN target aggregate only. When the same plan
+also upserts a SECOND aggregate (a sample updating its monthly meter in the
+same intent), tag that aggregate's write explicitly with
+`withMarker(op, "ensures")` — untagged fan-out rides as a mutate of a row
+that may not exist yet:
+
+```ts
+export const recordSample = directive("recordSample").ensures(Sample)
+  .payload(/* … */)
+  .plan((p) => {
+    const s = instance(Sample, sampleId(p));   // the directive's .ensures target
+    const m = instance(Meter, meterId(p));     // the sibling upsert
+    return [
+      set(s, "value", p.value),
+      withMarker(set(m, "month", monthOf(p)), "ensures"), // ONE tagged op marks the whole aggregate's event
+      set(m, "monthToDate", p.monthToDate),
+    ];
+  });
+```
+
+One tagged op per sibling aggregate is enough (conflicting markers for the
+same aggregate refuse at encode, fail-closed). This is exactly how Nomos
+Cloud's own usage tenant folds a reading AND its budget meter in ONE intent —
+so the budget invariant judges both together: a reading that would leave the
+meter over an unacked threshold refuses, and the sample refuses WITH it.
 
 ## Determinism or death
 
@@ -69,8 +152,10 @@ admission fails everywhere, forever.
   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.
+Export each at top level; `githolon compile` auto-discovers them by shape and
+routes them into the read manifest so they work at the edge AND in clients.
+After a compile, read `build/<pkg>.summary.txt` — it lists every aggregate,
+directive, query, count, and sum you actually built; if a declared read is
+missing there, it is missing everywhere.
 
 Next: [03-client.md](./03-client.md) — driving it from an app.

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

@@ -27,10 +27,12 @@ the three-era chain cold-verifies green end to end; also
 | 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 |
+| 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 |
-| 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` |
+| 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
@@ -49,32 +51,72 @@ 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.)*
+### 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)
 
@@ -119,5 +161,6 @@ the cloud fans the same deploy into every open shard
 `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).
+`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).