deepline 0.3.128 → 0.3.129

package/dist/bundling-sources/shared_libs/play-runtime/governor/governor.ts

@@ -20,7 +20,13 @@ import {
   resolveMaxConcurrentExternalCalls,
   resolveRowConcurrency,
 } from './policy';
-import { type PacingRule, type RateStateBackend } from './rate-state-backend';
+import {
+  type PacingPermit,
+  type PacingRule,
+  type ProviderConcurrencyGrant,
+  type ProviderPacingGrant,
+  type RateStateBackend,
+} from './rate-state-backend';
 import {
   createInMemoryAdaptiveAdmission,
   type RuntimeAdaptiveAdmission,
@@ -36,6 +42,30 @@ export interface WorkLease {
   release(): void;
 }
 
+/** A provider admission that may be returned only before its first fetch. */
+export interface ProviderPermit extends WorkLease {
+  /** Canonical provider bucket that admitted this physical attempt. */
+  readonly provider: string;
+  /** Server-authored attribution context for a later provider 429. */
+  readonly concurrencyGrant?: ProviderConcurrencyGrant | null;
+  /** Effective rate-controller reading for this physical provider permit. */
+  readonly pacingGrant?: ProviderPacingGrant | null;
+  /**
+   * Return an acquired provider permit before an outbound request started.
+   * Unlike `release`, this returns the rate reservation as well as any
+   * concurrency lease. It is deliberately required at this boundary so a
+   * caller cannot silently burn a ticket while re-admitting after local work.
+   */
+  cancel(): Promise<void>;
+  /**
+   * Return a due permit that lost a local capacity race so the next
+   * `acquireProviderPermit` for the same lane draws it locally. Frees the
+   * local concurrency slot like `cancel`, but keeps the rate ticket in the
+   * backend's lease block when that block is still live; otherwise refunds.
+   */
+  park(): Promise<void>;
+}
+
 export type BudgetKind = 'toolCall' | 'retry' | 'waterfallStep';
 
 /** Runtime identity and counters shared by inline composition. */
@@ -113,6 +143,16 @@ export interface PlayExecutionGovernor {
     opts?: { signal?: AbortSignal },
   ): Promise<WorkLease>;
 
+  /** Acquire only local external-execution capacity; this never charges a budget. */
+  acquireToolExecutionSlot(opts?: { signal?: AbortSignal }): Promise<WorkLease>;
+
+  /**
+   * Take immediately available local external-execution capacity, if any.
+   * This is deliberately non-blocking: a provider ticket that is already due
+   * must be re-admitted instead of aging behind a local queue.
+   */
+  tryAcquireToolExecutionSlot(): WorkLease | null;
+
   /**
    * Admit one brief runtime-to-app HTTP fetch/body exchange. Long provider or
    * fixture residence happens before this edge and must not occupy this slot.
@@ -121,6 +161,12 @@ export interface PlayExecutionGovernor {
     signal?: AbortSignal;
   }): Promise<WorkLease>;
 
+  /**
+   * Take a runtime-to-app transport slot only if one is immediately ready.
+   * A due provider permit must re-admit rather than age behind this queue.
+   */
+  tryAcquireIntegrationRequestSlot(): WorkLease | null;
+
   /**
    * Block until one physical provider HTTP attempt is admitted under the
    * provider's shared rate/concurrency rules. Call this immediately before the
@@ -129,7 +175,16 @@ export interface PlayExecutionGovernor {
   acquireProviderPermit(
     toolId: string,
     opts?: { signal?: AbortSignal },
-  ): Promise<WorkLease>;
+  ): Promise<ProviderPermit>;
+
+  /**
+   * Admit one physical provider attempt only from capacity this process
+   * already holds: the tool's local concurrency slot and a due permit in the
+   * rate backend's local state. Synchronous and never remote, so a caller may
+   * probe it while holding an execution slot. Null until a blocking
+   * `acquireProviderPermit` has resolved the tool's pacing at least once.
+   */
+  tryAcquireProviderPermit(toolId: string): ProviderPermit | null;
 
   /**
    * Suggested batch parallelism for a tool: the provider's own rate hints
@@ -171,6 +226,10 @@ export interface PlayExecutionGovernor {
      */
     toolId?: string;
     retryAfterMs: number;
+    /** Provider residence for the rejected physical request, when observed. */
+    latencyMs?: number | null;
+    /** Server-authored context for attributing this physical provider 429. */
+    concurrencyGrant?: ProviderConcurrencyGrant | null;
   }): Promise<void>;
 
   /** Feed clean provider calls back into adaptive admission. */
@@ -203,9 +262,37 @@ interface GovernorInput {
 
 class Semaphore {
   private inFlight = 0;
-  private readonly waiters: Array<() => void> = [];
+  private readonly waiters: Array<(reserved: boolean) => void> = [];
   constructor(private readonly limit: number) {}
 
+  private lease(): WorkLease {
+    this.inFlight += 1;
+    return this.leased();
+  }
+
+  /** Return a lease for capacity already reserved by a waiter handoff. */
+  private leased(): WorkLease {
+    let released = false;
+    return {
+      release: () => {
+        if (released) return;
+        released = true;
+        this.inFlight = Math.max(0, this.inFlight - 1);
+        const next = this.waiters.shift();
+        if (next) {
+          // Reserve before waking. A synchronous tryAcquire between this
+          // release and the promise continuation must not overtake FIFO work.
+          this.inFlight += 1;
+          next(true);
+        }
+      },
+    };
+  }
+
+  tryAcquire(): WorkLease | null {
+    return this.inFlight >= this.limit ? null : this.lease();
+  }
+
   async acquire(signal?: AbortSignal): Promise<WorkLease> {
     // Fail fast on an already-aborted signal: the parked-promise abort listener
     // below registers with { once: true } and never fires for a signal that was
@@ -217,10 +304,10 @@ class Semaphore {
         : new Error('Slot acquire aborted.');
     }
     while (this.inFlight >= this.limit) {
-      await new Promise<void>((resolve, reject) => {
-        const onResolve = () => {
+      const reserved = await new Promise<boolean>((resolve, reject) => {
+        const onResolve = (wasReserved: boolean) => {
           signal?.removeEventListener('abort', onAbort);
-          resolve();
+          resolve(wasReserved);
         };
         const onAbort = () => {
           const idx = this.waiters.indexOf(onResolve);
@@ -235,21 +322,17 @@ class Semaphore {
         signal?.addEventListener('abort', onAbort, { once: true });
       });
       if (signal?.aborted) {
+        // A release may have handed this waiter capacity immediately before
+        // cancellation became observable. Return that handoff so it cannot
+        // leak or strand the next queued call.
+        if (reserved) this.leased().release();
         throw signal.reason instanceof Error
           ? signal.reason
           : new Error('Slot acquire aborted.');
       }
+      if (reserved) return this.leased();
     }
-    this.inFlight += 1;
-    let released = false;
-    return {
-      release: () => {
-        if (released) return;
-        released = true;
-        this.inFlight = Math.max(0, this.inFlight - 1);
-        this.waiters.shift()?.();
-      },
-    };
+    return this.lease();
   }
 }
 
@@ -322,6 +405,63 @@ export function createPlayExecutionGovernor(
 
   const orgBucket = (provider: string) => `${input.scope.orgId}:${provider}`;
 
+  /** The tool's local semaphore for a declared `maxConcurrency`, else null. */
+  const providerConcurrencySlotsFor = (
+    toolId: string,
+    rules: readonly PacingRule[],
+  ): Semaphore | null => {
+    const declaredMaxConcurrency = Math.min(
+      ...rules.flatMap((rule) =>
+        rule.maxConcurrency != null ? [rule.maxConcurrency] : [],
+      ),
+    );
+    if (!Number.isFinite(declaredMaxConcurrency)) return null;
+    let slots = providerConcurrencySlotsByTool.get(toolId);
+    if (!slots) {
+      slots = new Semaphore(Math.max(1, declaredMaxConcurrency));
+      providerConcurrencySlotsByTool.set(toolId, slots);
+    }
+    return slots;
+  };
+
+  const providerPermitFrom = (
+    provider: string,
+    rateLease: PacingPermit,
+    localConcurrencySlot: WorkLease | null,
+  ): ProviderPermit => {
+    let settled = false;
+    return {
+      provider,
+      concurrencyGrant: rateLease.concurrencyGrant ?? null,
+      pacingGrant: rateLease.pacingGrant ?? null,
+      release() {
+        if (settled) return;
+        settled = true;
+        rateLease.release();
+        localConcurrencySlot?.release();
+      },
+      async cancel() {
+        if (settled) return;
+        settled = true;
+        try {
+          await rateLease.cancel();
+        } finally {
+          localConcurrencySlot?.release();
+        }
+      },
+      async park() {
+        if (settled) return;
+        settled = true;
+        try {
+          if (rateLease.park) await rateLease.park();
+          else await rateLease.cancel();
+        } finally {
+          localConcurrencySlot?.release();
+        }
+      },
+    };
+  };
+
   async function resolveScope(toolId: string, provider: string) {
     const resolved = await input.resolveRateScope?.(toolId, provider);
     const scope = [
@@ -427,8 +567,17 @@ export function createPlayExecutionGovernor(
     policy,
 
     acquireRowSlot: (opts) => rowSlots.acquire(opts?.signal),
+    async acquireToolExecutionSlot(opts) {
+      return await toolSlots.acquire(opts?.signal);
+    },
+
+    tryAcquireToolExecutionSlot: () => toolSlots.tryAcquire(),
+
+    tryAcquireIntegrationRequestSlot: () =>
+      integrationRequestSlots.tryAcquire(),
+
     async acquireToolSlot(_toolId, opts) {
-      const slot = await toolSlots.acquire(opts?.signal);
+      const slot = await governor.acquireToolExecutionSlot(opts);
       // Charge the logical call only after its local execution slot is held, so
       // a failed/aborted slot acquisition never consumes the budget. The
       // physical provider admission is intentionally deferred to
@@ -461,15 +610,12 @@ export function createPlayExecutionGovernor(
           rule.maxConcurrency != null ? [rule.maxConcurrency] : [],
         ),
       );
-      const localConcurrencySlot = Number.isFinite(declaredMaxConcurrency)
-        ? await (() => {
-            let slots = providerConcurrencySlotsByTool.get(toolId);
-            if (!slots) {
-              slots = new Semaphore(Math.max(1, declaredMaxConcurrency));
-              providerConcurrencySlotsByTool.set(toolId, slots);
-            }
-            return slots.acquire(opts?.signal);
-          })()
+      const localConcurrencySlots = providerConcurrencySlotsFor(
+        toolId,
+        pacing.rules,
+      );
+      const localConcurrencySlot = localConcurrencySlots
+        ? await localConcurrencySlots.acquire(opts?.signal)
         : null;
       try {
         const rateLease = await input.rateState.acquire({
@@ -478,18 +624,38 @@ export function createPlayExecutionGovernor(
           rules: pacing.rules,
           signal: opts?.signal,
         });
-        return {
-          release() {
-            rateLease.release();
-            localConcurrencySlot?.release();
-          },
-        };
+        return providerPermitFrom(pacing.provider, rateLease, localConcurrencySlot);
       } catch (error) {
         localConcurrencySlot?.release();
         throw error;
       }
     },
 
+    tryAcquireProviderPermit(toolId) {
+      const tryAcquire = input.rateState.tryAcquire;
+      const provider = providerByTool.get(toolId);
+      const rules = pacingRulesByTool.get(toolId);
+      const rateScope = scopeByTool.get(toolId);
+      if (!tryAcquire || !provider || !rules || !rateScope) return null;
+      const localConcurrencySlots = providerConcurrencySlotsFor(toolId, rules);
+      const localConcurrencySlot = localConcurrencySlots
+        ? localConcurrencySlots.tryAcquire()
+        : null;
+      if (localConcurrencySlots && !localConcurrencySlot) return null;
+      let rateLease: PacingPermit | null = null;
+      try {
+        rateLease = tryAcquire.call(input.rateState, {
+          bucketId: rateScope[0],
+          rateScopeToken: rateScope[1],
+          rules,
+        });
+      } finally {
+        if (!rateLease) localConcurrencySlot?.release();
+      }
+      if (!rateLease) return null;
+      return providerPermitFrom(provider, rateLease, localConcurrencySlot);
+    },
+
     async suggestedParallelism(toolId, fallback) {
       const pacing = await resolveAdaptivePacing(toolId);
       const concurrencyLimits = pacing.rules.flatMap((rule) =>
@@ -556,10 +722,16 @@ export function createPlayExecutionGovernor(
         });
       }
       const rateScope = scopeFor(bp.toolId, bp.provider);
+      const rules = bp.toolId ? pacingRulesByTool.get(bp.toolId) : undefined;
       await input.rateState.penalize({
         bucketId: rateScope[0],
         ...(rateScope[1] ? { rateScopeToken: rateScope[1] } : {}),
         cooldownMs: bp.retryAfterMs,
+        ...(rules ? { rules } : {}),
+        ...(bp.latencyMs != null ? { latencyMs: bp.latencyMs } : {}),
+        ...(bp.concurrencyGrant
+          ? { concurrencyGrant: bp.concurrencyGrant }
+          : {}),
       });
     },
 
@@ -572,6 +744,7 @@ export function createPlayExecutionGovernor(
         input.rateState.observeSuccess?.({
           bucketId: rateScope[0],
           rules,
+          latencyMs: success.latencyMs,
         });
         return;
       }
@@ -651,10 +824,15 @@ function createInlineChildGovernor(
     policy: root.policy,
     acquireRowSlot: (opts) => root.acquireRowSlot(opts),
     acquireToolSlot: (toolId, opts) => root.acquireToolSlot(toolId, opts),
+    acquireToolExecutionSlot: (opts) => root.acquireToolExecutionSlot(opts),
+    tryAcquireToolExecutionSlot: () => root.tryAcquireToolExecutionSlot(),
+    tryAcquireIntegrationRequestSlot: () =>
+      root.tryAcquireIntegrationRequestSlot(),
     acquireIntegrationRequestSlot: (opts) =>
       root.acquireIntegrationRequestSlot(opts),
     acquireProviderPermit: (toolId, opts) =>
       root.acquireProviderPermit(toolId, opts),
+    tryAcquireProviderPermit: (toolId) => root.tryAcquireProviderPermit(toolId),
     suggestedParallelism: (toolId, fallback) =>
       root.suggestedParallelism(toolId, fallback),
     suggestedDirectToolParallelism: (toolId, fallback) =>

package/dist/bundling-sources/shared_libs/play-runtime/governor/in-memory-rate-state-backend.ts

@@ -3,6 +3,7 @@ import type {
   PacingRule,
   RateStateBackend,
 } from './rate-state-backend';
+import { noopPacingPermit } from './rate-state-backend';
 
 /**
  * In-memory Rate State Backend for the single-process `cjs_node20` runner.
@@ -48,7 +49,7 @@ export class InMemoryRateStateBackend implements RateStateBackend {
   }): Promise<PacingPermit> {
     const { bucketId, rules, signal } = input;
     if (rules.length === 0) {
-      return { release() {} };
+      return noopPacingPermit();
     }
     // Stable order to avoid deadlock between concurrent acquirers on shared rules.
     const ordered = [...rules].sort((a, b) => a.ruleId.localeCompare(b.ruleId));
@@ -95,23 +96,36 @@ export class InMemoryRateStateBackend implements RateStateBackend {
       });
 
       if (decision.acquired) {
-        let released = false;
+        let settled = false;
+        const releaseConcurrency = async (refundRateReservation: boolean) => {
+          await this.withLock(() => {
+            for (const rule of ordered) {
+              const state = this.ruleStates.get(
+                this.key(bucketId, rule.ruleId),
+              );
+              if (!state) continue;
+              if (refundRateReservation && state.startedInWindow > 0) {
+                state.startedInWindow -= 1;
+              }
+              if (rule.maxConcurrency != null && state.activeCount > 0) {
+                state.activeCount -= 1;
+              }
+            }
+          });
+        };
         return {
           // The concurrency decrement is intentionally not awaitable (the permit
           // signature is sync `release(): void`). It still runs serialized under
           // the lock; do not "fix" this by trying to await a void.
           release: () => {
-            if (released) return;
-            released = true;
-            void this.withLock(() => {
-              for (const rule of ordered) {
-                if (rule.maxConcurrency == null) continue;
-                const state = this.ruleStates.get(
-                  this.key(bucketId, rule.ruleId),
-                );
-                if (state && state.activeCount > 0) state.activeCount -= 1;
-              }
-            });
+            if (settled) return;
+            settled = true;
+            void releaseConcurrency(false);
+          },
+          cancel: async () => {
+            if (settled) return;
+            settled = true;
+            await releaseConcurrency(true);
           },
         };
       }

package/dist/bundling-sources/shared_libs/play-runtime/governor/policy.ts

@@ -92,6 +92,14 @@ export const MAX_CONFIGURABLE_CONCURRENT_ROWS = 1_000;
 // available to long-residence providers while still bounding live calls.
 export const DEFAULT_MAX_IN_FLIGHT_TOOL_DISPATCH_GROUPS =
   MAX_CONFIGURABLE_CONCURRENT_EXTERNAL_CALLS;
+// One lane is one tool (or one batch bucket). Its in-flight groups are not
+// capped below the run-wide envelope: a group counts as in flight until its
+// slowest call returns, so with provider tails of 8-40 s a small per-lane
+// cap pinned every slot on nearly finished groups and left ~20 calls on the
+// wire per shape. Coalescing under saturation is handled by the round-trip
+// adaptive window in the dispatcher instead.
+export const DEFAULT_MAX_IN_FLIGHT_TOOL_DISPATCH_GROUPS_PER_LANE =
+  DEFAULT_MAX_IN_FLIGHT_TOOL_DISPATCH_GROUPS;
 // Launches persisted before this field existed used the original fixed
 // eight-slot policy. Preserve that value on their retries and resumes.
 export const LEGACY_MAX_CONCURRENT_EXTERNAL_CALLS = 8;
@@ -153,18 +161,23 @@ export const SHARED_EXECUTION_POLICY: ResolvedExecutionPolicy = {
     // Runs may request a value through the validated 1..1000 launch contract;
     // provider pacing and the runner-owned hard ceiling still apply.
     toolCalls: DEFAULT_MAX_CONCURRENT_EXTERNAL_CALLS,
-    // Physical runtime-to-app fetch/body admission. Keep short socket bursts
-    // below the sandbox/Vercel transport cliff while allowing many more logical
-    // calls to remain resident. This is deliberately independent of provider
-    // rate limits: it protects Deepline's own transport edge.
-    integrationRequests: 64,
+    // Physical runtime-to-app fetch/body admission. This is deliberately
+    // independent of provider rate limits: it protects Deepline's own
+    // transport edge. Measured at 1k rows on a warm production-shape preview
+    // estate: 256 here with a 1,024-request proxy limit took kareem from
+    // 8.7 to 11.2 rows/s and modal from 6.9 to 9.4; at 64 sockets 700-1,000
+    // resident calls waited seconds for a socket while the sandbox idled.
+    // Only a cold estate (replay samples fetched per call until cached)
+    // queues badly at this width, and that is a warm-up concern, not a cap.
+    integrationRequests: 256,
     // Scheduling cohorts overlap provider-response tails, but each cohort may
     // itself contain many logical calls. Keep this materially above the legacy
     // eight-group ceiling without creating one independently flushed cohort
     // per configured tool slot. The latter fragments batchable providers and
     // adds receipt/gateway round trips under wide (128+) runs.
     toolDispatchGroups: DEFAULT_MAX_IN_FLIGHT_TOOL_DISPATCH_GROUPS,
-    toolDispatchGroupsPerLane: DEFAULT_MAX_IN_FLIGHT_TOOL_DISPATCH_GROUPS,
+    toolDispatchGroupsPerLane:
+      DEFAULT_MAX_IN_FLIGHT_TOOL_DISPATCH_GROUPS_PER_LANE,
   },
   budgets: {
     // Runaway guards, not workload limits. A 5,000-row map calling several tools

package/dist/bundling-sources/shared_libs/play-runtime/governor/rate-state-backend.ts

@@ -30,6 +30,24 @@ export interface PacingRule {
   readonly maxConcurrency: number | null;
 }
 
+/**
+ * Effective shared rate captured when a physical request was admitted. It is
+ * read-only diagnostic context: callers cannot widen a provider limit.
+ */
+export type ProviderPacingGrant = {
+  readonly targetRequestsPerSecond: number | null;
+};
+
+/**
+ * Global occupancy and RTT baseline captured with one concurrency permit.
+ * Pure-rate permits publish only {@link ProviderPacingGrant}.
+ */
+export type ProviderConcurrencyGrant = ProviderPacingGrant & {
+  readonly admissionId: string;
+  readonly inFlightAtStart: number;
+  readonly minimumRttMs: number | null;
+};
+
 /**
  * Per-tool queue-hint metadata produced by the runtime tool catalog
  * (`packages/integrations/runtime-tool-metadata.ts`) and surfaced to the runtime via
@@ -49,9 +67,26 @@ export interface PlayQueueHint {
   maxConcurrency: number | null;
 }
 
-/** Handle returned by acquire(); release frees any concurrency held by the rules. */
+/** Handle returned by acquire(). */
 export interface PacingPermit {
+  /** Complete a dispatched request; frees only any concurrency held by the rules. */
   release(): void;
+  /**
+   * Cancel a ticket that never reached the provider. Unlike `release`, this
+   * returns its rate reservation before freeing any held concurrency.
+   */
+  cancel(): Promise<void>;
+  /**
+   * Return a due ticket that never reached the provider to the backend's local
+   * lease block, so the next acquire on the same lane draws it with no store
+   * round trip. Falls back to `cancel` when that block is gone or expired.
+   * Absent on backends that keep no local block; callers use `cancel` then.
+   */
+  park?(): Promise<void>;
+  /** Server-authored context for attributing this request's provider 429. */
+  readonly concurrencyGrant?: ProviderConcurrencyGrant | null;
+  /** Effective shared rate for every app-runtime provider permit. */
+  readonly pacingGrant?: ProviderPacingGrant | null;
 }
 
 /**
@@ -85,6 +120,18 @@ export interface RateStateBackend {
     signal?: AbortSignal;
   }): Promise<PacingPermit>;
 
+  /**
+   * Take a permit for `bucketId` only if one is already due in local state.
+   * Synchronous and non-blocking: never refills, sleeps, or reaches the store.
+   * Returns null when no due permit is held locally, when the pacer is
+   * holding the provider off, or when the backend keeps no local state.
+   */
+  tryAcquire?(input: {
+    bucketId: string;
+    rateScopeToken?: string | null;
+    rules: readonly PacingRule[];
+  }): PacingPermit | null;
+
   /**
    * Feed a server-observed Retry-After back so future acquires for this bucket
    * back off. Advisory and idempotent; never un-charges an in-flight call.
@@ -93,6 +140,12 @@ export interface RateStateBackend {
     bucketId: string;
     rateScopeToken?: string | null;
     cooldownMs: number;
+    /** Resolved provider rules for the rejected physical attempt. */
+    rules?: readonly PacingRule[];
+    /** Provider residence measured at the HTTP boundary. */
+    latencyMs?: number | null;
+    /** Server-authored context for attributing this physical provider 429. */
+    concurrencyGrant?: ProviderConcurrencyGrant | null;
   }): void | Promise<void>;
 
   /** Record confirmed provider success for adaptive recovery. */
@@ -100,10 +153,16 @@ export interface RateStateBackend {
     bucketId: string;
     rateScopeToken?: string | null;
     rules: readonly PacingRule[];
+    /** Provider residence measured at the HTTP boundary. */
+    latencyMs?: number | null;
   }): void;
 }
 
-const NOOP_PERMIT: PacingPermit = { release() {} };
+const NOOP_PERMIT: PacingPermit = {
+  release() {},
+  async cancel() {},
+  async park() {},
+};
 
 /** Permit used when a bucket has no rules — nothing to debit or release. */
 export function noopPacingPermit(): PacingPermit {

package/dist/bundling-sources/shared_libs/play-runtime/integration-operation-reader-fence/contracts.ts

@@ -12,6 +12,22 @@ export type IntegrationOperationStorageMode =
 export const INTEGRATION_OPERATION_CANONICAL_READER_CAPABILITY =
   'integration-operation-canonical-v1' as const;
 
+/**
+ * A strictly stronger reader proof. A gateway that reports this capability can
+ * materialize the existing canonical Integration Operation outcome and the
+ * immutable R2 receipt-value references that may be published beside it.
+ *
+ * Keep this distinct from the original canonical capability: an already-active
+ * canonical fence may have certified an older gateway image that cannot read a
+ * receipt reference yet.
+ */
+export const RUNTIME_RECEIPT_VALUE_REFERENCE_READER_CAPABILITY =
+  'runtime-receipt-value-reference-v1' as const;
+
+export type RuntimeGatewayReaderCapability =
+  | typeof INTEGRATION_OPERATION_CANONICAL_READER_CAPABILITY
+  | typeof RUNTIME_RECEIPT_VALUE_REFERENCE_READER_CAPABILITY;
+
 export type RuntimeGatewayRole = 'receipt' | 'execution';
 
 /**
@@ -20,7 +36,7 @@ export type RuntimeGatewayRole = 'receipt' | 'execution';
  * collects this evidence; this module records and validates its shape.
  */
 export type CanonicalReaderProof = {
-  capability: typeof INTEGRATION_OPERATION_CANONICAL_READER_CAPABILITY;
+  capability: RuntimeGatewayReaderCapability;
   sourceSha: string;
   machineIds: Readonly<Record<RuntimeGatewayRole, readonly string[]>>;
 };
@@ -47,6 +63,18 @@ export type ReaderFenceWriterMode = {
   failure?: 'store_unavailable' | 'invalid_record';
 };
 
+/**
+ * The additional format is write-enabled only after the stronger, exact-fleet
+ * proof reaches the durable mirror. A missing or unreadable mirror stays
+ * inline, which is compatible with every prior gateway image.
+ */
+export type RuntimeReceiptValueReferenceWriterMode = {
+  enabled: boolean;
+  source: 'fence' | 'absent' | 'fail_closed';
+  epoch: number | null;
+  failure?: 'store_unavailable' | 'invalid_record';
+};
+
 export type ReaderFenceApplyOutcome =
   | { kind: 'advanced'; fence: RuntimeGatewayReaderFence }
   | { kind: 'already_applied'; fence: RuntimeGatewayReaderFence }
@@ -59,6 +87,10 @@ export type ReaderFenceApplyOutcome =
 export type RuntimeGatewayReaderFenceJob = {
   /** Resolve the only format this gateway may write. Never returns canonical on uncertainty. */
   writerMode(input: { schema: string }): Promise<ReaderFenceWriterMode>;
+  /** Resolve whether this gateway may publish receipt value references. */
+  runtimeReceiptValueReferenceWriterMode(input: {
+    schema: string;
+  }): Promise<RuntimeReceiptValueReferenceWriterMode>;
   /** Advance the mirror only with a strictly newer epoch, or retry the exact same fence. */
   apply(
     candidate: RuntimeGatewayReaderFenceCandidate,