@githolon/dsl 0.30.1 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.30.1",
+  "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);
@@ -445,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).`,
     `{`,
@@ -455,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)` : ``}\`);`,
@@ -536,6 +547,24 @@ export interface RelationBootstrapLeg {
    *  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
@@ -594,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). */
@@ -862,6 +925,95 @@ function directiveHasPrerequisiteInvariant(mod: DomainModule, directiveId: strin
   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
@@ -916,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;
@@ -980,11 +1133,16 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
         bornContext,
       };
     }
-    // No born-domain path. If a standalone granter exists but carries a prerequisite it can't satisfy alone
-    // (and isn't the speculative lane), do NOT emit a doomed passing leg — return undefined so the caller's
-    // loud diagnostic names the unmet prerequisite. A speculative seed-path stays (it degrades safely).
+    // 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)) {
-      return undefined;
+      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
@@ -1019,6 +1177,7 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
     via,
     ...(seedSpeculative ? { seedSpeculative: true } : {}),
     ...(seedWritesRelations !== undefined ? { seedWritesRelations } : {}),
+    ...(prerequisiteSeeds !== undefined ? { prerequisiteSeeds } : {}),
   };
 }
 

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 {