create-githolon 0.80.1 → 0.81.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.80.1",
+  "version": "0.81.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,18 +29,36 @@ 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
+## FIRST decide the child's cardinality: **instance** or **singleton**
 
-`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 born child's workspace name **is its identity**, so before you write the birth you must answer one
+question: *can a parent have MANY of these children, or exactly ONE per key?* The DSL makes you state the
+answer at the call site — the same way a field states its merge driver — so you can't get it wrong by
+accident. Do **not** hand-roll the name.
+
+| You want… | Use | Naming | Re-birth |
+|---|---|---|---|
+| **Many children per parent** (a user has many estates, a project has many docs) | `birth.instance({ from, … })` | Nomos **mints** the child id from a `create()`d record — unique, captured, unforgeable | each call is a **new** child |
+| **Exactly one child per key** (one home per user, one settings-workspace per team) | `birth.singleton({ keyedBy, … })` | **derived** deterministically from the key | idempotent — same key ⇒ **same** child |
+
+> ⚠️ **The trap:** births are deterministic (no `Math.random`/`Date.now` in a plan), so the tempting move
+> is to derive the name from a stable field — `estate-<sha256(owner)>`. That silently caps the owner at
+> **one** estate forever. If you find yourself hashing a field to name a child, you almost always want
+> `birth.instance` (many) — reach for a derived name **only** when one-per-key is the actual intent, and
+> then let `birth.singleton` derive it for you.
+
+### `birth.instance` — many children per parent (the common case)
+
+The child's id is **minted**, exactly like `create(Agg)` mints an aggregate id: you `create()` a record for
+the birth (the audit/lineage row you'd want anyway) and its captured id names the child. It's unique by
+construction and reproduces byte-identically at `verify_chain` (the minted id rides the committed intent).
 
 ```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
+  .creates(EstateOrder)                       // the birth's lineage record on YOUR chain
   .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
@@ -48,20 +66,41 @@ export const birthEstateChild = directive("birthEstateChild")
   }))
   .plan((p) => {
     const actor = "user:" + p.owner;
-    birth({
-      workspace: p.child,
-      genesisChain: [
+    const order = create(EstateOrder).set("owner", p.owner).set("bornAt", p.bornAt);
+    const child = birth.instance({
+      from: order,                            // the child's id IS this record's minted id (no name to invent)
+      prefix: "estate-",                      // optional, human-legible
+      genesisChain: (estate) => [            // the builder receives the resolved child 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: "seedEstateChild", actor, payload: { owner: p.owner, estateName: estate, bornAt: p.bornAt } },
       ],
     });
+    order.set("workspaceName", child);        // record the minted name on the lineage row
     return [];
   })
   .births()                                   // declares the birth — the kernel folds the recipe
   .requires("creator");                       // the birth authority (see below)
 ```
 
+### `birth.singleton` — exactly one child per key (e.g. a home)
+
+The framework's own `birthHome` is a singleton: one home per user, `home-<hash(owner)>`, idempotent. That is
+the *correct* use of a derived name — and `birth.singleton` derives it for you:
+
+```ts
+const home = birth.singleton({
+  keyedBy: p.owner,                           // one home per owner; re-birth is a no-op (same name)
+  namespace: "home",                          // → home-<hash>
+  genesisChain: (home) => [ /* installs + seed the owner, using `home` as the name */ ],
+});
+```
+
+`keyedBy` may be a compound key (`["user:ada", "team-7"]`, order-sensitive) for one-child-per-pair.
+
+(Raw `birth({ workspace, genesisChain })` remains the low-level escape hatch for a name that is genuinely
+externally-determined — but if you're deriving it from your own data, use one of the two verbs above.)
+
 ## 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 +125,13 @@ 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 from a field** (`estate-<sha256(owner)>`). That is the cardinality
+  trap — it caps the parent at one child per key. Use `birth.instance` (many) or `birth.singleton` (one);
+  they own the naming so you can't collapse it by accident.
+- **Don't ask for a "child-birth primitive."** It already exists — `.births()` + `birth.instance` /
+  `birth.singleton`. 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 +148,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.instance` (many per owner) and is exercised by
+`bench/scale/home_delegated_estate.smoke.mjs`.
 
 ## Posture at birth
 
@@ -116,3 +160,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`.