create-githolon 0.69.3 → 0.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.69.3",
+  "version": "0.70.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/02-authoring.md

@@ -264,6 +264,54 @@ Cloud's own usage tenant folds a reading AND its budget meter in ONE intent —
 so the budget invariant judges both together: a reading that would leave the
 meter over an unacked threshold refuses, and the sample refuses WITH it.
 
+## Roles — sugar over relations (the kernel is the authority)
+
+A `role(...)` is the highest-level authz surface: it LOWERS onto the ONE ReBAC
+spine (relation tuples + the kernel gate). It is pure sugar — there is NO
+role-array membership check anywhere; every capability is a relation tuple the
+kernel judges.
+
+```ts
+import { role, aggregate, t, Lww, requires, directive, create } from "@githolon/dsl";
+
+export const editor = role("editor");                 // .edit / .view refs available immediately
+
+export const Note = aggregate("Note",
+  { author: t.string().merge(Lww), body: t.string().merge(Lww) },
+  { visibility: requires(editor.view) });             // Note is private behind the role's VIEW cap
+
+// EMIT the role's grant/revoke/seed directives + relation schema (auto-discovered by shape):
+export const noteRoles = editor.canEdit(Note).canView(Note).grantableBy("admin").emit();
+
+// Wire the role's EDIT ref onto a mutating directive — only an editor may write:
+export const editNote = directive("editNote")
+  .creates(Note)
+  .payload(z.object({ author: z.string().min(1), body: z.string().min(1) }))
+  .plan((p) => { create(Note).set("author", p.author).set("body", p.body); return []; })
+  .requires(editor.edit);
+```
+
+What `editor…emit()` gives you:
+
+- **Relation schema with TEETH** — the `editorEdit` write relation is authored
+  into the law, so `.requires(editor.edit)` never fails open (the fail-open
+  footgun is closed); `editorView` is a read-visibility cap (wire it as an
+  aggregate `requires(editor.view)`).
+- **Grant / revoke / seed directives** — `grantEditor` / `revokeEditor` seat or
+  remove the role's relation tuple, gated `.requires("admin")` (the kernel judges
+  the granter). `seedEditor` seats the `admin` grant-authority on a founding
+  principal at genesis/birth (ungated seed lane).
+- **Typed policy refs** — `editor.edit` / `editor.view` (never strings) for
+  `.requires(...)` and aggregate visibility.
+- **`canEdit<Agg>` / `canView<Agg>` codegen** (TS + Dart) — UI-hint helpers that
+  mirror the kernel's check over the folded tuples. **INFORMATIONAL only — the one
+  wasm gate is the authority and refuses regardless of what the helper returns.**
+  Use them to grey out a button, never to decide access.
+
+Roles are workspace-scoped (the read-visibility gate is workspace-scoped in the
+kernel). Per-record grants stay available via the lower-level
+`.requires(rel, { objectFrom })` axis. `grantableBy` defaults to `admin`.
+
 ## Determinism or death
 
 A plan is a PURE function of its payload. No `Date.now()`, no

package/template/docs/08-births.md

@@ -92,3 +92,12 @@ 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).
+
+## Posture at birth
+
+`birthChild` / `createWorkspace` take an optional `posture: "managed" | "sovereign"` (default **managed**)
+— the child's declared governance posture, mirrored onto its lineage record. A **Managed** child can be
+recovered by the operator on request (a rebirth heal = "ask us"); a **Sovereign** child's rebirth requires
+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.

package/template/docs/11-governance-postures.md

@@ -0,0 +1,89 @@
+# Governance postures — Managed and Sovereign
+
+Every platform you run on Nomos Cloud **declares a governance posture**. It decides one thing: **may the
+operator (the root custodian) run recovery verbs — rebirth, certifyEra, repairs — FOR your workspace
+without asking you first?** Both postures are first-class; you choose, and you can change your mind.
+
+The honest foundation, stated plainly and never hidden:
+
+- **Validity sovereignty is absolute for everyone.** Holons self-verify. The operator can *act* but can
+  never *lie* — every operator act is a signed, ordered, permanent fact in root's replayable chain.
+- **Custody power is irreducibly the host's while you are hosted.** No cryptography stops a landlord
+  changing the locks. What Nomos gives you is **detectability** (a custody break fails closed) and
+  **exit** (clone the ledger and leave — the byte-identical wasm makes self-hosting the ultimate exit).
+- Therefore **hosted sovereignty = law-encoded restraint + total detectability + credible exit.** Never
+  prevention.
+
+## Posture A — Managed (the default)
+
+Your platform's law folds an **OperatorGrant**: the root custodian may run recovery verbs for you — each
+a signed, attributed law fact + certificate you audit forever. This is *the assurance of being able to
+ask us for help*: if your chain scars unrecoverably, we can rebirth it for you without a ceremony.
+
+A workspace with **no posture fact at all is Managed** — that is the default, and nothing changes for a
+platform that never touches postures.
+
+## Posture B — Sovereign
+
+No OperatorGrant. Your founding key is terminal for your subtree's law. **The teeth:** root's
+`rebirthWorkspace` REFUSES for a Sovereign workspace unless the offer carries **your consent** — a
+`RebirthConsent` fact folded in **your own chain**, signed by your own admin, in your own history. The
+two-key ceremony: the custody act cannot move without BOTH root's law fact AND your consent fact.
+Operator restraint becomes law that replays, not policy you have to trust.
+
+### The honest ceiling (read this)
+
+> The operator controls root's law and could deploy law removing the consent check — but that act is
+> itself a signed, ordered, permanent fact in root's chain, visible to every tenant running `replay root`,
+> and grounds for exit-with-everything. Not "we can't" — "we can't secretly, and you can always leave."
+
+## Declaring and changing your posture
+
+Posture is **law-state in your own chain** (you own the fact), mirrored onto root's lineage record so the
+bailiff can consult it on the hot path without reading every tenant chain. **The tenant chain is
+authoritative — a mirror mismatch fails closed to Sovereign.**
+
+```bash
+# see the current posture, the consent state, and exactly what it means
+githolon posture <platform>
+
+# withdraw the operator grant (Managed → Sovereign) — forward-only; help already given stays in history
+githolon posture set <platform> sovereign --reason "we run our own recovery from here"
+
+# re-invite help (Sovereign → Managed)
+githolon posture set <platform> managed --reason "hand recovery back to the operator"
+```
+
+You can also declare a posture **at birth**: `birthChild` / `createWorkspace` take an optional
+`posture: "managed" | "sovereign"` (default managed), mirrored onto the child's lineage record.
+
+## The consent ceremony (Sovereign rebirth)
+
+When a Sovereign workspace needs a rebirth, the operator plans it but **cannot proceed until you consent
+in your own chain**:
+
+```bash
+# operator: sees the block up front
+githolon rebirth plan <ws>          # GOVERNANCE POSTURE → SOVEREIGN, consent ABSENT → refused pre-seed
+
+# tenant: fold the consent fact in YOUR OWN chain (signed by your admin)
+githolon consent rebirth <ws> --reason "authorising the reborn incarnation" [--expires-at <epoch-ms>]
+
+# operator: now the two-key ceremony is satisfied — the rebirth admits
+githolon rebirth apply --plan rebirths/<date>-<ws>/plan.json --gcp-secret nomos-root-custodian-key
+```
+
+Without a live consent fact, both the CLI (`rebirth apply`) and the custody act itself (a `428` refusal)
+decline and name the exact `githolon consent rebirth` command you need. Consent is forward-only and may
+carry an `expiresAt` window.
+
+## Recursion and exit
+
+A platform is root-for-its-subtree: it offers **its** children the same postures with its founding key in
+the operator role. **Custody does not nest** — a Sovereign sub-platform still rides the grandparent's
+bailiff; true custody independence is self-hosting (clone the ledger, run the byte-identical wasm
+yourself). No level ever rebirths itself; root operations stay the one extra-legal act, always named in
+CLI output.
+
+See also: [08-births.md](./08-births.md) (a Managed heal = "ask us"; a Sovereign heal = consent first) and
+the ratified spec `architecture/governance_postures.md`.