create-githolon 0.80.2 → 0.82.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.80.2",
+  "version": "0.82.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/08-births.md

@@ -29,39 +29,81 @@ A leaf child (a home, an estate item) is born with exactly:
 `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).
 
-## Copy `birthHome` — the canonical template
+## Every birth is **keyed** — so you can find the workspace again
 
-`birthHome` (in `@githolon/dsl`'s framework) is exactly this pattern for the **home** domain. To birth an
-**estate child** (or any leaf running your law), copy it and swap the seed:
+A workspace exists to be **used**, and using it — sync it, open it, place an asset in 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 `estateId`, 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, z } from "@githolon/dsl";
+import { directive, birth, create, z } from "@githolon/dsl";
 
-export const birthEstateChild = directive("birthEstateChild")
-  .creates(EstateChild)                       // the child lineage record on YOUR chain
+export const birthEstate = directive("birthEstate")
+  .creates(EstateBirth)                       // your lineage/audit row
   .payload(z.object({
-    child: z.string().min(1),                 // the child workspace name
-    owner: z.string().min(1),                 // the verified owner (a user:<uid> subject)
-    frameworkHash: z.string().min(1),         // pinned at your governance compile
-    lawHash: z.string().min(1),               // your ESTATE domain law package hash
+    estateId: 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({
-      workspace: p.child,
-      genesisChain: [
+    birth.keyed({
+      key: p.estateId,                        // ← the workspace name is derived from this
+      namespace: "estate",                    // → estate-<sha256(estate ⏎ estateId)[: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: "estate",    directiveId: "seedEstateChild", actor, payload: { owner: p.owner, bornAt: p.bornAt } },
+        { domain: "estate",    directiveId: "seedEstate", actor, payload: { estateId: p.estateId, workspaceName: ws, bornAt: p.bornAt } },
       ],
     });
     return [];
   })
-  .births()                                   // declares the birth — the kernel folds the recipe
-  .requires("creator");                       // the birth authority (see below)
+  .births()
+  .requires("estateCreator");
+```
+
+Then in the app you address that estate from just its id — **no lookup table, no persisted name**:
+
+```dart
+// Dart (nomos_client)
+final ws = deriveWorkspaceName('estate', estateId);
+final session = await engine.open(ws);        // open / sync / place assets — any device, any time
+```
+```ts
+// TS (@githolon/client)
+const ws = await deriveWorkspaceName('estate', estateId);
+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
+`estateWorkspaceForEstateId` — 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
@@ -86,10 +128,15 @@ relation models your policy; `creator` is the convention `birthChild` uses.)
 
 ## What NOT to do
 
-- **Don't ask for a "child-birth primitive."** It already exists — `.births()` + `birth(recipe)`. A home is
-  a first-class workspace; it births children exactly as root births platforms. Recursion is the law.
+- **Don't hand-roll the child's name** (`estate-<sha256(owner)>`, or your own `estateWorkspaceForEstateId`).
+  `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 verb.
+  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
@@ -106,7 +153,9 @@ npx githolon proof        # OFFLINE: drives your .births() directive on the real
 
 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/estate-birth` (nomos2 repo).
+A complete working two-domain births package to copy: `bench/scale/fixtures/home-delegated-estate` (nomos2
+repo) — it births estates with `birth.keyed` (addressable by estate key) and is exercised by
+`bench/scale/home_delegated_estate.smoke.mjs`.
 
 ## Posture at birth
 
@@ -116,3 +165,49 @@ recovered by the operator on request (a rebirth heal = "ask us"); a **Sovereign*
 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 estate 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 estates; U
+holds a **home** holon **H** on-device; U births an estate **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(EstateCreatorGrant)
+  .payload(z.object({ subject: roleSubject, delegationCert: z.string().min(1), grantedBy: roleSubject, grantedAt: z.string() }))
+  .plan((p) => {
+    create(EstateCreatorGrant).set("subject", p.subject).set("grantedAt", p.grantedAt);
+    return writeTuple({ object: "workspace:self", relation: "estateCreator", subject: p.subject, grantedBy: p.grantedBy, grantedAt: p.grantedAt });
+  })
+  .grants("estateCreator")
+  .delegatedRole("estateCreator", { 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 birthEstateWorkspace = directive("birthEstateWorkspace")
+  .creates(EstateBirthOrder).payload(/* … */).plan(/* birth(...) */)
+  .births()
+  .requires("estateCreator"); // ← 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 an estate 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`.