create-githolon 0.98.3 → 0.99.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.98.3",
+  "version": "0.99.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/03-client.md

@@ -63,10 +63,10 @@ The four-layer split (the blessed shape):
   final platform = await engine.open(cloud: cloud, workspace: platformWs);
   final platformClient = await PlatformClient.bind(platform);
 
-  // A `.births()` directive takes NO parent — the parent IS the session workspace:
-  final birth = await platformClient.birthProjectWorkspace(payload: order);
+  // One business birth; the parent is the bound session and Nomos owns the ceremony:
+  final projectRef = await platformClient.birth(project);
   // NomosRef is THE cross-workspace primitive — follow it, bind the next client:
-  final project = await engine.follow(birth.bornRefs.single);
+  final project = await engine.follow(projectRef);
   final projectClient = await ProjectClient.bind(project);
   ```
 

package/template/docs/08-births.md

@@ -1,213 +1,66 @@
-# Birthing child workspaces (law-at-birth)
+# Birth: give a business thing its own life
 
-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.
+Use `birth(Aggregate, spec)` when a business thing should be independently durable, portable, and
+recoverable. Describe the business facts once; Nomos owns the workspace, identity proof, provenance,
+persistence, and recovery beneath it.
 
-## 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 });
+import { Lww, aggregate, birth, t, z } from "@githolon/dsl";
+
+export const Project = aggregate("Project", {
+  reference: t.string().merge(Lww),
+  name: t.string().merge(Lww),
+  country: t.string().merge(Lww),
+});
+
+export const project = birth(Project, {
+  payload: z.object({
+    reference: z.string().min(1),
+    name: z.string().min(1),
+    country: z.string().length(2),
+  }),
+  key: (facts) => facts.reference,
+  plan: (project, facts) => project
+    .set("reference", facts.reference)
+    .set("name", facts.name)
+    .set("country", facts.country),
+});
 ```
 
-`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`:
+The generated client has one birth method:
 
 ```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
+const born = await app.birth({
+  reference: "PROJECT-001",
+  name: "Foundry retrofit",
+  country: "GB",
+});
 ```
 
-(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.)
+`born` is the typed reference to the business root. The call returns only after the birth is committed
+locally and persistence has been requested from the bound Nomos session.
 
-## What NOT to do
+That is the tenant contract. Do not create a birth directive, construct a child address, assemble setup
+steps, or expose framework hashes in application code. Those are framework implementation details.
 
-- **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).
+## One root per domain
 
-## Prove it — the 30-second loop
+A domain declares at most one business birth. This keeps the generated method unambiguous and makes the
+born aggregate the stable root of its workspace. Model other records beneath that root using ordinary
+aggregates and directives.
 
-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:
+## Prove it locally
 
 ```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
+npx githolon compile
+npx githolon proof
 ```
 
-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
-```
+The offline proof drives the real kernel. It checks that the child installs its law in-chain, authors the
+business root, verifies its full history, packs its custody, discards the resident copy, reopens from that
+custody, verifies again, and can still read the root.
 
-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.
+## Framework compatibility
 
-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`.
+The lower-level recipe APIs still exist for Nomos' built-in workspace laws and for older packages. They
+are not the tenant authoring surface. New business domains use `birth(Aggregate, spec)`.