create-githolon 0.3.0 → 0.4.0

package/package.json

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

@@ -59,8 +59,10 @@ The starter is the tutorial; this is the exact path from guestbook to your own l
 
 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; directives = zod payload → pure
-   plan; `addToSet` for AddWins sets — `set()` on a set field is refused).
+   (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).
 2. **Point the compile config at it** — `nomos.package.mjs`:
    ```js
    export default { name: "<pkg>", domains: [{ key: "<pkg>", modules: ["./domains/<yours>.ts"] }] };

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

@@ -29,7 +29,7 @@ the three-era chain cold-verifies green end to end; also
 | 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 |
+| 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` |
 | rewrite what old intents meant | **never** | history is sealed and self-verifying — that is the point |
 
@@ -76,25 +76,32 @@ 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
+### Old clients after a breaking change (the trap, now closed)
 
-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:
+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 verifies green — *(proof: the unchanged `tagSite`)*;
+  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 **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.
+  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
 

package/template/domains/guestbook.ts

@@ -38,18 +38,40 @@ export const ENTRY_MOODS = ["delighted", "happy", "neutral", "grumpy"] as const;
 
 // --- aggregate ----------------------------------------------------------------
 
-/** One guestbook entry. The wire type `GuestbookEntry` is what readers key on. */
-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)),
-});
+/** 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 ---------------------------------------------------------------
 

package/template/package.json

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