create-githolon 0.99.0 → 0.100.0

package/index.mjs

@@ -17,7 +17,7 @@ var NOMOS_VERSION = (() => {
 var args = process.argv.slice(2);
 if (args.includes("-h") || args.includes("--help")) {
   process.stdout.write(
-    "create-githolon \u2014 scaffold a Nomos domain package\n\nUsage:\n  npm create githolon <dir>        (or: npx create-githolon <dir>)\n\nScaffolds the starter domain + compile config + live e2e into <dir>\n(default: my-holon-app) and inits a git repo. After `githolon compile`,\n`githolon ledger init holon` mints YOUR holon locally \u2014 verified by the\nsame wasm gate the cloud runs, ready to birth by git push.\n\nFlags:\n  --no-git    skip git init\n"
+    "create-githolon \u2014 scaffold a Nomos business-law package\n\nUsage:\n  npm create githolon <dir>        (or: npx create-githolon <dir>)\n\nScaffolds one aggregate, one business birth, the compile config, and a\none-page explanation into <dir> (default: my-holon-app). The generated\nproof exercises the real local engine.\n\nFlags:\n  --no-git    skip git init\n"
   );
   process.exit(0);
 }
@@ -41,7 +41,7 @@ if (existsSync(path.join(targetDir, "vscode"))) {
 }
 var appHash = `${appName.replace(/[-\s]+/g, "_").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase()}_DOMAIN_HASH`;
 var subst = (s) => s.replaceAll("__APP_NAME__", appName).replaceAll("__APP_HASH__", appHash).replaceAll("__NOMOS_VERSION__", NOMOS_VERSION);
-for (const f of ["package.json", "README.md", "nomos.package.mjs", "CLAUDE.md", "domains/todo.ts", "test/e2e.mts"]) {
+for (const f of ["package.json", "README.md", "nomos.package.mjs", "CLAUDE.md", "domains/todo.ts"]) {
   const p = path.join(targetDir, f);
   if (existsSync(p)) writeFileSync(p, subst(readFileSync(p, "utf8")), "utf8");
 }
@@ -59,19 +59,15 @@ process.stdout.write(
   `
 Scaffolded ${appName} into ${rel}/${gitInited ? " (git repo)" : ""}
 
-Read docs/01-mental-model.md first \u2014 the docs travel with you, offline.
+Nomos in one page: ${path.join(rel, "README.md")}
 
 Next:
   cd ${rel}
   npm install
-  npx githolon compile        # \u2192 build/: deployable package + manifests + typed client + a generated proof
-  npx githolon proof          # run that proof live \u2014 GENERATED from your own law, no test rewriting
-  npx githolon login --agent  # a verified identity, no browser
+  npx githolon compile        # law + typed client + generated proof
+  npx githolon proof          # births your model in the real local engine
 
-Your law compiles + proves OFFLINE today (compile + proof above \u2014 no cloud, no account).
-To run it LIVE, deploy to a workspace you own: a workspace is born by its PARENT (a platform
-you control births homes/children \u2014 birthHome/birthChild). There is no host-side create \u2014 the
-flat 'ws create' lane is retired (orphanless holarchy). See docs/04-cloud.md for the birth-on-
-parent flow; self-serve keyless birth-under-root is in flight.
+The starter exposes one creation idea: app.birth(businessFacts).
+Identity, authorship, persistence, synchronisation, provenance, and recovery stay underneath it.
 `
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.99.0",
+  "version": "0.100.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/CLAUDE.md

@@ -1,36 +1,13 @@
-# __APP_NAME__ — Nomos domain package
+# __APP_NAME__
 
-A local-first Nomos domain: law authored in the `@githolon/dsl` TypeScript DSL under
-`domains/`, compiled into ONE deterministic GitHolon artifact, deployed to a workspace.
-Read `docs/01-mental-model.md` first — the docs travel with this repo, offline.
-
-## For AI agents
-
-This project's law is guarded by an author-time gate (static twins). Use it:
-
-- **Lint the law** — before compiling or deploying, run the gate over `nomos.package.mjs`:
-
-  ```bash
-  npx githolon check            # human report; exits non-zero on any REFUSE
-  npx githolon check --json     # the findings as a machine-readable array (file:line)
-  ```
-
-- **Preview a law evolution** — before deploying a change to already-deployed law, diff
-  against the prior deployed law and paste any generated `dispositions` block:
-
-  ```bash
-  npx githolon check --against build/<name>.deploy.json
-  ```
-
-- **Editor / agent diagnostics** — `npx githolon lsp` is a standard stdio Language Server
-  (red squiggles as you write law). For Claude Code, the `nomos-law` plugin ships it as a
-  plugin LSP; for Codex or other MCP clients, `githolon mcp` exposes the same gate as the
-  `nomos_check` and `nomos_evolve_preview` tools (`codex mcp add nomos -- githolon mcp`).
-
-## The loop
+This is a Nomos business-law package. Keep application code at the level of aggregates, `birth`, directives, and reads.
 
 ```bash
-npx githolon compile   # → build/: deployable package + typed client + a generated proof
-npx githolon proof     # run that proof offline on a local holon
-npx githolon deploy <ws>
+npx githolon check
+npx githolon compile
+npx githolon proof
 ```
+
+`check` reports statically provable refusals. `compile` emits the law and typed client. `proof` exercises the generated business path in the real local engine.
+
+Do not introduce application-facing identity, signing, storage, deployment, or recovery ceremonies. They belong beneath the generated `birth(payload)` surface.

package/template/README.md

@@ -1,144 +1,63 @@
-# __APP_NAME__ — a Nomos domain package
-
-Scaffolded by `npm create githolon`. One domain file, one config, one command —
-then an offline-first typed client against Nomos Cloud. Two ways to get a live
-workspace; both end in the same place.
+# __APP_NAME__
+
+Nomos lets you describe a business and leave the compute science to the framework.
+
+You write three things:
+
+- aggregates: the business things that exist;
+- birth: the facts required to give one of those things a durable life;
+- directives and reads: what may happen to it and what the application may ask.
+
+The starter in [`domains/todo.ts`](domains/todo.ts) gives a todo list its own durable life:
+
+```ts
+export const TodoList = aggregate("TodoList", {
+  reference: t.string().merge(Lww),
+  title: t.string().merge(Lww),
+});
+
+export const todoList = birth(TodoList, {
+  payload: z.object({
+    reference: z.string().min(1),
+    title: z.string().min(1),
+  }),
+  key: (facts) => facts.reference,
+  plan: (list, facts) => list
+    .set("reference", facts.reference)
+    .set("title", facts.title),
+});
+```
 
-New here? Read [docs/01-mental-model.md](./docs/01-mental-model.md) first — the
-docs travel with you, offline (the full index is [below](#docs--in-the-box)).
+The generated client exposes the same business idea:
 
-```bash
-npm install
-npx githolon compile          # → build/: deployable package + manifests + typed client + a generated proof
-npx githolon proof            # run that proof live — GENERATED from your own law, no test rewriting
-npx githolon login --agent    # self-onboard a verified identity (no browser; linkable to a full account later)
+```ts
+const list = await app.birth({
+  reference: "PERSONAL",
+  title: "Things to do",
+});
 ```
 
-**The shortest complete proof** — `npm install && npx githolon compile && npm run e2e`
-— IS the whole demonstration: your law deploys to a throwaway workspace, an
-ENFORCED-offline write (fetch is trapped) syncs through edge admission, and the
-cloud answers your declared query and count. Paths A/B below are for keeping a
-real workspace afterwards.
+That is the model. A born aggregate is a holon: its law, facts, and history travel together. It can act locally, survive disconnection, converge with other copies, explain every accepted change, and be reconstructed from its history.
+
+Nomos owns everything underneath `birth`: durable identity, authorship, law installation, local execution, validation, persistence, synchronisation, provenance, and recovery. Those mechanisms are implementation details, not application design choices.
 
-## Path A — deploy your law
+The development loop is one path:
 
 ```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/__APP_NAME__.deploy.json with the stored secret
-npm run e2e                # the full loop, live: offline write → sync → admission → cloud query
+npm install
+npx githolon compile
+npx githolon proof
 ```
 
-## Path B — mint a holon LOCALLY, push it, the cloud agrees
+`compile` emits the law, typed client, and a proof generated from this domain. `proof` drives the real engine locally, births the list, discards its resident copy, restores it from durable custody, verifies the full history again, and reads the business root back.
 
-This is the point of holons: predefined law you can assert to be true on your
-own machine, then have independently validated in the cloud. `ledger init`
-builds a brand-new GitHolon ledger locally — genesis (the nomos controller),
-then YOUR compiled law, every intent stamped `installedBy: <your identity>` —
-and verifies the chain with the SAME byte-identical wasm gate the cloud runs.
-Pushing it to an unborn workspace makes the cloud replay-verify the whole chain
-from genesis and re-derive your exact verdict (same head, same plans re-run)
-before serving anything. Authority lives in the git; no holon outranks another.
+Make it yours by renaming `TodoList`, changing its fields, and changing the birth payload. Keep the rule: application code supplies business facts; Nomos owns the machinery that makes those facts durable and trustworthy.
 
-```bash
-npx githolon ledger init holon    # mint + assert locally: chain VALID, head <h>, under YOUR uid
-npx githolon ledger verify holon  # re-assert any time
-cd holon
-npx githolon ws create <ws>       # birth the workspace (its parent's offer-effect); no secret minted
-npx githolon git remote <ws>      # wire the remote + credential helper for syncing
-git push nomos refs/heads/session/<id>  # sync your writes to the edge (main is not push-writable)
-npx githolon deploy <ws>          # idempotent (alreadyInstalled) + stages the read manifests so queries route
-cd ..
-```
+Useful files:
+
+- [`domains/todo.ts`](domains/todo.ts): the business model;
+- [`nomos.package.mjs`](nomos.package.mjs): the modules compiled into the package;
+- `build/__APP_NAME__.client.ts`: the generated typed client after `compile`;
+- `build/__APP_NAME__.proof.mts`: the generated proof after `compile`.
 
-After birth, `holon/` tracks YOUR workspace: new writes admitted on main arrive
-with `git pull`. (`githolon git setup` installed a git credential helper, so plain
-git just works against the cloud.)
-
-## Make it YOURS — the five-minute walkthrough
-
-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/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"] }] };
-   ```
-   **Naming convention: there isn't one.** `<pkg>` can be whatever you'd actually
-   call it — `potluck`, `tool-library`, `study_group`, even `Tool Library`.
-   Artifact filenames keep your name verbatim (`build/<pkg>.client.ts`); the
-   generated symbols normalize it for you (`toolLibraryClient(holon)`,
-   `TOOL_LIBRARY_DOMAIN_HASH`).
-3. **Compile and read what you built:**
-   ```bash
-   npx githolon compile && cat build/<pkg>.summary.txt
-   ```
-4. **Re-point the proof** — `build/<pkg>.proof.mts` needs nothing: it is
-   REGENERATED from your law on every compile (`npx githolon proof` runs it).
-   The narrated `test/e2e.mts` is yours to reshape: update the client import and
-   the directive/query/count names; `npm run typecheck` names every stale
-   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 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. Seven short
-pages, each under a screen and a half:
-
-1. [The mental model](./docs/01-mental-model.md) — holons, content-addressed
-   law, custody-not-truth, admission, no server authority.
-2. [Authoring law](./docs/02-authoring.md) — aggregates, field kinds, the
-   merge-driver table, plan ops (`addToSet` vs `set`), determinism rules,
-   declared reads (query/count/derived/sum).
-3. [The client](./docs/03-client.md) — `connect`, the generated client
-   contract, `sync` semantics (`admission: null` is normal), watches, dead
-   letters, the two-clientId concurrency proof.
-4. [Nomos Cloud](./docs/04-cloud.md) — both deploy lanes, `login --agent`
-   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.
-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 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/__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/__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.
-- `holon/` (after `ledger init`) — YOUR ledger, a normal git repo. Inspect it:
-  every commit is an intent envelope; `git log` IS the audit trail.
-
-## Authoring rules (the engine enforces these)
-
-- A directive's plan is a PURE function of `(payload, ports)` — timestamps ride
-  in the payload as ISO strings; no `Date.now()` / `Math.random()`. You rarely
-  stamp one by hand: payload fields named `…At` are auto-filled with ISO now()
-  by the generated client when you omit them (an explicit value always wins).
-- `create(Agg)` mints ids — `.creates` payloads never carry one.
-- Merge drivers are the law: `Lww`, `AddWins`, `MapOf(Lww)`.
-
-Everything you write here, and everything the tools generate for you, is yours.
+If you need to understand distributed systems, cryptography, storage topology, or recovery ceremonies to model the business, that concern has leaked out of Nomos.

package/template/domains/todo.ts

@@ -1,77 +1,25 @@
 /**
- * __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.
+ * __APP_NAME__ — the complete starter model.
+ *
+ * The app supplies business facts. Nomos gives the aggregate a durable life and owns identity,
+ * authorship, local execution, synchronisation, persistence, provenance, and recovery beneath it.
  */
-import {
-  z, aggregate, t, Lww, AddWins, directive, create, instance, set, addToSet,
-  query, count, writeTuple, RelationTuple, relationTuplesByObject,
-} from "@githolon/dsl";
+import { Lww, aggregate, birth, t, z } from "@githolon/dsl";
 
-// ── what we store ─────────────────────────────────────────────────────────────
 export const TodoList = aggregate("TodoList", {
-  title: t.string().merge(Lww), // last writer wins
+  /** A stable business key the caller already knows. */
+  reference: t.string().merge(Lww),
+  title: t.string().merge(Lww),
 });
 
-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.bool(),                      // a flag — Lww by default; reads back a real boolean
-  tags: t.set(t.string()).merge(AddWins), // concurrent taggers UNION — nobody's tag is lost
+/** The one public creation idea: give a todo list its own durable life. */
+export const todoList = birth(TodoList, {
+  payload: z.object({
+    reference: z.string().min(1),
+    title: z.string().min(1),
+  }),
+  key: (facts) => facts.reference,
+  plan: (list, facts) => list
+    .set("reference", facts.reference)
+    .set("title", facts.title),
 });
-
-// ── 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", false);
-    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 done/not-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.boolean() }))
-  .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 (done = false), per list.
-export const openTodosByList = count("openTodosByList")
-  .of(Todo).where((p) => p.field("done").eq(false)).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,10 +1,4 @@
-// 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 is auto-injected by shareList's `.ensures(RelationTuple)`; todo.ts only
-// re-exports the relationTuplesByObject query (the read side).
-// Building a Flutter app too? Add `dart: true` for the typed Dart frontend
-// (build/dart/) alongside the TS client.
+// The package is just the business-law modules Nomos should compile.
 export default {
   name: "__APP_NAME__",
   domains: [{ key: "todo", modules: ["./domains/todo.ts"] }],

package/template/package.json

@@ -3,11 +3,10 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
-  "description": "A Nomos domain package \u2014 authored in @githolon/dsl, compiled with `githolon compile`, deployed to Nomos Cloud with one POST.",
+  "description": "A Nomos business-law package: aggregates, birth, directives, and reads.",
   "scripts": {
     "compile": "githolon compile",
     "proof": "githolon proof",
-    "e2e": "tsx test/e2e.mts",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

package/template/docs/01-mental-model.md

@@ -1,57 +0,0 @@
-# The mental model
-
-Five ideas. Everything else in this scaffold is a consequence of them.
-
-## Holons
-
-A holon is the runtime: kernel + SQLite projection + an embedded deterministic
-JS engine, compiled into ONE `wasm32-wasip1` artifact. Every peer — the cloud
-edge, your laptop, a browser tab, the e2e test — runs the SAME bytes. That is
-why results agree: not because peers trust each other, but because they cannot
-diverge. There is no "server build" and "client build". There is one build.
-
-## Law
-
-Your domain — aggregates + directives in `domains/*.ts` — compiles to a
-package whose sha256 IS its identity (`policy:{hash}`). Law is
-content-addressed: a workspace doesn't run "version 3 of guestbook", it runs
-`policy:ab12…`, and the generated client carries that exact hash baked in.
-A write is judged against the hash it was authored under. No ambient config,
-no environment drift — if the bytes differ, it is different law.
-
-## Custody, not truth
-
-The ledger is a git repo. Git stores and transports the chain; it does not
-vouch for it. Every holon re-verifies everything it replays: contiguity,
-admission of every intent, plans re-run and byte-compared. So possession of
-the repo confers nothing — a chain is valid because it verifies, wherever it
-sits. This is why `git clone` of your workspace works with stock git, and why
-a chain minted on your laptop is exactly as good as one minted in the cloud.
-
-## Admission
-
-Clients author OFFLINE under the pulled law, then push to an untrusted
-`session/<clientId>` branch. The edge holon re-admits each intent — validates
-the payload, re-runs the plan, byte-compares the result — before merging to
-`main`. Verification, never trust: `refs/heads/main` is written only through
-that gate. A rejected intent is dead-lettered on both sides, never lost
-(see [03-client.md](./03-client.md)).
-
-## No server authority
-
-No holon outranks another. The cloud edge is custody plus a convenient
-always-on peer — its verdicts are re-derivable by anyone with the chain and
-the wasm. That's the point of Path B in the README: mint a ledger locally,
-verify it locally, push it, and watch the cloud re-derive your exact verdict
-before serving anything. Authority lives in the git, not in a hostname.
-
-## What this buys you
-
-- Offline is the normal case, not a degraded mode. Writes, queries, counts,
-  derived fields all run locally; sync is reconciliation, not submission.
-- Merges are law, not luck: every field declares its merge driver, so
-  concurrent edits resolve the same way on every peer
-  (see [02-authoring.md](./02-authoring.md)).
-- The audit trail is `git log`. Every commit is an intent envelope.
-
-Next: [02-authoring.md](./02-authoring.md) — what you actually write.