create-githolon 0.99.0 → 0.100.1

package/template/docs/10-flutter-layering.md

@@ -1,79 +0,0 @@
-# 10 — Flutter clients: layered packages + humane names
-
-`nomos-compile` can emit your generated Dart as **three sibling pub packages** instead of one
-flat tree, so a Flutter app can enforce a layered architecture with the package graph itself:
-
-```js
-// nomos.package.mjs
-export default {
-  name: "acme",
-  domains: [ /* … */ ],
-  dart: {
-    out: "build/dart",
-    packages: {
-      types:  "acme_nomos_types",   // pure data — frontend-safe
-      client: "acme_nomos_client",  // effectful runtime clients
-      test:   "acme_nomos_test",    // headless harness — dev_dependencies only
-    },
-    names: {
-      // public aliases over the stable generated identities (typedefs in the types barrel)
-      AcmeProjectCustomFieldDefinitionFieldType: "FieldType",
-      AcmeProjectDrawingTransform2d: "DrawingTransform2d",
-    },
-  },
-};
-```
-
-## The layering line
-
-**Don't ban generated types from UI; ban generated clients/runtime from UI.**
-
-```text
-your_frontend      -> acme_nomos_types            (payloads, read models, VOs/enums,
-                                                   typed watch/read accessors, aggregate meta)
-your_composition   -> acme_nomos_client + types   (offer methods over NomosBridge,
-                                                   sessions, sync, workspace lifecycle)
-apps/your_app      -> your_frontend + your_composition
-widget/e2e tests   -> acme_nomos_test             (dev_dependencies only)
-```
-
-- `types` depends ONLY on the pure `nomos_types` core — no bridge, no sessions, no lifecycle.
-  A type-only law change reaches the UI; a client/runtime change does not.
-- `client` depends on the types package + `nomos_client`. It re-exports the types barrel, so
-  composition code needs one import.
-- `test` re-exports the headless harness (`package:nomos_client/testing.dart`) plus the full
-  client layer.
-
-The generated `watch*/read*` accessors live in **types** on purpose: they are pure typed
-wrappers over an injected `NomosReads` seam (plain function fields) — the UI can render live
-data without ever seeing the runtime. Your composition layer constructs the one `NomosReads`
-from its bridge and hands it down.
-
-## What is generated-owned vs yours
-
-- `lib/src/generated/**` and each package barrel (`lib/<pkg>.dart`) are **generated-owned** —
-  wiped and rewritten on every compile. Never hand-edit them.
-- Each `pubspec.yaml` is scaffolded **only if missing** — you own versions, publishing
-  (`publish_to`), and any extra dependencies. Version the three packages independently: that
-  independence IS the blast-radius win; releasing them in lockstep rebuilds the god artifact
-  with more pubspecs.
-
-## Aliases (`dart.names`)
-
-Generated names are fully qualified (`<Domain><Aggregate><Field>…`) because identity must be
-collision-free across your whole law. The `names` map layers humane public names on top as
-`typedef` aliases in the types barrel. Validation is fail-closed at compile: the generated
-name must exist, and an alias may not collide with any generated public name or another alias.
-The compile summary prints long generated names that still lack an alias.
-
-Renaming an alias is free (it's a label over a stable identity — the law and the wire never
-see it). `names` works in the single-package emit too.
-
-## Notes
-
-- `dart.packages` implies `support: "package"` (pub dependencies on `nomos_types` /
-  `nomos_client`); combining it with `support: "vendored"` is a named compile refusal.
-- The scaffolded client/test pubspecs wire the sibling dependency as a `path:` (they are
-  co-emitted); replace with hosted constraints when you publish.
-- Types-file purity is enforced by the compiler, not convention: a generated types file that
-  imported anything beyond the `nomos_types` core would refuse the compile.

package/template/docs/11-governance-postures.md

@@ -1,89 +0,0 @@
-# Governance postures — Managed and Sovereign
-
-Every platform you run on Nomos Cloud **declares a governance posture**. It decides one thing: **may the
-operator (the root custodian) run recovery verbs — rebirth, certifyEra, repairs — FOR your workspace
-without asking you first?** Both postures are first-class; you choose, and you can change your mind.
-
-The honest foundation, stated plainly and never hidden:
-
-- **Validity sovereignty is absolute for everyone.** Holons self-verify. The operator can *act* but can
-  never *lie* — every operator act is a signed, ordered, permanent fact in root's replayable chain.
-- **Custody power is irreducibly the host's while you are hosted.** No cryptography stops a landlord
-  changing the locks. What Nomos gives you is **detectability** (a custody break fails closed) and
-  **exit** (clone the ledger and leave — the byte-identical wasm makes self-hosting the ultimate exit).
-- Therefore **hosted sovereignty = law-encoded restraint + total detectability + credible exit.** Never
-  prevention.
-
-## Posture A — Managed (the default)
-
-Your platform's law folds an **OperatorGrant**: the root custodian may run recovery verbs for you — each
-a signed, attributed law fact + certificate you audit forever. This is *the assurance of being able to
-ask us for help*: if your chain scars unrecoverably, we can rebirth it for you without a ceremony.
-
-A workspace with **no posture fact at all is Managed** — that is the default, and nothing changes for a
-platform that never touches postures.
-
-## Posture B — Sovereign
-
-No OperatorGrant. Your founding key is terminal for your subtree's law. **The teeth:** root's
-`rebirthWorkspace` REFUSES for a Sovereign workspace unless the offer carries **your consent** — a
-`RebirthConsent` fact folded in **your own chain**, signed by your own admin, in your own history. The
-two-key ceremony: the custody act cannot move without BOTH root's law fact AND your consent fact.
-Operator restraint becomes law that replays, not policy you have to trust.
-
-### The honest ceiling (read this)
-
-> The operator controls root's law and could deploy law removing the consent check — but that act is
-> itself a signed, ordered, permanent fact in root's chain, visible to every tenant running `replay root`,
-> and grounds for exit-with-everything. Not "we can't" — "we can't secretly, and you can always leave."
-
-## Declaring and changing your posture
-
-Posture is **law-state in your own chain** (you own the fact), mirrored onto root's lineage record so the
-bailiff can consult it on the hot path without reading every tenant chain. **The tenant chain is
-authoritative — a mirror mismatch fails closed to Sovereign.**
-
-```bash
-# see the current posture, the consent state, and exactly what it means
-githolon posture <platform>
-
-# withdraw the operator grant (Managed → Sovereign) — forward-only; help already given stays in history
-githolon posture set <platform> sovereign --reason "we run our own recovery from here"
-
-# re-invite help (Sovereign → Managed)
-githolon posture set <platform> managed --reason "hand recovery back to the operator"
-```
-
-You can also declare a posture **at birth**: `birthChild` / `createWorkspace` take an optional
-`posture: "managed" | "sovereign"` (default managed), mirrored onto the child's lineage record.
-
-## The consent ceremony (Sovereign rebirth)
-
-When a Sovereign workspace needs a rebirth, the operator plans it but **cannot proceed until you consent
-in your own chain**:
-
-```bash
-# operator: sees the block up front
-githolon rebirth plan <ws>          # GOVERNANCE POSTURE → SOVEREIGN, consent ABSENT → refused pre-seed
-
-# tenant: fold the consent fact in YOUR OWN chain (signed by your admin)
-githolon consent rebirth <ws> --reason "authorising the reborn incarnation" [--expires-at <epoch-ms>]
-
-# operator: now the two-key ceremony is satisfied — the rebirth admits
-githolon rebirth apply --plan rebirths/<date>-<ws>/plan.json --gcp-secret nomos-root-custodian-key
-```
-
-Without a live consent fact, both the CLI (`rebirth apply`) and the custody act itself (a `428` refusal)
-decline and name the exact `githolon consent rebirth` command you need. Consent is forward-only and may
-carry an `expiresAt` window.
-
-## Recursion and exit
-
-A platform is root-for-its-subtree: it offers **its** children the same postures with its founding key in
-the operator role. **Custody does not nest** — a Sovereign sub-platform still rides the grandparent's
-bailiff; true custody independence is self-hosting (clone the ledger, run the byte-identical wasm
-yourself). No level ever rebirths itself; root operations stay the one extra-legal act, always named in
-CLI output.
-
-See also: [08-births.md](./08-births.md) (a Managed heal = "ask us"; a Sovereign heal = consent first) and
-the ratified spec `architecture/governance_postures.md`.

package/template/test/e2e.mts

@@ -1,114 +0,0 @@
-// E2E: the FULL loop against a LIVE Nomos Cloud, driven through the GENERATED TYPED
-// CLIENT (`build/__APP_NAME__.client.ts` — emitted by githolon compile):
-//
-//   compile → create workspace → deploy (package + manifest overlay, ONE POST) →
-//   web client connects → TYPED createList + addTodo LOCALLY (offline writes) →
-//   sync + edge admission → the CLOUD's declared query + count return the work.
-//
-// The docs travel with you, offline: docs/01-mental-model.md first, then
-// docs/03-client.md explains every call here. This file is the NARRATED
-// walkthrough you reshape by hand; its GENERATED sibling — build/__APP_NAME__.proof.mts,
-// emitted by every compile from your own law — needs no rewriting: `githolon proof`.
-//
-// The OFFLINE convergence proof (two peers, blind edits, byte-identical sync, no cloud)
-// lives in test/convergence.local.mjs:  node test/convergence.local.mjs
-//
-// Run from this directory AFTER `npx githolon compile`:  npx tsx test/e2e.mts
-import { readFileSync } from "node:fs";
-import { connect } from "@githolon/client";
-import { todoClient, __APP_HASH__ } from "../build/__APP_NAME__.client.ts";
-
-const CLOUD = (process.env.NOMOS_CLOUD || "https://nomos.captainapp.co.uk").replace(/\/+$/, "");
-const WS = process.env.NOMOS_WS || "todo-e2e-" + Math.random().toString(36).slice(2, 8);
-
-// explicit annotation on the const so TS's never-call narrowing applies after fail(...)
-// IDENTITY NOTE: this proof uses the bare x-nomos-principal lane so the test is
-// SELF-CONTAINED (a throwaway workspace, no stored credentials). Real apps use
-// `githolon login --agent` (a VERIFIED identity) + `githolon ws create/deploy`.
-const fail: (m: string) => never = (m) => { console.error("✗ " + m); process.exit(1); };
-const ok = (m: string) => console.log("✓ " + m);
-
-const deploy = JSON.parse(readFileSync(new URL("../build/__APP_NAME__.deploy.json", import.meta.url), "utf8"));
-
-// 1. create the workspace (capture the ONE-TIME secret)
-let r = await fetch(`${CLOUD}/v1/workspaces/${WS}`, { method: "POST", headers: { "x-nomos-principal": "nomos-e2e-suite" } });
-let d = await r.json();
-if (!d.ok) fail(`create workspace: ${JSON.stringify(d)}`);
-const SECRET: string = d.workspaceSecret;
-if (!SECRET?.startsWith("nws_v1_")) fail(`no workspaceSecret returned: ${JSON.stringify(d)}`);
-ok(`workspace ${WS} created — controller ${d.controller.domainHash.slice(0, 12)}…`);
-
-// ownership: a deploy WITHOUT the secret must be refused
-r = await fetch(`${CLOUD}/v1/workspaces/${WS}/domains`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(deploy) });
-if (r.status !== 401) fail(`unauthenticated deploy was not refused (got ${r.status})`);
-ok("ownership — deploy without the workspace secret refused (401)");
-
-// deploy WITH the secret. The generated client's baked hash IS the deployed law's hash.
-r = await fetch(`${CLOUD}/v1/workspaces/${WS}/domains`, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${SECRET}` }, body: JSON.stringify(deploy) });
-d = await r.json();
-if (!d.ok || d.installation?.[0]?.data?.["status.phase"] !== "Active") fail(`deploy: ${JSON.stringify(d)}`);
-if (d.domainHash !== __APP_HASH__) fail(`deploy hash ${d.domainHash} != generated client's ${__APP_HASH__}`);
-ok(`law deployed Active — ${__APP_HASH__.slice(0, 12)}… (baked into the typed client)`);
-
-// 2. connect a web client (pulls wasm + manifests + ledger) and bind the typed surface
-const holon = await connect({ cloud: CLOUD, workspace: WS, clientId: "owner-1" });
-const app = todoClient(holon);
-ok(`web client connected — typed client bound (replica ${holon.replica.slice(0, 6)}…)`);
-
-// 3. LOCAL-FIRST writes — ENFORCED offline (fetch is trapped; any network touch fails).
-const realFetch = globalThis.fetch;
-globalThis.fetch = (() => { throw new Error("OFFLINE PROOF VIOLATED: local authoring touched the network"); }) as typeof fetch;
-
-// A directive returns the new local HEAD (a string). Aggregate ids are MINTED by the
-// engine — read them back from the declared query. `addTodo.listId` is a plain string
-// the app chooses (the grouping key), so we don't need createList's minted id to wire
-// todos to a list — we just key both on the same `listId`.
-const listId = "list-launch-plan";
-await app.createList({ title: "Launch plan" });
-await app.addTodo({ listId, text: "Draft the deck" });
-await app.addTodo({ listId, text: "Book the venue" });
-ok("typed offline writes — createList + 2 addTodo, under the pulled law");
-
-// the TYPED declared query routes LOCALLY; minted Todo ids come back on the rows
-const seeded = await app.todosByList({ listId });
-if (seeded.length !== 2) fail(`local query: expected 2 todos, got ${seeded.length}`);
-const t1 = seeded.find((row) => row.data.text === "Draft the deck")!.id;
-await app.toggleTodo({ todoId: t1, done: true });            // Lww boolean (t.bool)
-await app.tagTodo({ todoId: t1, tags: ["urgent", "q3"] });   // AddWins set
-ok(`read back a minted Todo id (${t1.slice(0, 16)}…) → toggled done + tagged`);
-
-const localOpen = await app.openTodosByList(listId);
-if (localOpen !== 1) fail(`local count: expected 1 open, got ${localOpen}`);
-ok("local reads route — todosByList = 2, openTodosByList = 1 (2 todos − 1 done), no network");
-
-globalThis.fetch = realFetch;
-ok("offline proof ENFORCED — fetch was trapped: local write/query/count touched no network");
-
-// 4. sync: push the session branch → edge admission merges to canonical main
-const s = await holon.sync();
-if (!s.admission?.ok) fail(`sync/admit: ${JSON.stringify(s)}`);
-ok("synced — session branch admitted onto canonical main");
-
-// 5. the CLOUD answers the declared query + the maintained count from canonical main
-d = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/query?queryId=todosByList&params=${encodeURIComponent(JSON.stringify({ listId }))}`)).json();
-if (!(d.ok && d.rows.length === 2)) fail(`cloud query: ${JSON.stringify(d)}`);
-ok("cloud query — todosByList returned both todos from canonical main");
-d = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/counts/openTodosByList?group=${encodeURIComponent(listId)}`)).json();
-if (!(d.ok && d.count === 1)) fail(`cloud count: ${JSON.stringify(d)}`);
-ok("cloud count — openTodosByList = 1 (the where-filtered O(1) tally, maintained)");
-
-// 6. SHARING — one native Zanzibar tuple. Author it through the owner's secret-gated
-//    /author lane, then read it back from the cloud's audit query.
-r = await fetch(`${CLOUD}/v1/workspaces/${WS}/author`, {
-  method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${SECRET}` },
-  body: JSON.stringify({ domain: "todo", directiveId: "shareList", payload: {
-    listId, userId: "bob", role: "editor", sharedBy: "owner-1", sharedAt: new Date().toISOString() } }),
-});
-d = await r.json();
-if (!d.ok) fail(`shareList author: ${JSON.stringify(d)}`);
-d = await (await fetch(`${CLOUD}/v1/workspaces/${WS}/query?queryId=relationTuplesByObject&params=${encodeURIComponent(JSON.stringify({ object: `TodoList:${listId}` }))}`)).json();
-const editor = (d.rows ?? []).find((u: { data: { relation: string } }) => u.data.relation === "editor");
-if (editor?.data?.subjects?.["user:bob"]?.status !== "active") fail(`sharing tuple not recorded: ${JSON.stringify(d)}`);
-ok("sharing — TodoList#editor@user:bob recorded as a native relation tuple (active)");
-
-console.log(`\nALL GREEN — typed client: compile → deploy → connect → typed offline writes → query/count → admit → cloud reads → native sharing (${WS})`);