@githolon/dsl 0.27.1 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/codegen_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,7 @@ 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 { finishCount } from "./count.js";
 import { mintedCreateField } from "./workspace_routing.js";
 import { deterministicPorts } from "./ctx.js";
@@ -336,6 +337,240 @@ 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,
+): string[] {
+  if (leg === undefined) return [];
+  const ACTOR = `"user:proof-conformance"`;
+  // Grant 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);
+      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);
+  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}).`,
+    `//    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.relation}" 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}").`,
+    `    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 (and the grant establishes). */
+  readonly relation: 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)`) or `"inferred"` (plan-probe). Cosmetic. */
+  readonly via: "marker" | "inferred";
+}
+
+/** 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);
+}
+
+/** 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] };
+}
+
+/** 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). */
+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 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.
+  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}`));
+  }
+  if (granter === undefined) return undefined;
+
+  // 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,
+    gatedPayload,
+    gatedAutoStamped: gatedSynth.autoStamped,
+    ...(gatedMintField !== undefined ? { gatedMintField, gatedAggregateId: gated.aggregateId } : {}),
+    grantDirectiveId: granter.id,
+    grantPayload,
+    grantAutoStamped: grantSynth.autoStamped,
+    grantSubjectFields: routed.subjectFields,
+    grantGrantedByFields: routed.grantedByFields,
+    via,
+  };
+}
+
 // ── 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 +869,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 +893,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 +967,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 +996,7 @@ export function legsForDomain(mod: DomainModule, modules: readonly DomainModule[
         }
       : {}),
     ...(childBirthWithSetup !== undefined ? { childBirth: childBirthWithSetup } : {}),
+    ...(relationBootstrap !== undefined ? { relationBootstrap } : {}),
   };
 }
 
@@ -1090,6 +1341,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 +1537,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 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/directive.ts

@@ -175,6 +175,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`
@@ -301,6 +312,14 @@ 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). */
@@ -492,6 +511,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 });
+    },
   };
 }