@githolon/dsl 0.30.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.30.0",
+  "version": "0.31.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/codegen_proof.ts

@@ -42,6 +42,7 @@ import type { DomainModule } from "./codegen_dart.js";
 import type { QueryDecl } from "./query.js";
 import type { FieldOp } from "./ops.js";
 import type { RelationTypeDecl, Rewrite } from "./relation_schema.js";
+import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import { finishCount } from "./count.js";
 import { mintedCreateField } from "./workspace_routing.js";
 import { deterministicPorts } from "./ctx.js";
@@ -364,18 +365,24 @@ function relationSeedLegLines(
   }
   const ACTOR = `"user:proof-conformance"`;
   const speculative = leg.seedSpeculative === true;
-  // Grant/seed payload: overwrite the routed subject/grantedBy fields (and any name-shaped fallback) with the actor.
-  const grantPayloadLit = (() => {
-    const overwrite = new Set<string>([...leg.grantSubjectFields, ...leg.grantGrantedByFields]);
-    const entries = Object.entries(leg.grantPayload).map(([k, v]) => {
-      // Also catch conventional subject/grantedBy field names the plan-probe couldn't value-match.
-      const looksSubject = /^(subject|principal|grantedBy|grantee|member|user|owner)$/i.test(k);
-      return overwrite.has(k) || looksSubject
+  // A payload literal with subject/founder-conventional fields (+ the routed set) overwritten to the actor —
+  // so a seat lands ON the actor AND every write-once/author-binding/founder-binding invariant holds.
+  const actorSeatLit = (payload: Record<string, unknown>, routed: readonly string[]): string => {
+    const overwrite = new Set<string>(routed);
+    const entries = Object.entries(payload).map(([k, v]) =>
+      overwrite.has(k) || /^(subject|principal|grantedBy|grantee|member|user|owner|founder)$/i.test(k)
         ? `${JSON.stringify(k)}: ${ACTOR}`
-        : `${JSON.stringify(k)}: ${JSON.stringify(v)}`;
-    });
+        : `${JSON.stringify(k)}: ${JSON.stringify(v)}`,
+    );
     return `{ ${entries.join(", ")} }`;
-  })();
+  };
+  const grantPayloadLit = actorSeatLit(leg.grantPayload, [...leg.grantSubjectFields, ...leg.grantGrantedByFields]);
+  // The PREREQUISITE-SEED CHAIN dispatches (each as the actor = founder) BEFORE the grant.
+  const prereqLines = (leg.prerequisiteSeeds ?? []).flatMap((seed) => [
+    `    // prerequisite: ${leg.domain}/${seed.directiveId} establishes the state the grant's invariant reads (as founder = ACTOR).`,
+    `    await ${factory}(holon, { actor: ACTOR }).${seed.directiveId}(${actorSeatLit(seed.payload, [])});`,
+    `    ok(\`relation bootstrap (prerequisite) — ${leg.domain}/${seed.directiveId} established (as founder \${ACTOR}) before the grant\`);`,
+  ]);
   const gatedPayloadLit = leg.gatedMintField !== undefined && leg.gatedAggregateId !== undefined
     ? `{ ...${JSON.stringify(leg.gatedPayload)}, ${JSON.stringify(leg.gatedMintField)}: await holon.mint(${JSON.stringify(leg.gatedAggregateId)}) }`
     : JSON.stringify(leg.gatedPayload);
@@ -383,6 +390,27 @@ function relationSeedLegLines(
     ? ` — a COMPUTED gate: granting "${leg.grantedRelation}" makes the actor satisfy "${leg.relation}" via the rewrite`
     : ``;
 
+  if (leg.bornContext !== undefined) {
+    // LAYER 4 — THE BORN-DOMAIN GENESIS-AUTHORITY PATH (co2 home). R is established ONLY by the birth genesis
+    // (e.g. birthHome → seedHomeCreator seats creator), and the seed carries an owner-binding PREREQUISITE a
+    // standalone re-seed can't satisfy. This leg is proven by `githolon proof` (offline, on the local wasm):
+    // the runner BIRTHS the workspace as the proof actor (= owner), then dispatches the gated directive INSIDE
+    // the born workspace as that owner, asserting ADMITTED at the real kernel gate (a refusal degrades to a
+    // diagnostic — never a false green). The LIVE `--live` lane proves the underlying birth via the child-birth
+    // leg; the gated-directive-in-born-context proof is the offline runner's (birthing a throwaway home per
+    // gated directive live would leave orphan workspaces).
+    const bc = leg.bornContext;
+    return [
+      `// ${n()}. RELATION BOOTSTRAP — LAYER 4 (born-domain genesis authority): \`${leg.domain}/${leg.gatedDirectiveId}\``,
+      `//    is GATED (\`.requires("${leg.relation}")\`), established ONLY by the birth genesis (\`${bc.birthDirectiveId}\` →`,
+      `//    \`${bc.seatsViaDirectiveId}\` seats "${leg.relation}") — NOT a standalone-replayable seed (its owner-binding`,
+      `//    prerequisite would false-fail). Proven by \`githolon proof\` (offline): birth the workspace as the owner,`,
+      `//    then dispatch \`${leg.gatedDirectiveId}\` INSIDE the born workspace as that owner (real-gate admitted).`,
+      `console.log("– relation-bootstrap leg (born-context) — \`${leg.domain}/${leg.gatedDirectiveId}\` .requires(\\"${leg.relation}\\") is proven in the BORN workspace by \`githolon proof\` (offline); the birth is proven live by the child-birth leg");`,
+      ``,
+    ];
+  }
+
   if (speculative) {
     // LAYER 3 (seed-path replay). The gate relation is reachable only through ttu/intersection/exclusion — no
     // directly-grantable base. We REPLAY the domain's declared seed and let the REAL GATE arbitrate: if the
@@ -424,9 +452,12 @@ function relationSeedLegLines(
     ];
   }
 
+  const prereqNote = (leg.prerequisiteSeeds ?? []).length > 0
+    ? ` The grant needs prerequisite seed(s) [${(leg.prerequisiteSeeds ?? []).map((s) => s.directiveId).join(", ")}] run first (as the actor = founder).`
+    : ``;
   return [
     `// ${n()}. RELATION BOOTSTRAP (seed-then-prove the POSITIVE): \`${leg.domain}/${leg.gatedDirectiveId}\` is GATED`,
-    `//    (\`.requires("${leg.relation}")\`). \`${leg.domain}/${leg.grantDirectiveId}\` GRANTS "${leg.grantedRelation}" (${leg.via})${computedNote}.`,
+    `//    (\`.requires("${leg.relation}")\`). \`${leg.domain}/${leg.grantDirectiveId}\` GRANTS "${leg.grantedRelation}" (${leg.via})${computedNote}.${prereqNote}`,
     `//    Grant it to the proof actor, THEN prove the gated write SUCCEEDS under that actor (what the negative`,
     `//    conformance leg above can't cover — a seeded holder authoring a gated write).`,
     `{`,
@@ -434,6 +465,7 @@ function relationSeedLegLines(
     `  globalThis.fetch = (() => { throw new Error("OFFLINE PROOF VIOLATED: relation-bootstrap touched the network"); }) as typeof fetch;`,
     `  try {`,
     `    const ACTOR = ${ACTOR};`,
+    ...prereqLines,
     `    // (1) grant "${leg.grantedRelation}" to ACTOR (the grant folds a writeTuple; subject seated on ACTOR).`,
     `    await ${factory}(holon, { actor: ACTOR }).${leg.grantDirectiveId}(${grantPayloadLit});`,
     `    ok(\`relation bootstrap (grant) — ${leg.domain}/${leg.grantDirectiveId} granted "${leg.grantedRelation}" to \${ACTOR}${leg.grantedRelation !== leg.relation ? ` (⇒ satisfies "${leg.relation}" via rewrite)` : ``}\`);`,
@@ -493,8 +525,10 @@ export interface RelationBootstrapLeg {
    *  `writeTuple(R)`), `"computed-base"` (R is computed; the grant seats a rewrite BASE relation the granter
    *  was found for), or `"seed-path"` (LAYER 3: R is reachable only through ttu/intersection/exclusion — no
    *  directly-grantable base — so a DECLARED SEED directive that establishes root authority is replayed and
-   *  the REAL KERNEL GATE is the arbiter of whether it authorizes the write). Audit + runner semantics. */
-  readonly via: "marker" | "inferred" | "computed-base" | "seed-path";
+   *  the REAL KERNEL GATE is the arbiter of whether it authorizes the write), or `"born-context"` (LAYER 4:
+   *  R is established by the domain's BIRTH GENESIS — the gated directive is proven INSIDE the born workspace
+   *  as the owner; see {@link BornContextAuthority}). Audit + runner semantics. */
+  readonly via: "marker" | "inferred" | "computed-base" | "seed-path" | "born-context";
   /** LAYER-3 ANTI-FALSE-GREEN FLAG. `true` ⇒ this is a SPECULATIVE seed-path leg: codegen could NOT prove
    *  (via rewrite resolution) that replaying `grantDirectiveId` authorizes the gated write — it discovered a
    *  seed that writes relation tuples and is DEFERRING to the real kernel gate. The runner replays the seed,
@@ -504,6 +538,55 @@ export interface RelationBootstrapLeg {
   readonly seedSpeculative?: boolean;
   /** The relations the discovered seed directive writes (layer-3 audit/diagnostic — what authority it seats). */
   readonly seedWritesRelations?: readonly string[];
+  /** LAYER 4 — THE BORN-DOMAIN GENESIS-AUTHORITY PATH. Present iff the gate relation is established by the
+   *  domain's BIRTH GENESIS (not a standalone-replayable seed): a `.births()` directive whose genesis chain
+   *  seats R (e.g. co2's `birthHome` → `seedHomeCreator` seats `creator`), and whose born workspace runs the
+   *  SAME law — so the gated directive can be proven INSIDE the born context, dispatched as the genesis-
+   *  established OWNER, where the seed's own prerequisite invariants (HomeCreatorSeedBindsOwner) hold. This
+   *  TAKES PRECEDENCE over a standalone seed (`grantDirectiveId`) for a born domain: a standalone re-seed
+   *  would trip the seed's owner-binding prerequisite (HomeOwner unset) and FALSE-fail. When present, the
+   *  runner IGNORES the standalone grant fields and proves via {@link BornContextAuthority}. */
+  readonly bornContext?: BornContextAuthority;
+  /** THE PREREQUISITE-SEED CHAIN (the composed co2_platform / `seedPlatformAdmin` case). Present iff the
+   *  granter (`grantDirectiveId`) carries a PREREQUISITE invariant whose state is established NOT by a birth
+   *  genesis but by a SIBLING SEED in the SAME domain (e.g. `seedPlatformAdmin`'s `PlatformAdminBindsFounder`
+   *  reads the founder singleton stamped by `seedPlatformFounder`). The runner dispatches these seeds IN ORDER
+   *  (each as the proof actor = founder, so their own write-once/author-binding invariants hold) BEFORE the
+   *  grant — then the grant + the gated write succeed. A non-birth analog of {@link BornContextAuthority}. */
+  readonly prerequisiteSeeds?: readonly PrerequisiteSeed[];
+}
+
+/** One prerequisite seed the runner dispatches (as the proof actor = founder) BEFORE the grant — it
+ *  establishes the state a granter's prerequisite invariant reads (e.g. the founder singleton). */
+export interface PrerequisiteSeed {
+  /** The seed directive id (e.g. `seedPlatformFounder`). */
+  readonly directiveId: string;
+  /** The synthesized payload; founder/subject-conventional fields are set to the proof actor at dispatch so
+   *  the seed's own write-once/author-binding invariants pass (founder == the seeding actor). */
+  readonly payload: Record<string, unknown>;
+  readonly autoStamped: readonly string[];
+}
+
+/** THE BORN-DOMAIN GENESIS AUTHORITY (layer 4): the self-birth directive whose genesis seats the gate relation
+ *  for the OWNER, plus what the runner needs to birth it (as the proof actor = the home owner) and then prove
+ *  the gated directive INSIDE the born workspace. The real kernel gate is the arbiter — a refusal degrades to
+ *  a diagnostic (never a false green). */
+export interface BornContextAuthority {
+  /** The self-birth directive (`birthHome`) whose genesis chain seats the gate relation. */
+  readonly birthDirectiveId: string;
+  /** The synthesized birth payload (auto-stamped `…At` omitted; framework/law-hash placeholders removed — the
+   *  runtime injects the REAL hashes + the proof actor as owner). */
+  readonly birthPayload: Record<string, unknown>;
+  readonly birthAutoStamped: readonly string[];
+  /** The birth payload field carrying the home OWNER — the runtime sets it to the proof actor, so the born
+   *  home is owned by (and seats the relation for) the actor the gated dispatch then runs as. */
+  readonly ownerField?: string;
+  /** The birth payload field carrying the framework-controller hash (runtime injects the real one). */
+  readonly frameworkHashField?: string;
+  /** The birth payload field carrying the child law hash (runtime injects the deployed package hash). */
+  readonly lawHashField?: string;
+  /** The genesis step directive that actually seats the relation (audit — e.g. `seedHomeCreator`). */
+  readonly seatsViaDirectiveId: string;
 }
 
 /** Run a directive's plan with a synthesized+probe payload under birth-probe globals and return the drained
@@ -540,27 +623,61 @@ function probePlanOps(
   return { ops, synth, probePayload };
 }
 
-/** Does this directive's plan GRANT `relation` — i.e. fold a relation-tuple write whose `relation` field is
- *  set to R (the `writeTuple`/`relateSubject` shape: a `set(rt, "relation", R)` op on a RelationTuple)? */
-function probeGrantsRelation(dir: Directive<unknown>, relation: string, where: string): boolean {
-  const probed = probePlanOps(dir, where);
-  if (probed === undefined) return false;
-  return probed.ops.some((o) => o.kind === "set" && o.field === "relation" && o.value === relation);
+/** The `status` of a `subjects` setEntry leaf (`writeTuple`/`removeTuple` lowers a JSON `{status, …}` leaf).
+ *  `"active"` = a POSITIVE grant; `"revoked"` = a REVOKE. `undefined` ⇒ not a parseable subject leaf. */
+function subjectLeafStatus(op: FieldOp): string | undefined {
+  if (op.kind !== "setEntry" || op.field !== "subjects" || typeof op.value !== "string") return undefined;
+  try {
+    return (JSON.parse(op.value) as { status?: unknown }).status as string | undefined;
+  } catch {
+    return undefined;
+  }
 }
 
-/** ALL relation names a directive's plan writes tuples for (the `set(rt, "relation", <name>)` ops) — the
- *  layer-3 seed discovery reads this to find a directive that ESTABLISHES relation authority, without needing
- *  the written relation to be a rewrite-resolvable base of the gate. `[]` ⇒ writes no relation tuples. */
-function probeRelationsWritten(dir: Directive<unknown>, where: string): string[] {
+/**
+ * The relations a directive's plan POSITIVELY GRANTS — judged PER RELATION-TUPLE (per `aggregateId`), never by
+ * relation-name alone. Both a grant (`writeTuple`, `status:"active"`) AND a revoke (`removeTuple`,
+ * `status:"revoked"`) emit `set(rt, "relation", R)` on the SAME reltuple aggregate; the ONLY discriminator is
+ * the `status` inside that tuple's `subjects` leaf. So a relation counts as GRANTED iff its tuple carries an
+ * ACTIVE subject leaf — a revoke of R is INELIGIBLE (bug: `revokeCo2PlatformRole` was inferred as a granter).
+ * A directive that writes AND removes DIFFERENT relations is judged per-tuple (each aggregateId independently).
+ */
+function probeGrantedRelations(dir: Directive<unknown>, where: string): string[] {
   const probed = probePlanOps(dir, where);
   if (probed === undefined) return [];
-  const out = new Set<string>();
+  // Group ops by the reltuple instance (aggregateId): each (object, relation) tuple is one bucket.
+  const byTuple = new Map<string, { relations: Set<string>; hasActive: boolean; hasRevoked: boolean }>();
   for (const o of probed.ops) {
-    if (o.kind === "set" && o.field === "relation" && typeof o.value === "string" && o.value.length > 0) out.add(o.value);
+    const key = o.aggregateId;
+    let bucket = byTuple.get(key);
+    if (bucket === undefined) { bucket = { relations: new Set(), hasActive: false, hasRevoked: false }; byTuple.set(key, bucket); }
+    if (o.kind === "set" && o.field === "relation" && typeof o.value === "string" && o.value.length > 0) bucket.relations.add(o.value);
+    const status = subjectLeafStatus(o);
+    if (status === "active") bucket.hasActive = true;
+    else if (status === "revoked") bucket.hasRevoked = true;
+  }
+  const out = new Set<string>();
+  for (const bucket of byTuple.values()) {
+    // A tuple GRANTS its relation(s) only when it seats an ACTIVE subject leaf. A tuple with only a revoked
+    // leaf (or no subject leaf at all — a materialize with no active seat) does NOT grant.
+    if (bucket.hasActive) for (const r of bucket.relations) out.add(r);
   }
   return [...out];
 }
 
+/** Does this directive's plan POSITIVELY GRANT `relation` (an ACTIVE `writeTuple`/`relateSubject` for R)?
+ *  A revoke (`removeTuple`, `status:"revoked"`) for R is NOT a grant (per-tuple status discriminator). */
+function probeGrantsRelation(dir: Directive<unknown>, relation: string, where: string): boolean {
+  return probeGrantedRelations(dir, where).includes(relation);
+}
+
+/** ALL relations a directive's plan POSITIVELY GRANTS (active writeTuples) — the layer-3 seed discovery reads
+ *  this to find a directive that ESTABLISHES relation authority. A revoke-only directive yields `[]` (it seats
+ *  no authority). `[]` ⇒ writes no ACTIVE relation tuples. */
+function probeRelationsWritten(dir: Directive<unknown>, where: string): string[] {
+  return probeGrantedRelations(dir, where);
+}
+
 /** Resolve WHICH grant-payload fields route into the tuple subject / grantedBy — by matching the op values
  *  the plan emitted (the subject `setEntry`'s entryKey, the `grantedBy` leaf) back to synthesized payload
  *  values. Best-effort: an unmatched routing just leaves the field list empty (runtime falls back). */
@@ -687,6 +804,216 @@ export function resolveGrantableBaseRelations(
   return out;
 }
 
+// ── LAYER 4: born-domain genesis-authority discovery (the co2 home case) ─────────────────────────────────
+//
+// A gate relation R may be established ONLY by the domain's BIRTH GENESIS — a `.births()` directive whose
+// genesis chain seats R for the owner (co2's `birthHome` genesis runs `seedHomeCreator`, seating `creator`).
+// The seed itself carries a PREREQUISITE (an owner-binding workspaceInvariant reading state set by an EARLIER
+// genesis step), so a standalone re-seed FALSE-fails (the prior state is absent). The law-true authority path
+// is to BIRTH the workspace (replaying the whole genesis, seating R for the owner) and prove the gated
+// directive INSIDE the born workspace, dispatched as that owner. Discovery probes each `.births()` directive's
+// genesis chain for a step that writeTuples R; if found, the born workspace (running the SAME law) is where
+// the gated directive proves.
+
+/** Probe a `.births()` directive's genesis chain (birth-probe globals) → the recorded steps + the synthesized
+ *  parent payload. `undefined` ⇒ not probeable / no recipe. Mirrors {@link discoverChildBirthLeg}'s probe. */
+function probeBirthGenesis(
+  birthDir: Directive<unknown>,
+  where: string,
+): { chain: Array<{ domain?: string; directiveId?: string; actor?: unknown }>; synth: SynthesizedPayload } | undefined {
+  let synth: SynthesizedPayload;
+  try {
+    synth = synthesizePayload(birthDir.payloadSchema as z.ZodTypeAny, where);
+  } catch {
+    return undefined;
+  }
+  const probePayload: Record<string, unknown> = { ...synth.value };
+  for (const f of synth.autoStamped) probePayload[f] = "2026-01-01T00:00:00Z";
+  let recipe: { genesisChain?: unknown } | undefined;
+  try {
+    withBirthProbeGlobals(() => {
+      __resetAuthoring();
+      __resetReads();
+      __resetBirths();
+      try {
+        birthDir.plan(probePayload as never, deterministicPorts({ physical: 1, replica: 1, principal: "principal:probe" }));
+      } finally {
+        try { __drainAuthoring(); __drainReads(); } catch { /* drained */ }
+      }
+      recipe = __drainBirths()[0] as typeof recipe;
+    });
+  } catch {
+    return undefined;
+  }
+  if (recipe === undefined || !Array.isArray(recipe.genesisChain)) return undefined;
+  return { chain: recipe.genesisChain as Array<{ domain?: string; directiveId?: string; actor?: unknown }>, synth };
+}
+
+/**
+ * Discover the BORN-DOMAIN genesis authority for a gate `relation`: a `.births()` directive in `mod` whose
+ * genesis chain seats `relation` (a genesis step whose directive `writeTuple`s R) AND whose born workspace
+ * runs the SAME law (so the gated directive is addressable there). Returns what the runner needs to birth the
+ * workspace as the proof actor (= the owner) + the owner/hash payload fields. `undefined` ⇒ no birth seats R.
+ */
+export function discoverBornContextAuthority(
+  mod: DomainModule,
+  relation: string,
+): BornContextAuthority | undefined {
+  const domain = mod.domain ?? mod.name;
+  const directives = mod.directives as Directive<unknown>[];
+  const byId = new Map(directives.map((d) => [d.id, d]));
+  for (const bd of directives) {
+    if (bd?.birthsChild !== true || typeof bd.payloadSchema !== "object") continue;
+    const probed = probeBirthGenesis(bd, `${domain}/${bd.id}`);
+    if (probed === undefined) continue;
+    const { chain, synth } = probed;
+    // Find the genesis step (in THIS domain) whose directive writeTuples `relation` — that step seats R.
+    let seatsVia: string | undefined;
+    for (const step of chain) {
+      if (step === null || typeof step !== "object" || step.domain !== domain || typeof step.directiveId !== "string") continue;
+      const stepDir = byId.get(step.directiveId);
+      if (stepDir === undefined) continue;
+      if (probeRelationsWritten(stepDir, `${domain}/${stepDir.id}`).includes(relation)) {
+        seatsVia = step.directiveId;
+        break;
+      }
+    }
+    if (seatsVia === undefined) continue;
+
+    // Resolve the owner field (the payload field whose value the genesis routes as the seed's subject/actor)
+    // + the framework/law-hash fields (matched by value against the genesis install steps), mirroring
+    // discoverChildBirthLeg. The owner field is the payload field carried as a genesis step actor.
+    const fieldForValue = (v: unknown): string | undefined =>
+      Object.entries(synth.value).find(([, sv]) => sv === v && typeof v === "string" && v.length > 0)?.[0];
+    const ownerField = (() => {
+      for (const step of chain as Array<{ actor?: unknown }>) {
+        const exact = fieldForValue(step?.actor);
+        if (exact !== undefined) return exact;
+        if (typeof step?.actor === "string") {
+          for (const [field, value] of Object.entries(synth.value)) {
+            if (typeof value === "string" && value.length > 0 && (step.actor === `user:${value}` || step.actor === `key:${value}`)) return field;
+          }
+        }
+      }
+      return undefined;
+    })();
+    const installSteps = chain.filter((s) => s !== null && typeof s === "object" && s.directiveId === "installDomain") as Array<{ domain?: string; payload?: { domainHash?: unknown } }>;
+    const frameworkHashField = fieldForValue(installSteps.find((s) => s.domain === "bootstrap")?.payload?.domainHash);
+    const lawHashField = fieldForValue(installSteps.find((s) => s.domain === "nomos")?.payload?.domainHash);
+
+    const birthPayload: Record<string, unknown> = { ...synth.value };
+    if (frameworkHashField !== undefined) delete birthPayload[frameworkHashField];
+    if (lawHashField !== undefined) delete birthPayload[lawHashField];
+
+    return {
+      birthDirectiveId: bd.id,
+      birthPayload,
+      birthAutoStamped: synth.autoStamped,
+      ...(ownerField !== undefined ? { ownerField } : {}),
+      ...(frameworkHashField !== undefined ? { frameworkHashField } : {}),
+      ...(lawHashField !== undefined ? { lawHashField } : {}),
+      seatsViaDirectiveId: seatsVia,
+    };
+  }
+  return undefined;
+}
+
+/** Does any workspaceInvariant fire ON `directiveId` — i.e. does that directive carry a PREREQUISITE (a
+ *  declared invariant reading state another step must establish first)? A standalone replay of such a
+ *  directive can FALSE-fail (the prior state is absent), so a born domain must prove via the genesis path. */
+function directiveHasPrerequisiteInvariant(mod: DomainModule, directiveId: string): boolean {
+  return (mod.workspaceInvariants ?? []).some((inv) => inv.on === directiveId);
+}
+
+/** The AGGREGATE TYPES a directive's plan writes (set/ensure/create ops) — used to find the sibling seed that
+ *  establishes the state a prerequisite invariant reads. `[]` ⇒ not probeable / writes nothing. */
+function probeWritesAggregateTypes(dir: Directive<unknown>, where: string): Set<string> {
+  const probed = probePlanOps(dir, where);
+  const out = new Set<string>();
+  if (probed === undefined) return out;
+  for (const o of probed.ops) if (typeof o.aggregateType === "string" && o.aggregateType.length > 0) out.add(o.aggregateType);
+  return out;
+}
+
+/** The aggregate TYPES a workspaceInvariant's declared reads depend on — the state its predicate needs to be
+ *  established first. A `pre:`-prefixed read id is a PRE-apply self-check (write-once), NOT a cross-step
+ *  dependency, so it's excluded. Best-effort: an un-callable reads fn yields none. */
+function invariantReadAggregateTypes(inv: { reads: (ctx: { intent: Record<string, unknown>; principal?: string }) => Array<{ aggregate: string; id: string }> }): Set<string> {
+  const out = new Set<string>();
+  let refs: Array<{ aggregate: string; id: string }>;
+  try {
+    refs = inv.reads({ intent: {}, principal: "" });
+  } catch {
+    return out;
+  }
+  for (const r of refs) {
+    if (r === null || typeof r !== "object") continue;
+    if (typeof r.id === "string" && r.id.startsWith("pre:")) continue; // write-once self-check, not a dependency
+    if (typeof r.aggregate === "string" && r.aggregate.length > 0) out.add(r.aggregate);
+  }
+  return out;
+}
+
+/**
+ * Discover the PREREQUISITE-SEED CHAIN for a granter whose prerequisite invariant(s) read state established by
+ * SIBLING SEEDS in the same domain (the composed co2_platform / `seedPlatformAdmin` case — `seedPlatformAdmin`
+ * needs the founder singleton `seedPlatformFounder` stamps). Returns the ordered seeds to dispatch (as the
+ * proof actor = founder) BEFORE the grant, or `undefined` when the prerequisite can't be satisfied by a
+ * sibling seed (fail-closed — the caller then falls through to born-context / the diagnostic).
+ *
+ * Principled: for each invariant on `dir`, resolve the aggregate types its reads depend on; for each type NOT
+ * written by `dir` itself (a genuine cross-step dependency), find a sibling seed that writes it, then RECURSE
+ * into that seed's own prerequisites (bounded by a visited set + a small depth cap — no cycles, no fabrication).
+ */
+export function discoverPrerequisiteChain(mod: DomainModule, granter: Directive<unknown>): PrerequisiteSeed[] | undefined {
+  const domain = mod.domain ?? mod.name;
+  const directives = mod.directives as Directive<unknown>[];
+  const invariants = (mod.workspaceInvariants ?? []) as Array<WorkspaceInvariantDecl>;
+  const chain: PrerequisiteSeed[] = [];
+  const inChain = new Set<string>();
+  const synthSeed = (dir: Directive<unknown>): PrerequisiteSeed | undefined => {
+    let synth: SynthesizedPayload;
+    try {
+      synth = synthesizePayload(dir.payloadSchema as z.ZodTypeAny, `${domain}/${dir.id}`);
+    } catch {
+      return undefined;
+    }
+    const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === dir.aggregateId);
+    const mintField = agg !== undefined ? mintedCreateField(dir, agg) : undefined;
+    const payload: Record<string, unknown> = { ...synth.value };
+    if (mintField !== undefined) delete payload[mintField];
+    return { directiveId: dir.id, payload, autoStamped: synth.autoStamped };
+  };
+  // Resolve `dir`'s prerequisites (a sibling seed per cross-step aggregate dependency), recursively. Returns
+  // false when ANY prerequisite has no establishing sibling seed (the whole chain is then unsatisfiable).
+  const resolve = (dir: Directive<unknown>, depth: number): boolean => {
+    if (depth > 8) return false; // guard runaway recursion
+    for (const inv of invariants) {
+      if (inv.on !== dir.id) continue;
+      const dirWrites = probeWritesAggregateTypes(dir, `${domain}/${dir.id}`);
+      for (const aggType of invariantReadAggregateTypes(inv)) {
+        if (dirWrites.has(aggType)) continue; // self-dependency (dir establishes it in its own apply)
+        // Find a sibling seed that WRITES aggType (not `dir`, not the gated directive, not itself gated).
+        const seedDir = directives.find(
+          (d) => d !== dir && d.requiresRelationGate === undefined && typeof d?.payloadSchema === "object"
+            && d.birthsChild !== true && probeWritesAggregateTypes(d, `${domain}/${d.id}`).has(aggType),
+        );
+        if (seedDir === undefined) return false; // unmet prerequisite → chain unsatisfiable
+        if (!inChain.has(seedDir.id)) {
+          if (!resolve(seedDir, depth + 1)) return false; // establish the seed's OWN prerequisites first
+          const s = synthSeed(seedDir);
+          if (s === undefined) return false;
+          inChain.add(seedDir.id);
+          chain.push(s); // dependency-first order: the seed runs before `dir`
+        }
+      }
+    }
+    return true;
+  };
+  if (!resolve(granter, 0)) return undefined;
+  return chain.length > 0 ? chain : undefined;
+}
+
 /** Discover the RELATION-BOOTSTRAP leg for a module: the first gated (`.requires(R)`) directive plus the
  *  sibling that ESTABLISHES the actor's authority for R. In priority order: (1) a DIRECT granter of R (a
  *  `.grants(R)` marker or a plan-probed `writeTuple(R)`) — the original lane; (2) REWRITE-AWARE — when R is
@@ -741,6 +1068,7 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
   let via: "marker" | "inferred" | "computed-base" | "seed-path" = "marker";
   let seedSpeculative = false;
   let seedWritesRelations: string[] | undefined;
+  let prerequisiteSeeds: PrerequisiteSeed[] | undefined;
   let found = findGranterFor(relation);
   if (found !== undefined) {
     via = found.via;
@@ -765,14 +1093,59 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
       // guard: `seedSpeculative`). Prefer a seed that seats the MOST relations (a genesis/owner seed like
       // estate's, which lands admin/creator/estateOwner together — the broadest root authority).
       const seed = discoverSeedDirective(candidates, domain);
-      if (seed === undefined) return undefined; // no seed path → the caller emits the diagnostic
-      found = { granter: seed.dir, via: "inferred" };
-      grantedRelation = seed.relationsWritten[0] ?? relation; // cosmetic — the seed's primary relation
-      via = "seed-path";
-      seedSpeculative = true;
-      seedWritesRelations = seed.relationsWritten;
+      if (seed !== undefined) {
+        found = { granter: seed.dir, via: "inferred" };
+        grantedRelation = seed.relationsWritten[0] ?? relation; // cosmetic — the seed's primary relation
+        via = "seed-path";
+        seedSpeculative = true;
+        seedWritesRelations = seed.relationsWritten;
+      }
     }
   }
+
+  // (4) BORN-DOMAIN GENESIS AUTHORITY (the co2 home case) — precedence over a standalone seed. The standalone
+  // path is "clean" ONLY when a granter was found, it isn't the speculative seed-path lane, AND that granter
+  // carries NO prerequisite invariant (a standalone re-seed of a prerequisite-gated granter — e.g.
+  // seedHomeCreator, gated by HomeCreatorSeedBindsOwner — would FALSE-fail because the prior genesis state is
+  // absent). When the standalone path is NOT clean, prefer proving the gated directive INSIDE the born
+  // workspace, whose genesis seats R for the owner.
+  const standaloneClean =
+    found !== undefined && !seedSpeculative && !directiveHasPrerequisiteInvariant(mod, found.granter.id);
+  if (!standaloneClean) {
+    const bornContext = discoverBornContextAuthority(mod, relation);
+    if (bornContext !== undefined) {
+      return {
+        domain,
+        gatedDirectiveId: gated.id,
+        relation,
+        grantedRelation: relation,
+        gatedPayload,
+        gatedAutoStamped: gatedSynth.autoStamped,
+        ...(gatedMintField !== undefined ? { gatedMintField, gatedAggregateId: gated.aggregateId } : {}),
+        // grant fields are UNUSED for a born-context leg (the runner births + dispatches inside); populate them
+        // with the genesis seed's id / empty payload so the shape stays uniform (never dispatched standalone).
+        grantDirectiveId: bornContext.seatsViaDirectiveId,
+        grantPayload: {},
+        grantAutoStamped: [],
+        grantSubjectFields: [],
+        grantGrantedByFields: [],
+        via: "born-context",
+        bornContext,
+      };
+    }
+    // No born-domain path. A standalone granter with a prerequisite it can't satisfy alone (and not the
+    // speculative lane): try the PREREQUISITE-SEED CHAIN — a sibling seed establishes the prerequisite state
+    // (the composed co2_platform case: `seedPlatformFounder` stamps the founder `seedPlatformAdmin` binds to).
+    // The runner dispatches the chain (as the proof actor = founder) BEFORE the grant. If no chain satisfies
+    // the prerequisite, do NOT emit a doomed passing leg — return undefined so the diagnostic names the gap.
+    // A speculative seed-path stays (it degrades safely at runtime).
+    if (found !== undefined && !seedSpeculative && directiveHasPrerequisiteInvariant(mod, found.granter.id)) {
+      const chain = discoverPrerequisiteChain(mod, found.granter);
+      if (chain === undefined) return undefined;
+      prerequisiteSeeds = chain;
+    }
+  }
+  if (found === undefined) return undefined; // no granter at all → the caller emits the diagnostic
   const granter = found.granter;
 
   // Synthesize the grant payload + resolve which fields route into subject / grantedBy (so runtime seats the
@@ -804,6 +1177,7 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
     via,
     ...(seedSpeculative ? { seedSpeculative: true } : {}),
     ...(seedWritesRelations !== undefined ? { seedWritesRelations } : {}),
+    ...(prerequisiteSeeds !== undefined ? { prerequisiteSeeds } : {}),
   };
 }
 
@@ -845,6 +1219,19 @@ export function diagnoseRelationBootstrapGap(mod: DomainModule): string | undefi
   if (discoverRelationBootstrapLeg(mod) !== undefined) return undefined; // resolved — no gap
   const relation = gated.requiresRelationGate!.relation;
   const object = gated.requiresRelationGate!.object;
+  // NAME THE UNMET PREREQUISITE (co2 home diagnostic): when a granter of R exists but carries a prerequisite
+  // invariant a standalone re-seed can't satisfy AND no birth genesis seats R, say so precisely.
+  const directivesAll = mod.directives as Directive<unknown>[];
+  const prereqGranter = directivesAll.find(
+    (d) => d !== gated && typeof d?.payloadSchema === "object" && d.birthsChild !== true
+      && probeGrantsRelation(d, relation, `${domain}/${d.id}`) && directiveHasPrerequisiteInvariant(mod, d.id),
+  );
+  if (prereqGranter !== undefined) {
+    const inv = (mod.workspaceInvariants ?? []).find((i) => i.on === prereqGranter.id);
+    return `${domain}/${gated.id} is gated by .requires("${relation}") but the proof cannot seed authority: the only granter of "${relation}" is `
+      + `${domain}/${prereqGranter.id}, which carries the prerequisite invariant '${inv?.id ?? "?"}' (it reads state an EARLIER step must establish), so a standalone re-seed FALSE-fails — and no \`.births()\` genesis seats "${relation}" to prove it in a born workspace. `
+      + `Establish "${relation}" via a birth genesis (a \`.births()\` whose chain runs ${prereqGranter.id} after seeding its prerequisite), or prove ${gated.id} by hand. (The negative conformance leg still proves the gate refuses an actorless offer.)`;
+  }
   const bases = resolveGrantableBaseRelations(mod.relationTypes, object, relation).filter((b) => b !== relation);
   const tried = bases.length > 0
     ? `no directive grants "${relation}" directly, nor any of its directly-grantable rewrite bases [${bases.join(", ")}]`
@@ -1544,7 +1931,7 @@ function generateBirthOnlyProof(
     `import { readFileSync } from "node:fs";`,
     `import { connect, encodeIntentOfferBytes } from "@githolon/client";`,
     `import { ${factory}, ${hashConst} } from "./${opts.packageName}.client.ts";`,
-    `void connect; void ${factory};`,
+    `void connect; void encodeIntentOfferBytes; 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);`,
@@ -1552,6 +1939,11 @@ function generateBirthOnlyProof(
     ...v2IdentityAndCleanupPreamble(opts, hashConst, n),
     ``,
     ...liveChildBirthLegLines(cb, opts, n),
+    // THE RELATION-BOOTSTRAP LEG (incl. LAYER 4 born-context): a birth-only domain may ALSO carry a gated
+    // non-birth directive whose authority is established by the birth genesis (co2 home's updateHomeProfile
+    // via birthHome→seedHomeCreator). Emit it so the birth-only proof names it (the born-context proof itself
+    // runs in the offline `githolon proof` lane). No-op when the domain has no gated directive.
+    ...relationSeedLegLines(primaryLegs.relationBootstrap, factory, n, primaryLegs.relationBootstrap === undefined ? diagnoseRelationBootstrapGap(mod) : undefined),
     `console.log(\`\\nALL GREEN — generated proof for "${opts.packageName}": deploy → child birth (\${WS} → the born child) → verified\`);`,
     ``,
     ...v2CatchFinally(),

package/src/framework/platform_admin.ts

@@ -0,0 +1,285 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * framework/platform_admin.ts — `seedPlatformAdmin`, THE PLATFORM ANALOG OF `seedHomeCreator`.
+ *
+ * WHY THIS EXISTS. A tenant platform (an org’s self-governing workspace) declares CUSTOM governance roles
+ * (`platformAdmin`, `platformMember`, …) as `relationType("workspace").relation("platformAdmin", …)` and gates its
+ * directives on them (`grantRole.requires("platformAdmin")`, `revokeRole.requires(
+ * "platformAdmin")`). But there is NO in-law bootstrap for the FOUNDING admin: `grantRole` is
+ * itself `platformAdmin`-gated (chicken/egg) and `revokeRole` REMOVES authority. So a platform's
+ * founding authority was only ever seated IMPLICITLY at platform birth (the `grantAdmin` step inside
+ * `buildGenesisChain`, which seats the FRAMEWORK `admin` relation — OUTSIDE the tenant's own domain), a
+ * seat a single-domain `githolon proof` can neither see nor establish.
+ *
+ * `seedPlatformAdmin` front-loads this into the framework, EXACTLY as `seedHomeCreator`
+ * (`framework/home.ts` shape) seats a home's `creator`: a first-class, PROVABLE founding-admin bootstrap
+ * that seats a TENANT-NAMED governance relation for a founder principal, at genesis, write-once, bound to
+ * the verified genesis author. Every platform then gets a consistent, proof-discoverable founding-admin
+ * seat tied to a real AuthProvider identity ("bring your own auth").
+ *
+ * ── BLAST RADIUS: IMPORTABLE, npm-only ──────────────────────────────────────────────────────────
+ * This is a TENANT-IMPORTABLE primitive — a directive/aggregate/invariant factory a tenant imports into
+ * THEIR OWN platform-governance domain and deploys via THEIR normal `evolve`. It seats a relation on
+ * `workspace:self` in the TENANT'S domain; it does NOT touch the running root/platform governance bundle
+ * (`framework/workspaces.ts`). This mirrors `home.ts`: `seedHomeOwner`/`birthHome`/`homeNameBindsOwner`
+ * are exported framework primitives a tenant composes into a SEPARATE, per-home deployable package — they
+ * are NOT baked into root's live governance. Adopting `seedPlatformAdmin` is a tenant recompile + evolve
+ * of their platform domain; no governance re-deploy, no re-birth.
+ *
+ * ── WHAT IT SEATS (design choice (b) — a tenant-NAMED relation, directly) ────────────────────────
+ * We seat the tenant's OWN relation (`platformAdmin`) directly, not the framework `admin` relation. Rationale:
+ *   • Tenant-owned governance — the platform's roles are the platform's law; the founding seat should be a
+ *     fact IN the tenant's domain, provable from that domain alone (the `githolon proof` subject).
+ *   • Self-contained per role, no rewrite plumbing required. (For a platform whose roles should ALL derive
+ *     from one admin, the tenant may instead seat ONE relation here and link the rest by rewrite —
+ *     `relation("platformMember", { rewrite: union(self(), computed("platformAdmin")) })` — design choice (a). We
+ *     support that cleanly too: seat once, rewrite the rest. Nothing here forbids it.)
+ *   • The relation is CLOSED OVER by the factory (LAW), never payload-carried — a payload-carried relation
+ *     would let a caller seat ANY relation (a forge). The founder subject is payload-carried but bound.
+ *
+ * ── HOW A TENANT ADOPTS (a platform-governance domain — before → after) ───────────────────────────────────────────
+ * BEFORE (the gap): a `platform-governance` domain with `platformAdmin`/`platformMember` relations, `grantRole
+ * .requires("platformAdmin")`, `revokeRole.requires("platformAdmin")` — but no in-law way to seat the
+ * first `platformAdmin`, so `githolon proof` can't establish authority for the gated directives.
+ * AFTER (one import + include, then evolve):
+ *
+ *   import { seedPlatformAdmin } from "@githolon/dsl";
+ *   export const founding = seedPlatformAdmin({ relation: "platformAdmin" });
+ *   export const PlatformFounder = founding.PlatformFounder;          // the founder singleton
+ *   export const seedPlatformFounder = founding.seedPlatformFounder;  // stamps the founder (genesis)
+ *   export const seatFoundingAdmin = founding.seedPlatformAdmin;           // seats platformAdmin@founder (genesis)
+ *   export const platformFounderWriteOnce = founding.platformFounderWriteOnce;
+ *   export const platformAdminBindsFounder = founding.platformAdminBindsFounder;
+ *   export const platformFounder = founding.platformFounder;          // audit query
+ *   // the platform's genesis chain runs, after the law installs:
+ *   //   [ … installDomain×2, seedGenesis, seedPlatformFounder(founder), seatFoundingAdmin(founder) ]
+ *
+ * The tenant DEPLOYS this via `evolve` (npm-only recompile + their normal deploy); no root/platform
+ * governance re-deploy, no re-birth. A NEW platform seeds it in its birth genesis; an EXISTING platform
+ * that was already born with an implicit `admin` seat evolves to ADD the tenant-relation seat (a
+ * one-time `seedPlatformFounder`+`seatFoundingAdmin` authored by the existing admin — see the note on the
+ * write-once posture below for the existing-platform lane).
+ *
+ * ── SECURITY POSTURE (mirror `seedHomeCreator`: genesis-only, ungated-but-safe) ──────────────────
+ * The seeds carry NO `.requires` (gating the founding seat on the relation it establishes is the very
+ * chicken/egg this primitive dissolves). They are safe because they are CONTROL-PLANE SEEDS:
+ *   1. WRITE-ONCE — `platformFounderWriteOnce` refuses `seedPlatformFounder` if a founder is ALREADY
+ *      seated (a `pre:`-apply read of the singleton). So the founder can be stamped exactly once; a
+ *      replayed/injected re-seat on the open session lane is refused.
+ *   2. FOUNDER == VERIFIED GENESIS AUTHOR — `platformFounderWriteOnce` also binds the recorded founder to
+ *      `ctx.principal` (the captured, peer-identical author). The upstream VERIFICATION is the birth
+ *      offer's principal (the parent's gate verified an AuthProvider identity before the offer-effect ran
+ *      the genesis actor as that founder) — the SAME "bring your own auth" boundary `birthHome` relies on.
+ *      (We do NOT REQUIRE `ctx.principalVerified` inside the child gate: genesis runs on a warrant-free
+ *      prefix — the warrant lands LAST, `home.ts` "BREAK 1" — so `principalVerified` is not yet true at
+ *      the seed step; requiring it would make every platform un-birthable. The verified-founder guarantee
+ *      is therefore the offer principal, asserted upstream, not re-asserted here. See the report.)
+ *   3. THE SEAT CAN ONLY GRANT THE FOUNDER — `platformAdminBindsFounder` refuses `seedPlatformAdmin`
+ *      unless its tuple subject == the recorded founder. So even an ungated seed can seat NO ONE but the
+ *      write-once founder. The tuple is a positive `writeTuple` grant (never a revoke).
+ * Together: the ONLY principal that can ever hold the seeded relation via this primitive is the write-once
+ * founder bound to the verified genesis author. This is `seedHomeCreator`'s posture, at platform grain.
+ *
+ * ── PROVABLE ────────────────────────────────────────────────────────────────────────────────────
+ * `seedPlatformAdmin` (the tuple-seating directive) is marked `.grants(relation)` — the producer marker
+ * (`codegen_proof.ts`) so the proof's bootstrap discovery finds the granter UNAMBIGUOUSLY (no inference,
+ * no guessing) and proves the platform's `.requires(relation)`-gated directives (`grantRole`/`revokeRole`)
+ * from it — the born-context / relation-bootstrap proof leg the layer-4 discovery understands.
+ *
+ * ── ERA-SAFE ────────────────────────────────────────────────────────────────────────────────────
+ * A factory: a package that never CALLS `seedPlatformAdmin({…})` emits none of these directives /
+ * aggregates / invariants and is byte-identical to before this file existed.
+ */
+import { z } from "zod";
+import { aggregate, instance, type AggregateHandle } from "../aggregate.js";
+import { t } from "../fields.js";
+import { Lww } from "../drivers.js";
+import { directive, type RequirableDirective } from "../directive.js";
+import { set } from "../ops.js";
+import { query, type QueryDecl } from "../query.js";
+import { writeTuple, RelationTuple } from "./relations.js";
+import { workspaceInvariant, refAs, type WorkspaceInvariantDecl } from "./workspace_invariant.js";
+
+/** The founder singleton's stable instance id — one founder per platform workspace (`workspace:self`). */
+export const PLATFORM_FOUNDER_ID = "platform-founder:self";
+
+/** The object every seat is written against — the self-relative workspace scope (`workspace:self#R`),
+ *  the SAME self-relative posture the framework `admin`/`creator` relations use (custody guarantees a
+ *  workspace only ever folds its OWN relation tuples, so the seat is name-plumbing-free). */
+const SELF_WORKSPACE_OBJECT = "workspace:self";
+
+/** A tuple SUBJECT: `user:<uid>` (an AuthProvider identity) or `key:<keyHash>` (a control-plane key —
+ *  e.g. a platform's `sha256(platformAdminKey)`). Mirrors the relation-tuple subject vocabulary; a raw
+ *  uid carrying `:` / a bare `*` is refused so it can never forge a wildcard/userset. */
+const FOUNDER_SUBJECT_RE = /^(user|key):[A-Za-z0-9][A-Za-z0-9_.:/-]*$/;
+const founderSubject = z.string().regex(FOUNDER_SUBJECT_RE, "founder must be user:<uid> or key:<keyHash>");
+
+/** A relation name (the seated edge label) — a bare identifier, like a directive/cap name. */
+const RELATION_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+
+/** The bundle a `seedPlatformAdmin({ relation })` call yields — the aggregate, the two genesis seeds, the
+ *  two binding invariants, and the audit query. Spread the members into a platform-governance domain
+ *  module (see the adoption sketch at the top of this file). */
+export interface PlatformAdminSeed {
+  /** The founder singleton aggregate — records the platform's founding principal (write-once at genesis). */
+  readonly PlatformFounder: AggregateHandle;
+  /** GENESIS SEED 1 — stamps the founder singleton (write-once, bound to the verified genesis author). */
+  readonly seedPlatformFounder: RequirableDirective<{ founder: string; seededAt: string }>;
+  /** GENESIS SEED 2 — seats `workspace:self#<relation>@<founder>` (the founding-admin tuple). `.grants(R)`. */
+  readonly seedPlatformAdmin: RequirableDirective<{ founder: string; seededAt: string }>;
+  /** The write-once + author-binding invariant on {@link seedPlatformFounder}. */
+  readonly platformFounderWriteOnce: WorkspaceInvariantDecl;
+  /** The subject-binding invariant on {@link seedPlatformAdmin} (the seat can grant NO ONE but the founder). */
+  readonly platformAdminBindsFounder: WorkspaceInvariantDecl;
+  /** Audit read: "who is this platform's founder?" — the recorded founder + the relation seated. */
+  readonly platformFounder: QueryDecl;
+  /** The relation this bundle seats (echoed back for the tenant's convenience). */
+  readonly relation: string;
+}
+
+/** Optional id overrides — a platform seating MORE THAN ONE founding relation from the same founder passes
+ *  distinct ids per call so the directives/invariants/aggregate don't collide. Defaults suit the common
+ *  single-founding-relation case. */
+export interface SeedPlatformAdminOptions {
+  /** The tenant governance relation to seat for the founder (`"platformAdmin"`). Required. */
+  readonly relation: string;
+  /** The founder singleton aggregate id (default `"PlatformFounder"`). Share it across multi-relation
+   *  seats so one founder identity is recorded once and seated into several relations. */
+  readonly founderAggregateId?: string;
+  /** The founder-stamp directive id (default `"seedPlatformFounder"`). */
+  readonly founderDirectiveId?: string;
+  /** The tuple-seat directive id (default `"seedPlatformAdmin"`). */
+  readonly seatDirectiveId?: string;
+  /** The write-once invariant id (default `"PlatformFounderWriteOnce"`). */
+  readonly writeOnceInvariantId?: string;
+  /** The subject-binding invariant id (default `"PlatformAdminBindsFounder"`). */
+  readonly bindsInvariantId?: string;
+  /** The audit-query id (default `"platformFounder"`). */
+  readonly queryId?: string;
+}
+
+/**
+ * `seedPlatformAdmin({ relation })` — build the founding-admin bootstrap bundle for a tenant platform.
+ * See the file header for the full doctrine, security posture, and adoption sketch.
+ */
+export function seedPlatformAdmin(opts: SeedPlatformAdminOptions): PlatformAdminSeed {
+  const relation = opts.relation;
+  if (typeof relation !== "string" || !RELATION_RE.test(relation)) {
+    throw new Error(
+      `seedPlatformAdmin({ relation }): relation must be a bare relation name (matched ${RELATION_RE}); got ${JSON.stringify(relation)}`,
+    );
+  }
+  const founderAggregateId = opts.founderAggregateId ?? "PlatformFounder";
+  const founderDirectiveId = opts.founderDirectiveId ?? "seedPlatformFounder";
+  const seatDirectiveId = opts.seatDirectiveId ?? "seedPlatformAdmin";
+  const writeOnceInvariantId = opts.writeOnceInvariantId ?? "PlatformFounderWriteOnce";
+  const bindsInvariantId = opts.bindsInvariantId ?? "PlatformAdminBindsFounder";
+  const queryId = opts.queryId ?? "platformFounder";
+
+  /** The founder singleton — a platform's founding principal + the relation it was seated into (audit). */
+  const PlatformFounder = aggregate(founderAggregateId, {
+    /** The founding principal — a `user:<uid>` / `key:<keyHash>` subject; write-once at genesis. */
+    principal: t.string().merge(Lww),
+    /** The governance relation seated for the founder (echo of the factory's `relation`). */
+    relation: t.string().merge(Lww),
+    /** ISO-8601, caller-stamped (determinism — no clock in the plan). */
+    seededAt: t.string().merge(Lww),
+  });
+
+  /**
+   * GENESIS SEED 1 — stamp the founder singleton at the fixed id. Authored by the platform's birth/genesis
+   * chain; on the open session lane it is refused by {@link platformFounderWriteOnce} (a genesis founder is
+   * already seated by then) + the author binding. `.ensures` (a deterministic-keyed singleton).
+   */
+  const seedPlatformFounder = directive(founderDirectiveId)
+    .ensures(PlatformFounder)
+    .payload(z.object({ founder: founderSubject, seededAt: z.string().min(1) }))
+    .plan((p) => {
+      const h = instance(PlatformFounder, PLATFORM_FOUNDER_ID);
+      return [set(h, "principal", p.founder), set(h, "relation", relation), set(h, "seededAt", p.seededAt)];
+    });
+
+  /**
+   * WRITE-ONCE + AUTHOR-BINDING invariant on {@link seedPlatformFounder}. Reads the PRE-apply singleton
+   * (the `pre:` id lane — see `workspaces.ts::retireOwnOnly`): a founder may be stamped exactly ONCE, and
+   * only for the VERIFIED genesis author (`ctx.principal` — the captured, peer-identical author identity;
+   * the upstream verification is the birth offer's principal, see the file header). Runs at the ONE gate
+   * on every lane (author / edge admission / verify_chain).
+   */
+  const platformFounderWriteOnce = workspaceInvariant(writeOnceInvariantId)
+    .on(founderDirectiveId)
+    .reads(() => [refAs("prior", founderAggregateId, "pre:" + PLATFORM_FOUNDER_ID)])
+    .assert(({ prior }, ctx) => {
+      const seated = (prior ?? {}) as { principal?: string };
+      // WRITE-ONCE: a founder already recorded ⇒ refuse a re-seat (the seat is immutable after genesis).
+      if (seated.principal) {
+        return { reject: "platform-founder-write-once: a founding admin is already seated for this platform" };
+      }
+      // AUTHOR BINDING: the recorded founder MUST be the captured, verified author of this seed. So a seed
+      // can only stamp ITS OWN author as the founder — never a third party.
+      const author = ctx?.principal ?? "";
+      const intent = (ctx?.intent ?? {}) as { founder?: string };
+      return author && intent.founder === author
+        ? { accept: true }
+        : { reject: "platform-founder-must-bind-verified-author: the seeded founder must equal the seeding principal" };
+    });
+
+  /**
+   * GENESIS SEED 2 — seat the founding tuple `workspace:self#<relation>@<founder>` (a POSITIVE grant, never
+   * a revoke). Marked `.grants(relation)` so the proof's bootstrap discovery finds it unambiguously. Gated
+   * by {@link platformAdminBindsFounder} — the tuple subject can be NO ONE but the recorded founder.
+   */
+  const seedPlatformAdminDirective = directive(seatDirectiveId)
+    // `.ensures(RelationTuple)` — the deterministic-keyed (object, relation) tuple aggregate is admitted by
+    // the id-mint gate (upsert-by-deterministic-key); the tenant includes `RelationTuple` in its aggregates.
+    .ensures(RelationTuple)
+    .payload(z.object({ founder: founderSubject, seededAt: z.string().min(1) }))
+    .plan((p) =>
+      writeTuple({
+        object: SELF_WORKSPACE_OBJECT,
+        relation,
+        subject: p.founder,
+        grantedBy: p.founder,
+        grantedAt: p.seededAt,
+      }),
+    )
+    .grants(relation);
+
+  /**
+   * SUBJECT-BINDING invariant on {@link seedPlatformAdminDirective}. Reads the founder singleton (stamped
+   * by seed 1 earlier in the genesis chain) and refuses unless the tuple's subject == the recorded founder.
+   * So the founding relation can be seated for the write-once founder and NO ONE ELSE — even though the
+   * seed itself carries no `.requires`.
+   */
+  const platformAdminBindsFounder = workspaceInvariant(bindsInvariantId)
+    .on(seatDirectiveId)
+    .reads(() => [refAs("founder", founderAggregateId, PLATFORM_FOUNDER_ID)])
+    .assert(({ founder }, ctx) => {
+      const rec = (founder ?? {}) as { principal?: string };
+      const intent = (ctx?.intent ?? {}) as { founder?: string };
+      // The seat's subject MUST be the recorded (write-once, author-bound) founder.
+      if (!rec.principal) {
+        return { reject: "platform-admin-seat-needs-founder: seed the platform founder before seating its relation" };
+      }
+      return rec.principal === intent.founder
+        ? { accept: true }
+        : { reject: "platform-admin-binds-founder: the seated relation may be granted only to the recorded founder" };
+    });
+
+  /** Audit read — "who is this platform's founder + which relation was seated". */
+  const platformFounder = query(queryId).key("principal").returns(PlatformFounder);
+
+  return {
+    PlatformFounder,
+    seedPlatformFounder,
+    seedPlatformAdmin: seedPlatformAdminDirective,
+    platformFounderWriteOnce,
+    platformAdminBindsFounder,
+    platformFounder,
+    relation,
+  };
+}

package/src/index.ts

@@ -312,6 +312,14 @@ export {
   birthAttestation,
   parentAttestedBirth,
 } from "./framework/home.js";
+// THE PLATFORM FOUNDING-ADMIN BOOTSTRAP (the platform analog of seedHomeCreator) — a tenant-importable
+// factory that seats a tenant-named governance relation for a write-once, author-bound founder at genesis.
+export {
+  seedPlatformAdmin,
+  PLATFORM_FOUNDER_ID,
+  type PlatformAdminSeed,
+  type SeedPlatformAdminOptions,
+} from "./framework/platform_admin.js";
 // THE GENESIS WARRANT (identity_keys.md step 0) — the in-history birth fact that lets
 // the gate's genesis clause admit a founding control-plane grant on a virgin chain.
 export {