@githolon/dsl 0.108.3 → 0.108.6

package/src/directive.ts

@@ -23,7 +23,11 @@ import type { PlannedOp } from "./ops.js";
 import type { Ports } from "./ctx.js";
 import type { RelationDecl } from "./relation.js";
 import type { QueryDecl } from "./query.js";
-import { normalizeActivity, type ActivityInput, type ActivityDescriptor } from "./activity.js";
+import {
+  normalizeActivity,
+  type ActivityInput,
+  type ActivityDescriptor,
+} from "./activity.js";
 import { idOfMetaOf } from "./value_object.js";
 import { BIRTH_METER_QUERIES } from "./birth_meter.js";
 import { zodDef, zodKind, zodObjectShape } from "./zod_introspection.js";
@@ -128,29 +132,52 @@ function payloadIdSelector<P>(selector: PayloadIdSelector<P>): {
       optional: false,
     };
     return {
-      field: (payload) => resolveInvariantReadId(readId, payload as Record<string, unknown>) ?? "",
+      field: (payload) =>
+        resolveInvariantReadId(readId, payload as Record<string, unknown>) ??
+        "",
       path: [selector],
       readId,
     };
   }
   if (Array.isArray(selector)) {
-    const readId: InvariantReadId = { source: "template", parts: [...selector], optional: false };
+    const readId: InvariantReadId = {
+      source: "template",
+      parts: [...selector],
+      optional: false,
+    };
     return {
-      field: (payload) => resolveInvariantReadId(readId, payload as Record<string, unknown>) ?? "",
+      field: (payload) =>
+        resolveInvariantReadId(readId, payload as Record<string, unknown>) ??
+        "",
       readId,
     };
   }
-  if (typeof selector === "object" && selector !== null && "source" in selector) {
+  if (
+    typeof selector === "object" &&
+    selector !== null &&
+    "source" in selector
+  ) {
     if (selector.source === "item") {
-      throw new Error("directive precondition ids cannot use item-relative read parts");
+      throw new Error(
+        "directive precondition ids cannot use item-relative read parts"
+      );
     }
-    const readId: InvariantReadId = selector.source === "literal"
-      ? selector
-      : selector.transform === "none"
-        ? { source: "payload", path: selector.path, prefix: "", suffix: "", optional: false }
+    const readId: InvariantReadId =
+      selector.source === "literal"
+        ? selector
+        : selector.transform === "none"
+        ? {
+            source: "payload",
+            path: selector.path,
+            prefix: "",
+            suffix: "",
+            optional: false,
+          }
         : { source: "template", parts: [selector], optional: false };
     return {
-      field: (payload) => resolveInvariantReadId(readId, payload as Record<string, unknown>) ?? "",
+      field: (payload) =>
+        resolveInvariantReadId(readId, payload as Record<string, unknown>) ??
+        "",
       ...(readId.source === "payload" ? { path: readId.path } : {}),
       readId,
     };
@@ -215,6 +242,15 @@ export interface BusinessSourceTrust {
   /** Hidden trust payload fields populated from custody identity; v2 leaves the signing-key set empty. */
   readonly genesisField: string;
   readonly keyHashesField: string;
+  /**
+   * Optional indexed business query proving that this source is already seated.
+   * Generated clients use the declared query before authoring the hidden trust
+   * directive, so an idempotent prerequisite does not become a new commit on
+   * every business action.
+   */
+  readonly satisfiedByQueryId?: string;
+  /** Satisfaction-query key -> business payload field. */
+  readonly satisfiedByQueryArgs?: Readonly<Record<string, string>>;
 }
 
 export interface Directive<P = unknown> {
@@ -320,7 +356,10 @@ export interface Directive<P = unknown> {
     readonly object: string;
     /** PER-RECORD (§6): when set, the gate object is `<recordType>:<payload[idField]>` (the static
      *  `object` is the fallback). `undefined` ⇒ the static object — era-ruled, byte-identical replay. */
-    readonly objectFrom?: { readonly recordType: string; readonly idField: string };
+    readonly objectFrom?: {
+      readonly recordType: string;
+      readonly idField: string;
+    };
   };
   /**
    * Admit this directive when it is the exact target call carried by a verified,
@@ -330,6 +369,9 @@ export interface Directive<P = unknown> {
    * check remains the authorization decision.
    */
   readonly acceptsWorkspaceEffectGate?: true;
+  /** Recovery-only workspace-effect door. The carried source must prove it is this workspace's
+   * exact K_root-rooted birth parent; no Zanzibar relation or host assertion substitutes for it. */
+  readonly acceptsVerifiedBirthParentRecoveryGate?: true;
   /**
    * CROSS-CUSTODY ATTESTATION-AUTHORIZED (home_holons §3/§5). When `true`, this directive's authorization
    * is a carried §3 SIGNED QUOTE (the asserter's pubkey + a signature over the edge), NOT an author block —
@@ -572,6 +614,8 @@ export interface RequirableDirective<P> extends Directive<P> {
     copy?: Readonly<Record<string, string>>;
     genesisField?: string;
     keyHashesField?: string;
+    satisfiedBy?: QueryDecl;
+    satisfiedByArgs?: Readonly<Record<string, string>>;
   }): RequirableDirective<P>;
   /** Declare that this action can affect several records of its primary aggregate. */
   affectsMany(): RequirableDirective<P>;
@@ -585,9 +629,18 @@ export interface RequirableDirective<P> extends Directive<P> {
    * The compiler checks observable marked plan outputs against this certified effect signature; an
    * undeclared secondary output is a compile error rather than a runtime-only projection surprise.
    */
-  alsoWrites(aggregate: AggregateHandle, marker: ReferentialMarker): RequirableDirective<P>;
-  alsoWritesMany(aggregate: AggregateHandle, marker: ReferentialMarker): RequirableDirective<P>;
-  alsoWritesOptional(aggregate: AggregateHandle, marker: ReferentialMarker): RequirableDirective<P>;
+  alsoWrites(
+    aggregate: AggregateHandle,
+    marker: ReferentialMarker
+  ): RequirableDirective<P>;
+  alsoWritesMany(
+    aggregate: AggregateHandle,
+    marker: ReferentialMarker
+  ): RequirableDirective<P>;
+  alsoWritesOptional(
+    aggregate: AggregateHandle,
+    marker: ReferentialMarker
+  ): RequirableDirective<P>;
   alsoEnsures(aggregate: AggregateHandle): RequirableDirective<P>;
   alsoCreates(aggregate: AggregateHandle): RequirableDirective<P>;
   alsoEnsuresMany(aggregate: AggregateHandle): RequirableDirective<P>;
@@ -607,7 +660,10 @@ export interface RequirableDirective<P> extends Directive<P> {
    */
   requires(
     relation: string,
-    opts?: { object?: string; objectFrom?: { recordType: string; idField: string } },
+    opts?: {
+      object?: string;
+      objectFrom?: { recordType: string; idField: string };
+    }
   ): RequirableDirective<P>;
   /** Declare this exact call shape as an admissible signed parent-workspace effect. */
   acceptsWorkspaceEffect(): RequirableDirective<P>;
@@ -617,7 +673,10 @@ export interface RequirableDirective<P> extends Directive<P> {
    * gate verifies the quote + pins the principal to the attestation key, and the bailiff delivers it
    * host-free. Framework-only (the home law's `recordShare`). Returns a NEW requirable directive.
    */
-  attestationAuthorized(owner: { ownerObject: string; ownerField: string }): RequirableDirective<P>;
+  attestationAuthorized(owner: {
+    ownerObject: string;
+    ownerField: string;
+  }): RequirableDirective<P>;
   /**
    * Declare this directive a DELEGATED-AUTHORITY delivery (`delegated_authority_births.md`): its write folds
    * the delegated `relation` tuple ONLY behind a carried `DelegationCert` P signed — lowered into the
@@ -625,14 +684,20 @@ export interface RequirableDirective<P> extends Directive<P> {
    * `subjectField`/`certField` default to `"subject"`/`"delegationCert"`. Chain `.delegatedFrom(parent)` to
    * bind the grantor to this workspace's parent key. Returns a NEW requirable directive.
    */
-  delegatedRole(relation: string, opts?: { subjectField?: string; certField?: string }): RequirableDirective<P>;
+  delegatedRole(
+    relation: string,
+    opts?: { subjectField?: string; certField?: string }
+  ): RequirableDirective<P>;
   /**
    * `.delegatedFrom(parent)` — bind the delegating grantor to THIS workspace's parent key (the platform P
    * that bore this home): the `DelegationCert`'s grantor key MUST equal the base64 key at
    * `parentKeyObject.parentKeyField` (e.g. the birth-cert `birth-attestation:self`.`parentKey`, or a seeded
    * `platform-key:self`.`grantorKey`). Refines the `.delegatedRole()` gate. Returns a NEW requirable directive.
    */
-  delegatedFrom(parent: { parentKeyObject: string; parentKeyField: string }): RequirableDirective<P>;
+  delegatedFrom(parent: {
+    parentKeyObject: string;
+    parentKeyField: string;
+  }): RequirableDirective<P>;
   /**
    * Declare this directive a KEYLESS VERIFIED-FIRST-DEVICE bootstrap (keyless_verified_onboard.md): its
    * authorization is a carried, device-bound IdP `idpToken` re-verified against the workspace AuthProvider —
@@ -675,7 +740,10 @@ export interface RequirableDirective<P> extends Directive<P> {
    * …)` declaration (signature / accepted key + genesis / bounds / freshness). Callable multiple
    * times; deduped by `(queryId, from)`. Purely additive (the era rule).
    */
-  readsFrom(sourceWorkspace: string, query: { id: string }): RequirableDirective<P>;
+  readsFrom(
+    sourceWorkspace: string,
+    query: { id: string }
+  ): RequirableDirective<P>;
   /**
    * Declare ONE DYNAMIC (payload-routed) foreign read (dynamic_source_attested_reads.md): the plan may
    * `read(theQuery, args, { from: payload.<field> })` — the routed workspace is chosen at runtime by the
@@ -686,7 +754,7 @@ export interface RequirableDirective<P> extends Directive<P> {
   readsFrom(
     source: FromPayloadRef,
     query: { id: string },
-    opts: { policy: TrustPolicyDecl },
+    opts: { policy: TrustPolicyDecl }
   ): RequirableDirective<P>;
   /**
    * Declare ONE entry of the directive's EMIT boundary: an `eventType` its `plan` may
@@ -792,14 +860,16 @@ class DirectivePayloadStep<Id extends string> {
   constructor(
     private readonly id: Id,
     private readonly marker: ReferentialMarker,
-    private readonly aggregate: AggregateHandle,
+    private readonly aggregate: AggregateHandle
   ) {}
-  payload<S extends z.ZodTypeAny>(schema: S): DirectivePlanStep<Id, z.infer<S>> {
+  payload<S extends z.ZodTypeAny>(
+    schema: S
+  ): DirectivePlanStep<Id, z.infer<S>> {
     return new DirectivePlanStep(
       this.id,
       this.marker,
       this.aggregate,
-      schema as z.ZodType<z.infer<S>>,
+      schema as z.ZodType<z.infer<S>>
     );
   }
 }
@@ -820,13 +890,13 @@ class DirectivePlanStep<Id extends string, P> {
     private readonly payloadSchema: z.ZodType<P>,
     private readonly createOnceIdField?: (payload: unknown) => string,
     private readonly preconditions: PreconditionDescriptor[] = [],
-    private readonly targetField?: string,
+    private readonly targetField?: string
   ) {}
 
   /** Non-destructive copy carrying one more precondition (and/or the create-once id field). */
   private with(
     desc?: PreconditionDescriptor,
-    createOnceIdField?: (payload: unknown) => string,
+    createOnceIdField?: (payload: unknown) => string
   ): DirectivePlanStep<Id, P> {
     return new DirectivePlanStep(
       this.id,
@@ -835,7 +905,7 @@ class DirectivePlanStep<Id extends string, P> {
       this.payloadSchema,
       createOnceIdField ?? this.createOnceIdField,
       desc !== undefined ? [...this.preconditions, desc] : this.preconditions,
-      this.targetField,
+      this.targetField
     );
   }
 
@@ -845,10 +915,12 @@ class DirectivePlanStep<Id extends string, P> {
    * Use this only when the payload carries more than one reference to the same
    * aggregate and the compiler cannot choose without domain knowledge.
    */
-  target<K extends Extract<keyof P, string>>(field: K): DirectivePlanStep<Id, P> {
+  target<K extends Extract<keyof P, string>>(
+    field: K
+  ): DirectivePlanStep<Id, P> {
     if (this.marker !== "mutates" && this.marker !== "archives") {
       throw new Error(
-        `directive('${this.id}').target(...) is only valid on .mutates(...) or .archives(...)`,
+        `directive('${this.id}').target(...) is only valid on .mutates(...) or .archives(...)`
       );
     }
     const shape = zodObjectShape(this.payloadSchema);
@@ -856,7 +928,11 @@ class DirectivePlanStep<Id extends string, P> {
     const actual = schema === undefined ? undefined : idOfMetaOf(schema);
     if (actual !== this.aggregate.id) {
       throw new Error(
-        `directive('${this.id}').target('${field}') must name an idOf(${shortName(this.aggregate.id)}) payload field`,
+        `directive('${
+          this.id
+        }').target('${field}') must name an idOf(${shortName(
+          this.aggregate.id
+        )}) payload field`
       );
     }
     return new DirectivePlanStep(
@@ -866,7 +942,7 @@ class DirectivePlanStep<Id extends string, P> {
       this.payloadSchema,
       this.createOnceIdField,
       this.preconditions,
-      field,
+      field
     );
   }
 
@@ -881,7 +957,7 @@ class DirectivePlanStep<Id extends string, 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).`,
+          `CREATED aggregate's caller-supplied id (a .${this.marker} directive targets an existing id).`
       );
     }
     const selected = payloadIdSelector(idSelector);
@@ -891,13 +967,15 @@ class DirectivePlanStep<Id extends string, P> {
         aggregateId: this.aggregate.id,
         fieldNames: Object.keys(this.aggregate.fields).sort(),
         idField,
-        ...(selected.path === undefined ? {} : { idPayloadPath: selected.path }),
+        ...(selected.path === undefined
+          ? {}
+          : { idPayloadPath: selected.path }),
         ...(selected.readId === undefined ? {} : { readId: selected.readId }),
         kind: "absent",
         predicate: (row) => row === undefined,
         rejectCode: `${shortName(this.aggregate.id)}-exists`,
       },
-      idField,
+      idField
     );
   }
 
@@ -909,7 +987,7 @@ class DirectivePlanStep<Id extends string, P> {
   requiresExisting<F extends Record<string, Field>>(
     aggregate: AggregateHandle<string, F>,
     idSelector: PayloadIdSelector<P>,
-    rejectCode?: string,
+    rejectCode?: string
   ): DirectivePlanStep<Id, P> {
     const selected = payloadIdSelector(idSelector);
     return this.with({
@@ -935,7 +1013,7 @@ class DirectivePlanStep<Id extends string, P> {
     aggregate: AggregateHandle<string, F>,
     idSelector: PayloadIdSelector<P>,
     predicate: (row: ReadModelRow<F> | undefined) => boolean,
-    rejectCode: string,
+    rejectCode: string
   ): DirectivePlanStep<Id, P> {
     const selected = payloadIdSelector(idSelector);
     return this.with({
@@ -945,7 +1023,9 @@ class DirectivePlanStep<Id extends string, P> {
       ...(selected.path === undefined ? {} : { idPayloadPath: selected.path }),
       ...(selected.readId === undefined ? {} : { readId: selected.readId }),
       kind: "predicate",
-      predicate: predicate as (row: Record<string, unknown> | undefined) => boolean,
+      predicate: predicate as (
+        row: Record<string, unknown> | undefined
+      ) => boolean,
       rejectCode,
     });
   }
@@ -963,7 +1043,7 @@ class DirectivePlanStep<Id extends string, P> {
   precondition<F extends Record<string, Field>>(
     aggregate: AggregateHandle<string, F>,
     build: (ctx: PointGuardContext<P, F>) => PointGuardDeclaration,
-    rejectCode: string,
+    rejectCode: string
   ): DirectivePlanStep<Id, P> {
     const pointGuard = buildPointGuard(aggregate, build, rejectCode);
     return this.with({
@@ -986,7 +1066,8 @@ class DirectivePlanStep<Id extends string, P> {
         optional: false,
       },
       kind: "predicate",
-      predicate: (row) => evaluatePointGuard(pointGuard.predicate, row, undefined),
+      predicate: (row) =>
+        evaluatePointGuard(pointGuard.predicate, row, undefined),
       rejectCode,
       pointGuard,
     });
@@ -1002,18 +1083,18 @@ class DirectivePlanStep<Id extends string, P> {
     const trimmed = reason.trim();
     if (trimmed.length === 0) {
       throw new Error(
-        `directive('${this.id}').declassify(reason) needs a non-empty human reason — it is the audit record for an intended private-state refusal.`,
+        `directive('${this.id}').declassify(reason) needs a non-empty human reason — it is the audit record for an intended private-state refusal.`
       );
     }
     if (this.preconditions.length === 0) {
       throw new Error(
-        `directive('${this.id}').declassify(reason) must follow .requiresExisting(...), .where(...), or .withId(...).`,
+        `directive('${this.id}').declassify(reason) must follow .requiresExisting(...), .where(...), or .withId(...).`
       );
     }
     const last = this.preconditions[this.preconditions.length - 1]!;
     if (last.declassify !== undefined) {
       throw new Error(
-        `directive('${this.id}') already declassifies its most recent precondition — declare each policy once, beside its condition.`,
+        `directive('${this.id}') already declassifies its most recent precondition — declare each policy once, beside its condition.`
       );
     }
     return new DirectivePlanStep(
@@ -1022,11 +1103,8 @@ class DirectivePlanStep<Id extends string, P> {
       this.aggregate,
       this.payloadSchema,
       this.createOnceIdField,
-      [
-        ...this.preconditions.slice(0, -1),
-        { ...last, declassify: trimmed },
-      ],
-      this.targetField,
+      [...this.preconditions.slice(0, -1), { ...last, declassify: trimmed }],
+      this.targetField
     );
   }
 
@@ -1037,11 +1115,15 @@ class DirectivePlanStep<Id extends string, P> {
       const candidates = Object.entries(shape)
         .filter(([, schema]) => idOfMetaOf(schema) === this.aggregate.id)
         .map(([field]) => field);
-      const field = this.targetField ?? (candidates.length === 1 ? candidates[0] : undefined);
+      const field =
+        this.targetField ??
+        (candidates.length === 1 ? candidates[0] : undefined);
       if (this.targetField === undefined && candidates.length > 1) {
         throw new Error(
-          `directive('${this.id}') has several idOf(${shortName(this.aggregate.id)}) payload fields; ` +
-            `select the mutation target with .target('field') before .plan(...)`,
+          `directive('${this.id}') has several idOf(${shortName(
+            this.aggregate.id
+          )}) payload fields; ` +
+            `select the mutation target with .target('field') before .plan(...)`
         );
       }
       if (field !== undefined) {
@@ -1063,9 +1145,13 @@ class DirectivePlanStep<Id extends string, P> {
       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 } : {}),
+      ...(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 } : {}),
+      ...(this.preconditions.length > 0
+        ? { preconditions: this.preconditions }
+        : {}),
     });
   }
 }
@@ -1090,7 +1176,7 @@ function shortName(aggregateId: string): string {
  */
 export function recordObject(
   agg: AggregateHandle,
-  idField: string,
+  idField: string
 ): { recordType: string; idField: string } {
   return { recordType: agg.id, idField };
 }
@@ -1105,7 +1191,7 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
   const alsoWrites = (
     aggregate: AggregateHandle,
     marker: ReferentialMarker,
-    cardinality: "one" | "many" | "optional" = "one",
+    cardinality: "one" | "many" | "optional" = "one"
   ): RequirableDirective<P> => {
     // Dedup by (marker, aggregateId) + the primary target — declaring the same output twice is a no-op, and
     // re-declaring the primary aggregate is ignored (it is already the marker target). Sorted at emit time.
@@ -1120,9 +1206,10 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
     // different marker is a distinct lawful consequence: a `.mutates(A)` directive
     // may deliberately emit an Archive for A and must retain `.alsoArchives(A)` in
     // its typed effect signature.
-    const isPrimary = aggregate.id === base.aggregateId && marker === base.marker;
+    const isPrimary =
+      aggregate.id === base.aggregateId && marker === base.marker;
     const existing = (base.secondaryOutputs ?? []).find(
-      (s) => s.marker === marker && s.aggregateId === aggregate.id,
+      (s) => s.marker === marker && s.aggregateId === aggregate.id
     );
     if (
       isPrimary ||
@@ -1137,16 +1224,20 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       return makeRequirable({
         ...base,
         secondaryOutputs: (base.secondaryOutputs ?? []).map((output) =>
-          output === existing ? next : output,
+          output === existing ? next : output
         ),
       });
     }
-    return makeRequirable({ ...base, secondaryOutputs: [...(base.secondaryOutputs ?? []), next] });
+    return makeRequirable({
+      ...base,
+      secondaryOutputs: [...(base.secondaryOutputs ?? []), next],
+    });
   };
   return {
     ...base,
     affectsMany: () => makeRequirable({ ...base, outputCardinality: "many" }),
-    affectsOptional: () => makeRequirable({ ...base, outputCardinality: "optional" }),
+    affectsOptional: () =>
+      makeRequirable({ ...base, outputCardinality: "optional" }),
     example(payload: P): RequirableDirective<P> {
       if (isRuntimeLaw()) {
         // The Node authoring pass already proved this example. Executable law retains it as proof
@@ -1154,46 +1245,57 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
         return makeRequirable({ ...base, payloadExample: payload });
       }
       const parsed = base.payloadSchema.safeParse(payload);
-      if (!parsed.success) throw new Error(
-        `directive('${base.id}').example(...) must satisfy its payload schema: ${parsed.error.message}`,
-      );
+      if (!parsed.success)
+        throw new Error(
+          `directive('${base.id}').example(...) must satisfy its payload schema: ${parsed.error.message}`
+        );
       return makeRequirable({ ...base, payloadExample: parsed.data });
     },
     fromCurrentPrincipal(field: string): RequirableDirective<P> {
       const name = field.trim();
       if (name.length === 0) {
-        throw new Error("directive.fromCurrentPrincipal(field): field must be a non-empty payload field name");
+        throw new Error(
+          "directive.fromCurrentPrincipal(field): field must be a non-empty payload field name"
+        );
       }
       if (zodKind(base.payloadSchema) !== "object") {
         throw new Error(
-          `directive('${base.id}').fromCurrentPrincipal('${name}') needs an object payload schema`,
+          `directive('${base.id}').fromCurrentPrincipal('${name}') needs an object payload schema`
         );
       }
       const principalSchema = zodObjectShape(base.payloadSchema)[name];
       if (principalSchema === undefined) {
         throw new Error(
-          `directive('${base.id}').fromCurrentPrincipal('${name}') names no payload field`,
+          `directive('${base.id}').fromCurrentPrincipal('${name}') names no payload field`
         );
       }
       let principalValue = principalSchema;
-      while (zodKind(principalValue) === "optional" || zodKind(principalValue) === "default") {
+      while (
+        zodKind(principalValue) === "optional" ||
+        zodKind(principalValue) === "default"
+      ) {
         principalValue = zodDef(principalValue).innerType!;
       }
       if (zodKind(principalValue) !== "string") {
         throw new Error(
-          `directive('${base.id}').fromCurrentPrincipal('${name}') must bind a string payload field`,
+          `directive('${base.id}').fromCurrentPrincipal('${name}') must bind a string payload field`
         );
       }
-      if (base.businessPrincipalField !== undefined && base.businessPrincipalField !== name) {
+      if (
+        base.businessPrincipalField !== undefined &&
+        base.businessPrincipalField !== name
+      ) {
         throw new Error(
-          `directive('${base.id}').fromCurrentPrincipal(...) may bind only one identity field`,
+          `directive('${base.id}').fromCurrentPrincipal(...) may bind only one identity field`
         );
       }
       return makeRequirable({ ...base, businessPrincipalField: name });
     },
     fromRecord(field: string, opts?: { as?: string }): RequirableDirective<P> {
       if (typeof field !== "string" || field.length === 0) {
-        throw new Error("directive.fromRecord(field): field must be a non-empty payload field name");
+        throw new Error(
+          "directive.fromRecord(field): field must be a non-empty payload field name"
+        );
       }
       const prior = base.businessRecordInputs ?? [];
       const next: BusinessRecordInput = {
@@ -1202,30 +1304,33 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       };
       return makeRequirable({
         ...base,
-        businessRecordInputs: [...prior.filter((candidate) => candidate.field !== field), next],
+        businessRecordInputs: [
+          ...prior.filter((candidate) => candidate.field !== field),
+          next,
+        ],
       });
     },
     trustsSource(opts): RequirableDirective<P> {
       if (base.businessSourceTrust !== undefined) {
         throw new Error(
-          `directive('${base.id}').trustsSource(...) may be declared only once`,
+          `directive('${base.id}').trustsSource(...) may be declared only once`
         );
       }
       const fromPayload = opts.fromPayload.trim();
       if (fromPayload.length === 0 || opts.query.id.trim().length === 0) {
         throw new Error(
-          `directive('${base.id}').trustsSource(...) needs a source payload field and query`,
+          `directive('${base.id}').trustsSource(...) needs a source payload field and query`
         );
       }
       const matchingRead = (base.declaredForeignReads ?? []).some(
         (edge) =>
           !("from" in edge) &&
           edge.fromPayload === fromPayload &&
-          edge.queryId === opts.query.id,
+          edge.queryId === opts.query.id
       );
       if (!matchingRead) {
         throw new Error(
-          `directive('${base.id}').trustsSource(...) must follow its matching dynamic .readsFrom(...) declaration`,
+          `directive('${base.id}').trustsSource(...) must follow its matching dynamic .readsFrom(...) declaration`
         );
       }
       const via = opts.via as Directive<unknown> & {
@@ -1233,7 +1338,15 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       };
       if (via.businessBirthInternal !== true) {
         throw new Error(
-          `directive('${base.id}').trustsSource(...): the trust directive must be wrapped in nomosImplementationDetail(...) so tenant code cannot call it`,
+          `directive('${base.id}').trustsSource(...): the trust directive must be wrapped in nomosImplementationDetail(...) so tenant code cannot call it`
+        );
+      }
+      if (
+        (opts.satisfiedBy === undefined) !==
+        (opts.satisfiedByArgs === undefined)
+      ) {
+        throw new Error(
+          `directive('${base.id}').trustsSource(...): satisfiedBy and satisfiedByArgs must be declared together`
         );
       }
       return makeRequirable({
@@ -1246,16 +1359,26 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
           copy: { ...(opts.copy ?? {}) },
           genesisField: opts.genesisField ?? "sourceGenesis",
           keyHashesField: opts.keyHashesField ?? "sourceKeyHashes",
+          ...(opts.satisfiedBy === undefined
+            ? {}
+            : {
+                satisfiedByQueryId: opts.satisfiedBy.id,
+                satisfiedByQueryArgs: { ...(opts.satisfiedByArgs ?? {}) },
+              }),
         },
       });
     },
     alsoWrites,
     alsoWritesMany: (aggregate: AggregateHandle, marker: ReferentialMarker) =>
       alsoWrites(aggregate, marker, "many"),
-    alsoWritesOptional: (aggregate: AggregateHandle, marker: ReferentialMarker) =>
-      alsoWrites(aggregate, marker, "optional"),
-    alsoEnsures: (aggregate: AggregateHandle) => alsoWrites(aggregate, "ensures"),
-    alsoCreates: (aggregate: AggregateHandle) => alsoWrites(aggregate, "creates"),
+    alsoWritesOptional: (
+      aggregate: AggregateHandle,
+      marker: ReferentialMarker
+    ) => alsoWrites(aggregate, marker, "optional"),
+    alsoEnsures: (aggregate: AggregateHandle) =>
+      alsoWrites(aggregate, "ensures"),
+    alsoCreates: (aggregate: AggregateHandle) =>
+      alsoWrites(aggregate, "creates"),
     alsoEnsuresMany: (aggregate: AggregateHandle) =>
       alsoWrites(aggregate, "ensures", "many"),
     alsoCreatesMany: (aggregate: AggregateHandle) =>
@@ -1264,8 +1387,10 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       alsoWrites(aggregate, "ensures", "optional"),
     alsoCreatesOptional: (aggregate: AggregateHandle) =>
       alsoWrites(aggregate, "creates", "optional"),
-    alsoMutates: (aggregate: AggregateHandle) => alsoWrites(aggregate, "mutates"),
-    alsoArchives: (aggregate: AggregateHandle) => alsoWrites(aggregate, "archives"),
+    alsoMutates: (aggregate: AggregateHandle) =>
+      alsoWrites(aggregate, "mutates"),
+    alsoArchives: (aggregate: AggregateHandle) =>
+      alsoWrites(aggregate, "archives"),
     alsoMutatesMany: (aggregate: AggregateHandle) =>
       alsoWrites(aggregate, "mutates", "many"),
     alsoArchivesMany: (aggregate: AggregateHandle) =>
@@ -1276,7 +1401,10 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       alsoWrites(aggregate, "archives", "optional"),
     requires(
       relation: string,
-      opts?: { object?: string; objectFrom?: { recordType: string; idField: string } },
+      opts?: {
+        object?: string;
+        objectFrom?: { recordType: string; idField: string };
+      }
     ): RequirableDirective<P> {
       // THE ONE write-authz declaration (full-native Zanzibar, no mixed systems): the captured author
       // must HOLD `relation` on the object for the one gate to admit. Default object is self-relative
@@ -1289,14 +1417,19 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
         requiresRelationGate: {
           relation,
           object: opts?.object ?? "workspace:self",
-          ...(opts?.objectFrom !== undefined ? { objectFrom: opts.objectFrom } : {}),
+          ...(opts?.objectFrom !== undefined
+            ? { objectFrom: opts.objectFrom }
+            : {}),
         },
       });
     },
     acceptsWorkspaceEffect(): RequirableDirective<P> {
       return makeRequirable({ ...base, acceptsWorkspaceEffectGate: true });
     },
-    attestationAuthorized(owner: { ownerObject: string; ownerField: string }): RequirableDirective<P> {
+    attestationAuthorized(owner: {
+      ownerObject: string;
+      ownerField: string;
+    }): RequirableDirective<P> {
       // CROSS-CUSTODY ATTESTATION-AUTHORIZED (home_holons §3/§5): this directive's authorization is a
       // carried §3 signed quote, not an author block — lowered into the `nomosAttestationGate` era key, so
       // the one gate verifies the quote (binding its subject to the LAW-DECLARED `owner`), pins the principal
@@ -1319,13 +1452,22 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
         },
       });
     },
-    delegatedRole(relation: string, opts?: { subjectField?: string; certField?: string }): RequirableDirective<P> {
+    delegatedRole(
+      relation: string,
+      opts?: { subjectField?: string; certField?: string }
+    ): RequirableDirective<P> {
       // DELEGATED-AUTHORITY DELIVERY (delegated_authority_births.md): this directive's write folds the
       // delegated `relation` tuple ONLY behind a carried DelegationCert — lowered into the `nomosDelegationGate`
       // era key, so the one gate re-verifies P's grant to K_root OFFLINE on every peer. Field names default to
       // the framework convention here (the kernel reads them from the law's declaration, hardcoding nothing).
-      const prior = (base as { delegatedRoleGate?: { parentKeyObject?: string; parentKeyField?: string } })
-        .delegatedRoleGate;
+      const prior = (
+        base as {
+          delegatedRoleGate?: {
+            parentKeyObject?: string;
+            parentKeyField?: string;
+          };
+        }
+      ).delegatedRoleGate;
       return makeRequirable({
         ...base,
         delegatedRoleGate: {
@@ -1337,14 +1479,25 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
         },
       });
     },
-    delegatedFrom(parent: { parentKeyObject: string; parentKeyField: string }): RequirableDirective<P> {
+    delegatedFrom(parent: {
+      parentKeyObject: string;
+      parentKeyField: string;
+    }): RequirableDirective<P> {
       // .delegatedFrom(parent): bind the grantor to this workspace's parent key (the platform P). Refines the
       // .delegatedRole() gate (a preceding .delegatedRole() supplies relation/fields; this adds the binding).
-      const g = (base as { delegatedRoleGate?: {
-        relation: string; subjectField: string; certField: string;
-      } }).delegatedRoleGate;
+      const g = (
+        base as {
+          delegatedRoleGate?: {
+            relation: string;
+            subjectField: string;
+            certField: string;
+          };
+        }
+      ).delegatedRoleGate;
       if (g === undefined) {
-        throw new Error("directive.delegatedFrom(): call .delegatedRole(relation) before .delegatedFrom(parent)");
+        throw new Error(
+          "directive.delegatedFrom(): call .delegatedRole(relation) before .delegatedFrom(parent)"
+        );
       }
       return makeRequirable({
         ...base,
@@ -1391,17 +1544,27 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       // captured-read lane (#58). Both accumulate, dedup (ref types by value, queries
       // by id — later decl wins), sort — only the SET is the contract.
       const refTypes = reads.filter((r): r is string => typeof r === "string");
-      const queryDecls = reads.filter((r): r is QueryDecl => typeof r !== "string");
+      const queryDecls = reads.filter(
+        (r): r is QueryDecl => typeof r !== "string"
+      );
       const merged = [...new Set([...base.declaredReads, ...refTypes])].sort();
-      const byId = new Map<string, QueryDecl>((base.declaredQueryReads ?? []).map((q) => [q.id, q]));
+      const byId = new Map<string, QueryDecl>(
+        (base.declaredQueryReads ?? []).map((q) => [q.id, q])
+      );
       for (const q of queryDecls) byId.set(q.id, q);
-      const mergedQueries = [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-      return makeRequirable({ ...base, declaredReads: merged, declaredQueryReads: mergedQueries });
+      const mergedQueries = [...byId.values()].sort((a, b) =>
+        a.id < b.id ? -1 : a.id > b.id ? 1 : 0
+      );
+      return makeRequirable({
+        ...base,
+        declaredReads: merged,
+        declaredQueryReads: mergedQueries,
+      });
     },
     readsFrom(
       source: string | FromPayloadRef,
       query: { id: string },
-      opts?: { policy: TrustPolicyDecl },
+      opts?: { policy: TrustPolicyDecl }
     ): RequirableDirective<P> {
       // ATTESTED CROSS-WORKSPACE READ (slice B + dynamic policies): accumulate a STATIC (queryId, from)
       // edge OR a DYNAMIC (queryId, policy, fromPayload) edge, dedup by canonical key, sort (only the
@@ -1413,16 +1576,20 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
           throw new Error(
             `readsFrom(fromPayload('${source.payloadField}'), '${query.id}'): a payload-routed foreign ` +
               `read REQUIRES a trust policy — pass { policy: <trustPolicy(...) decl> } (the acceptable ` +
-              `sources are LAW-STATE, so the runtime-named workspace is judged against a folded allow-list).`,
+              `sources are LAW-STATE, so the runtime-named workspace is judged against a folded allow-list).`
           );
         }
         if (!isTrustPolicyDecl(policy)) {
           throw new Error(
             `readsFrom(fromPayload('${source.payloadField}'), '${query.id}'): { policy } must be a ` +
-              `trustPolicy(...) declaration.`,
+              `trustPolicy(...) declaration.`
           );
         }
-        entry = { queryId: query.id, policy: policy.policyId, fromPayload: source.payloadField };
+        entry = {
+          queryId: query.id,
+          policy: policy.policyId,
+          fromPayload: source.payloadField,
+        };
         if (policy.monotone === true) __registerMonotoneForeignQuery(query.id);
       } else {
         entry = { queryId: query.id, from: source };
@@ -1432,19 +1599,27 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
           ? `0\\0${e.from}\\0${e.queryId}`
           : `1\\0${e.policy}\\0${e.fromPayload}\\0${e.queryId}`;
       const prior = base.declaredForeignReads ?? [];
-      const byKey = new Map<string, ForeignReadEdge>(prior.map((e) => [canon(e), e]));
+      const byKey = new Map<string, ForeignReadEdge>(
+        prior.map((e) => [canon(e), e])
+      );
       byKey.set(canon(entry), entry);
-      const merged = [...byKey.values()].sort((a, b) => (canon(a) < canon(b) ? -1 : canon(a) > canon(b) ? 1 : 0));
+      const merged = [...byKey.values()].sort((a, b) =>
+        canon(a) < canon(b) ? -1 : canon(a) > canon(b) ? 1 : 0
+      );
       // Every admitted foreign read advances the reader-local source frontier in-band.
       // This is a framework consequence of `.readsFrom`, so make it part of the typed
       // effect signature here; tenant authors must not know the bookkeeping aggregate.
-      return makeRequirable({ ...base, declaredForeignReads: merged })
-        .alsoEnsures(NomosSourceFrontier);
+      return makeRequirable({
+        ...base,
+        declaredForeignReads: merged,
+      }).alsoEnsures(NomosSourceFrontier);
     },
     emits(eventType: string, opts?: { max?: number }): RequirableDirective<P> {
       // Accumulate one event type onto any prior emits; a `max` bound is recorded only
       // when supplied (so `{}` vs `{max}` is a real contract difference).
-      const merged: Record<string, { max?: number }> = { ...base.declaredEmits };
+      const merged: Record<string, { max?: number }> = {
+        ...base.declaredEmits,
+      };
       merged[eventType] = opts?.max !== undefined ? { max: opts.max } : {};
       return makeRequirable({ ...base, declaredEmits: merged });
     },
@@ -1457,20 +1632,35 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       // .creates target + any .alsoCreates). Non-law, additive — stored like `description`.
       const createdIds = [
         ...(base.marker === "creates" ? [base.aggregateId] : []),
-        ...(base.secondaryOutputs ?? []).filter((o) => o.marker === "creates").map((o) => o.aggregateId),
+        ...(base.secondaryOutputs ?? [])
+          .filter((o) => o.marker === "creates")
+          .map((o) => o.aggregateId),
       ];
-      return makeRequirable({ ...base, activityDescriptor: normalizeActivity(base.id, input, base.payloadSchema, createdIds) });
+      return makeRequirable({
+        ...base,
+        activityDescriptor: normalizeActivity(
+          base.id,
+          input,
+          base.payloadSchema,
+          createdIds
+        ),
+      });
     },
     declaresRelation(rel: RelationDecl): RequirableDirective<P> {
       // Accumulate onto any prior relations — additive, non-destructive. A relation lands in
       // the manifest keyed by its `proposes` directive (cross_workspace.md §3.2.1).
-      return makeRequirable({ ...base, declaredRelations: [...base.declaredRelations, rel] });
+      return makeRequirable({
+        ...base,
+        declaredRelations: [...base.declaredRelations, rel],
+      });
     },
     requiresHostCapability(...portIds: string[]): RequirableDirective<P> {
       // Accumulate onto any prior host-capability ports, dedup, sort — order is incidental to
       // the HOST/PORT contract; only the SET of required port ids matters. DISTINCT symbol from
       // the AUTHZ `requiresCapability` (the two axes never conflate).
-      const merged = [...new Set([...base.declaredHostCapabilities, ...portIds])].sort();
+      const merged = [
+        ...new Set([...base.declaredHostCapabilities, ...portIds]),
+      ].sort();
       return makeRequirable({ ...base, declaredHostCapabilities: merged });
     },
     births(): RequirableDirective<P> {
@@ -1482,10 +1672,18 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       // `nomosReadGate` era key carries them by construction and the meter reads the `.births()` dispatch
       // auto-captures (see `executeDirectiveToIntent`) CAS-verify on every lane. The era is the bundle:
       // recompiling under this DSL is what arms the meter (every pre-era bundle replays byte-green).
-      const byId = new Map<string, QueryDecl>((base.declaredQueryReads ?? []).map((q) => [q.id, q]));
+      const byId = new Map<string, QueryDecl>(
+        (base.declaredQueryReads ?? []).map((q) => [q.id, q])
+      );
       for (const q of BIRTH_METER_QUERIES) byId.set(q.id, q);
-      const mergedQueries = [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-      return makeRequirable({ ...base, birthsChild: true, declaredQueryReads: mergedQueries });
+      const mergedQueries = [...byId.values()].sort((a, b) =>
+        a.id < b.id ? -1 : a.id > b.id ? 1 : 0
+      );
+      return makeRequirable({
+        ...base,
+        birthsChild: true,
+        declaredQueryReads: mergedQueries,
+      });
     },
     resolves(field: string): RequirableDirective<P> {
       // THE DESIGNATED SURFACED RESOLVER: record which Surfaced field this directive resolves. Field
@@ -1494,13 +1692,13 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
       if (typeof field !== "string" || field.length === 0) {
         throw new Error(
           `directive('${base.id}').resolves(field) needs a non-empty field name — the Surfaced field ` +
-            `this directive is the designated resolver of (e.g. .resolves("title")).`,
+            `this directive is the designated resolver of (e.g. .resolves("title")).`
         );
       }
       if (base.resolvesField !== undefined && base.resolvesField !== field) {
         throw new Error(
           `directive('${base.id}').resolves("${field}"): already .resolves("${base.resolvesField}") — ` +
-            `a directive designates AT MOST ONE Surfaced field (write a second directive for the other).`,
+            `a directive designates AT MOST ONE Surfaced field (write a second directive for the other).`
         );
       }
       return makeRequirable({ ...base, resolvesField: field });
@@ -1509,13 +1707,17 @@ function makeRequirable<P>(base: Directive<P>): 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();
+      const merged = [
+        ...new Set([...(base.grantsRelation ?? []), relation]),
+      ].sort();
       return makeRequirable({ ...base, grantsRelation: merged });
     },
   };
 }
 
-export function directive<const Id extends string>(id: Id): DirectiveMarkerStep<Id> {
+export function directive<const Id extends string>(
+  id: Id
+): DirectiveMarkerStep<Id> {
   return new DirectiveMarkerStep(id);
 }
 
@@ -1525,7 +1727,7 @@ export function directive<const Id extends string>(id: Id): DirectiveMarkerStep<
  * framework lowering and temporary migration law, never a second application lane.
  */
 export function nomosImplementationDetail<T extends object>(
-  declaration: T,
+  declaration: T
 ): T & { readonly businessBirthInternal: true } {
   return { ...declaration, businessBirthInternal: true };
 }