create-githolon 0.98.3 → 0.100.0

package/template/docs/08-births.md

@@ -1,213 +0,0 @@
-# Birthing child workspaces (law-at-birth)
-
-A directive in your law can **birth a child workspace** that is born already running its own domain law.
-A home births project children; a platform births workspaces; root births platforms — all the **same one
-way**. You do *not* ask Nomos for a new primitive and you do *not* hand a finished workspace to the cloud.
-
-## How it works (birth is a kernel concern, defined by the ledger)
-
-Your directive declares `.births()` and, in its `plan`, authors the child's **genesis recipe** — the
-ordered intents the child will run — then calls `birth({ workspace, genesisChain })`. That's it. When the
-parent's offer is admitted, the kernel's birth offer-effect:
-
-1. spawns the child's (empty) custody,
-2. **installs the child's law in-chain** and folds the genesis recipe **through the child's own gate**,
-3. so the child **self-validates from intent 0** — it is not trusted, it proves itself.
-
-The host installs nothing and decides nothing. The recipe is a **ledger fact**, not a runtime trick.
-
-## The leaf recipe = two installs + your seed
-
-A leaf child (a home, a project) is born with exactly:
-
-```
-[ bootstrap/installDomain(<frameworkHash>),   // the bootstrap controller (bytes-by-hash, kernel-resolved)
-  nomos/installDomain(<lawHash>),             // YOUR child's domain law package
-  <your own seed step(s)> ]                   // e.g. seed the owner / initial state
-```
-
-`frameworkHash` + `lawHash` are the content hashes of the two packages, pinned at compile time (the kernel
-resolves the bytes from custody by hash — they are never shipped on the wire).
-
-## Every birth is **keyed** — so you can find the workspace again
-
-A workspace exists to be **used**, and using it — sync it, open it, add a task to it — means **finding it
-again**, often from another device or after a restart. So a born workspace's name is **never** opaque or
-minted-and-forgotten: it is always **derived from a key you already own** (a business id like `projectId`, or
-an owner uid). One verb: **`birth.keyed`**.
-
-> **The one rule.** The name comes from a key you own → the client re-derives the same name from that same
-> key with `deriveWorkspaceName(namespace, key)` → the workspace is addressable **forever, with zero
-> persistence**. Same key ⇒ same workspace (re-birth is idempotent). You never hand-roll a naming scheme, and
-> you never store a minted name to find it later.
-
-```ts
-import { directive, birth, create, z } from "@githolon/dsl";
-
-export const birthProject = directive("birthProject")
-  .creates(ProjectBirth)                      // your lineage/audit row
-  .payload(z.object({
-    projectId: z.string().min(1),             // THE KEY — an id you mint app-side; the workspace is FOR it
-    owner: z.string().min(1),
-    frameworkHash: z.string().min(1),
-    lawHash: z.string().min(1),
-    bornAt: z.string().min(1),                // ISO-8601, caller-stamped (determinism)
-  }))
-  .plan((p) => {
-    const actor = "user:" + p.owner;
-    birth.keyed({
-      key: p.projectId,                       // ← the workspace name is derived from this
-      namespace: "project",                   // → project-<sha256(project ⏎ projectId)[:40]>
-      genesisChain: (ws) => [                 // the builder receives the resolved name
-        { domain: "bootstrap", directiveId: "installDomain", actor, payload: { domainHash: p.frameworkHash }, domainHash: p.frameworkHash, domainPackageB64: "" },
-        { domain: "nomos",     directiveId: "installDomain", actor, payload: { domainHash: p.lawHash },       domainHash: p.lawHash,       domainPackageB64: "" },
-        { domain: "project",   directiveId: "seedProject", actor, payload: { projectId: p.projectId, workspaceName: ws, bornAt: p.bornAt } },
-      ],
-    });
-    return [];
-  })
-  .births()
-  .requires("projectCreator");
-```
-
-Then in the app you address that project from just its id — **no lookup table, no persisted name**:
-
-```dart
-// Dart (nomos_client)
-final ws = deriveWorkspaceName('project', projectId);
-final session = await engine.open(ws);        // open / sync / add tasks — any device, any time
-```
-```ts
-// TS (@githolon/client)
-const ws = await deriveWorkspaceName('project', projectId);
-const holon = await connect({ cloud, workspace: ws, clientId });
-```
-
-`deriveWorkspaceName` computes the byte-identical name the law's `birth.keyed` produced (contract-tested
-across the engine, Dart, and TS). This is the helper that replaces every hand-rolled
-`projectWorkspaceForProjectId` — delete yours and use this.
-
-### One-per-user things (a home): `birth.singleton`
-
-A "singleton" is just a keyed birth whose key is a natural single key — one home per user, so `key = owner`.
-Sugar over `birth.keyed`:
-
-```ts
-birth.singleton({ keyedBy: p.owner, namespace: "home", genesisChain: (home) => [ /* installs + seed */ ] });
-// app: deriveWorkspaceName('home', owner)
-```
-
-> ⚠️ **`birth.instance` is deprecated — don't use it.** It mints a name you throw away, so the born
-> workspace can only be reached via the birth result. There is no workspace you make and never want to find
-> again. Always `birth.keyed` (or `birth.singleton`).
-
-(Raw `birth({ workspace, genesisChain })` stays the low-level escape hatch for a name that is genuinely
-externally-determined — but if you're deriving it from your own data, use `birth.keyed`.)
-
-## From the app (Dart) — parentless, session-bound
-
-The generated Dart client emits a typed method per `.births()` directive, bound to the SESSION whose
-workspace IS the parent — no loose parent string, and the born child comes back as a followable ref:
-
-```dart
-final parentClient = await MyPlatformClient.bind(parentSession);
-final birth = await parentClient.birthProjectChild(payload: order);  // parent = the session workspace
-final child = await engine.follow(birth.bornRefs.single);            // mount the born child
-final childClient = await ProjectClient.bind(child);                 // typed client on the child
-```
-
-(The old `parent:` parameter survives one minor version as a deprecated legacy-gateway shim; its verdict
-rides `outcome.gatewayVerdict`.)
-
-## Authority — who may birth
-
-`.requires("creator")` gates the birth on a relation tuple. Grant the home owner `#creator` on their own
-home (self-bound at birth, the same way the owner is seeded) so a verified owner can birth their project
-children — and only their own. (Relations: `grant` / `writeTuple`, see `07-security.md`. Use whatever
-relation models your policy; `creator` is the convention `birthChild` uses.)
-
-## What NOT to do
-
-- **Don't hand-roll the child's name** (`project-<sha256(owner)>`, or your own `projectWorkspaceForProjectId`).
-  `birth.keyed` owns the naming and `deriveWorkspaceName` gives the client the identical name — hand-rolling
-  either half is how the two drift and a workspace becomes unfindable.
-- **Don't use `birth.instance`.** It's deprecated — it mints a name you can't re-derive, so the workspace is
-  addressable only via the birth result. Every workspace needs to be found again; birth it keyed.
-- **Don't ask for a "child-birth primitive."** It already exists — `.births()` + `birth.keyed`. A home is a
-  first-class workspace; it births children exactly as root births platforms.
-- **Don't hand-roll a second recipe *builder*** across your domains — keep the recipe inline (it's small)
-  or share one tiny helper *in your own code*; the framework deliberately keeps **one** birth primitive.
-- **Don't put a clock/random in the plan** — `bornAt` rides the payload (the timestamp doctrine).
-
-## Prove it — the 30-second loop
-
-Every compile validates your genesis recipe statically (child domain composed in the package? seed
-directive exists? recipe payload satisfies its schema? every plan returns an **array** of ops) and prints
-any problem as a `⚠ births` warning **containing the fix**. Then:
-
-```bash
-npx githolon compile      # ⚠ births warnings = fix these first (the message says how)
-npx githolon proof        # OFFLINE: drives your .births() directive on the real kernel, folds the
-                          # child through its OWN gate, reads the seed back, verify_chain green
-```
-
-A red proof names the exact genesis step the child's gate refused. The most common first-timer halt: a
-plan that returns a fluent builder — builders record themselves, so end the plan with `return [];`.
-A complete working two-domain births package to copy: `bench/scale/fixtures/home-delegated-estate` (nomos2
-repo) — it births child workspaces with `birth.keyed` (addressable by key) and is exercised by
-`bench/scale/home_delegated_estate.smoke.mjs`.
-
-## Posture at birth
-
-`birthChild` / `createWorkspace` take an optional `posture: "managed" | "sovereign"` (default **managed**)
-— the child's declared governance posture, mirrored onto its lineage record. A **Managed** child can be
-recovered by the operator on request (a rebirth heal = "ask us"); a **Sovereign** child's rebirth requires
-the child's own consent fact first (a heal = consent first). See
-[11-governance-postures.md](./11-governance-postures.md) for the two postures, the consent ceremony, and
-the exit rights.
-
-## Offline workspace creation via delegated authority (`delegatedRole` / `.delegatedFrom(parent)`)
-
-Sometimes a CHILD must birth its own children **offline**, under authority a PARENT granted — with no
-contact with the parent at authoring time. Example: a platform **P** lets a user **U** create projects; U
-holds a **home** holon **H** on-device; U births a project **E** as a child of H, offline, gated by H's
-law. The parent's grant cannot be an author-time attested read (that needs connectivity). Instead the
-grant is **delivered into H as a signed cert and folded as a local authority fact** — then read offline.
-
-Author the delivery directive with `.delegatedRole(relation).delegatedFrom(parent)`:
-
-```ts
-export const acceptDelegatedRole = directive("acceptDelegatedRole")
-  .creates(ProjectCreatorGrant)
-  .payload(z.object({ subject: roleSubject, delegationCert: z.string().min(1), grantedBy: roleSubject, grantedAt: z.string() }))
-  .plan((p) => {
-    create(ProjectCreatorGrant).set("subject", p.subject).set("grantedAt", p.grantedAt);
-    return writeTuple({ object: "workspace:self", relation: "projectCreator", subject: p.subject, grantedBy: p.grantedBy, grantedAt: p.grantedAt });
-  })
-  .grants("projectCreator")
-  .delegatedRole("projectCreator", { subjectField: "subject", certField: "delegationCert" })
-  .delegatedFrom({ parentKeyObject: "birth-attestation:self", parentKeyField: "parentKey" }); // H's parent P's key
-
-// the birth itself is gated on the DELIVERED local tuple — read OFFLINE, no parent contact:
-export const birthProjectWorkspace = directive("birthProjectWorkspace")
-  .creates(ProjectBirthOrder).payload(/* … */).plan(/* birth(...) */)
-  .births()
-  .requires("projectCreator"); // ← reads the delegated tuple folded by acceptDelegatedRole
-```
-
-How it works:
-- **The one gate re-verifies P's grant on every lane** (author / edge admission / verify_chain): the
-  carried `DelegationCert` must be signed by a grantor whose key chains to the pinned `K_root`, bind the
-  same `(relation, subject)` the tuple writes, and — `.delegatedFrom(parent)` — whose grantor key IS this
-  workspace's parent key. A forged / mis-bound / wrong-parent grant fails closed. This is the
-  `nomosDelegationGate` era key — a law that declares no `.delegatedRole()` is byte-identical.
-- **The birth is authored OFFLINE**, gated only by H's LOCAL folded tuple; `verify_chain` re-verifies the
-  delegation to `K_root` with no cross-workspace read.
-- **Revocation is forward-only + evidence-preserving.** P delivers a revoke (`removeTuple`, same gate);
-  the folded tuple flips revoked (`RemoveWins`), so U's NEXT birth refuses — but a project born WHILE the
-  grant was live re-verifies green forever (verify_chain re-folds the chain prefix at each intent's
-  position). Both the grant and the revoke are permanent ledger facts.
-
-The platform produces the cert with the `delegation_cert_sign` holon op (grantor secret injected per call,
-never persisted), carrying its lineage to `K_root`; the bailiff delivers it host-free. Worked end-to-end:
-`bench/scale/home_delegated_estate.smoke.mjs`; doctrine: `architecture/delegated_authority_births.md`.

package/template/docs/09-attested-reads.md

@@ -1,87 +0,0 @@
-# 09 — Attested cross-workspace reads (slice B)
-
-Your law can gate a write on a FACT IN ANOTHER WORKSPACE — without ever trusting the host,
-and without any peer opening the foreign chain at replay. The source's kernel SIGNS the
-answer; your law declares whose signature it trusts; every door (author, edge admission,
-`verify_chain` forever) re-verifies the signed envelope.
-
-## Declare the trust edge in law
-
-```ts
-import { z, directive, read, trustSource, foreignQuery } from "@githolon/dsl";
-
-const platformPolicy = foreignQuery("platformPolicy"); // the SOURCE's declared query, by id
-
-// module level — the trust boundary IS law (rides the domainHash):
-export const platformTrust = trustSource("acme-platform", {
-  genesis: "9d1c…",            // the source's genesis oid (its true identity — names are routing)
-  keyHashes: ["41aa…"],        // sha256 of the source's read-attestor public key(s)
-  maxAgeMs: 86_400_000,        // how stale an envelope may be vs the intent's own clock
-  minSourceEpoch: "birth",
-  monotone: true,              // refuse an answer older than one this chain already saw
-});
-
-export const enrollDevice = directive("enrollDevice")
-  .creates(HomeDevice)
-  .payload(z.object({ device: z.string() }))
-  .readsFrom("acme-platform", platformPolicy)   // the declared foreign read
-  .plan((p) => {
-    const rows = read(platformPolicy, { scope: "homes" }, { from: "acme-platform" });
-    if (rows[0]?.data?.enrollmentOpen !== "true") throw new Error("enrollment closed");
-    create(HomeDevice).set("device", p.device);
-    return [];
-  });
-```
-
-## Who fetches the evidence? THE AUTHOR — never the host
-
-The host never initiates a fetch (that would be orchestration — host-purge doctrine). Three
-lanes, in precedence order:
-
-1. **Carried** — the offer already contains `attestations: [{queryId, result, attestation}]`.
-   The gate judges the carried envelope; nothing ever replaces it.
-2. **Colocated (kernel-internal)** — when the source workspace is mounted in the SAME engine
-   instance (the container pool colocates workspaces), the engine plane serves + signs the
-   read in-kernel and injects it. Zero HTTP. The envelope is byte-identical to the HTTP lane —
-   colocation is invisible to the gate.
-3. **Client-carried (`?attest=1`)** — otherwise the CLIENT pre-fetches from the source's open
-   read lane and carries the envelope on the offer.
-
-## `@githolon/client` does the dance for you
-
-```ts
-const holon = await connect({ cloud, workspace, clientId,
-  attestedSources: { "acme-platform": "https://nomos.captainapp.co.uk" } }); // optional override
-await holon.dispatch("home", "enrollDevice", { device: "d-1" });
-// → the kernel refuses TYPED naming the missing read; the client fetches
-//   GET <sourceCloud>/v2/workspaces/acme-platform/platformPolicy?scope=homes&attest=1
-//   injects the signed envelope, retries — automatically.
-```
-
-**Offline:** if the source is unreachable, the offer FAILS with the named
-`attested-read-unreachable` error. There is NO stale fallback — a plan without its live
-premise cannot author. Retry when the source is reachable. You can also pre-fetch ahead of
-time (`holon.fetchAttestedRead(from, queryId, args)`) and pass
-`dispatch(..., { attestations: [entry] })`.
-
-## The two-step dance for THIN clients (raw HTTP, no SDK)
-
-1. `POST /v2/workspaces/<ws>/<directiveId>` with your payload. If the law declares foreign
-   reads and your body carries no matching attestation, you get **422** with:
-   `attested-read-unreachable: read('<queryId>', {from: '<source>'}) args={…} has no injected
-   attestation — pre-fetch it from the source's open read lane (?attest=1 …)`.
-2. `GET /v2/workspaces/<source>/<queryId>?<args>&attest=1` → `{ok, rows, attestation}` —
-   the source KERNEL signed it; the host relayed opaque bytes. Retry the POST with
-   `"attestations": [{"queryId": "<queryId>", "result": <rows>, "attestation": <attestation>}]`
-   in the body (it rides beside your payload fields, not inside them).
-
-No server fills this in for you — the refusal is the kernel INSTRUCTING you what evidence to
-carry. That is the design, not a limitation: the author carries the premise; every replayer
-verifies the signature forever, offline.
-
-## What the gate checks (every door, every peer, forever)
-
-declared edge ✓ → key hash ∈ your law's pins ∧ genesis matches ∧ signature verifies over the
-result ✓ → size bounds ✓ → freshness (`maxAgeMs` vs the intent's frozen clock, `minSourceEpoch`,
-the `monotone` frontier) ✓ → the plan re-runs with the replayed capture and byte-compares.
-A forged/tampered/stale/wrong-key envelope is a TYPED refusal. No peer ever contacts the source.

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})`);