@githolon/dsl 0.30.1 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.30.1",
+  "version": "0.31.1",
   "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/aggregate.ts

@@ -155,6 +155,17 @@ export interface AggregateHandle<
   readonly hasMany: HasManyFields<F>;
   /** Brand so a plain string is never accepted where a handle is required. */
   readonly __isAggregateHandle: true;
+  /**
+   * FRAMEWORK-SHARED brand (Dart-codegen hygiene). Set (by `framework/framework_aggregates.ts`)
+   * ONLY on the framework-owned aggregate singletons declared in `dsl/src/framework/` — most
+   * importantly `RelationTuple`, auto-added to EVERY relation-using domain. A branded aggregate's
+   * Dart surface (read-model class, typed-id class, by-id accessors) is emitted ONCE per package into
+   * a shared `nomos_framework.dart` file, NOT re-emitted in each domain's generated `.dart` — so a
+   * package barrel re-exporting several domains never gets a duplicate framework symbol (no hand-
+   * maintained `hide` clause). NOT hashed / NOT law: a pure frontend-codegen marker (like
+   * `readModelAggregates`). Identified by OBJECT IDENTITY (the branded singleton), so a tenant
+   * aggregate that merely SHARES a name is never misclassified. OMITTED on tenant aggregates. */
+  readonly framework?: true;
   /** Presence-only flag (hashed); OMITTED ENTIRELY when no invariant is declared. */
   readonly hasInvariant?: true;
   /** The executable body — ships in the engine bundle, NOT the manifest. */

package/src/codegen_dart.ts

@@ -1168,8 +1168,8 @@ function emitEvidenceRefClass(): string {
 
 /** True when ANY aggregate field in the module is `t.evidence()` — gates emitting the
  * shared [emitEvidenceRefClass] once. */
-function moduleUsesEvidence(mod: DomainModule): boolean {
-  return mod.aggregates.some((a) =>
+function moduleUsesEvidence(aggregates: readonly AggregateHandle[]): boolean {
+  return aggregates.some((a) =>
     Object.values(a.fields as Record<string, Field>).some((f) => f.kind === "evidence"),
   );
 }
@@ -2300,14 +2300,21 @@ function emitMintedCreates(
   directives: AnyDirective[],
   domainName: string,
   enumDartTypes: Map<string, string>,
+  /** Aggregate ids whose typed-id CLASS is emitted in the shared `nomos_framework.dart` (imported
+   *  here), so it must NOT be re-declared. Minting FACTORIES still emit and reference the imported
+   *  class. Empty = emit every id class locally (the single-domain / shared-file path). */
+  skipIdClassFor: ReadonlySet<string> = new Set(),
 ): string {
   const blocks: string[] = [];
 
   // (1) A typed id class per aggregate. Dedup by the typed-id class NAME: two wire
   // types never collide on a name (the name is a pure function of the type), and a
   // domain that re-exports a framework aggregate must not emit its id class twice.
+  // Framework-shared aggregates are emitted ONCE in the package's `nomos_framework.dart`,
+  // so their id class is SKIPPED here (referenced via import).
   const emittedIdClasses = new Set<string>();
   for (const agg of aggregates) {
+    if (skipIdClassFor.has(agg.id)) continue;
     const cls = typedIdClassForAggregateType(agg.id);
     if (emittedIdClasses.has(cls)) continue;
     emittedIdClasses.add(cls);
@@ -2565,12 +2572,49 @@ export interface DomainModule {
   dartRefImports?: DartRefImport[];
 }
 
+/** Options controlling FRAMEWORK-SHARED aggregate deduplication (Dart-codegen hygiene). */
+export interface GenerateDartDomainOptions {
+  /**
+   * Aggregate ids whose Dart surface (projection class, read model, typed-id class, by-id accessors)
+   * is emitted ONCE per package in the shared `nomos_framework.dart` and MUST NOT be re-emitted here —
+   * this domain REFERENCES them via {@link frameworkImportUri}. Empty/absent ⇒ emit everything locally
+   * (the legacy single-file behaviour; byte-identical to before this option existed).
+   */
+  readonly skipAggregateIds?: ReadonlySet<string>;
+  /**
+   * Framework-shared DIRECTIVE ids whose generated payload class (+ minted-create factory) is emitted
+   * ONCE per package in the shared file and MUST NOT be re-emitted here. The domain still OFFERS them
+   * (the client offer methods stay per-domain); only the payload TYPE moves to the shared file.
+   */
+  readonly skipDirectiveIds?: ReadonlySet<string>;
+  /**
+   * Framework-shared QUERY ids whose top-level `watch<Q>`/`read<Q>` accessors are emitted ONCE per
+   * package in the shared file and MUST NOT be re-emitted here. The client's per-domain query methods
+   * stay (they reference the shared read models via the framework import).
+   */
+  readonly skipQueryIds?: ReadonlySet<string>;
+  /**
+   * Relative import of the shared framework file (e.g. `nomos_framework.dart`). Added as an ordinary
+   * `import` so skipped framework symbols resolve. Omit when nothing is skipped.
+   */
+  readonly frameworkImportUri?: string;
+}
+
 /** Generate the full Dart source for one domain module. */
-export function generateDartDomain(mod: DomainModule): string {
+export function generateDartDomain(mod: DomainModule, opts: GenerateDartDomainOptions = {}): string {
   const domainKey = mod.domain ?? mod.name;
+  const skipAggregateIds = opts.skipAggregateIds ?? new Set<string>();
+  const skipDirectiveIds = opts.skipDirectiveIds ?? new Set<string>();
+  const skipQueryIds = opts.skipQueryIds ?? new Set<string>();
+  // The symbols whose Dart surface this file EMITS (framework-shared ones live in the shared file).
+  const localAggregates = mod.aggregates.filter((a) => !skipAggregateIds.has(a.id));
+  const localDirectives = mod.directives.filter((d) => !skipDirectiveIds.has(d.id));
+  const localQueries = (mod.queries ?? []).filter((q) => !skipQueryIds.has(q.id));
+  // Enums are collected from the LOCALLY-emitted symbols only — a framework directive/aggregate's
+  // enums ride the shared `nomos_framework.dart`, so a domain that skips them emits no dangling enum.
   const { dartTypes, decls } = collectEnums(
-    mod.aggregates,
-    mod.directives,
+    localAggregates,
+    localDirectives,
     domainKey,
   );
   const refIdClassForAggregate = refIdClassResolver(mod);
@@ -2583,7 +2627,7 @@ export function generateDartDomain(mod: DomainModule): string {
   );
   const enumBlock = decls.join("\n\n");
   const permissionVocabularyBlock = emitPermissionVocabulary(mod.permissionVocabulary);
-  const aggBlock = mod.aggregates
+  const aggBlock = localAggregates
     .map((a) =>
       emitAggregate(
         a,
@@ -2593,7 +2637,7 @@ export function generateDartDomain(mod: DomainModule): string {
       ),
     )
     .join("\n\n");
-  const dirBlock = mod.directives
+  const dirBlock = localDirectives
     .map((d) => emitDirective(d, domainKey, dartTypes))
     .join("\n\n");
 
@@ -2602,7 +2646,9 @@ export function generateDartDomain(mod: DomainModule): string {
   // ref fields name their target's typed id), plus a top-level `create…` factory that
   // mints THROUGH the kernel (no raw id) for every `.creates` directive carrying a
   // `mintSeed` + an own-id field.
-  const mintedBlock = emitMintedCreates(mod.aggregates, mod.directives, domainKey, dartTypes);
+  // Minted-create factories for framework directives (if any) live in the shared file — pass only the
+  // LOCAL directives here; framework typed-id classes are likewise skipped (referenced via import).
+  const mintedBlock = emitMintedCreates(mod.aggregates, localDirectives, domainKey, dartTypes, skipAggregateIds);
 
   // PROVIDER SDK (the symmetric twin of the peer payload classes): for each declared
   // `impureCapability` capability, a typed Obligation/Result/Failure + handler typedef + dispatcher.
@@ -2635,7 +2681,7 @@ export function generateDartDomain(mod: DomainModule): string {
     list.push(c);
     combinedsByType.set(c.of, list);
   }
-  const readModelBlock = mod.aggregates
+  const readModelBlock = localAggregates
     .filter((a) => readModelTypes.has(a.id))
     .map((a) =>
       emitReadModel(
@@ -2657,7 +2703,7 @@ export function generateDartDomain(mod: DomainModule): string {
   // §5 claim that "codegen already emits count reads" was wrong; this is the actual
   // first emission. The predicate is baked into the maintained counter and is
   // INVISIBLE to the generated accessor (worldview law).
-  const queryReads = (mod.queries ?? [])
+  const queryReads = localQueries
     .map((q) =>
       emitQueryReads(
         q,
@@ -2731,7 +2777,9 @@ export function generateDartDomain(mod: DomainModule): string {
     )
     .join("\n\n");
   const orderedReadBlock = (mod.orderedReads ?? []).map(emitOrderedReads).join("\n\n");
-  const byIdReads = mod.aggregates.map(emitAggregateByIdReads).join("\n\n");
+  // By-id accessors for framework-shared aggregates live in `nomos_framework.dart` (emitted once);
+  // this domain references them via the framework import.
+  const byIdReads = localAggregates.map(emitAggregateByIdReads).join("\n\n");
   const readBlock = [queryReads, countReads, sumReads, minReads, maxReads, existsReads, orderedReadBlock, byIdReads]
     .filter((s) => s !== "")
     .join("\n\n");
@@ -2739,7 +2787,7 @@ export function generateDartDomain(mod: DomainModule): string {
   // `_mapEq` is only referenced by aggregate `==`/`hashCode` for MAP fields. Emit it
   // ONLY when some aggregate has a map field, else a map-less domain trips an
   // unused-element lint.
-  const hasMapField = mod.aggregates.some((a) =>
+  const hasMapField = localAggregates.some((a) =>
     Object.values(a.fields as Record<string, Field>).some((f) => f.kind === "map"),
   );
   const helperBlock = hasMapField
@@ -2771,6 +2819,9 @@ export function generateDartDomain(mod: DomainModule): string {
     // out of nomos_client into the co-located tenant package). The framework barrel
     // re-exports wire/dispatch/subscriptions/provider, so one import covers them all.
     `import 'package:nomos_client/nomos_client.dart';`,
+    // FRAMEWORK-SHARED aggregates (RelationTuple, …) are emitted ONCE per package in the shared
+    // file; import it so this domain's read accessors / ref-id fields resolve those symbols.
+    ...(opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),
     ...(mod.dartImports ?? []).map(dartImportLine),
     ``,
     `// ---- enums ----`,
@@ -2783,7 +2834,7 @@ export function generateDartDomain(mod: DomainModule): string {
           ``,
         ]
       : []),
-    ...(moduleUsesEvidence(mod)
+    ...(moduleUsesEvidence(localAggregates)
       ? [
           `// ---- evidence (content-addressed EvidenceRef; evidence.md §9.2) ----`,
           emitEvidenceRefClass(),

package/src/codegen_dart_client.ts

@@ -99,6 +99,14 @@ export interface DartBridgeClientOptions {
   readonly interface?: unknown;
   /** Where the bridge/runtime support types are imported from. */
   readonly supportImport?: "vendored" | "package";
+  /**
+   * Relative import of the shared `nomos_framework.dart` (framework-shared aggregate types, emitted
+   * ONCE per package). When present the client IMPORTS it (its by-id accessors reference framework
+   * read models) and RE-EXPORTS it, so a package barrel re-exporting several domain clients surfaces
+   * the framework types EXACTLY ONCE (Dart de-dups re-exports of the SAME library) — no `hide` needed.
+   * Omit for a package with no framework-shared aggregates.
+   */
+  readonly frameworkImportUri?: string;
 }
 
 /** Generate the `<name>.client.dart` async bridge client for one domain module. */
@@ -245,9 +253,13 @@ export function generateDartBridgeClient(mod: DomainModule, opts: DartBridgeClie
     ...(opts.interface !== undefined ? [`import 'dart:convert';`, ``] : []),
     `import '${supportImport}';`,
     `import '${mod.name}.dart';`,
+    // Framework-shared aggregate types (RelationTupleReadModel, …) live in the ONE shared file — import
+    // them (the by-id accessors reference them) and re-export them (once per package, Dart de-dups).
+    ...(opts.frameworkImportUri !== undefined ? [`import '${opts.frameworkImportUri}';`] : []),
     `// Re-export the sibling types (read models + payloads + the bridge runtime) so ONE import of this`,
     `// client file gives an app the whole typed surface.`,
     `export '${mod.name}.dart';`,
+    ...(opts.frameworkImportUri !== undefined ? [`export '${opts.frameworkImportUri}';`] : []),
     `export '${supportImport}' show NomosBridge, BridgeTransport, NomosBridgeError, MissingOfferAuthority, kWebviewBridgeVersion;`,
     ``,
     `/// sha256 of the deployed \`.package.usda\` — the installed law this client offers under.`,

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/compile_package_main.ts

@@ -61,6 +61,11 @@ import {
   type PermissionVocabulary,
 } from "./codegen_dart.js";
 import { generateDartBridgeClient } from "./codegen_dart_client.js";
+import {
+  isFrameworkAggregate,
+  isFrameworkDirective,
+  isFrameworkQuery,
+} from "./framework/framework_aggregates.js";
 import { finishCount, type AnyCount } from "./count.js";
 import type { QueryDecl } from "./query.js";
 import type { SpatialDecl } from "./spatial.js";
@@ -387,35 +392,108 @@ function emitDart(
     removeVendoredDartSupport(dartOut);
   }
 
-  // 2. one generated file per composed domain — the TYPES (`<name>.dart`) + the async bridge
-  //    CLIENT (`<name>.client.dart`, the Flutter sibling of `<name>.client.ts`).
-  const written: string[] = [];
+  // 2. FRAMEWORK-SHARED symbol dedup (Dart-codegen hygiene). Framework-owned symbols fold into MANY
+  //    domains, so their generated Dart would be DEFINED once per domain — a package barrel re-exporting
+  //    ≥2 domains then COLLIDES (the historical `hide RelationTuple, EnrollDelegationPayload,
+  //    readSignerDelegationByUser, …` band-aid). THREE kinds are deduped, each identified by the
+  //    framework BRAND (object identity, so a tenant symbol that merely shares a name is never
+  //    misclassified) and emitted EXACTLY ONCE into `nomos_framework.dart`:
+  //      • AGGREGATES — read-model class, typed-id class, by-id accessors (`RelationTuple` auto-added
+  //        to every relation-using domain, `SignerDelegation`/`KeyScope`/… re-exported verbatim);
+  //      • DIRECTIVES — the generated payload class (relate/signer/enroll family). The domain still
+  //        OFFERS them (client offer methods stay per-domain); only the payload TYPE moves to the shared file;
+  //      • QUERIES — the top-level `watch<Q>`/`read<Q>` accessors.
+  //    Per-domain files SKIP each and IMPORT the shared file; clients RE-EXPORT it (Dart de-dups the
+  //    same-library re-export). So a barrel over all domains needs NO `hide` clause.
+  type ModDirective = DomainModule["directives"][number];
+  type ModQuery = NonNullable<DomainModule["queries"]>[number];
+  const frameworkAggById = new Map<string, AggregateHandle>();
+  const frameworkDirById = new Map<string, ModDirective>();
+  const frameworkQueryById = new Map<string, ModQuery>();
   for (const mod of modules) {
-    // Default the read-model allowlist to EVERY aggregate when the domain didn't pin one, so
-    // `<name>.dart` carries a read model per aggregate — the bridge client imports them. A domain
-    // that pins `readModelAggregates` keeps its choice (byte-identical to before this default).
-    const modForDart: DomainModule =
-      mod.readModelAggregates === undefined
-        ? { ...mod, readModelAggregates: mod.aggregates.map((a) => a.id) }
-        : mod;
-    const src = generateDartDomain(modForDart);
+    for (const a of mod.aggregates) if (isFrameworkAggregate(a)) frameworkAggById.set(a.id, a);
+    for (const d of mod.directives) if (isFrameworkDirective(d)) frameworkDirById.set(d.id, d);
+    for (const q of mod.queries ?? []) if (isFrameworkQuery(q)) frameworkQueryById.set(q.id, q);
+  }
+  const frameworkAggs = [...frameworkAggById.values()];
+  const frameworkDirs = [...frameworkDirById.values()];
+  const frameworkQueries = [...frameworkQueryById.values()];
+  const frameworkAggIds: ReadonlySet<string> = new Set(frameworkAggById.keys());
+  const frameworkDirIds: ReadonlySet<string> = new Set(frameworkDirById.keys());
+  const frameworkQueryIds: ReadonlySet<string> = new Set(frameworkQueryById.keys());
+  const hasFrameworkSymbols =
+    frameworkAggs.length > 0 || frameworkDirs.length > 0 || frameworkQueries.length > 0;
+  const FRAMEWORK_FILE = "nomos_framework";
+  const frameworkImportUri = hasFrameworkSymbols ? `${FRAMEWORK_FILE}.dart` : undefined;
+
+  const written: string[] = [];
+
+  const writeGenerated = (fileBase: string, src: string): string => {
     if (!src.includes(DART_PACKAGE_IMPORT)) {
       fail(
-        `generated Dart for domain '${mod.name}' does not carry the expected support import (${DART_PACKAGE_IMPORT}) — codegen_dart header drifted; fix the rewrite in compile_package_main.ts`,
+        `generated Dart for '${fileBase}' does not carry the expected support import (${DART_PACKAGE_IMPORT}) — codegen_dart header drifted; fix the rewrite in compile_package_main.ts`,
       );
     }
-    const p = path.join(dartOut, `${mod.name}.dart`);
+    const p = path.join(dartOut, `${fileBase}.dart`);
     writeFileSync(
       p,
       supportImport === "vendored" ? src.replace(DART_PACKAGE_IMPORT, DART_RELATIVE_IMPORT) : src,
       "utf8",
     );
     written.push(p);
+    return p;
+  };
+
+  // 2a. the shared framework file — the framework aggregates + directives + queries, ONCE. Its own
+  //     surface is emitted in full (no skip). Imported by every domain that folds any framework symbol.
+  if (hasFrameworkSymbols) {
+    const frameworkMod: DomainModule = {
+      name: FRAMEWORK_FILE,
+      domain: FRAMEWORK_FILE,
+      aggregates: frameworkAggs,
+      directives: frameworkDirs,
+      readModelAggregates: frameworkAggs.map((a) => a.id),
+      ...(frameworkQueries.length > 0 ? { queries: frameworkQueries } : {}),
+    };
+    writeGenerated(FRAMEWORK_FILE, generateDartDomain(frameworkMod));
+  }
+
+  // 2b. one generated file per composed domain — the TYPES (`<name>.dart`) + the async bridge
+  //     CLIENT (`<name>.client.dart`, the Flutter sibling of `<name>.client.ts`).
+  for (const mod of modules) {
+    // Default the read-model allowlist to EVERY aggregate when the domain didn't pin one, so
+    // `<name>.dart` carries a read model per aggregate — the bridge client imports them. A domain
+    // that pins `readModelAggregates` keeps its choice (byte-identical to before this default).
+    const modForDart: DomainModule =
+      mod.readModelAggregates === undefined
+        ? { ...mod, readModelAggregates: mod.aggregates.map((a) => a.id) }
+        : mod;
+    // Skip framework symbols this domain folds (they live in the shared file); reference them via the
+    // framework import. Only pass the import when this domain actually folds a framework symbol.
+    const domainFwAggIds = new Set(
+      modForDart.aggregates.filter((a) => frameworkAggIds.has(a.id)).map((a) => a.id),
+    );
+    const domainFwDirIds = new Set(
+      modForDart.directives.filter((d) => frameworkDirIds.has(d.id)).map((d) => d.id),
+    );
+    const domainFwQueryIds = new Set(
+      (modForDart.queries ?? []).filter((q) => frameworkQueryIds.has(q.id)).map((q) => q.id),
+    );
+    const foldsFramework = domainFwAggIds.size > 0 || domainFwDirIds.size > 0 || domainFwQueryIds.size > 0;
+    const domainFrameworkImport = foldsFramework ? frameworkImportUri : undefined;
+    const src = generateDartDomain(modForDart, {
+      skipAggregateIds: domainFwAggIds,
+      skipDirectiveIds: domainFwDirIds,
+      skipQueryIds: domainFwQueryIds,
+      ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
+    });
+    writeGenerated(mod.name, src);
 
     const clientSrc = generateDartBridgeClient(modForDart, {
       domainHash,
       interface: packageInterface[modForDart.domain ?? modForDart.name],
       supportImport,
+      ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
     });
     const cp = path.join(dartOut, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");

package/src/directive.ts

@@ -71,6 +71,16 @@ export interface Directive<P = unknown> {
   readonly aggregateId: string;
   readonly payloadSchema: z.ZodType<P>;
   readonly plan: (payload: P, ctx: Ports) => PlannedOp[];
+  /**
+   * FRAMEWORK-SHARED brand (Dart-codegen hygiene). Set (by `framework/framework_aggregates.ts`) ONLY on
+   * the framework-owned directive singletons declared in `dsl/src/framework/` (the relate/signer/enroll
+   * family — `relateSubject`, `enrollDelegation`, `advanceSignerEpoch`, …) which fold into MANY domains.
+   * A branded directive's generated Dart PAYLOAD TYPE (`EnrollDelegationPayload`, …) + any minted-create
+   * factory is emitted ONCE per package into the shared `nomos_framework.dart`, NOT re-emitted in each
+   * domain's `.dart` — so a package barrel re-exporting several domains never gets a duplicate payload
+   * class (no hand-maintained `hide` clause). NOT hashed / NOT law: a pure frontend-codegen marker.
+   * Identified by OBJECT IDENTITY, so a tenant directive that merely shares a name is never misclassified. */
+  readonly framework?: true;
   /**
    * Human-readable description of what this directive does — the SINGLE source of
    * the hover-doc text codegen emits onto each generated payload class + ctor (so

package/src/framework/framework_aggregates.ts

@@ -0,0 +1,138 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth. ⇒ ONE Nomos GitHolon wasm.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * THE FRAMEWORK-SYMBOL REGISTRY (Dart-codegen hygiene).
+ *
+ * Some DSL symbols are FRAMEWORK-owned + framework-SHARED: they are declared once in
+ * `dsl/src/framework/` and folded into MANY tenant domains. Three kinds collide in generated Dart:
+ *
+ *   • AGGREGATES — `RelationTuple` (auto-added to EVERY relation-using domain), plus `SignerDelegation`,
+ *     `KeyScope`, `WrappedKey`, `HomeOwner`, `WorkspaceSelf`, … re-exported verbatim so their events fold.
+ *     Each emits a read-model class + typed-id class + by-id accessors → `RelationTupleReadModel`,
+ *     `SignerDelegationId`, `watchSignerDelegationById`, … DEFINED per domain.
+ *   • DIRECTIVES — the relate/signer/enroll family (`relateSubject`, `enrollDelegation`,
+ *     `advanceSignerEpoch`, …) fold into many domains; each emits a payload class → `EnrollDelegationPayload`
+ *     DEFINED per domain.
+ *   • QUERIES — `signerDelegationByUser`, `relationTuplesByObject`, … emit top-level `watch<Q>`/`read<Q>`
+ *     accessors → `readSignerDelegationByUser`, `watchSignerDelegationByUser` DEFINED per domain.
+ *
+ * A package barrel re-exporting ≥2 domains COLLIDES on every such symbol — the historical band-aid was a
+ * hand-maintained `hide RelationTuple, EnrollDelegationPayload, readSignerDelegationByUser, …` clause on
+ * the tenant barrel. The fix: BRAND the framework SINGLETONS here (once, at module load) so the codegen
+ * emits their Dart surface EXACTLY ONCE per package (into the shared `nomos_framework.dart`) and SKIPS
+ * re-emitting them in each domain. Identification is by OBJECT IDENTITY (the brand rides the branded
+ * singleton), so a tenant symbol that merely SHARES a name is NEVER misclassified.
+ *
+ * FRONTEND CODEGEN ONLY — the brand is never hashed and never enters the USD IR / read manifest / law
+ * (identical guarantee to `readModelAggregates`). Deterministic: the registry is derived from the actual
+ * framework exports, not a hand-kept string list.
+ */
+import type { AggregateHandle } from "../aggregate.js";
+import type { Directive } from "../directive.js";
+import type { QueryDecl } from "../query.js";
+import * as disclosure from "./disclosure.js";
+import * as domainLifecycle from "./domain_lifecycle.js";
+import * as encryptionIdentity from "./encryption_identity.js";
+import * as encryptionScope from "./encryption_scope.js";
+import * as genesis from "./genesis.js";
+import * as home from "./home.js";
+import * as identity from "./identity.js";
+import * as relations from "./relations.js";
+import * as repair from "./repair.js";
+import * as signingIdentity from "./signing_identity.js";
+import * as workspaces from "./workspaces.js";
+
+// Every framework module that DECLARES aggregate / directive / query singletons. Namespace imports so
+// the registry is derived from the real exports (no hand-kept id list to drift).
+const FRAMEWORK_NAMESPACES: ReadonlyArray<Record<string, unknown>> = [
+  disclosure,
+  domainLifecycle,
+  encryptionIdentity,
+  encryptionScope,
+  genesis,
+  home,
+  identity,
+  relations,
+  repair,
+  signingIdentity,
+  workspaces,
+];
+
+function isAggregateHandle(v: unknown): v is AggregateHandle {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as { __isAggregateHandle?: unknown }).__isAggregateHandle === true
+  );
+}
+
+// A finished Directive duck-type ({id, plan, aggregateId}) — the SAME shape `directivesOf` discovers.
+function isDirective(v: unknown): v is Directive {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof (v as { id?: unknown }).id === "string" &&
+    typeof (v as { plan?: unknown }).plan === "function" &&
+    typeof (v as { aggregateId?: unknown }).aggregateId === "string"
+  );
+}
+
+// A finished QueryDecl duck-type ({id, key:[], returns:""}). Distinct from the un-keyed builder
+// (`KeylessQuery.key` is a FUNCTION); here `key` is an array and `returns` a string.
+function isQueryDecl(v: unknown): v is QueryDecl {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof (v as { id?: unknown }).id === "string" &&
+    Array.isArray((v as { key?: unknown }).key) &&
+    typeof (v as { returns?: unknown }).returns === "string"
+  );
+}
+
+const aggregateIds = new Set<string>();
+const directiveIds = new Set<string>();
+const queryIds = new Set<string>();
+
+// Brand every framework singleton at module load. Mutating the readonly `framework` slot on the
+// singleton is intentional: the branded object IS the one that flows through composition
+// (`composeDomainModule` keeps the discovered aggregate/directive/query object references; a tenant
+// re-exports the framework singleton verbatim), so the brand rides object identity everywhere.
+for (const ns of FRAMEWORK_NAMESPACES) {
+  for (const v of Object.values(ns)) {
+    if (isAggregateHandle(v)) {
+      (v as { framework?: true }).framework = true;
+      aggregateIds.add(v.id);
+    } else if (isDirective(v)) {
+      (v as { framework?: true }).framework = true;
+      directiveIds.add(v.id);
+    } else if (isQueryDecl(v)) {
+      (v as { framework?: true }).framework = true;
+      queryIds.add(v.id);
+    }
+  }
+}
+
+export const FRAMEWORK_AGGREGATE_IDS: ReadonlySet<string> = aggregateIds;
+export const FRAMEWORK_DIRECTIVE_IDS: ReadonlySet<string> = directiveIds;
+export const FRAMEWORK_QUERY_IDS: ReadonlySet<string> = queryIds;
+
+/**
+ * TRUE iff this aggregate is a framework-shared singleton whose Dart surface is emitted ONCE per
+ * package (in `nomos_framework.dart`). By the BRAND (object identity) — a tenant aggregate that
+ * happens to share an id is NOT a framework aggregate.
+ */
+export function isFrameworkAggregate(agg: Pick<AggregateHandle, "framework">): boolean {
+  return agg.framework === true;
+}
+
+/** TRUE iff this directive is a framework-shared singleton (its payload class lives in the shared file). */
+export function isFrameworkDirective(d: Pick<Directive, "framework">): boolean {
+  return d.framework === true;
+}
+
+/** TRUE iff this query is a framework-shared singleton (its accessors live in the shared file). */
+export function isFrameworkQuery(q: Pick<QueryDecl, "framework">): boolean {
+  return q.framework === true;
+}

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 {

package/src/query.ts

@@ -67,6 +67,16 @@ export interface QueryDecl {
   readonly key: string[];
   /** The aggregate TYPE id the query returns, e.g. `SampleThingAggregate`. */
   readonly returns: string;
+  /**
+   * FRAMEWORK-SHARED brand (Dart-codegen hygiene). Set (by `framework/framework_aggregates.ts`) ONLY on
+   * the framework-owned query singletons declared in `dsl/src/framework/` (`signerDelegationByUser`,
+   * `relationTuplesByObject`, …) which fold into MANY domains. A branded query's generated top-level
+   * `watch<Q>`/`read<Q>` accessors are emitted ONCE per package into the shared `nomos_framework.dart`,
+   * NOT re-emitted in each domain's `.dart` — so a package barrel re-exporting several domains never gets
+   * duplicate accessors (no hand-maintained `hide` clause). NOT hashed / NOT law: a pure frontend-codegen
+   * marker (never enters the read manifest / USD IR). Identified by OBJECT IDENTITY, so a tenant query
+   * that merely shares a name is never misclassified. */
+  readonly framework?: true;
 }
 
 /**