create-githolon 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.18.0",
+  "version": "0.19.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

@@ -0,0 +1,78 @@
+# 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 estate 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, an estate item) 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).
+
+## Copy `birthHome` — the canonical template
+
+`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:
+
+```ts
+import { directive, birth, z } from "@githolon/dsl";
+
+export const birthEstateChild = directive("birthEstateChild")
+  .creates(EstateChild)                       // the child 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
+    bornAt: z.string().min(1),                // ISO-8601, caller-stamped (determinism)
+  }))
+  .plan((p) => {
+    const actor = "user:" + p.owner;
+    birth({
+      workspace: p.child,
+      genesisChain: [
+        { 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 } },
+      ],
+    });
+    return [];
+  })
+  .births()                                   // declares the birth — the kernel folds the recipe
+  .requires("creator");                       // the birth authority (see below)
+```
+
+## 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 estate
+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 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 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.
+- **Don't put a clock/random in the plan** — `bornAt` rides the payload (the timestamp doctrine).