create-githolon 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.17.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/04-cloud.md

@@ -22,8 +22,8 @@ the principal births will ride; sessions auto-refresh from
 **Path A — deploy your law** (the cloud births the workspace):
 
 ```bash
-npx githolon ws create <ws>   # birth; the ONE-TIME workspaceSecret is saved to ~/.holon
-npx githolon deploy <ws>      # POST build/<pkg>.deploy.json with the stored secret
+npx githolon ws create <ws>   # birth; NO secret is minted — ownership is a law fact in the chain
+npx githolon deploy <ws>      # POST build/<pkg>.deploy.json, authenticated as your principal
 ```
 
 **Path B — the upload birth** (you birth it, the cloud verifies):
@@ -38,18 +38,23 @@ proves itself either way ([05-superpowers.md](./05-superpowers.md) walks B).
 
 ## Ownership
 
-The workspace secret gates LAW (deploys, retirement, secret rotation). End-user
-apps carry NO secret: reads and session pushes are open, judged by edge
-admission; the session lane structurally refuses control-plane intents. So law
-only ever enters through the secret-gated deploy. Lose the secret? It was
-shown once — `githolon secret rotate` with the current one, or ask the
-operator. Never embed it in an app.
+There is no host secret. Ownership is a LAW FACT bound IN THE CHAIN —
+`sha256(the push password)` written onto the law record at the upload birth (push
+with no password ⇒ born OPEN). Born-ness derives from custody (the ledger has a
+`main`); `/boot` returns no secret. DEPLOY write-authority is judged by the
+KERNEL at the offer gate — you authenticate as a principal the law grants deploy
+authority (`x-nomos-auth`, or transitionally `x-nomos-principal`), not a Bearer
+secret. End-user apps carry no credential: reads and session pushes are open,
+judged by edge admission; the session lane structurally refuses control-plane
+intents. So law only ever enters through a deploy the kernel authorizes. There is
+nothing host-side to rotate (`/rotate-secret` is retired, 410); to re-own, re-birth
+via the upload lane with a new push password — or ask the operator.
 
 ## Dead-letter retry — the operator's unjam
 
 Domain-rejected intents land in the workspace DLQ with full provenance
-(`GET /v1/workspaces/<ws>/dead-letters`, owner-keyed). Ship the law fix via
-the deploy lane, then `POST /v1/workspaces/<ws>/dead-letters/retry?id=` (or
+(`GET /v2/workspaces/<ws>/dead-letters`, owner-keyed). Ship the law fix via
+the deploy lane, then `POST /v2/workspaces/<ws>/dead-letters/retry?id=` (or
 client-side `retryDeadLetter(id)`). The refused work — somebody's actual
 writes — lands on main. DELETE discards, explicitly.
 

package/template/docs/07-security.md

@@ -31,8 +31,9 @@ export const Note = aggregate("Note",
 // (the bindings the read gate reads). Forgetting this is the #1 mistake.
 export const UserPermission = userPermissionAggregate;
 
-// The owner bestows the cap on a reader. Authored through the secret-gated
-// `/author` lane (or `githolon author`) — only the owner can grant.
+// The owner bestows the cap on a reader. Authored through the gateway offer lane
+// (`POST /v2/workspaces/<ws>/grantReader`, authenticated as the owning principal) —
+// write-authority is kernel-judged at the offer gate; there is no host secret.
 export const grantReader = directive("grantReader").ensures(UserPermission)
   .payload(z.object({ principal: z.string(), grantedBy: z.string(), grantedAt: z.string() }))
   .plan((p) => grant({
@@ -71,9 +72,11 @@ How it behaves:
   the maintained projection — cost scales with the number of *identities*, not
   your data volume (revoking one reader over 10k private records stays fast).
 
-The owner grants through the secret-gated lane; your end-user app carries **no
-secret** — its writes are judged by edge admission, and it simply can't author a
-grant. Authority enters only through the owner.
+The owner grants through the gateway offer lane, authenticated as the owning
+principal (write-authority is kernel-judged at the offer gate — no host secret);
+your end-user app carries **no** credential — its writes are judged by edge
+admission, and it simply can't author a grant. Authority enters only through a
+principal the law authorizes.
 
 ## Layer 2 — encrypted fields: operator-blind, end-to-end
 

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).