@githolon/dsl 0.28.0 → 0.29.1

package/package.json

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

@@ -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_proof.ts

@@ -41,6 +41,7 @@ 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";
@@ -348,15 +349,26 @@ function relationSeedLegLines(
   leg: RelationBootstrapLeg | undefined,
   factory: string,
   n: () => number,
+  diagnostic?: string,
 ): string[] {
-  if (leg === undefined) return [];
+  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"`;
-  // Grant payload: overwrite the routed subject/grantedBy fields (and any name-shaped fallback) with the actor.
+  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)$/i.test(k);
+      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)}`;
@@ -366,9 +378,54 @@ function relationSeedLegLines(
   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.relation}" (${leg.via}).`,
+    `//    (\`.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).`,
     `{`,
@@ -376,10 +433,10 @@ function relationSeedLegLines(
     `  globalThis.fetch = (() => { throw new Error("OFFLINE PROOF VIOLATED: relation-bootstrap touched the network"); }) as typeof fetch;`,
     `  try {`,
     `    const ACTOR = ${ACTOR};`,
-    `    // (1) grant "${leg.relation}" to ACTOR (the grant folds a writeTuple; subject seated on 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.relation}" to \${ACTOR}\`);`,
-    `    // (2) the GATED write now SUCCEEDS under the seeded actor (holds "${leg.relation}").`,
+    `    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 {`,
@@ -406,8 +463,13 @@ export interface RelationBootstrapLeg {
   readonly domain: string;
   /** The gated directive id (`.requires(relation)`). */
   readonly gatedDirectiveId: string;
-  /** The relation the gate requires (and the grant establishes). */
+  /** 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[];
@@ -426,8 +488,21 @@ export interface RelationBootstrapLeg {
   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)`) or `"inferred"` (plan-probe). Cosmetic. */
-  readonly via: "marker" | "inferred";
+  /** 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
@@ -472,6 +547,19 @@ function probeGrantsRelation(dir: Directive<unknown>, relation: string, where: s
   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). */
@@ -503,19 +591,122 @@ function resolveGrantSubjectFields(
   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 R (prefer a `.grants(R)` marker; else plan-probe for a granting `writeTuple`).
- *  `undefined` ⇒ no gated directive, or no discoverable granter (the negative conformance leg still runs). */
+ *  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,
-  );
+  const isGatedProvable = (d: Directive<unknown> | undefined): boolean =>
+    d?.requiresRelationGate !== undefined &&
+    typeof d.payloadSchema === "object" &&
+    d.birthsChild !== true &&
+    d.attestationAuthorizedGate === undefined;
+  // PREFER a gated `.creates` as the bootstrap target: a gated create is exactly the shape excluded from the
+  // naive standalone-create leg (isStandaloneCreate), so the bootstrap leg is its ONLY positive proof — seed
+  // authority, then prove the CREATE is admitted. When no gated create exists, fall back to any gated write
+  // (a gated `.mutates`/`.ensures`), so an un-created gated law is still proven.
+  const gated = directives.find((d) => isGatedProvable(d) && d.marker === "creates")
+    ?? directives.find((d) => isGatedProvable(d));
   if (gated === undefined) return undefined;
   const relation = gated.requiresRelationGate!.relation;
 
@@ -531,16 +722,57 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
   const gatedPayload: Record<string, unknown> = { ...gatedSynth.value };
   if (gatedMintField !== undefined) delete gatedPayload[gatedMintField];
 
-  // Find the granter. FIRST prefer a `.grants(R)` marker (static, unambiguous). ELSE plan-probe siblings for
-  // a granting `writeTuple` whose relation === R. Never the gated directive itself.
+  // 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);
-  let via: "marker" | "inferred" = "marker";
-  let granter = candidates.find((d) => (d.grantsRelation ?? []).includes(relation));
-  if (granter === undefined) {
-    via = "inferred";
-    granter = candidates.find((d) => probeGrantsRelation(d, relation, `${domain}/${d.id}`));
+  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;
+    }
   }
-  if (granter === undefined) return undefined;
+  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
@@ -559,6 +791,7 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
     domain,
     gatedDirectiveId: gated.id,
     relation,
+    grantedRelation,
     gatedPayload,
     gatedAutoStamped: gatedSynth.autoStamped,
     ...(gatedMintField !== undefined ? { gatedMintField, gatedAggregateId: gated.aggregateId } : {}),
@@ -568,9 +801,61 @@ export function discoverRelationBootstrapLeg(mod: DomainModule): RelationBootstr
     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). */
@@ -904,13 +1189,17 @@ export interface ProofLegs {
  *  The SINGLE source of the create-leg selection — `generateTsProof` (the .mts marker) and
  *  `proofLegsIndex` (the per-domain index) both call this, so the offline lane proves any domain the
  *  same way the generated proof proves its primary one. */
-/** A `.creates` directive the proof can DRIVE from a synthesized sample offline: not a `.births()` (a birth
- *  is the child-birth lane), not ATTESTATION-AUTHORIZED (needs a signed §3 quote no synthesizer can produce —
- *  e.g. the home law's `recordShare`). Those are NOT standalone-provable offline; the domain proves via its
- *  child-birth leg / compile-valid instead. */
+/** A `.creates` directive the proof can DRIVE from a synthesized sample offline WITH NO SEEDED AUTHORITY: not
+ *  a `.births()` (a birth is the child-birth lane), not ATTESTATION-AUTHORIZED (needs a signed §3 quote no
+ *  synthesizer can produce — e.g. the home law's `recordShare`), and NOT AUTHZ-GATED (`.requires(R)` — a
+ *  gated create dispatched with no seeded authority is REFUSED at the gate; its metadata already says it
+ *  needs authority, so the naive standalone leg must not touch it — it is proven POSITIVELY by the
+ *  relation-bootstrap leg / the born-child genesis instead). Those are NOT standalone-provable offline; the
+ *  domain proves via its bootstrap / child-birth / compile-valid legs instead. */
 function isStandaloneCreate(d: Directive<unknown> | undefined): boolean {
   return d?.marker === "creates" && typeof d.payloadSchema === "object"
-    && d.birthsChild !== true && d.attestationAuthorizedGate === undefined;
+    && d.birthsChild !== true && d.attestationAuthorizedGate === undefined
+    && d.requiresRelationGate === undefined;
 }
 
 export function proofLegsForModule(mod: DomainModule): ProofLegs | null {
@@ -1264,19 +1553,94 @@ function generateBirthOnlyProof(
   return out.join("\n");
 }
 
+/**
+ * THE BOOTSTRAP-ONLY PROOF (gated-create isolation): a package whose ONLY creating write is AUTHZ-GATED
+ * (`.creates(...).requires(R)` — co2's estate `createSite`). It has no ungated standalone create to dispatch
+ * naively (that would be REFUSED at the gate with no seeded authority) and no `.births()` genesis. So the
+ * proof deploys the law, connects, and drives the RELATION-BOOTSTRAP leg as its primary write: seed authority
+ * (layers 1-3), THEN prove the gated create is ADMITTED — the ordering (seed BEFORE the gated dispatch) is
+ * correct by construction. If authority genuinely can't be seeded, the leg emits the loud diagnostic (never a
+ * false green). The offline runner proves the same leg locally (`githolon proof`); this `.mts` is `--live`.
+ */
+function generateBootstrapOnlyProof(
+  mod: DomainModule,
+  opts: TsProofOptions,
+  primaryLegs: ProofLegs,
+): string {
+  const domain = mod.domain ?? mod.name;
+  const factory = tsClientFactoryName(domain);
+  const hashConst = tsHashConstName(opts.packageName);
+  const rb = primaryLegs.relationBootstrap;
+  if (rb === undefined) {
+    // Only reached defensively — the caller gates on relationBootstrap !== undefined.
+    throw new Error(`domain '${domain}' has a gated create but no relation-bootstrap leg to prove it (no seedable authority)`);
+  }
+  const slug =
+    opts.packageName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 24) || "domain";
+  const legsMarker = JSON.stringify(primaryLegs);
+  let step = 0;
+  const n = () => ++step;
+  const out: string[] = [];
+  out.push(
+    `// AUTO-GENERATED by nomos-compile — the RUNNABLE PROOF for package "${opts.packageName}",`,
+    `// synthesized from the domain's OWN law. This package's ONLY creating write is AUTHZ-GATED`,
+    `// (\`${domain}/${rb.gatedDirectiveId}\` .requires("${rb.relation}")), so the proof SEEDS authority first,`,
+    `// then proves the gated create is admitted — never a naive dispatch the gate would refuse. Reshape the`,
+    `// law, recompile, and this proof reshapes itself — no test rewriting. Run it:`,
+    `//`,
+    `//   npx githolon proof        (offline legs on a local holon)`,
+    `//   npx githolon proof --live (or: npx tsx build/${opts.packageName}.proof.mts — the full cloud loop)`,
+    `//`,
+    `// Regenerated on every compile; do not edit.`,
+    `// @nomos-proof-legs ${legsMarker}`,
+    `import { readFileSync } from "node:fs";`,
+    `import { connect, encodeIntentOfferBytes } from "@githolon/client";`,
+    `import { ${factory}, ${hashConst} } from "./${opts.packageName}.client.ts";`,
+    `void connect; void encodeIntentOfferBytes; void ${factory};`,
+    ``,
+    `const CLOUD = (process.env.NOMOS_CLOUD || "https://nomos.captainapp.co.uk").replace(/\\/+$/, "");`,
+    `const WS = process.env.NOMOS_WS || ${JSON.stringify(slug + "-proof-")} + Math.random().toString(36).slice(2, 8);`,
+    ``,
+    ...v2IdentityAndCleanupPreamble(opts, hashConst, n),
+    ``,
+    `// ${n()}. connect + bind the GENERATED typed client (the relation-bootstrap leg drives it with an actor)`,
+    `const holon = await connect({ cloud: CLOUD, workspace: WS, clientId: "proof-1" });`,
+    `ok(\`web client connected — ${factory} bound (replica \${holon.replica.slice(0, 6)}…)\`);`,
+    ``,
+    // The SAME relation-bootstrap emitter the standalone proof uses — seed authority, then prove the GATED
+    // CREATE is admitted (layers 1-3; a speculative seed-path degrades to a diagnostic, never a false green).
+    ...relationSeedLegLines(rb, factory, n),
+    `console.log(\`\\nALL GREEN — generated proof for "${opts.packageName}": deploy → seed authority → gated create ${rb.gatedDirectiveId} admitted (\${WS})\`);`,
+    ``,
+    ...v2CatchFinally(),
+    ``,
+  );
+  return out.join("\n");
+}
+
 export function generateTsProof(modules: readonly DomainModule[], opts: TsProofOptions): string {
-  // PRIMARY-DOMAIN SELECTION: the live `.mts` drives a STANDALONE create when the package has one (the full
-  // deploy → write → query → sync → cloud loop). A BIRTH-ONLY package (every `.creates` is also a `.births()`
-  // — the home/estate composable shape) has no standalone create to drive, so the primary becomes the first
-  // `.births()` domain and the live `.mts` drives the birth as its primary write. Either way, the marker =
-  // the primary domain's FULL legs (so the offline runner + the index never describe different directives).
+  // PRIMARY-DOMAIN SELECTION: the live `.mts` drives a STANDALONE (ungated) create when the package has one
+  // (the full deploy → write → query → sync → cloud loop). Else a BIRTH package (`.births()`) drives the
+  // birth. Else a GATED-CREATE package — whose only creating write `.requires(R)` (co2's estate `createSite`)
+  // — drives the RELATION-BOOTSTRAP leg as its primary write: seed authority, THEN the gated create is
+  // admitted (never a naive first dispatch that the gate would refuse). Either way, the marker = the primary
+  // domain's FULL legs (so the offline runner + the index never describe different directives).
   const hasStandaloneCreate = (m: DomainModule): boolean =>
     (m.directives as Directive<unknown>[]).some((d) => isStandaloneCreate(d));
   const hasBirth = (m: DomainModule): boolean => birthDirectiveOf(m) !== undefined;
-  const mod = modules.find(hasStandaloneCreate) ?? modules.find(hasBirth);
+  const isBootstrapProvable = (m: DomainModule): boolean => {
+    try { return discoverRelationBootstrapLeg(m) !== undefined; } catch { return false; }
+  };
+  const mod = modules.find(hasStandaloneCreate) ?? modules.find(hasBirth) ?? modules.find(isBootstrapProvable);
   if (mod === undefined) {
+    // No provable creating write anywhere. If a GATED create exists but its authority can't be seeded, surface
+    // the loud bootstrap diagnostic (never a false green); else the generic "add a .creates" remedy.
+    const gapMod = modules.find((m) => diagnoseRelationBootstrapGap(m) !== undefined);
+    const gap = gapMod !== undefined ? diagnoseRelationBootstrapGap(gapMod) : undefined;
     throw new Error(
-      `no .creates directive in any domain — a generated proof needs one creating write (or a .births() birth directive); add a directive(...).creates(...) (test/e2e.mts remains the hand-authored lane)`,
+      gap !== undefined
+        ? `no proof could be synthesized: ${gap}`
+        : `no .creates directive in any domain — a generated proof needs one creating write (or a .births() birth directive); add a directive(...).creates(...) (test/e2e.mts remains the hand-authored lane)`,
     );
   }
   const domain = mod.domain ?? mod.name;
@@ -1284,18 +1648,24 @@ export function generateTsProof(modules: readonly DomainModule[], opts: TsProofO
   const hashConst = tsHashConstName(opts.packageName);
   // THE MARKER (since 0.5.0) + the per-domain index are ONE synthesis (`legsForDomain`) — the proof body, its
   // marker, and the index can never describe different directives. The primary domain's legs carry whichever
-  // of standalone / child-birth it has.
+  // of standalone / child-birth / relation-bootstrap it has.
   const primaryLegs = legsForDomain(mod, modules);
   const childBirth = primaryLegs.childBirth;
 
-  // The standalone-create lane (when the primary has one). A birth-only primary skips this — its primary
-  // write is the child-birth leg below.
-  const createDir = (mod.directives as Directive<unknown>[]).find(
-    (d) => d?.marker === "creates" && typeof d.payloadSchema === "object" && d.birthsChild !== true,
-  );
+  // The standalone-create lane needs an UNGATED create (isStandaloneCreate — never a gated/birth/attestation
+  // create, which the gate would refuse dispatched with no seeded authority). Absent one, the primary write
+  // is the birth leg (a `.births()` domain) or the relation-bootstrap leg (a gated-create domain).
+  const createDir = (mod.directives as Directive<unknown>[]).find((d) => isStandaloneCreate(d));
   if (createDir === undefined) {
-    // BIRTH-ONLY PRIMARY: emit a birth-shaped proof (no standalone create/query/count/concurrency legs).
-    return generateBirthOnlyProof(mod, modules, opts, primaryLegs);
+    // BIRTH-ONLY PRIMARY: emit a birth-shaped proof (the birth replays genesis, seating authority, then the
+    // born child self-validates — a gated child-domain create is proven INSIDE the born child context).
+    if (primaryLegs.childBirth !== undefined) return generateBirthOnlyProof(mod, modules, opts, primaryLegs);
+    // BOOTSTRAP-ONLY PRIMARY: the only creating write is GATED — deploy, then seed authority + prove the
+    // gated create is admitted (the relation-bootstrap leg is its ONLY positive proof).
+    if (primaryLegs.relationBootstrap !== undefined) return generateBootstrapOnlyProof(mod, opts, primaryLegs);
+    // A gated create with no seedable authority: loud diagnostic (compile skips the proof, law still ships).
+    const gap = diagnoseRelationBootstrapGap(mod);
+    throw new Error(gap !== undefined ? `no proof could be synthesized for '${domain}': ${gap}` : `domain '${domain}' has no provable creating write`);
   }
   const agg = (mod.aggregates as AggregateHandle[]).find((a) => a.id === createDir.aggregateId);
   if (agg === undefined) {
@@ -1537,10 +1907,11 @@ 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 to the proof actor, then prove
-  // the gated write SUCCEEDS under that actor. Runs on the LOCAL holon (fetch re-trapped). Emits nothing when
-  // no granter is discoverable (the negative conformance leg still covers the gate).
-  out.push(...relationSeedLegLines(relationBootstrap, 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.

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
@@ -201,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;
 }
 
 /**
@@ -325,50 +375,149 @@ export interface RequirableDirective<P> extends Directive<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: [],
@@ -377,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

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,
+    };
+  });
+}