@githolon/dsl 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/births.ts

@@ -50,6 +50,30 @@ export function __drainBirths(): BirthRecipe[] {
  * kernel executes the birth ONLY for a directive its resolved law names there (the era rule: pre-feature
  * chains carry no key, so they replay byte-green and the kernel does nothing). A plan may birth at most one
  * child per intent (one offer, one defined consequence — the unix model).
+ *
+ * TO BIRTH A LEAF CHILD RUNNING ITS OWN LAW (a home, an estate child) — copy `framework/home.ts`'s
+ * `birthHome`. The recipe is just the two-layer law install + your own seed step; there is NO helper to
+ * fabricate it and you do NOT need a new primitive (recursion is the law — a home births children exactly
+ * as root births platforms). `buildGenesisChain` is the ONE builder for the PLATFORM shape (it adds the
+ * `seedGenesis → grantAdmin → birthCloud` tail); a leaf just omits that tail:
+ *
+ * ```ts
+ * export const birthEstateChild = directive("birthEstateChild")
+ *   .creates(EstateChild)
+ *   .payload(z.object({ child: z.string(), owner: z.string(),
+ *     frameworkHash: z.string(), lawHash: z.string(), bornAt: z.string() }))
+ *   .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()             // the kernel's run_birth_effect folds the recipe through the CHILD's own gate
+ *   .requires("creator"); // grant the parent's owner #creator (self-bound) — the birth authority
+ * ```
  */
 export function birth(recipe: BirthRecipe): void {
   footprint.push(recipe);

package/src/codegen_proof.ts

@@ -42,6 +42,10 @@ import type { DomainModule } from "./codegen_dart.js";
 import type { QueryDecl } from "./query.js";
 import { finishCount } from "./count.js";
 import { mintedCreateField } from "./workspace_routing.js";
+import { deterministicPorts } from "./ctx.js";
+import { __resetBirths, __drainBirths } from "./births.js";
+import { __resetAuthoring, __drainAuthoring } from "./authoring.js";
+import { __resetReads, __drainReads } from "./read.js";
 import {
   autoStampFields,
   tsClientFactoryName,
@@ -179,6 +183,223 @@ function findConcurrencyLeg(
   return undefined;
 }
 
+// ── child-birth discovery (the G3 `.births()` lane — prove a parent birth end-to-end into the child) ──────
+
+/** ONE step of a discovered birth recipe's genesis chain (the subset codegen reads). */
+interface DiscoveredGenesisStep {
+  readonly domain: string;
+  readonly directiveId: string;
+}
+
+/** A discovered CHILD-BIRTH leg: a parent `.births()` directive proven end-to-end into the child it births
+ *  (install the framework + child law in-chain → run the child genesis seed → mount the born child →
+ *  verify it). The runtime obtains the actual born WORKSPACE NAME from the offer's `born` result (the recipe
+ *  workspace is plan-derived — often `…-<sha256(owner)>` — so it is not statically known), and injects the
+ *  REAL `frameworkHash`/`lawHash` (the local wasm's controller hash + the package domainHash) onto the
+ *  synthesized payload (the synthesizer only produces `sample-*` placeholders, which the child install
+ *  would refuse). */
+export interface ChildBirthLeg {
+  /** The domain the `.births()` directive lives in. */
+  readonly parentDomain: string;
+  /** The `.births()` directive id the parent drives to birth the child. */
+  readonly birthDirectiveId: string;
+  /** The synthesized parent payload (auto-stamped `…At` omitted; `frameworkHash`/`lawHash` placeholders
+   *  REMOVED — the runtime injects the real hashes onto these fields by name). */
+  readonly birthPayload: Record<string, unknown>;
+  /** Required `…At` fields the runtime stamps with ISO now() at dispatch (mirrors the create leg). */
+  readonly birthAutoStamped: readonly string[];
+  /** The payload field that carries the bootstrap framework-controller hash (runtime: the local wasm's own
+   *  controller hash) — discovered from the recipe's `bootstrap/installDomain` step's payload, by matching
+   *  the field whose synthesized value the recipe routed there. `undefined` ⇒ the recipe hard-codes it. */
+  readonly frameworkHashField?: string;
+  /** The payload field that carries the child law hash (runtime: the deployed package domainHash). */
+  readonly lawHashField?: string;
+  /** The CHILD domain key the recipe's seed step targets (e.g. `estate`) — the child-only law installed
+   *  by this birth. This is what makes a child-only domain proof-addressable (gaps 1+3). */
+  readonly childDomain: string;
+  /** The child genesis SEED directive the recipe runs (e.g. `seedEstateWorkspace`). */
+  readonly childSeedDirectiveId: string;
+  /** The aggregate the child seed `.ensures`/`.creates` (e.g. `EstateOwner`) — read back to prove the seed ran. */
+  readonly childSeedAggregateId?: string;
+  /** The instance id the child seed writes, when it is a fixed singleton (`<Agg>:self` / a constant id) —
+   *  lets the proof read the seeded record by id with no query. `undefined` ⇒ fall back to the child query. */
+  readonly childSeedInstanceId?: string;
+  /** A child declared query that reads the seed back (returns the seed aggregate). `undefined` ⇒ by-id only. */
+  readonly childQuery?: { readonly id: string; readonly key: readonly string[] };
+}
+
+/** A stub `nomos` global (mint + sha256) so a `.births()` plan that mints / hashes a child name runs to
+ *  completion at codegen. The hash is a deterministic STUB (the codegen never needs the real digest — the
+ *  recipe's workspace is read at RUNTIME from the offer's `born`); mint mirrors `harvestPrincipalFlows`. */
+function withBirthProbeGlobals<T>(run: () => T): T {
+  const g = globalThis as unknown as { nomos?: { mint?: (t: string) => string; sha256?: (s: string) => string; read?: unknown } };
+  const had = "nomos" in g;
+  const prior = g.nomos;
+  g.nomos = {
+    ...(prior ?? {}),
+    mint: (typeTag: string) => `${typeTag}_0192f00d-0000-7000-8000-000000000000`,
+    // A deterministic 64-hex STUB digest (length-stable so a `.slice(0, n)` name template still works).
+    sha256: (s: string) => {
+      let h = 2166136261 >>> 0;
+      for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 16777619) >>> 0; }
+      return h.toString(16).padStart(8, "0").repeat(8);
+    },
+  };
+  try {
+    return run();
+  } finally {
+    if (had && prior !== undefined) g.nomos = prior; else delete g.nomos;
+  }
+}
+
+/**
+ * Discover the CHILD-BIRTH leg a `.births()` directive declares: run its plan with a synthesized payload +
+ * the birth-probe globals, drain the recorded birth recipe (`birth(recipe)` → `__drainBirths`), and read the
+ * recipe's genesis chain to learn the CHILD domain + seed directive + the framework/law install fields.
+ *
+ * This is the SAME compile-time plan-execution technique `harvestPrincipalFlows` (the endorse discovery) and
+ * `directiveRoutes`/`codegen_dart` already use — the plan is a pure function of (payload, ports). Best-effort:
+ * a plan that can't be probed (or doesn't record a 3-step `installDomain×2 + seed` leaf recipe) returns
+ * `undefined` and the directive proves only `compile-valid`. Never throws (drains the sinks on any path).
+ */
+export function discoverChildBirthLeg(
+  birthDir: Directive<unknown>,
+  parentDomain: string,
+  modules: readonly DomainModule[],
+): ChildBirthLeg | undefined {
+  if (birthDir.birthsChild !== true) return undefined;
+  let recipe: { workspace?: unknown; genesisChain?: unknown } | undefined;
+  let synth: SynthesizedPayload;
+  try {
+    synth = synthesizePayload(birthDir.payloadSchema as z.ZodTypeAny, `${parentDomain}/${birthDir.id}`);
+  } catch {
+    return undefined;
+  }
+  // The plan needs concrete payload VALUES for every field it reads to build the recipe (frameworkHash /
+  // lawHash / owner …). The synthesizer omits `…At` (auto-stamped) + optional fields; fill the auto-stamped
+  // ones with a probe ISO string so the plan runs (the values are irrelevant to discovery — only the recipe
+  // SHAPE is read).
+  const probePayload: Record<string, unknown> = { ...synth.value };
+  for (const f of synth.autoStamped) probePayload[f] = "2026-01-01T00:00:00Z";
+  try {
+    withBirthProbeGlobals(() => {
+      __resetAuthoring();
+      __resetReads();
+      __resetBirths();
+      try {
+        birthDir.plan(probePayload as never, deterministicPorts({ physical: 1, replica: 1, principal: "principal:probe" }));
+      } finally {
+        try { __drainAuthoring(); __drainReads(); } catch { /* sinks may be drained */ }
+      }
+      const drained = __drainBirths();
+      recipe = drained[0] as typeof recipe;
+    });
+  } catch {
+    return undefined;
+  }
+  if (recipe === undefined || !Array.isArray(recipe.genesisChain)) return undefined;
+  const chain = recipe.genesisChain as DiscoveredGenesisStep[];
+  // The child seed = the FIRST genesis step that is neither bootstrap nor nomos installDomain (the leaf's
+  // own seed). A platform-shaped recipe (seedGenesis → grantAdmin → birthCloud tail) is out of scope here —
+  // we prove the LEAF birth shape (install×2 + one seed), the home/estate composable case.
+  const seedStep = chain.find(
+    (s) => s !== null && typeof s === "object" && s.directiveId !== "installDomain"
+      && s.domain !== "bootstrap" && s.domain !== "nomos",
+  );
+  if (seedStep === undefined) return undefined;
+  const childDomain = seedStep.domain;
+  const childSeedDirectiveId = seedStep.directiveId;
+
+  // Resolve the child seed's aggregate + singleton id + read query from the CHILD domain module (so the
+  // child read-model leg reads the right thing). The child law is in THIS package (the one-package pattern
+  // — the parent folds it so the kernel can route its bytes by hash).
+  const childMod = modules.find((m) => (m.domain ?? m.name) === childDomain);
+  let childSeedAggregateId: string | undefined;
+  let childSeedInstanceId: string | undefined;
+  let childQuery: ChildBirthLeg["childQuery"];
+  if (childMod !== undefined) {
+    const seedDir = (childMod.directives as Directive<unknown>[]).find((d) => d?.id === childSeedDirectiveId);
+    if (seedDir !== undefined) {
+      childSeedAggregateId = seedDir.aggregateId;
+      childSeedInstanceId = discoverSingletonInstanceId(seedDir);
+      const q = ((childMod.queries ?? []) as QueryDecl[]).find((qq) => qq.returns === seedDir.aggregateId && qq.key.length > 0);
+      if (q !== undefined) childQuery = { id: q.id, key: q.key };
+    }
+  }
+
+  // The framework/law install FIELDS: which parent-payload field the recipe routed into each install step's
+  // `domainHash`. The recipe step's payload value === the parent payload value for that field — match by value.
+  const installSteps = chain.filter((s) => s !== null && typeof s === "object" && s.directiveId === "installDomain") as Array<DiscoveredGenesisStep & { payload?: { domainHash?: unknown } }>;
+  const fieldForValue = (v: unknown): string | undefined =>
+    Object.entries(synth.value).find(([, sv]) => sv === v && typeof v === "string" && v.length > 0)?.[0];
+  const bootstrapStep = installSteps.find((s) => s.domain === "bootstrap");
+  const nomosStep = installSteps.find((s) => s.domain === "nomos");
+  const frameworkHashField = bootstrapStep ? fieldForValue(bootstrapStep.payload?.domainHash) : undefined;
+  const lawHashField = nomosStep ? fieldForValue(nomosStep.payload?.domainHash) : undefined;
+
+  // The parent payload the leg dispatches: the synthesized values MINUS the framework/law-hash placeholders
+  // (the runtime injects the REAL hashes onto those fields by name — a `sample-*` hash would fail the child
+  // install) MINUS the auto-stamped fields (stamped at dispatch).
+  const birthPayload: Record<string, unknown> = { ...synth.value };
+  if (frameworkHashField !== undefined) delete birthPayload[frameworkHashField];
+  if (lawHashField !== undefined) delete birthPayload[lawHashField];
+
+  return {
+    parentDomain,
+    birthDirectiveId: birthDir.id,
+    birthPayload,
+    birthAutoStamped: synth.autoStamped,
+    ...(frameworkHashField !== undefined ? { frameworkHashField } : {}),
+    ...(lawHashField !== undefined ? { lawHashField } : {}),
+    childDomain,
+    childSeedDirectiveId,
+    ...(childSeedAggregateId !== undefined ? { childSeedAggregateId } : {}),
+    ...(childSeedInstanceId !== undefined ? { childSeedInstanceId } : {}),
+    ...(childQuery !== undefined ? { childQuery } : {}),
+  };
+}
+
+/** Discover the SINGLETON instance id a seed directive writes (a fixed `<Agg>:self`-shaped id), by running
+ *  its plan with a probe payload + birth-probe globals and reading the first written op's instance id when
+ *  it is a constant (the same id across two distinct probe payloads). `undefined` ⇒ not a fixed singleton. */
+function discoverSingletonInstanceId(seedDir: Directive<unknown>): string | undefined {
+  const idsFor = (seed: number): string | undefined => {
+    let synth: SynthesizedPayload;
+    try {
+      synth = synthesizePayload(seedDir.payloadSchema as z.ZodTypeAny, `seed/${seedDir.id}`);
+    } catch {
+      return undefined;
+    }
+    const payload: Record<string, unknown> = { ...synth.value };
+    for (const f of synth.autoStamped) payload[f] = `2026-0${seed}-01T00:00:00Z`;
+    // Make string fields distinct per-seed so a payload-derived id would DIFFER across runs (a true
+    // singleton id is constant regardless).
+    for (const [k, v] of Object.entries(payload)) if (typeof v === "string" && !synth.autoStamped.includes(k)) payload[k] = `${v}-${seed}`;
+    let id: string | undefined;
+    withBirthProbeGlobals(() => {
+      __resetAuthoring();
+      __resetReads();
+      __resetBirths();
+      try {
+        const returned = seedDir.plan(payload as never, deterministicPorts({ physical: seed, replica: 1 }));
+        const ops = [...__drainAuthoring(), ...(Array.isArray(returned) ? returned : [])];
+        const first = ops.find((o) => (o as { aggregateId?: string }).aggregateId !== undefined) as { aggregateId?: string } | undefined;
+        id = first?.aggregateId;
+      } catch {
+        id = undefined;
+      } finally {
+        try { __drainReads(); __drainBirths(); } catch { /* drained */ }
+      }
+    });
+    return id;
+  };
+  const a = idsFor(1);
+  const b = idsFor(2);
+  // A fixed singleton: a non-empty id that does NOT vary with the payload AND isn't a per-instance type tag
+  // (a TYPE id equals the aggregate type — that's the legacy one-per-workspace shape, also fine to read by id).
+  return a !== undefined && a === b ? a : undefined;
+}
+
 // ── the generator ─────────────────────────────────────────────────────────────────
 
 export interface TsProofOptions {
@@ -188,28 +409,51 @@ export interface TsProofOptions {
   readonly domainHash: string;
 }
 
+/** THE PROOF TAXONOMY (co2 feedback): which legs a domain carries.
+ *   · `compile-valid`        — the law compiled (always — every compiled domain is at least this).
+ *   · `standalone-provable`  — a `.creates` write proven offline (dispatch → declared query/count locally).
+ *   · `child-birth-provable` — a `.births()` directive proven END-TO-END into the child it births.
+ *   · `live-cloud-provable`  — the full cloud loop (the `.mts` `--live` lane) completes (the primary domain). */
+export type ProofKind = "compile-valid" | "standalone-provable" | "child-birth-provable" | "live-cloud-provable";
+
 /** The machine-readable OFFLINE legs for ONE domain (the `@nomos-proof-legs`
  *  marker shape; the `proof-legs.json` index is a map of these by domain key). */
 export interface ProofLegs {
   readonly domain: string;
-  readonly directiveId: string;
-  readonly aggregateId: string;
-  readonly payload: Record<string, unknown>;
-  readonly autoStamped: readonly string[];
+  /** THE TAXONOMY (co2 feedback) — the legs this domain has, in proof order. EVERY domain has at least
+   *  `compile-valid`. OPTIONAL + ADDITIVE: an older-compiler legs file without it is treated as
+   *  `["standalone-provable"]` (it only emitted standalone-provable domains). */
+  readonly legs?: readonly ProofKind[];
+  /** The standalone-create directive id — present iff this domain is `standalone-provable`. */
+  readonly directiveId?: string;
+  readonly aggregateId?: string;
+  readonly payload?: Record<string, unknown>;
+  readonly autoStamped?: readonly string[];
   readonly mintField?: string;
   readonly query?: { readonly id: string; readonly params: Record<string, unknown> };
   readonly count?: { readonly id: string; readonly group: string };
+  /** THE CHILD-BIRTH LEG — present iff this domain has a `.births()` directive (it is `child-birth-provable`).
+   *  When this domain is itself the BORN child's law (no standalone create), the index also registers the
+   *  child domain key pointing at the SAME leg, so `proof --domain <child>` resolves through the parent birth. */
+  readonly childBirth?: ChildBirthLeg;
 }
 
-/** Synthesize the offline legs for one domain module, or `null` when it has no
- *  creating write (nothing to prove). The SINGLE source of the leg-selection
- *  logic — `generateTsProof` (the .mts marker) and `proofLegsIndex` (the
- *  per-domain index) both call this, so the offline lane proves any domain the
+/** Synthesize the standalone-create offline legs for one domain module, or `null` when it has no
+ *  creating write (nothing to prove standalone — it may still be child-birth-provable / compile-valid).
+ *  The SINGLE source of the create-leg selection — `generateTsProof` (the .mts marker) and
+ *  `proofLegsIndex` (the per-domain index) both call this, so the offline lane proves any domain the
  *  same way the generated proof proves its primary one. */
+/** A `.creates` directive the proof can DRIVE from a synthesized sample offline: not a `.births()` (a birth
+ *  is the child-birth lane), not ATTESTATION-AUTHORIZED (needs a signed §3 quote no synthesizer can produce —
+ *  e.g. the home law's `recordShare`). Those are NOT standalone-provable offline; the domain proves via its
+ *  child-birth leg / compile-valid instead. */
+function isStandaloneCreate(d: Directive<unknown> | undefined): boolean {
+  return d?.marker === "creates" && typeof d.payloadSchema === "object"
+    && d.birthsChild !== true && d.attestationAuthorizedGate === undefined;
+}
+
 export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
-  const createDir = (mod.directives as Directive<unknown>[]).find(
-    (d) => d?.marker === "creates" && typeof d.payloadSchema === "object",
-  );
+  const createDir = (mod.directives as Directive<unknown>[]).find((d) => isStandaloneCreate(d));
   if (createDir === undefined) return null;
   const domain = mod.domain ?? mod.name;
   const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === createDir.aggregateId);
@@ -226,6 +470,7 @@ export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
     .find((c) => c.of === agg.id && (c as { where?: unknown }).where == null && (c.by == null || baseValue[c.by] !== undefined));
   return {
     domain,
+    legs: ["compile-valid", "standalone-provable"],
     directiveId: createDir.id,
     aggregateId: agg.id,
     payload: baseValue,
@@ -236,49 +481,309 @@ export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
   };
 }
 
-/** The per-domain legs index for `build/<name>.proof-legs.json` — every domain
- *  with a creating write, plus the default (the first, which the .mts proves).
- *  `githolon proof [--domain <key>]` runs any of these offline. */
+/** The first `.births()` directive in a module (with a synthesizable payload), or undefined. */
+function birthDirectiveOf(mod: DomainModule): Directive<unknown> | undefined {
+  return (mod.directives as Directive<unknown>[]).find((d) => d?.birthsChild === true && typeof d.payloadSchema === "object");
+}
+
+/** Build the legs for ONE domain module — every leg it carries (compile-valid always; standalone-provable
+ *  when it has a `.creates`; child-birth-provable when it has a `.births()`). NEVER null: every compiled
+ *  domain is at least `compile-valid` (gaps 1+3 — every domain is proof-addressable). */
+export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[]): ProofLegs {
+  const domain = mod.domain ?? mod.name;
+  // The standalone-create leg (when the domain has a non-birth `.creates`). FAIL SOFT: an exotic payload
+  // shape the synthesizer can't sample just drops the standalone leg (the domain stays compile-valid /
+  // child-birth-provable), never loses the index.
+  let standalone: ProofLegs | null = null;
+  try {
+    standalone = proofLegsForModule(mod);
+  } catch {
+    standalone = null;
+  }
+  // The child-birth leg (when the domain has a `.births()` directive) — discovered by running its plan.
+  const birthDir = birthDirectiveOf(mod);
+  const childBirth = birthDir !== undefined ? discoverChildBirthLeg(birthDir, domain, modules) : undefined;
+
+  const legs: ProofKind[] = ["compile-valid"];
+  if (standalone !== null) legs.push("standalone-provable");
+  if (childBirth !== undefined) legs.push("child-birth-provable");
+
+  return {
+    domain,
+    legs,
+    ...(standalone !== null
+      ? {
+          directiveId: standalone.directiveId,
+          aggregateId: standalone.aggregateId,
+          payload: standalone.payload,
+          autoStamped: standalone.autoStamped,
+          ...(standalone.mintField !== undefined ? { mintField: standalone.mintField } : {}),
+          ...(standalone.query !== undefined ? { query: standalone.query } : {}),
+          ...(standalone.count !== undefined ? { count: standalone.count } : {}),
+        }
+      : {}),
+    ...(childBirth !== undefined ? { childBirth } : {}),
+  };
+}
+
+/** The per-domain legs index for `build/<name>.proof-legs.json` — EVERY compiled domain is addressable
+ *  (gaps 1+3, co2 feedback), with its taxonomy (compile-valid | standalone-provable | child-birth-provable).
+ *  A CHILD-ONLY law (no standalone create, installed only via a parent birth) is registered under its OWN
+ *  domain key pointing at the parent birth that proves it. `githolon proof [--domain <key>]` resolves for
+ *  every domain. The default is the first STANDALONE-provable domain (the live `.mts` lane needs one), else
+ *  the first child-birth-provable, else the first compiled domain. */
 export function proofLegsIndex(modules: readonly DomainModule[]): { default: string; domains: Record<string, ProofLegs> } | null {
   const domains: Record<string, ProofLegs> = {};
-  let first: string | undefined;
+  const order: string[] = [];
   for (const mod of modules) {
-    // FAIL SOFT per-module: a sibling domain whose payload can't be synthesized
-    // (an exotic zod shape synthesizePayload throws on) must not lose the index
-    // for the domains that DO synthesize — skip it, keep the rest.
-    let legs: ProofLegs | null;
-    try {
-      legs = proofLegsForModule(mod);
-    } catch {
-      continue;
-    }
-    if (legs === null) continue;
+    const legs = legsForDomain(mod, modules);
+    if (domains[legs.domain] === undefined) order.push(legs.domain);
     domains[legs.domain] = legs;
-    if (first === undefined) first = legs.domain;
   }
-  return first === undefined ? null : { default: first, domains };
+  // CHILD-DOMAIN ADDRESSABILITY: a `.births()` directive names a CHILD domain (e.g. `estate`) that may have
+  // no standalone leg of its own. Register that child domain key pointing at the PARENT's child-birth leg
+  // (so `proof --domain estate` proves it THROUGH the birth that installs it — the only way it comes to be).
+  for (const legs of [...Object.values(domains)]) {
+    const cb = legs.childBirth;
+    if (cb === undefined) continue;
+    const existing = domains[cb.childDomain];
+    if (existing === undefined) {
+      // A pure child-only domain whose ONLY proof is the parent birth: register it as child-birth-provable.
+      domains[cb.childDomain] = { domain: cb.childDomain, legs: ["compile-valid", "child-birth-provable"], childBirth: cb };
+      if (!order.includes(cb.childDomain)) order.push(cb.childDomain);
+    } else if (existing.childBirth === undefined) {
+      // The child domain ALSO compiled standalone (e.g. it has its own create) — add the child-birth leg to it.
+      const mergedLegs = [...new Set([...(existing.legs ?? ["compile-valid"]), "child-birth-provable" as const])];
+      domains[cb.childDomain] = { ...existing, legs: mergedLegs, childBirth: cb };
+    }
+  }
+  if (order.length === 0) return null;
+  const standaloneFirst = order.find((d) => (domains[d]!.legs ?? []).includes("standalone-provable"));
+  const childBirthFirst = order.find((d) => (domains[d]!.legs ?? []).includes("child-birth-provable"));
+  const def = standaloneFirst ?? childBirthFirst ?? order[0]!;
+  return { default: def, domains };
 }
 
-export function generateTsProof(modules: readonly DomainModule[], opts: TsProofOptions): string {
-  // The proof drives the FIRST domain that has a creating write — without one
-  // there is nothing to author, so there is nothing to prove.
-  const mod = modules.find((m) =>
-    (m.directives as Directive<unknown>[]).some((d) => d?.marker === "creates" && typeof d.payloadSchema === "object"),
+// ── shared `.mts` fragments (the v2 contract — G1: no host secret; deploy is OPEN + kernel-gated) ─────────
+
+/**
+ * THE V2 PREAMBLE (G1, gap 4): create a throwaway workspace (NO secret comes back — ownership is a ledger
+ * fact), then deploy YOUR compiled law via the OPEN lane (`POST /domains`, no Bearer; write-authority is
+ * kernel-judged at the offer gate). Identity rides `x-nomos-principal` (transitional bare-uid lane), the
+ * same header `cli/src/cloud.ts deploy()` + the 0.18 host-strip lane present. Declares `fail`/`ok`/`deploy`/
+ * `r`/`d`/`runError`/`PRINCIPAL` and opens the `try {` (closed by {@link v2CatchFinally}).
+ */
+function v2IdentityAndCleanupPreamble(opts: TsProofOptions, hashConst: string, n: () => number): string[] {
+  return [
+    `// IDENTITY NOTE: this proof uses the bare x-nomos-principal lane so it is SELF-CONTAINED (a throwaway`,
+    `// workspace, no stored credentials). Real apps use \`githolon login --agent\` (a VERIFIED identity)`,
+    `// + \`githolon ws create/deploy\`. (G1: a create returns NO workspaceSecret — ownership is a ledger`,
+    `// fact; deploy is OPEN + kernel-gated, authenticated by the principal, not a host secret.)`,
+    `const fail: (m: string) => never = (m) => { throw new Error(m); };`,
+    `const ok = (m: string) => console.log("✓ " + m);`,
+    `const PRINCIPAL = process.env.NOMOS_PRINCIPAL || "githolon-proof";`,
+    ``,
+    `const deploy = JSON.parse(readFileSync(new URL(${JSON.stringify(`./${opts.packageName}.deploy.json`)}, import.meta.url), "utf8"));`,
+    ``,
+    `// CLEANUP CONTRACT: the throwaway workspace is RETIRED on every exit (green or jammed) — a proof never`,
+    `// leaves orphans. PROOF_KEEP=1 (githolon proof --live --keep) keeps it and prints the persist command.`,
+    `let runError: unknown = null;`,
+    `let born_ws = false;`,
+    `try {`,
+    ``,
+    `// ${n()}. a throwaway workspace — born by the create (G1: NO secret is returned; ownership is a ledger fact)`,
+    `let r = await fetch(\`\${CLOUD}/v2/workspaces/\${WS}\`, { method: "POST", headers: { "x-nomos-principal": PRINCIPAL } });`,
+    `let d = await r.json();`,
+    `if (!d.ok) fail(\`create workspace: \${JSON.stringify(d)}\`);`,
+    `born_ws = true;`,
+    `ok(\`workspace \${WS} created (no host secret — ownership is a ledger fact; PROOF_KEEP=1 keeps it)\`);`,
+    ``,
+    `// ${n()}. deploy YOUR compiled law via the OPEN lane (POST /domains, no Bearer — kernel-judged authority,`,
+    `//    authenticated as PRINCIPAL via x-nomos-principal; a refusal answers as a TYPED kernel verdict 422)`,
+    `r = await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/domains\`, { method: "POST", headers: { "content-type": "application/json", "x-nomos-principal": PRINCIPAL }, body: JSON.stringify(deploy) });`,
+    `d = await r.json();`,
+    `if (!d.ok || d.installation?.[0]?.data?.["status.phase"] !== "Active") fail(\`deploy: \${JSON.stringify(d)}\`);`,
+    `if (d.domainHash !== ${hashConst}) fail(\`deploy hash \${d.domainHash} != the generated client's \${${hashConst}}\`);`,
+    `ok(\`law deployed Active — \${${hashConst}.slice(0, 12)}… (the content hash baked into your typed client)\`);`,
+  ];
+}
+
+/**
+ * THE V2 CATCH/FINALLY (G1, gap 4): retire the throwaway workspace on every exit via the OPEN lane (no
+ * Bearer — there is no host secret to present; a retire is a SIGNED governance offer in the real lane, but
+ * the open self-retire suffices to clean up a throwaway). PROOF_KEEP=1 keeps it.
+ */
+function v2CatchFinally(): string[] {
+  return [
+    `} catch (e) {`,
+    `  runError = e;`,
+    `  console.error("✗ " + ((e as Error)?.message ?? e));`,
+    `} finally {`,
+    `  // THE CLEANUP CONTRACT: never an orphaned cloud workspace. Retired on every exit path (open lane — no`,
+    `  // host secret exists post-G1); PROOF_KEEP=1 keeps it and prints the persist command.`,
+    `  if (born_ws && process.env.PROOF_KEEP === "1") {`,
+    `    console.log(\`workspace \${WS} KEPT — retire it when done: githolon ws retire \${WS}\`);`,
+    `  } else if (born_ws) {`,
+    `    const rr = await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/retire\`, { method: "POST", headers: { "x-nomos-principal": PRINCIPAL } }).then((x) => x.json()).catch(() => ({}));`,
+    `    console.log(\`  retired \${WS}: \${(rr as { ok?: boolean }).ok === true}\`);`,
+    `  }`,
+    `  process.exit(runError ? 1 : 0);`,
+    `}`,
+  ];
+}
+
+/**
+ * THE LIVE CHILD-BIRTH LEG (G3, gap 2): drive the parent `.births()` directive against the cloud workspace,
+ * then read the BORN CHILD workspace it spawned (the kernel's offer-effect installs the child law in-chain +
+ * folds the child genesis through the child's OWN gate). Verifies the child came up BORN (its read model has
+ * the seeded record) — the cloud's offer response surfaces `born: [{workspace, head}]`. The frameworkHash +
+ * lawHash are injected from the deployed law (the child install resolves bytes by hash from the parent's
+ * custody; a `sample-*` hash would fail). The dispatch rides the gateway offer lane (authenticated principal).
+ */
+function liveChildBirthLegLines(cb: ChildBirthLeg, opts: TsProofOptions, n: () => number): string[] {
+  const hashConst = tsHashConstName(opts.packageName);
+  // The birth payload literal: the synthesized values + the REAL hashes onto the discovered fields + the
+  // auto-stamped `…At` fields stamped now.
+  const lines: string[] = [];
+  lines.push(
+    `// ${n()}. CHILD BIRTH (G3 — birth is the defined consequence of an offer): drive \`${cb.parentDomain}/${cb.birthDirectiveId}\``,
+    `//    against the cloud; the kernel's offer-effect installs the child law in-chain + folds the child's`,
+    `//    genesis (estate/${cb.childSeedDirectiveId}) through the CHILD's own gate, then BORNS the child workspace.`,
+    `{`,
+    `  const birthPayload: Record<string, unknown> = { ...${JSON.stringify(cb.birthPayload)} };`,
+    ...(cb.frameworkHashField !== undefined
+      ? [
+          `  // The framework CONTROLLER hash (the bootstrap install-target the child runs as intent 0) — read it`,
+          `  // from the workspace's own status (the kernel's controllerHash); the child install resolves the bytes`,
+          `  // by hash from the parent's custody, so this MUST be the real framework hash (a guess would fail).`,
+          `  const st = await (await fetch(\`\${CLOUD}/v2/workspaces/\${WS}\`)).json().catch(() => ({}));`,
+          `  const frameworkHash = st.controller?.domainHash ?? st.controllerHash ?? "";`,
+          `  if (!frameworkHash) fail("could not resolve the framework controller hash from the workspace status — needed for the child's in-chain installDomain");`,
+          `  birthPayload[${JSON.stringify(cb.frameworkHashField)}] = frameworkHash;`,
+        ]
+      : []),
+    `  birthPayload[${JSON.stringify(cb.lawHashField ?? "lawHash")}] = ${hashConst};`,
+    ...cb.birthAutoStamped.map((f) => `  birthPayload[${JSON.stringify(f)}] = new Date().toISOString();`),
+    `  const br = await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/${cb.birthDirectiveId}\`, { method: "POST", headers: { "content-type": "application/json", "x-nomos-principal": PRINCIPAL }, body: JSON.stringify(birthPayload) });`,
+    `  const bd = await br.json();`,
+    `  if (!bd.ok) fail(\`child birth offer ${cb.parentDomain}/${cb.birthDirectiveId} refused: \${JSON.stringify(bd)}\`);`,
+    `  const born: Array<{ workspace?: string }> = bd.born ?? [];`,
+    `  const childWs = born[0]?.workspace;`,
+    `  if (!childWs) fail(\`birth admitted but the offer-effect spawned no child (born=\${JSON.stringify(born)})\`);`,
+    `  ok(\`child birth — \${childWs} born by ${cb.parentDomain}/${cb.birthDirectiveId} (the offer-effect installed the child law + folded its genesis)\`);`,
+    `  // The BORN child runs its OWN law: read the seeded ${cb.childSeedAggregateId ?? "record"} back from the child workspace.`,
+    ...(cb.childSeedInstanceId !== undefined
+      ? [
+          `  const cr = await fetch(\`\${CLOUD}/v2/workspaces/\${childWs}/aggregates/\${encodeURIComponent(${JSON.stringify(cb.childSeedInstanceId)})}\`).then((x) => x.json()).catch(() => ({}));`,
+          `  if (!(cr.rows?.length >= 1)) fail(\`the born child did not seed ${cb.childSeedAggregateId ?? "its record"} (${cb.childSeedInstanceId}): \${JSON.stringify(cr)}\`);`,
+          `  ok(\`the born child's read model has the genesis seed — ${cb.childSeedDirectiveId} ran inside \${childWs}\`);`,
+        ]
+      : cb.childQuery !== undefined
+        ? [
+            `  const cr = await fetch(\`\${CLOUD}/v2/workspaces/\${childWs}/${cb.childQuery.id}?${cb.childQuery.key.map((k) => `${encodeURIComponent(k)}=\${encodeURIComponent(String(birthPayload[${JSON.stringify(k)}] ?? ""))}`).join("&")}\`).then((x) => x.json()).catch(() => ({}));`,
+            `  if (!(cr.ok && cr.rows?.length >= 1)) fail(\`the born child's declared query ${cb.childQuery.id} returned nothing: \${JSON.stringify(cr)}\`);`,
+            `  ok(\`the born child's declared query ${cb.childQuery.id} returns the genesis seed — ${cb.childSeedDirectiveId} ran inside \${childWs}\`);`,
+          ]
+        : [
+            `  ok(\`the child \${childWs} is born (no declared read on its seed aggregate — declare a query to read it back)\`);`,
+          ]),
+    `}`,
+    ``,
   );
+  return lines;
+}
+
+/**
+ * THE BIRTH-ONLY PROOF (gap 2): a package whose primary write is a `.births()` directive (no standalone
+ * create — the home/estate composable shape). Deploy the parent law, drive the birth, verify the born child.
+ * (The offline runner proves the same legs LOCALLY on the vendored wasm — that is the default `githolon
+ * proof` lane; this `.mts` is the live `--live` lane.)
+ */
+function generateBirthOnlyProof(
+  mod: DomainModule,
+  modules: readonly DomainModule[],
+  opts: TsProofOptions,
+  primaryLegs: ProofLegs,
+): string {
+  void modules;
+  const domain = mod.domain ?? mod.name;
+  const factory = tsClientFactoryName(domain);
+  const hashConst = tsHashConstName(opts.packageName);
+  const cb = primaryLegs.childBirth;
+  if (cb === undefined) {
+    throw new Error(
+      `domain '${domain}' has a .births() directive but its child-birth leg could not be discovered (the plan did not record a leaf genesis recipe: bootstrap/installDomain → nomos/installDomain → <child>/<seed>) — prove it by hand in test/e2e.mts`,
+    );
+  }
+  const slug =
+    opts.packageName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 24) || "domain";
+  const legsMarker = JSON.stringify(primaryLegs);
+  let step = 0;
+  const n = () => ++step;
+  const out: string[] = [];
+  out.push(
+    `// AUTO-GENERATED by nomos-compile — the RUNNABLE PROOF for package "${opts.packageName}",`,
+    `// synthesized from the domain's OWN law. This package's primary write is a BIRTH (a .births()`,
+    `// directive), so the proof drives the birth end-to-end into the BORN child. Reshape the law,`,
+    `// recompile, and this proof reshapes itself — no test rewriting. Run it:`,
+    `//`,
+    `//   npx githolon proof        (offline legs on a local holon)`,
+    `//   npx githolon proof --live (or: npx tsx build/${opts.packageName}.proof.mts — the full cloud loop)`,
+    `//`,
+    `// Regenerated on every compile; do not edit.`,
+    `// @nomos-proof-legs ${legsMarker}`,
+    `import { readFileSync } from "node:fs";`,
+    `import { connect } from "@githolon/client";`,
+    `import { ${factory}, ${hashConst} } from "./${opts.packageName}.client.ts";`,
+    `void connect; void ${factory};`,
+    ``,
+    `const CLOUD = (process.env.NOMOS_CLOUD || "https://nomos.captainapp.co.uk").replace(/\\/+$/, "");`,
+    `const WS = process.env.NOMOS_WS || ${JSON.stringify(slug + "-proof-")} + Math.random().toString(36).slice(2, 8);`,
+    ``,
+    ...v2IdentityAndCleanupPreamble(opts, hashConst, n),
+    ``,
+    ...liveChildBirthLegLines(cb, opts, n),
+    `console.log(\`\\nALL GREEN — generated proof for "${opts.packageName}": deploy → child birth (\${WS} → the born child) → verified\`);`,
+    ``,
+    ...v2CatchFinally(),
+    ``,
+  );
+  return out.join("\n");
+}
+
+export function generateTsProof(modules: readonly DomainModule[], opts: TsProofOptions): string {
+  // PRIMARY-DOMAIN SELECTION: the live `.mts` drives a STANDALONE create when the package has one (the full
+  // deploy → write → query → sync → cloud loop). A BIRTH-ONLY package (every `.creates` is also a `.births()`
+  // — the home/estate composable shape) has no standalone create to drive, so the primary becomes the first
+  // `.births()` domain and the live `.mts` drives the birth as its primary write. Either way, the marker =
+  // the primary domain's FULL legs (so the offline runner + the index never describe different directives).
+  const hasStandaloneCreate = (m: DomainModule): boolean =>
+    (m.directives as Directive<unknown>[]).some((d) => isStandaloneCreate(d));
+  const hasBirth = (m: DomainModule): boolean => birthDirectiveOf(m) !== undefined;
+  const mod = modules.find(hasStandaloneCreate) ?? modules.find(hasBirth);
   if (mod === undefined) {
     throw new Error(
-      `no .creates directive in any domain — a generated proof needs one creating write; add a directive(...).creates(...) (test/e2e.mts remains the hand-authored lane)`,
+      `no .creates directive in any domain — a generated proof needs one creating write (or a .births() birth directive); add a directive(...).creates(...) (test/e2e.mts remains the hand-authored lane)`,
     );
   }
   const domain = mod.domain ?? mod.name;
   const factory = tsClientFactoryName(domain);
   const hashConst = tsHashConstName(opts.packageName);
+  // THE MARKER (since 0.5.0) + the per-domain index are ONE synthesis (`legsForDomain`) — the proof body, its
+  // marker, and the index can never describe different directives. The primary domain's legs carry whichever
+  // of standalone / child-birth it has.
+  const primaryLegs = legsForDomain(mod, modules);
+  const childBirth = primaryLegs.childBirth;
 
-  // SAME predicate as the mod selection above AND proofLegsForModule — so the
-  // proof body, its marker, and the index can never describe different directives.
+  // The standalone-create lane (when the primary has one). A birth-only primary skips this — its primary
+  // write is the child-birth leg below.
   const createDir = (mod.directives as Directive<unknown>[]).find(
-    (d) => d?.marker === "creates" && typeof d.payloadSchema === "object",
-  )!;
+    (d) => d?.marker === "creates" && typeof d.payloadSchema === "object" && d.birthsChild !== true,
+  );
+  if (createDir === undefined) {
+    // BIRTH-ONLY PRIMARY: emit a birth-shaped proof (no standalone create/query/count/concurrency legs).
+    return generateBirthOnlyProof(mod, modules, opts, primaryLegs);
+  }
   const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === createDir.aggregateId);
   if (agg === undefined) {
     throw new Error(
@@ -341,9 +846,9 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   const listAccessor = `list${agg.id}s`;
 
   // THE MACHINE-READABLE LEGS (parsed by `githolon`'s offline proof runner —
-  // cli/src/proof_offline.ts). The ONE leg-synthesis (`proofLegsForModule`) feeds
+  // cli/src/proof_offline.ts). The ONE leg-synthesis (`legsForDomain`) feeds
   // both this marker and the per-domain `proof-legs.json` index, so they never drift.
-  const legsMarker = JSON.stringify(proofLegsForModule(mod));
+  const legsMarker = JSON.stringify(primaryLegs);
 
   let step = 0;
   const n = () => ++step;
@@ -366,35 +871,7 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `const CLOUD = (process.env.NOMOS_CLOUD || "https://nomos.captainapp.co.uk").replace(/\\/+$/, "");`,
     `const WS = process.env.NOMOS_WS || ${JSON.stringify(slug + "-proof-")} + Math.random().toString(36).slice(2, 8);`,
     ``,
-    `// IDENTITY NOTE: this proof uses the bare x-nomos-principal lane so it is`,
-    `// SELF-CONTAINED (a throwaway workspace, no stored credentials). Real apps use`,
-    `// \`githolon login --agent\` (a VERIFIED identity) + \`githolon ws create/deploy\`.`,
-    `const fail: (m: string) => never = (m) => { throw new Error(m); };`,
-    `const ok = (m: string) => console.log("✓ " + m);`,
-    ``,
-    `const deploy = JSON.parse(readFileSync(new URL(${JSON.stringify(`./${opts.packageName}.deploy.json`)}, import.meta.url), "utf8"));`,
-    ``,
-    `// CLEANUP CONTRACT: the throwaway workspace is RETIRED on every exit (green or`,
-    `// jammed) — a proof never leaves orphans. PROOF_KEEP=1 (githolon proof --live --keep)`,
-    `// keeps it and prints the FULL secret once, with the persist command.`,
-    `let SECRET = "";`,
-    `let runError: unknown = null;`,
-    `try {`,
-    ``,
-    `// ${n()}. a throwaway workspace (the ONE-TIME secret comes back on create)`,
-    `let r = await fetch(\`\${CLOUD}/v2/workspaces/\${WS}\`, { method: "POST", headers: { "x-nomos-principal": "githolon-proof" } });`,
-    `let d = await r.json();`,
-    `if (!d.ok) fail(\`create workspace: \${JSON.stringify(d)}\`);`,
-    `SECRET = d.workspaceSecret;`,
-    `if (!SECRET?.startsWith("nws_v1_")) fail(\`no workspaceSecret returned: \${JSON.stringify(d)}\`);`,
-    `ok(\`workspace \${WS} created (one-time secret held for cleanup — PROOF_KEEP=1 keeps the workspace and prints it)\`);`,
-    ``,
-    `// ${n()}. deploy YOUR compiled law (build/${opts.packageName}.deploy.json) WITH the secret`,
-    `r = await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/domains\`, { method: "POST", headers: { "content-type": "application/json", authorization: \`Bearer \${SECRET}\` }, body: JSON.stringify(deploy) });`,
-    `d = await r.json();`,
-    `if (!d.ok || d.installation?.[0]?.data?.["status.phase"] !== "Active") fail(\`deploy: \${JSON.stringify(d)}\`);`,
-    `if (d.domainHash !== ${hashConst}) fail(\`deploy hash \${d.domainHash} != the generated client's \${${hashConst}}\`);`,
-    `ok(\`law deployed Active — \${${hashConst}.slice(0, 12)}… (the content hash baked into your typed client)\`);`,
+    ...v2IdentityAndCleanupPreamble(opts, hashConst, n),
     ``,
     `// ${n()}. connect + bind the GENERATED typed client`,
     `const holon = await connect({ cloud: CLOUD, workspace: WS, clientId: "proof-1" });`,
@@ -532,6 +1009,12 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     );
   }
 
+  // THE CHILD-BIRTH LEG (G3, gap 2): when the primary domain has a `.births()` directive, prove the birth
+  // END-TO-END against the cloud — drive the parent birth offer, then read the BORN child workspace it spawns.
+  if (childBirth !== undefined) {
+    out.push(...liveChildBirthLegLines(childBirth, opts, n));
+  }
+
   out.push(
     `// ${n()}. CONVERGENCE: the original instance adopts canonical main in place — no reconnect`,
     `await holon.pull();`,
@@ -541,23 +1024,9 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
     `if (head !== remoteMain) fail(\`not converged in place: local \${head?.slice(0, 10)} vs main \${remoteMain?.slice(0, 10)}\`);`,
     `ok("converged in place — local head == canonical main");`,
     ``,
-    `console.log(\`\\nALL GREEN — generated proof for "${opts.packageName}": deploy → offline write → local reads → admission → cloud reads${concurrency ? ` → AddWins merge` : ``} → convergence (\${WS})\`);`,
+    `console.log(\`\\nALL GREEN — generated proof for "${opts.packageName}": deploy → offline write → local reads → admission → cloud reads${concurrency ? ` → AddWins merge` : ``}${childBirth !== undefined ? ` → child birth` : ``} → convergence (\${WS})\`);`,
     ``,
-    `} catch (e) {`,
-    `  runError = e;`,
-    `  console.error("✗ " + ((e as Error)?.message ?? e));`,
-    `} finally {`,
-    `  // THE CLEANUP CONTRACT: never an orphaned cloud workspace. Retired on every`,
-    `  // exit path; PROOF_KEEP=1 keeps it and prints the FULL secret exactly once.`,
-    `  if (SECRET && process.env.PROOF_KEEP === "1") {`,
-    `    console.log(\`workspace \${WS} KEPT — secret \${SECRET}\`);`,
-    `    console.log(\`  persist it: githolon secret set \${WS} <the secret above>   (then: githolon ws retire \${WS} when done)\`);`,
-    `  } else if (SECRET) {`,
-    `    const rr = await fetch(\`\${CLOUD}/v2/workspaces/\${WS}/retire\`, { method: "POST", headers: { authorization: \`Bearer \${SECRET}\` } }).then((x) => x.json()).catch(() => ({}));`,
-    `    console.log(\`  retired \${WS}: \${(rr as { ok?: boolean }).ok === true}\`);`,
-    `  }`,
-    `  process.exit(runError ? 1 : 0);`,
-    `}`,
+    ...v2CatchFinally(),
     ``,
   );
 

package/src/compile_package_main.ts

@@ -1452,8 +1452,8 @@ async function main(): Promise<void> {
   console.log(`  deploy     ${rel(deployPath)}`);
   console.log(``);
   console.log(`deploy (Nomos Cloud):`);
-  console.log(`  githolon ws create <ws> && githolon deploy <ws>   # the secret is saved + sent for you`);
-  console.log(`  # raw lane: curl -X POST -H 'content-type: application/json' -H 'Authorization: Bearer <workspaceSecret>' \\`);
+  console.log(`  githolon login --agent && githolon ws create <ws> && githolon deploy <ws>   # no secret — deploy is OPEN, kernel-judged at the offer gate`);
+  console.log(`  # raw lane: curl -X POST -H 'content-type: application/json' -H 'x-nomos-principal: <your-auth-uid>' \\`);
   console.log(`  #   --data-binary @${rel(deployPath)} https://nomos.captainapp.co.uk/v2/workspaces/<ws>/domains`);
   if (proofPath !== undefined) {
     console.log(`prove it OFFLINE first: npx githolon proof        # the generated proof's offline legs on a LOCAL holon (no cloud workspace)`);