@githolon/dsl 0.27.1 → 0.29.0

package/package.json

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

@@ -114,6 +114,21 @@ export type HasManyFields<F extends Record<string, Field>> = {
   [K in keyof F as IsHasMany<F[K]> extends true ? K : never]: F[K];
 };
 
+/** The value TYPE a stored field decodes to (the `T` in `Field<T, K>`) — `unknown` for an untyped field. */
+export type FieldValue<Fld> = Fld extends Field<infer T> ? T : unknown;
+
+/**
+ * The READ-MODEL ROW shape a projected aggregate decodes to — one property per STORED field, at its
+ * decoded value type (`Field<T>` → `T`), EVERY field optional (folds are partial — a projection may lack
+ * a field). The compile-time twin of the codegen `<Agg>Data` interface, derived from the SAME field kinds.
+ * Used to type the `.where(Agg, idFn, predicate)` row so `row.status !== "deleted"` type-checks and a
+ * typo'd field name is a compile error. (The ABSENT case — the whole instance missing — is modelled as
+ * `ReadModelRow<F> | undefined` at the predicate boundary.)
+ */
+export type ReadModelRow<F extends Record<string, Field>> = {
+  [K in keyof StoredFields<F>]?: FieldValue<StoredFields<F>[K]>;
+};
+
 /** Runtime partition of a declared field record into stored fields + virtual `hasMany` inverses. */
 function partitionFields(fields: Record<string, Field>): {
   stored: Record<string, Field>;

package/src/build_package.ts

@@ -53,6 +53,7 @@ import type { CombinedDecl } from "./combined.js";
 import type { ImpureCapabilityDecl } from "./codegen_provider_dart.js";
 import type { WorkspaceTypeDecl } from "./workspace_type.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
+import { synthesizePreconditionInvariants } from "./precondition.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
 import { domainHash, emitManifestBytes } from "./manifest.js";
 import { emitUsd } from "./usd.js";
@@ -181,6 +182,11 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   const maxes = [...(spec.maxes ?? [])];
   const workspaceTypes = [...(spec.workspaceTypes ?? [])];
   const workspaceInvariants = [...(spec.workspaceInvariants ?? [])];
+  // DESUGAR the write-path precondition primitives (`.requiresExisting`/`.creates(Agg,idFn)`/`.where`):
+  // each directive's descriptors synthesize workspace invariants (LANE B) appended to the SAME list a
+  // hand-authored `workspaceInvariant(...)` occupies — so downstream treats them identically. Era-safe:
+  // a directive with no precondition synthesizes nothing (byte-identical manifest).
+  for (const d of directives) workspaceInvariants.push(...synthesizePreconditionInvariants(d));
   const relationTypes = [...(spec.relationTypes ?? [])];
   const dartImports = [...(spec.dartImports ?? [])];
   // THE PEER-SOVEREIGN ROOT-OF-TRUST: a home/child law that exports `requireParentAttestedBirth` declares

package/src/codegen_dart.ts

@@ -737,22 +737,30 @@ function typedIdClassForAggregateType(aggregateType: string): string {
 function collectEnums(
   aggregates: AggregateHandle[],
   directives: AnyDirective[],
+  domainKey: string,
 ): { dartTypes: Map<string, string>; decls: string[] } {
   const dartTypes = new Map<string, string>(); // "a|b|c" -> DartEnumName
   const usedNames = new Set<string>(); // every emitted enum name (collision guard)
   const decls: string[] = [];
+  // Generated enum types are DOMAIN-QUALIFIED (`EstateStatusEnum`,
+  // `Co2PlatformStatusEnum`) so two domains re-exported through one Dart barrel
+  // never collide on a bare `StatusEnum` — the collision that otherwise forces a
+  // hand-maintained `hide` list on the package barrel. The prefix is the field's
+  // semantic home, not an accident of import order.
+  const domainPrefix = dartTypeNameFromField(domainKey);
   const register = (preferredName: string, values: readonly string[]) => {
     const key = values.join("|");
     if (dartTypes.has(key)) return;
-    // Two DIFFERENT value-sets can prefer the SAME name (e.g. several `status`
-    // fields with distinct literal lists all want `StatusEnum`). Suffix on collision
-    // so each distinct value-set gets a UNIQUE Dart enum (`StatusEnum`, `Status2Enum`).
-    const base = `${dartTypeNameFromField(preferredName)}Enum`;
+    // Two DIFFERENT value-sets WITHIN one domain can prefer the SAME name (e.g.
+    // several `status` fields with distinct literal lists all want `StatusEnum`).
+    // Suffix on collision so each distinct value-set gets a UNIQUE Dart enum
+    // (`EstateStatusEnum`, `EstateStatus2Enum`).
+    const base = `${domainPrefix}${dartTypeNameFromField(preferredName)}Enum`;
     let name = base;
     let n = 1;
     while (usedNames.has(name)) {
       n += 1;
-      name = `${dartTypeNameFromField(preferredName)}${n}Enum`;
+      name = `${domainPrefix}${dartTypeNameFromField(preferredName)}${n}Enum`;
     }
     usedNames.add(name);
     dartTypes.set(key, name);
@@ -2560,7 +2568,11 @@ export interface DomainModule {
 /** Generate the full Dart source for one domain module. */
 export function generateDartDomain(mod: DomainModule): string {
   const domainKey = mod.domain ?? mod.name;
-  const { dartTypes, decls } = collectEnums(mod.aggregates, mod.directives);
+  const { dartTypes, decls } = collectEnums(
+    mod.aggregates,
+    mod.directives,
+    domainKey,
+  );
   const refIdClassForAggregate = refIdClassResolver(mod);
   const aggregatesById = new Map<string, AggregateHandle>();
   for (const a of mod.aggregates) aggregatesById.set(a.id, a);

package/src/codegen_proof.ts

@@ -40,6 +40,8 @@ import type { Field } from "./fields.js";
 import type { Directive } from "./directive.js";
 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 { finishCount } from "./count.js";
 import { mintedCreateField } from "./workspace_routing.js";
 import { deterministicPorts } from "./ctx.js";
@@ -336,6 +338,520 @@ function authorityConformanceLegLines(
   ];
 }
 
+/**
+ * THE RELATION-BOOTSTRAP LEG (the seed-then-prove POSITIVE — complements the negative conformance leg). On the
+ * LOCAL holon with fetch trapped: (1) dispatch the GRANT directive under the proof actor (its subject fields
+ * overwritten to the actor so the relation seats ON it), then (2) dispatch the GATED directive under the SAME
+ * actor and assert it SUCCEEDS — proving that once relation R is granted, an actor holding R authors the gated
+ * write (the exact loop the negative leg can't cover). Emits nothing when no granter is discoverable.
+ */
+function relationSeedLegLines(
+  leg: RelationBootstrapLeg | undefined,
+  factory: string,
+  n: () => number,
+  diagnostic?: string,
+): string[] {
+  if (leg === undefined) {
+    if (diagnostic === undefined) return [];
+    // A gated directive exists but no authority could be seeded — say EXACTLY why (a useful failure, not a
+    // silent skip). The gate is still proven negatively by the conformance leg above.
+    return [
+      `// ${n()}. relation-bootstrap leg: this law has a gated directive the proof COULD NOT seed authority for.`,
+      `console.log(${JSON.stringify(`– relation-bootstrap leg SKIPPED — ${diagnostic}`)});`,
+      ``,
+    ];
+  }
+  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
+        ? `${JSON.stringify(k)}: ${ACTOR}`
+        : `${JSON.stringify(k)}: ${JSON.stringify(v)}`;
+    });
+    return `{ ${entries.join(", ")} }`;
+  })();
+  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);
+  const computedNote = leg.grantedRelation !== leg.relation && !speculative
+    ? ` — a COMPUTED gate: granting "${leg.grantedRelation}" makes the actor satisfy "${leg.relation}" via the rewrite`
+    : ``;
+
+  if (speculative) {
+    // LAYER 3 (seed-path replay). The gate relation is reachable only through ttu/intersection/exclusion — no
+    // directly-grantable base. We REPLAY the domain's declared seed and let the REAL GATE arbitrate: if the
+    // gated write is ADMITTED, it is a green positive leg; if REFUSED, it is a DIAGNOSTIC (never a false
+    // green) — the discovered seed was not the authority path. Step (2) is wrapped so a refusal degrades.
+    const seats = (leg.seedWritesRelations ?? [leg.grantedRelation]).join(", ");
+    return [
+      `// ${n()}. RELATION BOOTSTRAP — LAYER 3 (seed-path replay): \`${leg.domain}/${leg.gatedDirectiveId}\` is GATED`,
+      `//    (\`.requires("${leg.relation}")\`), reachable only via ttu/intersection (no directly-grantable base).`,
+      `//    REPLAY the declared seed \`${leg.domain}/${leg.grantDirectiveId}\` (seats [${seats}]) on the actor, then let`,
+      `//    the REAL gate decide: admitted ⇒ proven; refused ⇒ diagnostic (a speculative seed never false-greens).`,
+      `{`,
+      `  const realFetch3 = globalThis.fetch;`,
+      `  globalThis.fetch = (() => { throw new Error("OFFLINE PROOF VIOLATED: relation-bootstrap touched the network"); }) as typeof fetch;`,
+      `  try {`,
+      `    const ACTOR = ${ACTOR};`,
+      `    let seedReplayed = false;`,
+      `    try {`,
+      `      await ${factory}(holon, { actor: ACTOR }).${leg.grantDirectiveId}(${grantPayloadLit});`,
+      `      seedReplayed = true;`,
+      `    } catch (e) {`,
+      `      console.log(\`– relation-bootstrap leg SKIPPED (layer-3 seed-path) — the declared seed ${leg.domain}/${leg.grantDirectiveId} could not be replayed (\${(e as Error)?.message ?? e}); gate ${leg.gatedDirectiveId} stays proven negatively\`);`,
+      `    }`,
+      `    if (seedReplayed) {`,
+      `      try {`,
+      `        await ${factory}(holon, { actor: ACTOR }).${leg.gatedDirectiveId}(${gatedPayloadLit});`,
+      `        ok(\`relation bootstrap (seed-path) — ${leg.domain}/${leg.gatedDirectiveId} authored after replaying the declared seed ${leg.grantDirectiveId} (the REAL gate confirmed it establishes authority for "${leg.relation}")\`);`,
+      `      } catch (e) {`,
+      `        // ANTI-FALSE-GREEN: the real gate REFUSED — the discovered seed was not the authority path. Do NOT`,
+      `        // assert a passing leg; emit a diagnostic (the conformance leg still proves the gate has teeth).`,
+      `        console.log(\`– relation-bootstrap leg SKIPPED (layer-3 seed-path) — replaying ${leg.grantDirectiveId} did NOT authorize ${leg.gatedDirectiveId} .requires("${leg.relation}") on the real gate (\${(e as Error)?.message ?? e}); no seed-path is provable\`);`,
+      `      }`,
+      `    }`,
+      `  } finally {`,
+      `    globalThis.fetch = realFetch3;`,
+      `  }`,
+      `}`,
+      ``,
+    ];
+  }
+
+  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}.`,
+    `//    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).`,
+    `{`,
+    `  const realFetch3 = globalThis.fetch;`,
+    `  globalThis.fetch = (() => { throw new Error("OFFLINE PROOF VIOLATED: relation-bootstrap touched the network"); }) as typeof fetch;`,
+    `  try {`,
+    `    const ACTOR = ${ACTOR};`,
+    `    // (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)` : ``}\`);`,
+    `    // (2) the GATED write now SUCCEEDS under the seeded actor (holds "${leg.relation}"${leg.grantedRelation !== leg.relation ? ` via "${leg.grantedRelation}"` : ``}).`,
+    `    await ${factory}(holon, { actor: ACTOR }).${leg.gatedDirectiveId}(${gatedPayloadLit});`,
+    `    ok(\`relation bootstrap (prove) — ${leg.domain}/${leg.gatedDirectiveId} authored under the seeded holder of "${leg.relation}" (gated write SUCCEEDS once granted)\`);`,
+    `  } finally {`,
+    `    globalThis.fetch = realFetch3;`,
+    `  }`,
+    `}`,
+    ``,
+  ];
+}
+
+// ── relation-bootstrap discovery (seed the gate: grant relation R, then prove a .requires(R) write SUCCEEDS) ──
+//
+// The NEGATIVE conformance leg above proves an ACTORLESS gated offer can't be generated. This POSITIVE leg
+// proves the other half: with the relation GRANTED, an actor that holds it authors the gated write SUCCESS-
+// fully. It needs a sibling directive that ESTABLISHES the relation (folds a granting `writeTuple`). We find
+// it two ways: FIRST a `.grants(R)` producer marker (the static, unambiguous lane — symmetric to `.requires`);
+// ELSE plan-probe each sibling for a `writeTuple`/relation-tuple op whose `relation === R` (inference).
+
+/** A discovered RELATION-BOOTSTRAP leg: a gated (`.requires(R)`) directive plus the sibling directive that
+ *  GRANTS R. The proof dispatches the grant FIRST (its subject/grantedBy set to the seeded proof actor), then
+ *  dispatches the gated directive under that actor and asserts it SUCCEEDS — the seed-then-prove positive. */
+export interface RelationBootstrapLeg {
+  /** The gated directive's domain. */
+  readonly domain: string;
+  /** The gated directive id (`.requires(relation)`). */
+  readonly gatedDirectiveId: string;
+  /** The relation the GATE requires. */
+  readonly relation: string;
+  /** The relation the GRANT actually establishes on the actor. For a DIRECT grant this === `relation`; for a
+   *  COMPUTED gate relation it is the directly-grantable BASE relation (e.g. gate `estateMember` → grant
+   *  `estateOwner`), resolved by walking the relation-schema rewrite. Holding it makes the actor satisfy
+   *  `relation` through the computed chain. */
+  readonly grantedRelation: string;
+  /** The synthesized gated-directive payload (auto-stamped `…At` omitted; mintField removed). */
+  readonly gatedPayload: Record<string, unknown>;
+  readonly gatedAutoStamped: readonly string[];
+  /** When the gated directive's own id is kernel-minted, the field to mint at runtime. */
+  readonly gatedMintField?: string;
+  /** The gated create's aggregate id (the mint's type tag) — present when `gatedMintField` is. */
+  readonly gatedAggregateId?: string;
+  /** The granting directive id (the sibling that folds the granting `writeTuple`). */
+  readonly grantDirectiveId: string;
+  /** The synthesized grant payload (auto-stamped `…At` omitted). The SUBJECT fields (below) are overwritten
+   *  at runtime with the seeded proof actor so the grant seats authority ON that actor. */
+  readonly grantPayload: Record<string, unknown>;
+  readonly grantAutoStamped: readonly string[];
+  /** The grant-payload field(s) whose value the plan routed into the tuple SUBJECT — set to the proof actor
+   *  at dispatch so the granted relation lands on the actor the gated write runs as. */
+  readonly grantSubjectFields: readonly string[];
+  /** Grant-payload field(s) routed into the tuple `grantedBy` — set to the proof actor (free attribution). */
+  readonly grantGrantedByFields: readonly string[];
+  /** How the granter was resolved — `"marker"` (`.grants(R)` on R directly), `"inferred"` (a plan-probed
+   *  `writeTuple(R)`), `"computed-base"` (R is computed; the grant seats a rewrite BASE relation the granter
+   *  was found for), or `"seed-path"` (LAYER 3: R is reachable only through ttu/intersection/exclusion — no
+   *  directly-grantable base — so a DECLARED SEED directive that establishes root authority is replayed and
+   *  the REAL KERNEL GATE is the arbiter of whether it authorizes the write). Audit + runner semantics. */
+  readonly via: "marker" | "inferred" | "computed-base" | "seed-path";
+  /** LAYER-3 ANTI-FALSE-GREEN FLAG. `true` ⇒ this is a SPECULATIVE seed-path leg: codegen could NOT prove
+   *  (via rewrite resolution) that replaying `grantDirectiveId` authorizes the gated write — it discovered a
+   *  seed that writes relation tuples and is DEFERRING to the real kernel gate. The runner replays the seed,
+   *  attempts the gated write, and: ADMITTED ⇒ green positive leg (the law truly authorizes it); REFUSED ⇒
+   *  NOT a proof failure but an honest DIAGNOSTIC (the discovered seed was not the authority path) — a
+   *  speculative seed can NEVER emit a false green. Absent/false ⇒ layers 1/2 (a refusal IS a loud regression). */
+  readonly seedSpeculative?: boolean;
+  /** The relations the discovered seed directive writes (layer-3 audit/diagnostic — what authority it seats). */
+  readonly seedWritesRelations?: readonly string[];
+}
+
+/** Run a directive's plan with a synthesized+probe payload under birth-probe globals and return the drained
+ *  field ops (authoring sink + returned ops). `undefined` ⇒ the plan couldn't be probed. */
+function probePlanOps(
+  dir: Directive<unknown>,
+  where: string,
+): { ops: FieldOp[]; synth: SynthesizedPayload; probePayload: Record<string, unknown> } | undefined {
+  let synth: SynthesizedPayload;
+  try {
+    synth = synthesizePayload(dir.payloadSchema as z.ZodTypeAny, where);
+  } catch {
+    return undefined;
+  }
+  const probePayload: Record<string, unknown> = { ...synth.value };
+  for (const f of synth.autoStamped) probePayload[f] = "2026-01-01T00:00:00Z";
+  let ops: FieldOp[] = [];
+  try {
+    withBirthProbeGlobals(() => {
+      __resetAuthoring();
+      __resetReads();
+      __resetBirths();
+      try {
+        const returned = dir.plan(probePayload as never, deterministicPorts({ physical: 1, replica: 1, principal: "principal:probe" }));
+        const drained = [...__drainAuthoring(), ...(Array.isArray(returned) ? returned : [])];
+        ops = drained.filter((o): o is FieldOp => (o as { kind?: string }).kind !== "strike");
+      } finally {
+        try { __drainReads(); __drainBirths(); } catch { /* drained */ }
+      }
+    });
+  } catch {
+    return undefined;
+  }
+  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);
+}
+
+/** 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[] {
+  const probed = probePlanOps(dir, where);
+  if (probed === undefined) return [];
+  const out = new Set<string>();
+  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);
+  }
+  return [...out];
+}
+
+/** 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). */
+function resolveGrantSubjectFields(
+  probed: { ops: FieldOp[]; synth: SynthesizedPayload },
+): { subjectFields: string[]; grantedByFields: string[] } {
+  const { ops, synth } = probed;
+  const fieldForValue = (v: unknown): string | undefined =>
+    typeof v === "string" && v.length > 0
+      ? Object.entries(synth.value).find(([, sv]) => sv === v)?.[0]
+      : undefined;
+  const subjectFields = new Set<string>();
+  const grantedByFields = new Set<string>();
+  for (const o of ops) {
+    // The subject rides the tuple map entry KEY (`setEntry(rt, "subjects", <subjectRaw>, leaf)`).
+    if (o.kind === "setEntry" && o.field === "subjects" && typeof o.entryKey === "string") {
+      const f = fieldForValue(o.entryKey);
+      if (f !== undefined) subjectFields.add(f);
+      // grantedBy rides the JSON leaf value — scan the serialized leaf for any synthesized payload value.
+      if (typeof o.value === "string") {
+        for (const [name, sv] of Object.entries(synth.value)) {
+          if (typeof sv === "string" && sv.length > 0 && name !== fieldForValue(o.entryKey) && o.value.includes(sv)) {
+            grantedByFields.add(name);
+          }
+        }
+      }
+    }
+  }
+  return { subjectFields: [...subjectFields], grantedByFields: [...grantedByFields] };
+}
+
+// ── rewrite-aware base-relation resolution (the COMPUTED-authority lane) ──────────────────────────────
+//
+// A gate `.requires(R)` may name a COMPUTED relation — one nobody grants a direct tuple for. The owner
+// satisfies R through a Zanzibar REWRITE (e.g. `estateMember = self ∪ computed("estateOwner")` ⇒ an
+// `estateOwner` IS an `estateMember`). The direct-granter search below can't find a granter of R (nobody
+// writes an `estateMember` tuple), so the positive leg was impossible without the domain hand-seeding a
+// tuple. This resolver walks R's rewrite in the module's relation schema and returns the ordered set of
+// directly-grantable BASE relations B such that granting B on the gate object makes the actor satisfy R:
+// seed B (via its `.grants(B)` directive / plan-probed writeTuple), then the gated write admits.
+//
+// PRINCIPLED, never a guess: it descends `this`/`self` (R itself is directly grantable), `computed(B)`
+// (B satisfies R — recurse into B), and `union` (ANY branch that yields a base suffices — OR semantics).
+// `intersection`/`exclusion`/`ttu` (tuple_to_userset — a cross-object two-hop) are NOT locally decidable
+// from a same-object grant, so they yield nothing here and the caller falls through to the seed-path lane.
+
+/** Is relation `rel` on `decl` DIRECTLY GRANTABLE — i.e. its rewrite admits `this` (stores direct tuples)
+ *  and it `allow`s ≥1 subject class (a `writeTuple`/grant can seat a principal on it)? */
+function isDirectlyGrantable(decl: RelationTypeDecl, rel: string): boolean {
+  const def = decl.relations.get(rel);
+  if (def === undefined) return false;
+  if (def.allowed.length === 0) return false; // fail-closed: stores no direct tuples
+  return rewriteAdmitsThis(def.rewrite);
+}
+
+/** Does a rewrite include `_this` (directly-stored tuples) somewhere a same-object grant lands — i.e. at the
+ *  top or inside a `union`? `null` ⇒ pure direct `this`. (A `this` buried under intersection/exclusion is not
+ *  a clean grant target — treat conservatively as non-admitting for the seed lane.) */
+function rewriteAdmitsThis(r: Rewrite | null): boolean {
+  if (r === null) return true;
+  switch (r.kind) {
+    case "this":
+      return true;
+    case "union":
+      return r.children.some((c) => rewriteAdmitsThis(c));
+    default:
+      return false;
+  }
+}
+
+/**
+ * Resolve the ordered directly-grantable BASE relations whose grant makes an actor satisfy `relation` on
+ * `objectType`, by walking the rewrite in the module's relation schema. Returns [] when the relation is not
+ * computed in a locally-decidable way (intersection/exclusion/ttu, an undeclared type, or nothing grantable)
+ * — the caller then tries the direct-granter or seed-path lanes. R itself, when directly grantable, is the
+ * FIRST candidate (the existing direct-grant lane covers it, but listing it keeps this the single resolver).
+ */
+export function resolveGrantableBaseRelations(
+  relationTypes: readonly RelationTypeDecl[] | undefined,
+  objectType: string,
+  relation: string,
+): string[] {
+  // The gate object is a `<type>:<id>` reference (e.g. `workspace:self`); a relation schema is keyed by TYPE.
+  const type = objectType.includes(":") ? objectType.slice(0, objectType.indexOf(":")) : objectType;
+  const decl = (relationTypes ?? []).find((t) => t.type === type);
+  if (decl === undefined) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  const pushBase = (rel: string): void => {
+    if (!seen.has(rel) && isDirectlyGrantable(decl, rel)) {
+      seen.add(rel);
+      out.push(rel);
+    }
+  };
+  // Walk from `relation` collecting grantable bases reachable via this/computed/union.
+  const visited = new Set<string>();
+  const walk = (rel: string): void => {
+    if (visited.has(rel)) return;
+    visited.add(rel);
+    const def = decl.relations.get(rel);
+    if (def === undefined) return;
+    // If THIS relation is directly grantable, granting it satisfies itself (and thus `relation` through the
+    // computed chain that led here).
+    pushBase(rel);
+    walkRewrite(def.rewrite);
+  };
+  const walkRewrite = (r: Rewrite | null): void => {
+    if (r === null) return;
+    switch (r.kind) {
+      case "this":
+        return; // handled by pushBase at the relation level
+      case "computed":
+        walk(r.relation); // an actor holding the computed sibling satisfies this relation
+        return;
+      case "union":
+        for (const c of r.children) walkRewrite(c);
+        return;
+      // intersection/exclusion/ttu: not locally decidable from a single same-object grant → yield nothing.
+      default:
+        return;
+    }
+  };
+  walk(relation);
+  return out;
+}
+
+/** 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
+ *  COMPUTED, resolve a directly-grantable BASE relation B (via the relation schema's rewrite) and find its
+ *  granter, so granting B makes the actor satisfy R. `undefined` ⇒ no gated directive, or no granter for R
+ *  or any of its bases (the caller may then fall through to the seed-path lane; the negative conformance
+ *  leg always still runs). */
+export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstrapLeg | undefined {
+  const domain = mod.domain ?? mod.name;
+  const directives = mod.directives as Directive<unknown>[];
+  const gated = directives.find(
+    (d) =>
+      d?.requiresRelationGate !== undefined &&
+      typeof d.payloadSchema === "object" &&
+      d.birthsChild !== true &&
+      d.attestationAuthorizedGate === undefined,
+  );
+  if (gated === undefined) return undefined;
+  const relation = gated.requiresRelationGate!.relation;
+
+  // Synthesize the gated payload (mirror of the conformance leg — mintField removed, auto-stamped omitted).
+  let gatedSynth: SynthesizedPayload;
+  try {
+    gatedSynth = synthesizePayload(gated.payloadSchema as z.ZodTypeAny, `${domain}/${gated.id}`);
+  } catch {
+    return undefined;
+  }
+  const gatedAgg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === gated.aggregateId);
+  const gatedMintField = gatedAgg !== undefined ? mintedCreateField(gated, gatedAgg) : undefined;
+  const gatedPayload: Record<string, unknown> = { ...gatedSynth.value };
+  if (gatedMintField !== undefined) delete gatedPayload[gatedMintField];
+
+  // Find a granter that establishes the actor's authority for the gate relation. Never the gated directive.
+  //   (1) DIRECT: a `.grants(R)` marker (unambiguous), ELSE a plan-probed `writeTuple(R)`.
+  //   (2) COMPUTED-BASE: when R is computed, walk the relation-schema rewrite for the directly-grantable BASE
+  //       relations B (e.g. gate `estateMember` → `estateOwner`/`admin`), and find a granter for a base —
+  //       granting B makes the actor satisfy R through the computed chain (what estate's seed does).
+  const candidates = directives.filter((d) => d !== gated && typeof d?.payloadSchema === "object" && d.birthsChild !== true);
+  const findGranterFor = (rel: string): { granter: Directive<unknown>; via: "marker" | "inferred" } | undefined => {
+    const marked = candidates.find((d) => (d.grantsRelation ?? []).includes(rel));
+    if (marked !== undefined) return { granter: marked, via: "marker" };
+    const inferred = candidates.find((d) => probeGrantsRelation(d, rel, `${domain}/${d.id}`));
+    return inferred !== undefined ? { granter: inferred, via: "inferred" } : undefined;
+  };
+
+  // (1) direct grant of R.
+  let grantedRelation = relation;
+  let via: "marker" | "inferred" | "computed-base" | "seed-path" = "marker";
+  let seedSpeculative = false;
+  let seedWritesRelations: string[] | undefined;
+  let found = findGranterFor(relation);
+  if (found !== undefined) {
+    via = found.via;
+  } else {
+    // (2) rewrite-aware: R is computed — resolve grantable base relations and find a granter for one.
+    const bases = resolveGrantableBaseRelations(mod.relationTypes, gated.requiresRelationGate!.object, relation)
+      .filter((b) => b !== relation); // R itself already tried in (1)
+    for (const base of bases) {
+      const f = findGranterFor(base);
+      if (f !== undefined) {
+        found = f;
+        grantedRelation = base;
+        via = "computed-base";
+        break;
+      }
+    }
+    if (found === undefined) {
+      // (3) SEED-PATH REPLAY (the general fallback): R is reachable only through ttu/intersection/exclusion —
+      // no directly-grantable base for layer 2. Discover a DECLARED seed directive that ESTABLISHES relation
+      // authority (its plan writes ≥1 relation tuple) and route its subject to the proof actor. We do NOT
+      // claim this authorizes the gated write — the REAL KERNEL GATE decides at runtime (the anti-false-green
+      // guard: `seedSpeculative`). Prefer a seed that seats the MOST relations (a genesis/owner seed like
+      // estate's, which lands admin/creator/estateOwner together — the broadest root authority).
+      const seed = discoverSeedDirective(candidates, domain);
+      if (seed === undefined) return undefined; // no seed path → the caller emits the diagnostic
+      found = { granter: seed.dir, via: "inferred" };
+      grantedRelation = seed.relationsWritten[0] ?? relation; // cosmetic — the seed's primary relation
+      via = "seed-path";
+      seedSpeculative = true;
+      seedWritesRelations = seed.relationsWritten;
+    }
+  }
+  const granter = found.granter;
+
+  // Synthesize the grant payload + resolve which fields route into subject / grantedBy (so runtime seats the
+  // grant on the proof actor). Best-effort: an un-probable grant plan still emits the leg (runtime overwrites
+  // any field whose name looks like a subject/grantedBy anyway).
+  let grantSynth: SynthesizedPayload;
+  try {
+    grantSynth = synthesizePayload(granter.payloadSchema as z.ZodTypeAny, `${domain}/${granter.id}`);
+  } catch {
+    return undefined;
+  }
+  const grantPayload: Record<string, unknown> = { ...grantSynth.value };
+  const probed = probePlanOps(granter, `${domain}/${granter.id}`);
+  const routed = probed !== undefined ? resolveGrantSubjectFields(probed) : { subjectFields: [], grantedByFields: [] };
+
+  return {
+    domain,
+    gatedDirectiveId: gated.id,
+    relation,
+    grantedRelation,
+    gatedPayload,
+    gatedAutoStamped: gatedSynth.autoStamped,
+    ...(gatedMintField !== undefined ? { gatedMintField, gatedAggregateId: gated.aggregateId } : {}),
+    grantDirectiveId: granter.id,
+    grantPayload,
+    grantAutoStamped: grantSynth.autoStamped,
+    grantSubjectFields: routed.subjectFields,
+    grantGrantedByFields: routed.grantedByFields,
+    via,
+    ...(seedSpeculative ? { seedSpeculative: true } : {}),
+    ...(seedWritesRelations !== undefined ? { seedWritesRelations } : {}),
+  };
+}
+
+/** A discovered layer-3 SEED directive: a sibling (non-gated, non-birth) whose plan writes relation tuples,
+ *  so replaying it SEATS relation authority the gate's rewrite may consume. Ranked by how many relations it
+ *  writes (a broad genesis/owner seed outranks a single-relation grant). `undefined` ⇒ no such directive. */
+function discoverSeedDirective(
+  candidates: readonly Directive<unknown>[],
+  domain: string,
+): { dir: Directive<unknown>; relationsWritten: string[] } | undefined {
+  let best: { dir: Directive<unknown>; relationsWritten: string[] } | undefined;
+  for (const d of candidates) {
+    // Skip a directive that is itself authz-gated — replaying it would need its OWN authority first (a seed
+    // must be an ungated genesis/bootstrap the proof can drive under a bare actor).
+    if (d.requiresRelationGate !== undefined) continue;
+    const written = probeRelationsWritten(d, `${domain}/${d.id}`);
+    if (written.length === 0) continue;
+    if (best === undefined || written.length > best.relationsWritten.length) {
+      best = { dir: d, relationsWritten: written.sort() };
+    }
+  }
+  return best;
+}
+
+/**
+ * When a module HAS a gated (`.requires(R)`) directive but `discoverRelationBootstrapLeg` finds no granter
+ * (neither a direct granter of R nor one for any rewrite BASE of R), explain EXACTLY what is missing so the
+ * proof fails usefully rather than silently skipping the positive leg. `undefined` ⇒ nothing to diagnose
+ * (no gated directive, or the leg WAS discovered). Never throws.
+ */
+export function diagnoseRelationBootstrapGap(mod: DomainModule): string | undefined {
+  const domain = mod.domain ?? mod.name;
+  const directives = mod.directives as Directive<unknown>[];
+  const gated = directives.find(
+    (d) => d?.requiresRelationGate !== undefined && typeof d.payloadSchema === "object"
+      && d.birthsChild !== true && d.attestationAuthorizedGate === undefined,
+  );
+  if (gated === undefined) return undefined;
+  if (discoverRelationBootstrapLeg(mod) !== undefined) return undefined; // resolved — no gap
+  const relation = gated.requiresRelationGate!.relation;
+  const object = gated.requiresRelationGate!.object;
+  const bases = resolveGrantableBaseRelations(mod.relationTypes, object, relation).filter((b) => b !== relation);
+  const tried = bases.length > 0
+    ? `no directive grants "${relation}" directly, nor any of its directly-grantable rewrite bases [${bases.join(", ")}]`
+    : (mod.relationTypes ?? []).some((t) => t.type === (object.includes(":") ? object.slice(0, object.indexOf(":")) : object))
+      ? `"${relation}" on "${object}" is not directly grantable and its rewrite (intersection/exclusion/tuple_to_userset) has no locally-seedable base relation`
+      : `no relation schema declares object type "${object}", so "${relation}" cannot be resolved to a grantable base`;
+  return `${domain}/${gated.id} is gated by .requires("${relation}") but the proof cannot seed authority: ${tried}, `
+    + `AND no ungated seed/genesis directive writes any relation tuple to replay (layer-3 seed-path found nothing). `
+    + `Add a directive that folds a granting writeTuple for "${relation}" (or a grantable base of it) and mark it .grants(...), `
+    + `or expose a genesis/seed directive that establishes the owner's root authority. (The negative conformance leg still proves the gate refuses an actorless offer.)`;
+}
+
 // ── child-birth discovery (the G3 `.births()` lane — prove a parent birth end-to-end into the child) ──────
 
 /** ONE step of a discovered birth recipe's genesis chain (the subset codegen reads). */
@@ -634,8 +1150,9 @@ export interface TsProofOptions {
  *   · `compile-valid`        — the law compiled (always — every compiled domain is at least this).
  *   · `standalone-provable`  — a `.creates` write proven offline (dispatch → declared query/count locally).
  *   · `child-birth-provable` — a `.births()` directive proven END-TO-END into the child it births.
+ *   · `relation-bootstrap-provable` — a `.requires(R)`-gated write proven to SUCCEED after granting R (seed-then-prove).
  *   · `live-cloud-provable`  — the full cloud loop (the `.mts` `--live` lane) completes (the primary domain). */
-export type ProofKind = "compile-valid" | "standalone-provable" | "child-birth-provable" | "live-cloud-provable";
+export type ProofKind = "compile-valid" | "standalone-provable" | "child-birth-provable" | "relation-bootstrap-provable" | "live-cloud-provable";
 
 /** The machine-readable OFFLINE legs for ONE domain (the `@nomos-proof-legs`
  *  marker shape; the `proof-legs.json` index is a map of these by domain key). */
@@ -657,6 +1174,10 @@ export interface ProofLegs {
    *  When this domain is itself the BORN child's law (no standalone create), the index also registers the
    *  child domain key pointing at the SAME leg, so `proof --domain <child>` resolves through the parent birth. */
   readonly childBirth?: ChildBirthLeg;
+  /** THE RELATION-BOOTSTRAP LEG — present iff this domain has a `.requires(R)`-gated directive AND a
+   *  discoverable granter of R (a `.grants(R)` marker, or a plan-probed granting `writeTuple`). Proves the
+   *  gated write SUCCEEDS once R is granted (the seed-then-prove positive). Additive: absent ⇒ older/ungated. */
+  readonly relationBootstrap?: RelationBootstrapLeg;
 }
 
 /** Synthesize the standalone-create offline legs for one domain module, or `null` when it has no
@@ -727,9 +1248,19 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
   const childBirth = birthDir !== undefined ? allBirths.find((b) => b.parentDomain === domain && b.birthDirectiveId === birthDir.id) : undefined;
   const childBirthWithSetup = childBirth !== undefined ? attachParentSetup(childBirth, allBirths) : undefined;
 
+  // The relation-bootstrap leg (when the domain has a `.requires(R)`-gated directive AND a discoverable
+  // granter of R). FAIL SOFT: no granter → no leg (the negative conformance leg still covers the gate).
+  let relationBootstrap: RelationBootstrapLeg | undefined;
+  try {
+    relationBootstrap = discoverRelationBootstrapLeg(mod);
+  } catch {
+    relationBootstrap = undefined;
+  }
+
   const legs: ProofKind[] = ["compile-valid"];
   if (standalone !== null) legs.push("standalone-provable");
   if (childBirthWithSetup !== undefined) legs.push("child-birth-provable");
+  if (relationBootstrap !== undefined) legs.push("relation-bootstrap-provable");
 
   return {
     domain,
@@ -746,6 +1277,7 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
         }
       : {}),
     ...(childBirthWithSetup !== undefined ? { childBirth: childBirthWithSetup } : {}),
+    ...(relationBootstrap !== undefined ? { relationBootstrap } : {}),
   };
 }
 
@@ -1090,6 +1622,11 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   // throws MissingOfferAuthority. `undefined` ⇒ a documented no-op (the domain authors openly).
   const conformance = discoverAuthorityConformanceLeg(mod);
 
+  // THE RELATION-BOOTSTRAP LEG (the seed-then-prove positive): grant relation R to the proof actor, then prove
+  // a `.requires(R)`-gated write SUCCEEDS under that actor. `undefined` ⇒ no gated directive or no discoverable
+  // granter (the negative conformance leg still runs). Comes from the SAME `legsForDomain` synthesis (marker).
+  const relationBootstrap = primaryLegs.relationBootstrap;
+
   // Workspace-name slug: any package name → a safe, recognizable ws prefix.
   const slug =
     opts.packageName
@@ -1281,6 +1818,12 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   // offer is impossible to GENERATE (throws MissingOfferAuthority before any submit). No-op when un-gated.
   out.push(...authorityConformanceLegLines(conformance, factory, n));
 
+  // THE RELATION-BOOTSTRAP LEG (seed-then-prove the POSITIVE): grant relation R (or a rewrite base of it) to
+  // the proof actor, then prove the gated write SUCCEEDS under that actor. Runs on the LOCAL holon (fetch
+  // re-trapped). When no granter is discoverable but a gated directive exists, emits a CLEAR diagnostic naming
+  // exactly what's missing (the negative conformance leg still covers the gate).
+  out.push(...relationSeedLegLines(relationBootstrap, factory, n, relationBootstrap === undefined ? diagnoseRelationBootstrapGap(mod) : undefined));
+
   // THE CHILD-BIRTH LEG (G3, gap 2): when the primary domain has a `.births()` directive, prove the birth
   // END-TO-END against the cloud — drive the parent birth offer, then read the BORN child workspace it spawns.
   if (childBirth !== undefined) {

package/src/compile_package_main.ts

@@ -78,6 +78,7 @@ import {
   sha256HexUtf8,
   type Mod,
 } from "./build_package.js";
+import { synthesizePreconditionInvariants } from "./precondition.js";
 import { collectEngineRouting } from "./engine_entry.js";
 import {
   discover,
@@ -672,10 +673,18 @@ async function main(): Promise<void> {
       ...discover<CombinedDecl>(merged, isCombinedDecl),
       ...resolveNamed<CombinedDecl>(merged, d.combineds, "combineds"),
     ];
+    // Hand-authored invariants ONLY — the DESUGARED write-path preconditions are synthesized INSIDE
+    // `composeDomainModule` (the one owner of directive discovery), so passing them here too would
+    // double-emit. They are recomposed below purely for the openapi self-describe decls.
     const workspaceInvariants = [
       ...discover<WorkspaceInvariantDecl>(merged, isWorkspaceInvariantDecl),
       ...resolveNamed<WorkspaceInvariantDecl>(merged, d.workspaceInvariants, "workspaceInvariants"),
     ];
+    // The FULL invariant set (hand-authored ∪ synthesized preconditions) — for the openapi decls only.
+    const workspaceInvariantsForDecls = [
+      ...workspaceInvariants,
+      ...directivesOf(merged).flatMap((dir) => synthesizePreconditionInvariants(dir)),
+    ];
     // Native Zanzibar relation schema (P1) — auto-discovered by brand, like workspaceInvariants.
     const relationTypes = [
       ...discover<RelationTypeDecl>(merged, isRelationTypeDecl),
@@ -782,7 +791,7 @@ async function main(): Promise<void> {
       if (mins.length > 0) declsForDomain.mins = mins.map((e) => finishExtremum(e));
       if (maxes.length > 0) declsForDomain.maxes = maxes.map((e) => finishExtremum(e));
       if (spatials.length > 0) declsForDomain.spatials = spatials.map((s) => ({ id: s.id, of: s.of, on: s.on }));
-      if (workspaceInvariants.length > 0) declsForDomain.workspaceInvariants = workspaceInvariants.map((w) => ({ id: w.id, on: w.on }));
+      if (workspaceInvariantsForDecls.length > 0) declsForDomain.workspaceInvariants = workspaceInvariantsForDecls.map((w) => ({ id: w.id, on: w.on }));
       if (Object.keys(declsForDomain).length > 0) openapiDeclsByDomain[d.key] = declsForDomain;
     }
 

package/src/directive.ts

@@ -16,7 +16,8 @@
  * contract §1 (creates/mutates/ensures/archives).
  */
 import type { z } from "zod";
-import type { AggregateHandle } from "./aggregate.js";
+import type { AggregateHandle, ReadModelRow } from "./aggregate.js";
+import type { Field } from "./fields.js";
 import type { PlannedOp } from "./ops.js";
 import type { Ports } from "./ctx.js";
 import type { CertifiedReadDecl } from "./certified_read.js";
@@ -25,6 +26,37 @@ import type { QueryDecl } from "./query.js";
 
 export type ReferentialMarker = "creates" | "mutates" | "ensures" | "archives";
 
+/**
+ * A DECLARATIVE WRITE-PATH PRECONDITION (the precondition-primitives arc). One descriptor per
+ * `.requiresExisting` / `.creates(Agg).payload(...).withId(idFn)` create-once / `.where` marker on a directive. Each
+ * desugars — at `composeDomainModule` — to the SAME mechanism: a synthesized `workspaceInvariant`
+ * whose `.reads` resolves the ONE by-id ref (`ref(<Agg>, idFn(payload))`) and whose `.assert`
+ * evaluates `predicate(row)` over the resolved (possibly-absent → `undefined`) snapshot, yielding a
+ * typed refusal (`rejectCode`) at the ONE gate on EVERY lane (author / edge admission / verify_chain).
+ * NO kernel/wasm change — it rides the live #266 workspace-invariant + ref-resolution lane (an absent
+ * ref resolves to an empty/undefined snapshot, NEVER a refusal — proven by the framework's own
+ * `homeNameBindsOwner`, which reads `owner ?? {}`).
+ *
+ * `kind` fixes the predicate for the two specializations so ONE desugaring path serves all three:
+ *   - `exists`    — refuse when the row is ABSENT (`requiresExisting`).
+ *   - `absent`    — refuse when the row is PRESENT (`.creates(Agg).payload(...).withId(idFn)` create-once).
+ *   - `predicate` — refuse when the user `predicate(row)` is false (`.where`).
+ * The `predicate` is stored for ALL kinds (the specializations synthesize a fixed presence predicate),
+ * so the desugaring reads one field. `idField` is the pure payload→instance-id extractor.
+ */
+export interface PreconditionDescriptor {
+  /** The guarded aggregate's TYPE id (the ref type the synthesized invariant resolves). */
+  readonly aggregateId: string;
+  /** Pure payload → target instance id (no clock, no IO — re-derived identically on every peer). */
+  readonly idField: (payload: unknown) => string;
+  /** The fixed-predicate specialization, or `predicate` for the general `.where` form. */
+  readonly kind: "exists" | "absent" | "predicate";
+  /** The row predicate — `row` is the resolved snapshot or `undefined` when the instance is absent. */
+  readonly predicate: (row: Record<string, unknown> | undefined) => boolean;
+  /** The typed refusal code emitted when the predicate is false. */
+  readonly rejectCode: string;
+}
+
 /**
  * A pure, replay-stable derivation of the authz SCOPE an authored intent targets,
  * from its payload — e.g. `(p) => ["site", p.siteId]`. It MUST be a pure function
@@ -175,6 +207,17 @@ export interface Directive<P = unknown> {
    * `attestationAuthorizedGate`/`.attestationAuthorized()` naming convention; the declaration is the noun.)
    */
   readonly birthsChild?: boolean;
+  /**
+   * PROOF-TOOLING PRODUCER MARKER (relation-seed leg). Declares that this directive ESTABLISHES the named
+   * relation(s) — i.e. its `plan` folds a `writeTuple` that grants the relation. Purely a static hint for
+   * the proof generator's relation-bootstrap leg (`discoverRelationBootstrapLeg`): it disambiguates which
+   * sibling directive to run FIRST to seed the actor before proving a `.requires(R)`-gated write succeeds,
+   * and resolves the "who grants the granter" / multiple-candidate ambiguity that pure plan-probe inference
+   * cannot. NO kernel/manifest effect (it is NOT lowered into any era key — the gate is the `writeTuple` the
+   * plan already folds); a directive that never calls `.grants()` is byte-identical to before. Set via the
+   * chainable `.grants(relation)` (symmetric to `.requires`).
+   */
+  readonly grantsRelation?: string[];
   /**
    * The directive's DECLARED required HOST CAPABILITIES — the capability PORTS the HOST must
    * PROVIDE for this directive to run (`OFFER_KERNEL_ARCHITECTURE.dot` cluster_ports / `OFFER_FLOW.dot`
@@ -190,6 +233,24 @@ export interface Directive<P = unknown> {
    * manifest is byte-identical to before this existed (the pinned #136 hashes stay UNCHANGED).
    */
   readonly declaredHostCapabilities: string[];
+  /**
+   * DECLARATIVE WRITE-PATH PRECONDITIONS (the precondition-primitives arc) — the `.requiresExisting`
+   * / `.creates(Agg).payload(...).withId(idFn)` create-once / `.where` markers, each a {@link PreconditionDescriptor}.
+   * DESUGARED at `composeDomainModule` into synthesized `workspaceInvariant`s (one per descriptor) that
+   * ride the existing #266 lane — so downstream (manifest, USD IR, `nomosInvariantGate` era key, engine
+   * bundle) treats them IDENTICALLY to a hand-authored `workspaceInvariant`. Purely additive +
+   * OMITTED ENTIRELY when empty, so a directive using none is byte-identical in the canonical manifest
+   * to before this existed (the markers only emit the already-existing invariant era key, when used).
+   */
+  readonly preconditions?: PreconditionDescriptor[];
+  /**
+   * CALLER-SUPPLIED-ID CREATE-ONCE (`.creates(Agg)….withId(idFn)`). When set, the directive `creates` the
+   * aggregate at an APP-SUPPLIED stable id (`idFn(payload)`, like `.ensures`) rather than a minted id,
+   * guarded by an `absent` precondition (a duplicate id is a typed `"<agg>-exists"` refusal). Carries the
+   * extractor so codegen/authoring knows the id is caller-supplied. OMITTED for the minted `.creates(Agg)`
+   * path (byte-identical). The marker stays `"creates"`.
+   */
+  readonly createOnceIdField?: (payload: unknown) => string;
 }
 
 /**
@@ -301,55 +362,162 @@ export interface RequirableDirective<P> extends Directive<P> {
    * the canonical manifest to before this existed (the era rule). Returns a NEW requirable directive.
    */
   births(): RequirableDirective<P>;
+  /**
+   * PROOF-TOOLING PRODUCER MARKER (symmetric to `.requires`): declare that this directive ESTABLISHES the
+   * named relation (its `plan` folds a `writeTuple` granting it). A pure proof-generator hint — NO kernel /
+   * manifest / era-key effect. It tells the relation-bootstrap proof leg which sibling to run FIRST to seed
+   * the actor before proving a `.requires(relation)`-gated write succeeds, and resolves inference ambiguity.
+   * Accumulates + dedups; additive + non-destructive. A directive that never calls this is byte-identical.
+   */
+  grants(relation: string): RequirableDirective<P>;
 }
 
 /** Stage 1: id + a referential marker (which fixes the target aggregate). */
 class DirectiveMarkerStep<Id extends string> {
   constructor(private readonly id: Id) {}
+  /**
+   * `creates(Agg)` — Nomos MINTS the id (byte-identical to before this arg existed). For CREATE-ONCE at an
+   * APP-SUPPLIED stable id, chain `.payload(...).withId(p => p.id)` on the plan step (typed against the
+   * inferred payload) — the id form lives POST-`.payload` so the extractor is fully payload-typed.
+   */
   creates(agg: AggregateHandle): DirectivePayloadStep<Id> {
-    return new DirectivePayloadStep(this.id, "creates", agg.id);
+    return new DirectivePayloadStep(this.id, "creates", agg);
   }
   mutates(agg: AggregateHandle): DirectivePayloadStep<Id> {
-    return new DirectivePayloadStep(this.id, "mutates", agg.id);
+    return new DirectivePayloadStep(this.id, "mutates", agg);
   }
   ensures(agg: AggregateHandle): DirectivePayloadStep<Id> {
-    return new DirectivePayloadStep(this.id, "ensures", agg.id);
+    return new DirectivePayloadStep(this.id, "ensures", agg);
   }
   archives(agg: AggregateHandle): DirectivePayloadStep<Id> {
-    return new DirectivePayloadStep(this.id, "archives", agg.id);
+    return new DirectivePayloadStep(this.id, "archives", agg);
   }
 }
 
-/** Stage 2: attach a Zod payload schema (drives `plan`'s payload type). */
+/** Stage 2: attach a Zod payload schema (drives `plan`'s payload type). Carries the marker's aggregate
+ *  HANDLE forward so the plan step's create-once `.withId` knows its target. */
 class DirectivePayloadStep<Id extends string> {
   constructor(
     private readonly id: Id,
     private readonly marker: ReferentialMarker,
-    private readonly aggregateId: string,
+    private readonly aggregate: AggregateHandle,
   ) {}
   payload<S extends z.ZodTypeAny>(schema: S): DirectivePlanStep<Id, z.infer<S>> {
     return new DirectivePlanStep(
       this.id,
       this.marker,
-      this.aggregateId,
+      this.aggregate,
       schema as z.ZodType<z.infer<S>>,
     );
   }
 }
 
-/** Stage 3: define `plan`, producing the finished Directive. */
+/**
+ * Stage 3: declare write-path PRECONDITIONS (post-`.payload`, so the payload type `P` is BOUND and every
+ * extractor/predicate is fully typed) and define `.plan`, producing the finished Directive. The markers
+ * live HERE — `directive(id).mutates(Agg).payload(schema).requiresExisting(Agg, p => p.siteId).plan(...)`
+ * — so `p` is the inferred payload (a typo like `p.siteid` is a COMPILE error) and `.where`'s row is the
+ * aggregate's typed read model (`row.status` is known, a wrong field a compile error). Each accumulates a
+ * {@link PreconditionDescriptor} that threads into the finished directive; `.plan` is the terminal.
+ */
 class DirectivePlanStep<Id extends string, P> {
   constructor(
     private readonly id: Id,
     private readonly marker: ReferentialMarker,
-    private readonly aggregateId: string,
+    private readonly aggregate: AggregateHandle,
     private readonly payloadSchema: z.ZodType<P>,
+    private readonly createOnceIdField?: (payload: unknown) => string,
+    private readonly preconditions: PreconditionDescriptor[] = [],
   ) {}
+
+  /** Non-destructive copy carrying one more precondition (and/or the create-once id field). */
+  private with(
+    desc?: PreconditionDescriptor,
+    createOnceIdField?: (payload: unknown) => string,
+  ): DirectivePlanStep<Id, P> {
+    return new DirectivePlanStep(
+      this.id,
+      this.marker,
+      this.aggregate,
+      this.payloadSchema,
+      createOnceIdField ?? this.createOnceIdField,
+      desc !== undefined ? [...this.preconditions, desc] : this.preconditions,
+    );
+  }
+
+  /**
+   * CREATE-ONCE at an APP-SUPPLIED stable id (`.creates(Agg).payload(...).withId(p => p.siteId)`). The id
+   * comes from `idFn(payload)` (like `.ensures`) instead of a minted id, and a duplicate id is a typed
+   * `"<agg>-exists"` refusal (an auto-desugared `absent` precondition). `idFn` is a PURE, fully-typed
+   * function of the inferred payload. ONLY valid on a `.creates` directive (it defines the created id).
+   * Additive; `.creates(Agg)` with no `.withId` is the minted path (byte-identical).
+   */
+  withId(idFn: (payload: P) => string): DirectivePlanStep<Id, P> {
+    if (this.marker !== "creates") {
+      throw new Error(
+        `directive('${this.id}').withId(...) is only valid on a .creates(...) directive — it fixes the ` +
+          `CREATED aggregate's caller-supplied id (a .${this.marker} directive targets an existing id).`,
+      );
+    }
+    const idField = idFn as (payload: unknown) => string;
+    return this.with(
+      {
+        aggregateId: this.aggregate.id,
+        idField,
+        kind: "absent",
+        predicate: (row) => row === undefined,
+        rejectCode: `${shortName(this.aggregate.id)}-exists`,
+      },
+      idField,
+    );
+  }
+
+  /**
+   * DECLARATIVE WRITE-PATH PRECONDITION — refuse if the target aggregate instance is ABSENT. Sugar for
+   * `.where(Agg, idFn, row => row !== undefined, "<agg>-not-found")` (the fixed `exists` specialization of
+   * the ONE desugaring path). `idFn` is a PURE, fully-typed payload → instance id. Additive.
+   */
+  requiresExisting<F extends Record<string, Field>>(
+    aggregate: AggregateHandle<string, F>,
+    idFn: (payload: P) => string,
+    rejectCode?: string,
+  ): DirectivePlanStep<Id, P> {
+    return this.with({
+      aggregateId: aggregate.id,
+      idField: idFn as (payload: unknown) => string,
+      kind: "exists",
+      predicate: (row) => row !== undefined,
+      rejectCode: rejectCode ?? `${shortName(aggregate.id)}-not-found`,
+    });
+  }
+
+  /**
+   * DECLARATIVE WRITE-PATH PRECONDITION — the GENERAL form: refuse if `predicate(row)` over the target's
+   * CURRENT (pre-apply) row is false. `row` is the aggregate's TYPED read model ({@link ReadModelRow} —
+   * one property per stored field at its decoded type, all optional) or `undefined` when the instance is
+   * ABSENT (so the predicate decides absence semantics too). `rejectCode` is the typed refusal. Callable
+   * multiple times to accumulate distinct guards.
+   */
+  where<F extends Record<string, Field>>(
+    aggregate: AggregateHandle<string, F>,
+    idFn: (payload: P) => string,
+    predicate: (row: ReadModelRow<F> | undefined) => boolean,
+    rejectCode: string,
+  ): DirectivePlanStep<Id, P> {
+    return this.with({
+      aggregateId: aggregate.id,
+      idField: idFn as (payload: unknown) => string,
+      kind: "predicate",
+      predicate: predicate as (row: Record<string, unknown> | undefined) => boolean,
+      rejectCode,
+    });
+  }
+
   plan(fn: (payload: P, ctx: Ports) => PlannedOp[]): RequirableDirective<P> {
     return makeRequirable({
       id: this.id,
       marker: this.marker,
-      aggregateId: this.aggregateId,
+      aggregateId: this.aggregate.id,
       payloadSchema: this.payloadSchema,
       plan: fn,
       declaredReads: [],
@@ -358,10 +526,27 @@ class DirectivePlanStep<Id extends string, P> {
       declaredCertifiedReads: {},
       declaredRelations: [],
       declaredHostCapabilities: [],
+      // `.withId(...)` — record the caller-supplied-id extractor (codegen/authoring hint). The `absent`
+      // create-once guard is already in `preconditions` (seeded by `.withId`). Omit-when-absent.
+      ...(this.createOnceIdField !== undefined ? { createOnceIdField: this.createOnceIdField } : {}),
+      // Omit-when-empty so a directive with no precondition is byte-identical (the era rule).
+      ...(this.preconditions.length > 0 ? { preconditions: this.preconditions } : {}),
     });
   }
 }
 
+/**
+ * Short, lower-camel name for an aggregate id — the reject-code stem. `EstateSite` → `estateSite`;
+ * `inventory.Item` → `item` (the SAME derivation the workspace-invariant ref-name uses). Used to build
+ * the default reject codes `"<agg>-not-found"` / `"<agg>-exists"`.
+ */
+function shortName(aggregateId: string): string {
+  const short = aggregateId.includes(".")
+    ? aggregateId.slice(aggregateId.lastIndexOf(".") + 1)
+    : aggregateId;
+  return short.length > 0 ? short[0]!.toLowerCase() + short.slice(1) : short;
+}
+
 /**
  * Build a PER-RECORD authz object template (home_holons §6) for `.requires(rel, { objectFrom })`. The
  * gate then checks the relation on `<Agg>:<validated_payload[idField]>` — the specific record this
@@ -492,6 +677,13 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       // the birth after admit. Era-ruled: a non-birthing directive omits the flag and is byte-identical.
       return makeRequirable({ ...base, birthsChild: true });
     },
+    grants(relation: string): RequirableDirective<P> {
+      // PROOF-TOOLING PRODUCER MARKER (symmetric to `.requires`): record that this directive establishes
+      // `relation` (its plan folds a granting `writeTuple`). NO kernel/manifest effect — a pure static hint
+      // the proof generator's relation-bootstrap leg reads. Accumulate + dedup; additive + non-destructive.
+      const merged = [...new Set([...(base.grantsRelation ?? []), relation])].sort();
+      return makeRequirable({ ...base, grantsRelation: merged });
+    },
   };
 }
 

package/src/engine_entry.ts

@@ -54,6 +54,7 @@
 import { executeDirectiveToIntent } from "./wire_encode.js";
 import { expandCapabilityExports } from "./capability_exports.js";
 import { RelationTuple } from "./framework/relations.js";
+import { synthesizePreconditionInvariants } from "./precondition.js";
 import { generateOpenApiFragment, mergeOpenApiFragments, type OpenApiDoc } from "./codegen_openapi.js";
 import type { QueryDecl } from "./query.js";
 import type { AnyCount } from "./count.js";
@@ -360,6 +361,14 @@ function buildDomainSlice(mod: DomainModuleExports): DomainSlice {
       wsInvariants.set(w.id, w);
     }
   }
+  // ── DESUGARED write-path preconditions (`.requiresExisting`/`.creates(Agg,idFn)`/`.where`) ──
+  // The synthesized workspace invariants are NOT module exports (they are generated from the directive
+  // markers), so the export-scan above never sees them. Synthesize them here — from the SAME discovered
+  // directives — so the SEALED ENGINE registers their `reads`/`assert` bodies and the gate actually
+  // enforces them on every lane. Byte-identical for a directive with no precondition (synthesizes none).
+  for (const directive of dirs.values()) {
+    for (const w of synthesizePreconditionInvariants(directive)) wsInvariants.set(w.id, w);
+  }
 
   return { registry, deriveds, combineds, invariants, aggInvariants, wsInvariants };
 }

package/src/index.ts

@@ -75,7 +75,13 @@ export {
   type PlannedEventMarker,
   type StrikeOp,
 } from "./ops.js";
-export { directive, recordObject, type Directive, type ReferentialMarker } from "./directive.js";
+export {
+  directive,
+  recordObject,
+  type Directive,
+  type ReferentialMarker,
+  type PreconditionDescriptor,
+} from "./directive.js";
 // FIRST-CLASS WORKSPACE TYPES (sharding §10 RATIFIED, slice 1) live on the SUBPATH
 // `@githolon/dsl/workspace-type` (`workspaceType("estate").root(Estate).hasMany(...)`),
 // NOT this runtime barrel — the barrel is bundled into EVERY tenant's engine lump, and

package/src/precondition.ts

@@ -0,0 +1,92 @@
+// 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} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * precondition — the DESUGARING of the write-path precondition primitives.
+ *
+ * The three directive markers (`.requiresExisting` / `.creates(Agg).payload(...).withId(idFn)` create-once / `.where`)
+ * each record a {@link PreconditionDescriptor}. Here — at `composeDomainModule`, the ONE place a
+ * directive's descriptors and the domain's `workspaceInvariants` list co-exist — every descriptor is
+ * SYNTHESIZED into a {@link WorkspaceInvariantDecl} (LANE B — the ref-by-id lane) and appended to the
+ * same array a hand-authored `workspaceInvariant(...)` occupies. Downstream (manifest, USD IR, the
+ * `nomosInvariantGate` era key, the engine bundle, openapi) then treats them IDENTICALLY — the marker
+ * is pure sugar over the live #266 workspace-invariant lane.
+ *
+ * WHY LANE B (ref-by-id), not the captured-read lane (A):
+ *   - The invariant resolves ONE instance by its INSTANCE id via `ref(Agg, idFn(payload))`. An absent
+ *     ref resolves to an empty/undefined snapshot with NO refusal on ANY lane — PROVEN by the
+ *     framework's own `homeNameBindsOwner` (`.reads([refAs("owner", "HomeOwner", id)])` + `owner ?? {}`),
+ *     which runs BEFORE the singleton exists, including at `verify_chain`. Every invariant body in the
+ *     codebase guards `snaps[name] ?? {}`, so absent-resolves-empty is the established contract.
+ *   - Lane A (an auto-minted `query("<Agg>ById").key("id")`) is NOT expressible: a query index key MUST
+ *     be a DECLARED aggregate FIELD (see `query.ts`), and an aggregate's INSTANCE id is not a field — so
+ *     there is no field to index a by-instance-id read on. Ref-by-id resolves by instance id directly.
+ *
+ * The synthesized invariant is a plain branded `WorkspaceInvariantDecl` (bodies ship in the engine
+ * bundle, PRESENCE-only is hashed — id + the directive it is `on`). Its id is STABLE + deterministic
+ * (`<directiveId>__precondition__<Agg>__<kind>[#n]`), so recompiles are byte-stable.
+ */
+import type { Directive, PreconditionDescriptor } from "./directive.js";
+import {
+  refAs,
+  type InvariantRef,
+  type WorkspaceInvariantDecl,
+} from "./framework/workspace_invariant.js";
+
+/** The stable ref binding name the synthesized invariant resolves the target under. */
+const REF_NAME = "target";
+
+/**
+ * Deterministic id for a synthesized precondition invariant. Stable across compiles (a pure function of
+ * the directive id, aggregate id, kind, and — only when a directive declares MORE THAN ONE guard of the
+ * same (agg, kind) — a disambiguating index). The `#n` suffix is OMITTED for the first/only such guard so
+ * the common single-guard case stays terse and stable.
+ */
+export function preconditionInvariantId(
+  directiveId: string,
+  desc: PreconditionDescriptor,
+  ordinal: number,
+): string {
+  const base = `${directiveId}__precondition__${desc.aggregateId}__${desc.kind}`;
+  return ordinal === 0 ? base : `${base}#${ordinal}`;
+}
+
+/**
+ * Synthesize the `WorkspaceInvariantDecl`s for ONE directive's precondition descriptors (LANE B). Returns
+ * `[]` for a directive with none (the era rule — no invariant emitted, byte-identical). The invariant:
+ *   - `.on(directiveId)`  — fires for this directive.
+ *   - `.reads`            — resolves the ONE by-id ref `refAs(REF_NAME, <Agg>, idFn(payload))`.
+ *   - `.assert`           — evaluates the descriptor's `predicate` over the resolved snapshot; an ABSENT
+ *                           instance passes `undefined` (the row is `snapshots[REF_NAME]`, which the kernel
+ *                           omits when the ref does not resolve). True ⇒ `{accept}`; false ⇒ the reject code.
+ */
+export function synthesizePreconditionInvariants<P>(directive: Directive<P>): WorkspaceInvariantDecl[] {
+  const descs = directive.preconditions ?? [];
+  if (descs.length === 0) return [];
+  // Disambiguate repeated (agg, kind) guards by a per-(agg,kind) ordinal so ids stay stable + unique.
+  const seen = new Map<string, number>();
+  return descs.map((desc) => {
+    const key = `${desc.aggregateId}__${desc.kind}`;
+    const ordinal = seen.get(key) ?? 0;
+    seen.set(key, ordinal + 1);
+    const id = preconditionInvariantId(directive.id, desc, ordinal);
+    return {
+      id,
+      on: directive.id,
+      reads: (ctx: { intent: Record<string, unknown> }): InvariantRef[] => [
+        refAs(REF_NAME, desc.aggregateId, desc.idField(ctx.intent)),
+      ],
+      assert: (snapshots: Record<string, Record<string, unknown>>) => {
+        // The kernel resolves the ref into `snapshots[REF_NAME]`; an ABSENT instance leaves the key
+        // undefined (proven safe — `homeNameBindsOwner`), so `undefined` is the "row does not exist" signal.
+        const row = snapshots[REF_NAME] as Record<string, unknown> | undefined;
+        return desc.predicate(row) ? { accept: true } : { reject: desc.rejectCode };
+      },
+      __isWorkspaceInvariant: true as const,
+    };
+  });
+}