create-githolon 0.81.0 → 0.83.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.81.0",
+  "version": "0.83.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,77 +29,80 @@ 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).
 
-## FIRST decide the child's cardinality: **instance** or **singleton**
+## Every birth is **keyed** — so you can find the workspace again
 
-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.
+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`**.
 
-| 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).
+> **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 birthEstateChild = directive("birthEstateChild")
-  .creates(EstateOrder)                       // the birth's lineage record on YOUR chain
+export const birthEstate = directive("birthEstate")
+  .creates(EstateBirth)                       // your lineage/audit row
   .payload(z.object({
-    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;
-    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
+    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, estateName: estate, bornAt: p.bornAt } },
+        { domain: "estate",    directiveId: "seedEstate", actor, payload: { estateId: p.estateId, workspaceName: ws, 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)
+  .births()
+  .requires("estateCreator");
 ```
 
-### `birth.singleton` — exactly one child per key (e.g. a home)
+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`
 
-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:
+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
-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 */ ],
-});
+birth.singleton({ keyedBy: p.owner, namespace: "home", genesisChain: (home) => [ /* installs + seed */ ] });
+// app: deriveWorkspaceName('home', owner)
 ```
 
-`keyedBy` may be a compound key (`["user:ada", "team-7"]`, order-sensitive) for one-child-per-pair.
+> ⚠️ **`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 })` 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.)
+(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
 
@@ -125,11 +128,13 @@ relation models your policy; `creator` is the convention `birthChild` uses.)
 
 ## What NOT to do
 
-- **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 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 primitive.
 - **Don't put a clock/random in the plan** — `bornAt` rides the payload (the timestamp doctrine).
@@ -149,7 +154,7 @@ 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/home-delegated-estate` (nomos2
-repo) — it births estates with `birth.instance` (many per owner) and is exercised by
+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