deepline 0.3.128 → 0.3.129

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

@@ -1,27 +1,346 @@
+import type { RuntimeMapHeapAdmissionSnapshot } from './map-memory-limits';
+import type {
+  RuntimeMemoryLedger,
+  RuntimeMemoryLedgerSnapshot,
+} from './memory-ledger';
 import type {
   PlayExecutionGovernor,
+  ProviderPermit,
   WorkLease,
 } from './governor/governor';
+import type {
+  ProviderConcurrencyGrant,
+  ProviderPacingGrant,
+} from './governor/rate-state-backend';
+import type { ExecuteServerTiming } from './execute-server-timing';
 
 export type RuntimeResourceLease = WorkLease;
+export type RuntimeProviderPermit = ProviderPermit;
 
 export type RuntimeResourceObservation = {
   toolId?: string | null;
   providerResourceKey?: string | null;
+  /**
+   * Canonical pacing-provider bucket for fixture/report attribution. This is
+   * intentionally separate from `providerResourceKey`: the latter retains
+   * the tool-keyed physical-request facts that provenance-disabled fixtures
+   * need, while this joins admission and response residence under the bucket
+   * the shared controller actually permitted.
+   */
+  providerTelemetryKey?: string | null;
+  /**
+   * Read-only shared-controller state captured with the permit that admitted
+   * this physical request. Observation never adjusts rate or concurrency.
+   */
+  providerConcurrencyGrant?: ProviderConcurrencyGrant | null;
+  /** Effective shared-rate reading for every provider permit. */
+  providerPacingGrant?: ProviderPacingGrant | null;
+  /**
+   * Physical provider work already resident in this runtime when this request
+   * crossed the dispatch boundary. This is a bounded, run-local diagnostic;
+   * it never participates in provider admission or controller decisions.
+   */
+  providerRunInFlightAtDispatch?: number | null;
   rowEstimatedBytes?: number | null;
   rowAdmissionWaitMs?: number | null;
   toolAdmissionWaitMs?: number | null;
+  providerAdmissionWaitMs?: number | null;
+  externalExecutionWaitMs?: number | null;
   providerLatencyMs?: number | null;
+  /** Wait for the runner-to-app transport slot inside provider residence. */
+  transportSlotWaitMs?: number | null;
+  /** Fetch dispatch to response headers. */
+  fetchToHeadersMs?: number | null;
+  /** The execute route's own `Server-Timing` account of that same request. */
+  executeServerTiming?: ExecuteServerTiming | null;
+  /** Response headers to a fully read and parsed body. */
+  bodyReadMs?: number | null;
+  /** Sandbox-side simulated provider residence in fixture mode. */
+  fixtureDelayMs?: number | null;
   providerSuccess?: boolean;
   provider429?: boolean;
+  /**
+   * A Deepline relay/gateway concurrency shed (429 with the concurrency
+   * backpressure marker). Counted apart from provider 429s and never fed to
+   * provider pacing: the shed is our own admission, not the provider's.
+   */
+  concurrencyShedDelayMs?: number | null;
   retryAfterMs?: number | null;
   receiptLatencyMs?: number | null;
+  /** Per-dispatch-group receipt get+claim round trips in the hydration turn. */
+  receiptClaimMs?: number | null;
+  /**
+   * What a hydration turn queued for a slot on the bounded completed-receipt
+   * hydration lane, before the claim round trip inside the turn started
+   * counting. Observed once per call the turn is blocking, and an explicit
+   * zero for a turn that found the lane free, so the population is every call
+   * that took a turn rather than only the ones that queued.
+   */
+  receiptHydrationGateWaitMs?: number | null;
+  /**
+   * Time a provider response body waited for byte headroom before it was read.
+   * Headers have already arrived, so this is not provider residence.
+   */
+  providerBodyAdmissionWaitMs?: number | null;
+  /**
+   * A queued tool call's enqueue to the launch of the dispatch group that
+   * carries it: coalescing window, group and lane caps, and dispatcher passes.
+   */
+  dispatchQueueWaitMs?: number | null;
+  /**
+   * Wall inside one map row between a tool call's result reaching the resolver
+   * and that resolver's next enqueue — or the resolver returning. This is the
+   * row's own time: user code, cell serialization, checkpoint work.
+   */
+  rowResolverGapMs?: number | null;
+  /** One logical tool call's enqueue to its result delivery. */
+  toolCallLogicalWallMs?: number | null;
+  /**
+   * One provider call's fully read and parsed response body to the moment that
+   * call's result is handed back to the row that asked for it: receipt
+   * completion, result wrapping, and whatever the dispatcher does in between.
+   * Recorded only for a call that made a provider request — a cache hit and a
+   * follower deliver a body they never read.
+   */
+  resultDeliveryMs?: number | null;
+  /**
+   * Sub-phases of `resultDelivery`, in the order one call walks them. With
+   * `receiptCompletionQueue` and `receiptCompletionFlight` between them they
+   * partition the delivery interval, so a delivery nobody can explain is a
+   * named gap between two of these rather than an unmeasured whole.
+   *
+   * All five are observed ONCE PER CALL, for exactly the calls `resultDelivery`
+   * is observed for. A stage a given path does not have is recorded as an
+   * explicit `0` at the point where it would otherwise close — an always-fresh
+   * call has no receipt to publish, so its publication stages are zero rather
+   * than absent. A zero therefore means "this stage is not on this path", and a
+   * missing observation would mean the per-call means were taken over different
+   * populations and could not be summed against the whole.
+   *
+   * `deliveryWrap`: parsed provider body to the wrapped result existing —
+   * result metadata lookup, dataset attach, and the rest of what the module
+   * dispatcher does before it hands the result to its Tool Call job.
+   */
+  deliveryWrapMs?: number | null;
+  /**
+   * Wrapped result to this call's completion reaching the completion writer:
+   * the Tool Call job's return path, and then either the cohort's one-turn
+   * publication coalescing or — off the cohort, for a fenced, uncacheable, or
+   * natively batched call — the resolve site's own re-wrap and completion
+   * serialization. Every receipt-backed path measures it; only a call with no
+   * receipt at all records the explicit zero.
+   */
+  deliveryPublishWaitMs?: number | null;
+  /**
+   * This call's own receipt write settling to the row's pending tool call
+   * resolving: cohort group resolution or per-member presentation, and the
+   * resolver hand-back. Taken from the per-receipt settlement, never from the
+   * batch that carried it — a row waits for its own receipt to be durable.
+   */
+  deliveryResolveMs?: number | null;
+  /**
+   * Sub-phases of `receiptCompletionFlight`, which is otherwise one opaque
+   * batch launch to response. `flightSerialize` is the batch's pre-transport
+   * work — the queue and egress accounting, completion validation, and wire
+   * record construction; `flightTransport` is the completion request itself,
+   * request body through parsed response, measured on completion requests only
+   * rather than borrowed from `gatewayRoundTrip`, which every runtime API
+   * action shares; and `flightDecode` is everything after it, including a
+   * `reconcileIncomplete` durable read-back.
+   *
+   * Like `receiptCompletionFlight` itself, each is recorded once per RECEIPT in
+   * the batch rather than once per coalesced statement: every receipt inherits
+   * the flight of the batch that carried it, so these stay per-call phases
+   * comparable with the rest of the delivery partition.
+   */
+  flightSerializeMs?: number | null;
+  flightTransportMs?: number | null;
+  flightDecodeMs?: number | null;
+  /** Receipt gateway `Server-Timing` entries for one runtime API response. */
+  gatewayAuthLaunchMs?: number | null;
+  gatewayAuthVerifyMs?: number | null;
+  gatewayBodyParseMs?: number | null;
+  /** Gunzip of a compressed request body, inside `gatewayBodyParseMs`. */
+  gatewayBodyInflateMs?: number | null;
+  gatewayPoolWaitMs?: number | null;
+  /** Inside gatewayCallback: bounded R2 receipt-value persistence wall. */
+  gatewayReceiptValuePersistMs?: number | null;
+  gatewayCallbackMs?: number | null;
+  /** Client-measured wall of that same request, for the client/server split. */
+  gatewayRoundTripMs?: number | null;
+  /** Runner CPU-path wall before the request starts: JSON serialization once. */
+  gatewayRequestSerializeMs?: number | null;
+  /** Runner CPU-path wall before the request starts: request wire packing. */
+  gatewayRequestPackMs?: number | null;
+  /** The gateway's own account of its auth-session cache for that request. */
+  gatewayAuthSession?: 'hit' | 'miss' | 'coalesced' | 'unknown' | null;
+  /**
+   * Request body bytes for one runtime API request: what was serialized, and
+   * what actually went on the wire. Recorded for EVERY request, compressed or
+   * not, so the run-level ratio is taken over the whole population rather than
+   * the flattering subset. On a sandbox ~95 ms from the gateway it is the WIRE
+   * size, not the decoded size, that sets how many congestion-window round
+   * trips a request costs.
+   */
+  gatewayRequestRawBytes?: number | null;
+  gatewayRequestWireBytes?: number | null;
+  /** Completion enqueue to the launch of the batch that carries it. */
+  receiptCompletionQueueMs?: number | null;
+  /**
+   * Completion batch launch to its gateway response, recorded once per RECEIPT
+   * in that batch. Once per statement made it a mean over a different
+   * population than the per-call phases it partitions with, which on a 1000-row
+   * modal shape left most of `resultDelivery` owned by nothing.
+   */
+  receiptCompletionFlightMs?: number | null;
+  /**
+   * Completion responses that returned no stored receipt and had to be
+   * hydrated by a durable-store read-back.
+   */
+  receiptCompletionReadBacks?: number | null;
+  /** Wall for one batched durable receipt read-back after a compact ack. */
+  receiptCompletionReadBackMs?: number | null;
+  /** Compact `persisted` acknowledgements that reused the caller's live value. */
+  receiptCompletionLiveResultReuses?: number | null;
+  /** Cache-cohort completions that retained their already-live result. */
+  receiptCompletionLivePublicationResults?: number | null;
+  /** Compact `existing` acknowledgements naming an already-durable winner. */
+  receiptCompletionExistingWinners?: number | null;
+  /** Compact terminal acknowledgements from a gateway without a disposition. */
+  receiptCompletionLegacyAcknowledgements?: number | null;
+  /** Missing or malformed completion acknowledgement entries. */
+  receiptCompletionMissingAcknowledgements?: number | null;
+  /** A completion acknowledgement that was not terminal. */
+  receiptCompletionNonterminalAcknowledgements?: number | null;
+  /** Read-back entries that recovered a complete durable output. */
+  receiptCompletionReadBackRecovered?: number | null;
+  /** Read-back entries that still did not yield a complete durable output. */
+  receiptCompletionReadBackMissing?: number | null;
+  receiptEgressBatchSize?: number | null;
+  receiptEgressBytes?: number | null;
+  /** Bounded completion-writer state sampled at each state transition. */
+  receiptCompletionWriterInFlightBatches?: number | null;
+  receiptCompletionWriterQueued?: number | null;
+  receiptCompletionWriterBufferedItems?: number | null;
+  receiptCompletionWriterBufferedBytes?: number | null;
   sheetFlushLatencyMs?: number | null;
   sheetFlushBytes?: number | null;
-  memoryBytes?: number | null;
 };
 
 export type RuntimeResourceSnapshot = {
+  /**
+   * Selected execute-route stages across every physical request that published
+   * the complete timing header. Kept once per run so mixed-provider fixtures
+   * cannot overflow the terminal metadata envelope.
+   */
+  executeRoute?: RuntimeExecuteRouteTiming;
+  phases: {
+    rowAdmission: RuntimePhaseDistribution;
+    providerAdmission: RuntimePhaseDistribution;
+    externalExecution: RuntimePhaseDistribution;
+    providerResidence: RuntimePhaseDistribution;
+    /**
+     * Sub-phases of providerResidence, so a slow call can be attributed:
+     * residence = fixtureDelay + transportSlotWait + fetchToHeaders + bodyRead
+     * + an unattributed remainder.
+     */
+    fixtureDelay: RuntimePhaseDistribution;
+    transportSlotWait: RuntimePhaseDistribution;
+    fetchToHeaders: RuntimePhaseDistribution;
+    bodyRead: RuntimePhaseDistribution;
+    /** Sampled setTimeout lateness, not a per-call phase. */
+    eventLoopLag: RuntimePhaseDistribution;
+    receiptSettlement: RuntimePhaseDistribution;
+    /**
+     * Sub-phases of receipt orchestration, which `receiptSettlement` alone
+     * cannot separate: the claim turn before provider work, the completion's
+     * wait for a batch, and that batch's own flight.
+     */
+    receiptClaim: RuntimePhaseDistribution;
+    /**
+     * The queue in front of `receiptClaim`. A bounded lane serializes
+     * completed-receipt payload expansion, so a shape whose receipts are large
+     * keeps the lane busy and its dispatch groups wait for a slot before their
+     * claim can start. That wall sits inside `toolCallLogicalWall` after
+     * `dispatchQueueWait` and before any provider work, and no other phase
+     * covers it, so a logical wall that residence and delivery cannot explain
+     * is read against this phase first.
+     *
+     * Charged to each call in the group whose turn it is — like
+     * `receiptCompletionFlight`, and unlike `receiptClaim`, which is recorded
+     * once per turn — so its per-call mean is over the same population as the
+     * wall it is subtracted from. The per-map `receipt_hydration_gate` log
+     * line still reports the turn-level view (turns, queued turns, and the
+     * lane's own total wait).
+     */
+    receiptHydrationGateWait: RuntimePhaseDistribution;
+    receiptCompletionQueue: RuntimePhaseDistribution;
+    receiptCompletionFlight: RuntimePhaseDistribution;
+    /** One durable read-back batch after a compact completion acknowledgement. */
+    receiptCompletionReadBack: RuntimePhaseDistribution;
+    rowPersistence: RuntimePhaseDistribution;
+    /**
+     * The three phases that account for a row's life OUTSIDE the per-call
+     * phases above. A modal shape whose measured per-call phases sum to a
+     * quarter of the wall a row spends per call is spending the rest either
+     * queued for a dispatch group (`dispatchQueueWait`) or inside its own
+     * resolver between calls (`rowResolverGap`); `toolCallLogicalWall` is the
+     * enqueue-to-delivery total those two must be checked against.
+     */
+    dispatchQueueWait: RuntimePhaseDistribution;
+    rowResolverGap: RuntimePhaseDistribution;
+    toolCallLogicalWall: RuntimePhaseDistribution;
+    /**
+     * The tail of `toolCallLogicalWall`: parsed provider body to the row's own
+     * result. `providerResidence` ends where this begins, so a logical wall
+     * that neither residence nor `dispatchQueueWait` explains is being spent
+     * here — receipt completion and delivery — rather than on the provider.
+     */
+    resultDelivery: RuntimePhaseDistribution;
+    /**
+     * The partition of `resultDelivery`, in call order:
+     * `deliveryWrap` + `deliveryPublishWait` + `receiptCompletionQueue` +
+     * `receiptCompletionFlight` + `deliveryResolve` = `resultDelivery`, and
+     * `flightSerialize` + `flightTransport` + `flightDecode` =
+     * `receiptCompletionFlight`. Every one of them is recorded for exactly the
+     * calls `resultDelivery` is — one that read a provider body of its own —
+     * counting the same population at the same per-call granularity: the
+     * publication phases are an explicit zero on a path without a receipt
+     * (always-fresh), they are measured at the resolve site on a receipt-backed
+     * path that does not reach the receipt cohort (fenced, uncacheable, or
+     * natively batched), and the flight and its three parts are recorded once
+     * per receipt rather than once per coalesced completion statement. The
+     * counts are therefore comparable on any shape, and a difference between
+     * the sum and the whole is a real gap rather than a sampling artifact.
+     */
+    deliveryWrap: RuntimePhaseDistribution;
+    deliveryPublishWait: RuntimePhaseDistribution;
+    deliveryResolve: RuntimePhaseDistribution;
+    flightSerialize: RuntimePhaseDistribution;
+    flightTransport: RuntimePhaseDistribution;
+    flightDecode: RuntimePhaseDistribution;
+    /**
+     * The receipt gateway's own `Server-Timing` account of a runtime API
+     * request, beside the client-measured wall of the same request
+     * (`gatewayRoundTrip`). The gateway's action duration starts AFTER
+     * authentication, so its logs cannot see `gatewayAuthLaunch`,
+     * `gatewayAuthVerify`, or `gatewayBodyParse`; a round trip far above the
+     * server-reported sum is network, and one that matches it is the gateway.
+     */
+    gatewayAuthLaunch: RuntimePhaseDistribution;
+    gatewayAuthVerify: RuntimePhaseDistribution;
+    gatewayBodyParse: RuntimePhaseDistribution;
+    /** Inside `gatewayBodyParse`, not beside it. Zero on uncompressed requests. */
+    gatewayBodyInflate: RuntimePhaseDistribution;
+    gatewayPoolWait: RuntimePhaseDistribution;
+    /** Inside `gatewayCallback`, never add it beside that total. */
+    gatewayReceiptValuePersist: RuntimePhaseDistribution;
+    gatewayCallback: RuntimePhaseDistribution;
+    gatewayRoundTrip: RuntimePhaseDistribution;
+    /** Runner-local work deliberately excluded from `gatewayRoundTrip`. */
+    gatewayRequestSerialize: RuntimePhaseDistribution;
+    gatewayRequestPack: RuntimePhaseDistribution;
+  };
   rows: {
     acquired: number;
     estimatedBytes: number;
@@ -36,16 +355,334 @@ export type RuntimeResourceSnapshot = {
     bytes: number;
     latencyMsEwma: number | null;
   };
+  resultEgress: {
+    batches: number;
+    receipts: number;
+    bytes: number;
+    maxBatchBytes: number | null;
+    /** High-water marks of the bounded completion writer for this run. */
+    writerPeakInFlightBatches: number;
+    writerPeakQueued: number;
+    writerPeakBufferedItems: number;
+    writerPeakBufferedBytes: number;
+    /**
+     * Receipts whose completion response carried no stored receipt and were
+     * hydrated by a second full read of the durable store.
+     */
+    readBacks: number;
+    /** Compact acknowledgements where this caller could reuse the live value. */
+    liveResultReuses: number;
+    /** Publish-only cache cohorts that retained their already-live value. */
+    livePublicationResults: number;
+    /** Compact acknowledgements naming an already-durable winner. */
+    existingWinners: number;
+    /** Compact acknowledgements from an older gateway without a disposition. */
+    legacyAcknowledgements: number;
+    /** Completion response entries that were absent or malformed. */
+    missingAcknowledgements: number;
+    /** Completion response entries that did not reach a terminal state. */
+    nonterminalAcknowledgements: number;
+    /** Read-back entries that did recover a complete durable output. */
+    readBackRecovered: number;
+    /** Read-back entries still missing a complete durable output. */
+    readBackMissing: number;
+  };
+  /** Relay concurrency sheds the runner paced on instead of failing rows. */
+  concurrencyShed: {
+    count: number;
+    delayMsEwma: number | null;
+  };
+  /**
+   * What the receipt gateway reported about itself, counted rather than timed.
+   * A miss rate near one means every runtime API request paid a fresh token
+   * verification, which the gateway's own action logs do not show.
+   */
+  gateway: {
+    authSession: {
+      hit: number;
+      miss: number;
+      coalesced: number;
+      unknown: number;
+    };
+    /**
+     * What the runtime API transport put on the wire across the run.
+     *
+     * `wireBytes / rawBytes` is the realized compression ratio, over every
+     * request rather than only the compressed ones. `count` is the denominator
+     * for both, so a readout can also state mean request size — the number the
+     * ~95 ms round trip is multiplied by.
+     */
+    requestBody: {
+      count: number;
+      rawBytes: number;
+      wireBytes: number;
+    };
+  };
   providers: Record<
     string,
     {
+      admission: RuntimePhaseTiming;
+      residence: RuntimePhaseTiming;
+      fetchToHeaders: RuntimePhaseTiming;
+      latencyMsEwma: number | null;
+      retryAfterMsEwma: number | null;
+      provider429Count: number;
+    }
+  >;
+  /**
+   * Capped, canonical-provider attribution. Unlike `providers`, each entry
+   * joins permit wait and provider residence for one controller bucket, so a
+   * fixture readout can show where external response time went without
+   * conflating an admission key with a tool id.
+   */
+  providerAttribution: Record<
+    string,
+    {
+      admission: RuntimePhaseTiming;
+      residence: RuntimePhaseTiming;
+      fixtureDelay: RuntimePhaseTiming;
+      transportSlotWait: RuntimePhaseTiming;
+      fetchToHeaders: RuntimePhaseTiming;
+      bodyRead: RuntimePhaseTiming;
+      /** Local response-body byte-admission total in milliseconds. */
+      gateMs: number;
+      controller: {
+        /** Physical requests whose permit carried shared-controller context. */
+        permits: number;
+        /** Bucket occupancy captured before the request joined it. */
+        inFlightAtPermit: RuntimeSampleTiming;
+        /**
+         * Run-local physical provider work already resident when dispatch
+         * began. Unlike `inFlightAtPermit`, this is available to pure-rate
+         * buckets that deliberately have no shared concurrency lease.
+         */
+        runInFlightAtDispatch: RuntimeSampleTiming;
+        /** Null when the active rate backend did not publish a reading. */
+        targetRequestsPerSecondEwma: number | null;
+        minimumRttMsEwma: number | null;
+      };
       latencyMsEwma: number | null;
       retryAfterMsEwma: number | null;
       provider429Count: number;
     }
   >;
+  /**
+   * Process-level cost at snapshot time. On a 1 vCPU sandbox, cpu user+system
+   * milliseconds divided by the map wall is the runtime's own CPU floor.
+   */
+  process: {
+    cpuUserMs: number;
+    cpuSystemMs: number;
+    rssBytes: number | null;
+    maxRssBytes: number | null;
+    heapUsedBytes: number | null;
+    externalBytes: number | null;
+  } | null;
+  /** Final heap-admission state of each map, keyed by table namespace. */
+  mapAdmission: Record<string, RuntimeMapHeapAdmissionSnapshot>;
+  /**
+   * The runtime's byte ledger: what it says it is holding, how that compares
+   * to what the process reports, and how often admission had to hold. Null
+   * when no ledger is attached to this governor.
+   */
+  memory: RuntimeMemorySnapshot | null;
+};
+
+/**
+ * The ledger plus the admission counters that say how often bytes actually
+ * constrained the map. `predictedLiveBytes` diverging from `observedLiveBytes`
+ * by more than the calibration factor explains is the signal that the runtime
+ * is retaining bytes nothing registered.
+ */
+export type RuntimeMemorySnapshot = RuntimeMemoryLedgerSnapshot & {
+  /** Probes, across every map, that paused new row admission under pressure. */
+  admissionHolds: number;
+  /** Watchdog memory-pressure signals delivered to admission. */
+  externalPressureSignals: number;
+  /** Live-memory or RSS pressure episodes admission observed. */
+  memoryPressureEvents: number;
+};
+
+/** Aggregate phase timing from the runner's monotonic clock. */
+export type RuntimePhaseTiming = {
+  count: number;
+  totalMs: number;
+  maxMs: number | null;
+  ewmaMs: number | null;
+};
+
+/**
+ * Selected execute-route stages for the same population as `fetchToHeaders`.
+ * These are nested because they partition handler work inside that wall; they
+ * must never be added to provider residence as independent phases.
+ */
+export type RuntimeExecuteRouteTiming = {
+  /** Every selected stage was present for this many physical requests. */
+  count: number;
+  totalMs: number;
+  chargeOpenMs: number;
+  fixtureLoadMs: number;
+  executeMs: number;
+  /**
+   * Where `chargeOpenMs` went, nested rather than summed: these are disjoint
+   * slices of it, never independent phases. Present only when the deployed app
+   * publishes the complete substage set, so a rolling deploy cannot build this
+   * sum over a different request population than `chargeOpenMs` itself.
+   */
+  chargeOpen?: {
+    count: number;
+    eligibilityMs: number;
+    capPreflightMs: number;
+    openMutationMs: number;
+    /** Wall slept in admission retry backoff: same-org OCC contention. */
+    retryWaitMs: number;
+  };
+  /**
+   * The execution gateway's own response-path timing, nested beside the app
+   * handler rather than summed into it. `upstreamHeadersMs` contains the
+   * handler `total`, which exposes the bounded relay-to-app platform/transit
+   * residual without claiming it is all network time.
+   */
+  gateway?: {
+    count: number;
+    authLaunchMs: number;
+    authVerifyMs: number;
+    bodyParseMs: number;
+    dispatchPoolMs: number;
+    dispatchCallbackMs: number;
+    /** Relay fetch issuance -> app response headers; contains handler total. */
+    upstreamHeadersMs: number;
+    /** App headers -> relay's fully buffered upstream body. */
+    upstreamBodyMs: number;
+  };
+};
+
+/**
+ * A compact, unitless sample aggregate. Provider permits use it for bucket
+ * occupancy at admission, rather than mislabelling an in-flight count as ms.
+ */
+export type RuntimeSampleTiming = {
+  count: number;
+  total: number;
+  max: number | null;
+  ewma: number | null;
+};
+
+/**
+ * A fixture can touch many tool ids, but it should never make terminal
+ * diagnostics grow with unbounded provider cardinality. Keep the canonical
+ * attribution view useful for a multi-provider Play while rolling additional
+ * named buckets into a named remainder.
+ */
+// This record travels inside the fixed 32 KiB terminal metadata envelope.
+// Eleven named controller buckets plus `other` exactly fill the twelve rows
+// the fixture readout renders; the remainder preserves all physical work
+// without allowing a mixed-provider run to drop every runtime diagnostic.
+const MAX_PROVIDER_ATTRIBUTION_BUCKETS = 11;
+const PROVIDER_ATTRIBUTION_OTHER_KEY = 'other';
+
+/**
+ * One non-zero histogram bucket, as `[bucketIndex, count]`.
+ *
+ * Only non-zero buckets are emitted. A dense 18-entry array per phase would
+ * cost the terminal metadata record several kilobytes it does not have; a
+ * phase's durations in practice occupy a handful of adjacent buckets.
+ */
+export type RuntimePhaseHistogramBucket = [bucketIndex: number, count: number];
+
+/**
+ * A phase timing plus the shape of its durations.
+ *
+ * A mean is dragged by the tail: one 13 s stall inside a thousand 150 ms calls
+ * moves it as far as adding 13 ms to every call, and those two facts call for
+ * opposite fixes. The percentiles separate them. They are bucket-resolution
+ * estimates — the bucket that holds the rank, interpolated linearly across
+ * that bucket's width — so they place a value inside a power-of-two band and
+ * never claim millisecond accuracy. No estimate exceeds the observed `maxMs`.
+ */
+export type RuntimePhaseDistribution = RuntimePhaseTiming & {
+  p50Ms: number | null;
+  p90Ms: number | null;
+  p99Ms: number | null;
+  /** Non-zero log2 buckets, ascending, as `[bucketIndex, count]` pairs. */
+  buckets: RuntimePhaseHistogramBucket[];
 };
 
+/**
+ * The fixed log2 duration histogram every phase records into.
+ *
+ * Bucket 0 holds everything under 1 ms, bucket `i` in 1..16 holds
+ * `[2^(i-1), 2^i)` ms, and bucket 17 holds everything at or above 65,536 ms.
+ * The bounds never move with the data, so two runs' buckets are directly
+ * comparable and a readout can draw them without carrying a schema.
+ */
+export const RUNTIME_PHASE_HISTOGRAM_BUCKET_COUNT = 18;
+export const RUNTIME_PHASE_HISTOGRAM_OVERFLOW_LOWER_MS = 65_536;
+
+/** The bucket a duration in milliseconds falls in. */
+export function runtimePhaseHistogramBucketIndex(valueMs: number): number {
+  if (!(valueMs >= 1)) return 0;
+  const floored = Math.floor(valueMs);
+  if (floored >= RUNTIME_PHASE_HISTOGRAM_OVERFLOW_LOWER_MS) {
+    return RUNTIME_PHASE_HISTOGRAM_BUCKET_COUNT - 1;
+  }
+  // For a positive 32-bit integer, 32 - clz32(n) is floor(log2(n)) + 1, which
+  // is exact where Math.log2 would need a rounding argument at the bounds.
+  return 32 - Math.clz32(floored);
+}
+
+/** The half-open `[lowerMs, upperMs)` a bucket covers; the last is open-ended. */
+export function runtimePhaseHistogramBucketBoundsMs(index: number): {
+  lowerMs: number;
+  upperMs: number | null;
+} {
+  if (index <= 0) return { lowerMs: 0, upperMs: 1 };
+  if (index >= RUNTIME_PHASE_HISTOGRAM_BUCKET_COUNT - 1) {
+    return {
+      lowerMs: RUNTIME_PHASE_HISTOGRAM_OVERFLOW_LOWER_MS,
+      upperMs: null,
+    };
+  }
+  return { lowerMs: 2 ** (index - 1), upperMs: 2 ** index };
+}
+
+/**
+ * A bucket-resolution percentile estimate over a log2 histogram.
+ *
+ * Walks the buckets to the one holding rank `quantile * count`, then
+ * interpolates linearly across that bucket. The open-ended top bucket
+ * interpolates toward the observed maximum, and the estimate is capped at that
+ * maximum so a reader never sees a percentile above a value that happened.
+ */
+export function runtimePhaseHistogramPercentileMs(input: {
+  buckets: readonly number[];
+  count: number;
+  maxMs: number | null;
+  quantile: number;
+}): number | null {
+  if (input.count <= 0) return null;
+  const rank = input.quantile * input.count;
+  let cumulative = 0;
+  for (let index = 0; index < input.buckets.length; index += 1) {
+    const bucketCount = input.buckets[index] ?? 0;
+    if (bucketCount <= 0) continue;
+    if (cumulative + bucketCount < rank) {
+      cumulative += bucketCount;
+      continue;
+    }
+    const bounds = runtimePhaseHistogramBucketBoundsMs(index);
+    const upperMs =
+      bounds.upperMs ?? Math.max(bounds.lowerMs, input.maxMs ?? bounds.lowerMs);
+    const position = Math.min(
+      1,
+      Math.max(0, (rank - cumulative) / bucketCount),
+    );
+    const estimate = bounds.lowerMs + (upperMs - bounds.lowerMs) * position;
+    return input.maxMs === null ? estimate : Math.min(estimate, input.maxMs);
+  }
+  return input.maxMs;
+}
+
 export interface RuntimeResourceGovernor {
   acquireRow(input?: {
     estimatedBytes?: number | null;
@@ -58,10 +695,49 @@ export interface RuntimeResourceGovernor {
     estimatedCost?: number | null;
     signal?: AbortSignal;
   }): Promise<RuntimeResourceLease>;
+  /** Bound only the active provider execution; the caller owns its budget charge. */
+  acquireExternalExecutionSlot(input?: {
+    providerResourceKey?: string | null;
+    signal?: AbortSignal;
+  }): Promise<RuntimeResourceLease>;
+  /**
+   * Non-blocking external-capacity probe used at a due provider ticket. A
+   * caller that misses this probe must re-admit instead of dispatching late.
+   */
+  tryAcquireExternalExecutionSlot(input?: {
+    providerResourceKey?: string | null;
+  }): RuntimeResourceLease | null;
+  chargeToolCall(): Promise<void>;
   acquireProviderPermit(input: {
     toolId: string;
     signal?: AbortSignal;
-  }): Promise<RuntimeResourceLease>;
+  }): Promise<RuntimeProviderPermit>;
+  /**
+   * Non-blocking provider admission from capacity this process already holds.
+   * Safe to probe while holding an external execution slot; null means the
+   * caller must release that slot and re-admit through the blocking path.
+   */
+  tryAcquireProviderPermit(input: {
+    toolId: string;
+  }): RuntimeProviderPermit | null;
+  /**
+   * Observe one physical provider request's run-local residence. This is not
+   * a permit: it cannot block, queue, or widen capacity. Callers must release
+   * it exactly when the response body is terminal.
+   */
+  beginProviderExecution(input: {
+    providerResourceKey?: string | null;
+    providerTelemetryKey?: string | null;
+  }): {
+    providerTelemetryKey: string;
+    inFlightAtDispatch: number;
+    release(): void;
+  };
+  /**
+   * Probe app transport capacity at the physical provider-dispatch edge. A
+   * caller that misses it must cancel and re-admit its provider ticket.
+   */
+  tryAcquireIntegrationRequestSlot(): RuntimeResourceLease | null;
   suggestedToolParallelism(toolId: string, fallback: number): Promise<number>;
   suggestedDirectToolParallelism(
     toolId: string,
@@ -72,9 +748,24 @@ export interface RuntimeResourceGovernor {
     provider: string;
     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>;
   observe(input: RuntimeResourceObservation): void;
   snapshot(): RuntimeResourceSnapshot;
+  /** Stop the event-loop lag sampler. The timer is unref'd either way. */
+  stopSampling(): void;
+  /** Smoothed event-loop lag from the sampler, or null before its first tick. */
+  eventLoopLagEwmaMs(): number | null;
+  /** Retain a closed map's admission snapshot for the terminal summary. */
+  recordMapAdmission(
+    mapName: string,
+    snapshot: RuntimeMapHeapAdmissionSnapshot,
+  ): void;
+  /** The byte ledger every retention site registers against, if attached. */
+  readonly memoryLedger: RuntimeMemoryLedger | null;
 }
 
 type Ewma = {
@@ -97,10 +788,121 @@ function createEwma(alpha = 0.2): Ewma {
   };
 }
 
+function createPhaseTiming(): {
+  observe(value: number | null | undefined): void;
+  snapshot(): RuntimePhaseTiming;
+  distribution(): RuntimePhaseDistribution;
+} {
+  const ewma = createEwma();
+  const buckets = new Array<number>(RUNTIME_PHASE_HISTOGRAM_BUCKET_COUNT).fill(
+    0,
+  );
+  let count = 0;
+  let totalMs = 0;
+  let maxMs: number | null = null;
+  return {
+    observe(value) {
+      if (value == null || !Number.isFinite(value)) return;
+      const normalized = Math.max(0, value);
+      count += 1;
+      totalMs += normalized;
+      maxMs = maxMs === null ? normalized : Math.max(maxMs, normalized);
+      ewma.observe(normalized);
+      const bucket = runtimePhaseHistogramBucketIndex(normalized);
+      buckets[bucket] = (buckets[bucket] ?? 0) + 1;
+    },
+    snapshot() {
+      return { count, totalMs, maxMs, ewmaMs: ewma.value };
+    },
+    distribution() {
+      const percentile = (quantile: number) =>
+        runtimePhaseHistogramPercentileMs({
+          buckets,
+          count,
+          maxMs,
+          quantile,
+        });
+      return {
+        count,
+        totalMs,
+        maxMs,
+        ewmaMs: ewma.value,
+        p50Ms: percentile(0.5),
+        p90Ms: percentile(0.9),
+        p99Ms: percentile(0.99),
+        buckets: buckets.flatMap((bucketCount, index) =>
+          bucketCount > 0
+            ? [[index, bucketCount] as RuntimePhaseHistogramBucket]
+            : [],
+        ),
+      };
+    },
+  };
+}
+
+function createSampleTiming(): {
+  observe(value: number | null | undefined): void;
+  snapshot(): RuntimeSampleTiming;
+} {
+  const ewma = createEwma();
+  let count = 0;
+  let total = 0;
+  let max: number | null = null;
+  return {
+    observe(value) {
+      if (value == null || !Number.isFinite(value)) return;
+      const normalized = Math.max(0, value);
+      count += 1;
+      total += normalized;
+      max = max === null ? normalized : Math.max(max, normalized);
+      ewma.observe(normalized);
+    },
+    snapshot() {
+      return { count, total, max, ewma: ewma.value };
+    },
+  };
+}
+
+/** Sampling cadence for runner event-loop lateness. */
+const EVENT_LOOP_LAG_SAMPLE_INTERVAL_MS = 500;
+
 function elapsedSince(startedAt: number): number {
   return Math.max(0, Date.now() - startedAt);
 }
 
+function readProcessUsage(): RuntimeResourceSnapshot['process'] {
+  try {
+    const cpu = process.cpuUsage();
+    const memory = process.memoryUsage();
+    const resources =
+      typeof process.resourceUsage === 'function'
+        ? process.resourceUsage()
+        : null;
+    const finite = (value: unknown): number | null =>
+      typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? value
+        : null;
+    // maxRSS is reported in kibibytes on Linux and bytes on macOS; the sandbox
+    // is Linux, and the snapshot names the unit it stores.
+    const maxRssRaw = finite(resources?.maxRSS);
+    return {
+      cpuUserMs: Math.round(cpu.user / 1_000),
+      cpuSystemMs: Math.round(cpu.system / 1_000),
+      rssBytes: finite(memory.rss),
+      maxRssBytes:
+        maxRssRaw === null
+          ? null
+          : process.platform === 'darwin'
+            ? maxRssRaw
+            : maxRssRaw * 1024,
+      heapUsedBytes: finite(memory.heapUsed),
+      externalBytes: finite(memory.external),
+    };
+  } catch {
+    return null;
+  }
+}
+
 function resourceKey(input?: string | null): string {
   const trimmed = input?.trim();
   return trimmed || 'unknown';
@@ -108,13 +910,129 @@ function resourceKey(input?: string | null): string {
 
 export function createRuntimeResourceGovernor(input: {
   executionGovernor: PlayExecutionGovernor;
+  /**
+   * The runtime's byte ledger. Attached by the Play Context so the terminal
+   * summary carries what the runner was actually holding, not only what the
+   * process happened to report at snapshot time.
+   */
+  memoryLedger?: RuntimeMemoryLedger | null;
 }): RuntimeResourceGovernor {
   const rowAdmissionWait = createEwma();
   const toolAdmissionWait = createEwma();
   const sheetFlushLatency = createEwma();
+  const phases = {
+    rowAdmission: createPhaseTiming(),
+    providerAdmission: createPhaseTiming(),
+    externalExecution: createPhaseTiming(),
+    providerResidence: createPhaseTiming(),
+    fixtureDelay: createPhaseTiming(),
+    transportSlotWait: createPhaseTiming(),
+    fetchToHeaders: createPhaseTiming(),
+    bodyRead: createPhaseTiming(),
+    eventLoopLag: createPhaseTiming(),
+    receiptSettlement: createPhaseTiming(),
+    receiptClaim: createPhaseTiming(),
+    receiptHydrationGateWait: createPhaseTiming(),
+    receiptCompletionQueue: createPhaseTiming(),
+    receiptCompletionFlight: createPhaseTiming(),
+    receiptCompletionReadBack: createPhaseTiming(),
+    rowPersistence: createPhaseTiming(),
+    dispatchQueueWait: createPhaseTiming(),
+    rowResolverGap: createPhaseTiming(),
+    toolCallLogicalWall: createPhaseTiming(),
+    resultDelivery: createPhaseTiming(),
+    deliveryWrap: createPhaseTiming(),
+    deliveryPublishWait: createPhaseTiming(),
+    deliveryResolve: createPhaseTiming(),
+    flightSerialize: createPhaseTiming(),
+    flightTransport: createPhaseTiming(),
+    flightDecode: createPhaseTiming(),
+    gatewayAuthLaunch: createPhaseTiming(),
+    gatewayAuthVerify: createPhaseTiming(),
+    gatewayBodyParse: createPhaseTiming(),
+    gatewayBodyInflate: createPhaseTiming(),
+    gatewayPoolWait: createPhaseTiming(),
+    gatewayReceiptValuePersist: createPhaseTiming(),
+    gatewayCallback: createPhaseTiming(),
+    gatewayRoundTrip: createPhaseTiming(),
+    gatewayRequestSerialize: createPhaseTiming(),
+    gatewayRequestPack: createPhaseTiming(),
+  };
+  const executeRoute: RuntimeExecuteRouteTiming = {
+    count: 0,
+    totalMs: 0,
+    chargeOpenMs: 0,
+    fixtureLoadMs: 0,
+    executeMs: 0,
+  };
+  const executeChargeOpen = {
+    count: 0,
+    eligibilityMs: 0,
+    capPreflightMs: 0,
+    openMutationMs: 0,
+    retryWaitMs: 0,
+  };
+  const executeGateway = {
+    count: 0,
+    authLaunchMs: 0,
+    authVerifyMs: 0,
+    bodyParseMs: 0,
+    dispatchPoolMs: 0,
+    dispatchCallbackMs: 0,
+    upstreamHeadersMs: 0,
+    upstreamBodyMs: 0,
+  };
+  const gatewayAuthSessionCounters = {
+    hit: 0,
+    miss: 0,
+    coalesced: 0,
+    unknown: 0,
+  };
+  const gatewayRequestBodyCounters = {
+    count: 0,
+    rawBytes: 0,
+    wireBytes: 0,
+  };
   const providers = new Map<
     string,
     {
+      admission: ReturnType<typeof createPhaseTiming>;
+      residence: ReturnType<typeof createPhaseTiming>;
+      fixtureDelay: ReturnType<typeof createPhaseTiming>;
+      transportSlotWait: ReturnType<typeof createPhaseTiming>;
+      fetchToHeaders: ReturnType<typeof createPhaseTiming>;
+      bodyRead: ReturnType<typeof createPhaseTiming>;
+      bodyAdmissionWait: ReturnType<typeof createPhaseTiming>;
+      controllerPermits: number;
+      inFlightAtPermit: ReturnType<typeof createSampleTiming>;
+      targetRequestsPerSecond: Ewma;
+      minimumRttMs: Ewma;
+      latency: Ewma;
+      retryAfter: Ewma;
+      provider429Count: number;
+    }
+  >();
+  // This tracker mirrors the capped terminal attribution names. It is a
+  // measurement of work that entered provider residence, not another
+  // admission mechanism. Reservations prevent a burst of distinct providers
+  // from making the tracker grow before their terminal observations arrive.
+  const providerAttributionReservations = new Set<string>();
+  const activeProviderExecutions = new Map<string, number>();
+  const providerAttribution = new Map<
+    string,
+    {
+      admission: ReturnType<typeof createPhaseTiming>;
+      residence: ReturnType<typeof createPhaseTiming>;
+      fixtureDelay: ReturnType<typeof createPhaseTiming>;
+      transportSlotWait: ReturnType<typeof createPhaseTiming>;
+      fetchToHeaders: ReturnType<typeof createPhaseTiming>;
+      bodyRead: ReturnType<typeof createPhaseTiming>;
+      bodyAdmissionWait: ReturnType<typeof createPhaseTiming>;
+      controllerPermits: number;
+      inFlightAtPermit: ReturnType<typeof createSampleTiming>;
+      runInFlightAtDispatch: ReturnType<typeof createSampleTiming>;
+      targetRequestsPerSecond: Ewma;
+      minimumRttMs: Ewma;
       latency: Ewma;
       retryAfter: Ewma;
       provider429Count: number;
@@ -131,12 +1049,64 @@ export function createRuntimeResourceGovernor(input: {
     acquired: 0,
     bytes: 0,
   };
+  const resultEgressCounters = {
+    batches: 0,
+    receipts: 0,
+    bytes: 0,
+    maxBatchBytes: null as number | null,
+    writerPeakInFlightBatches: 0,
+    writerPeakQueued: 0,
+    writerPeakBufferedItems: 0,
+    writerPeakBufferedBytes: 0,
+    readBacks: 0,
+    liveResultReuses: 0,
+    livePublicationResults: 0,
+    existingWinners: 0,
+    legacyAcknowledgements: 0,
+    missingAcknowledgements: 0,
+    nonterminalAcknowledgements: 0,
+    readBackRecovered: 0,
+    readBackMissing: 0,
+  };
+  const concurrencyShedCounters = { count: 0 };
+  const concurrencyShedDelay = createEwma();
+  const mapAdmission: Record<string, RuntimeMapHeapAdmissionSnapshot> = {};
+
+  const readMemorySnapshot = (): RuntimeMemorySnapshot | null => {
+    const ledger = input.memoryLedger?.snapshot();
+    if (!ledger) return null;
+    let admissionHolds = 0;
+    let externalPressureSignals = 0;
+    let memoryPressureEvents = 0;
+    for (const admission of Object.values(mapAdmission)) {
+      admissionHolds += admission.admissionHolds;
+      externalPressureSignals += admission.externalPressureSignals;
+      memoryPressureEvents += admission.memoryPressureEvents;
+    }
+    return {
+      ...ledger,
+      admissionHolds,
+      externalPressureSignals,
+      memoryPressureEvents,
+    };
+  };
 
   const providerStats = (key: string) => {
     const normalized = resourceKey(key);
     let stats = providers.get(normalized);
     if (!stats) {
       stats = {
+        admission: createPhaseTiming(),
+        residence: createPhaseTiming(),
+        fixtureDelay: createPhaseTiming(),
+        transportSlotWait: createPhaseTiming(),
+        fetchToHeaders: createPhaseTiming(),
+        bodyRead: createPhaseTiming(),
+        bodyAdmissionWait: createPhaseTiming(),
+        controllerPermits: 0,
+        inFlightAtPermit: createSampleTiming(),
+        targetRequestsPerSecond: createEwma(),
+        minimumRttMs: createEwma(),
         latency: createEwma(),
         retryAfter: createEwma(),
         provider429Count: 0,
@@ -146,10 +1116,314 @@ export function createRuntimeResourceGovernor(input: {
     return stats;
   };
 
+  const providerAttributionKey = (key: string): string => {
+    const normalized = resourceKey(key);
+    if (
+      normalized === PROVIDER_ATTRIBUTION_OTHER_KEY ||
+      providerAttribution.has(normalized) ||
+      providerAttributionReservations.has(normalized)
+    ) {
+      return normalized;
+    }
+    const namedCount = new Set([
+      ...[...providerAttribution.keys()].filter(
+        (provider) => provider !== PROVIDER_ATTRIBUTION_OTHER_KEY,
+      ),
+      ...providerAttributionReservations,
+    ]).size;
+    if (namedCount >= MAX_PROVIDER_ATTRIBUTION_BUCKETS) {
+      return PROVIDER_ATTRIBUTION_OTHER_KEY;
+    }
+    providerAttributionReservations.add(normalized);
+    return normalized;
+  };
+
+  const providerAttributionStats = (key: string) => {
+    const attributionKey = providerAttributionKey(key);
+    let stats = providerAttribution.get(attributionKey);
+    if (!stats) {
+      stats = {
+        admission: createPhaseTiming(),
+        residence: createPhaseTiming(),
+        fixtureDelay: createPhaseTiming(),
+        transportSlotWait: createPhaseTiming(),
+        fetchToHeaders: createPhaseTiming(),
+        bodyRead: createPhaseTiming(),
+        bodyAdmissionWait: createPhaseTiming(),
+        controllerPermits: 0,
+        inFlightAtPermit: createSampleTiming(),
+        runInFlightAtDispatch: createSampleTiming(),
+        targetRequestsPerSecond: createEwma(),
+        minimumRttMs: createEwma(),
+        latency: createEwma(),
+        retryAfter: createEwma(),
+        provider429Count: 0,
+      };
+      providerAttribution.set(attributionKey, stats);
+    }
+    return stats;
+  };
+
+  const observeProviderStats = (
+    stats: {
+      admission: ReturnType<typeof createPhaseTiming>;
+      residence: ReturnType<typeof createPhaseTiming>;
+      fixtureDelay: ReturnType<typeof createPhaseTiming>;
+      transportSlotWait: ReturnType<typeof createPhaseTiming>;
+      fetchToHeaders: ReturnType<typeof createPhaseTiming>;
+      bodyRead: ReturnType<typeof createPhaseTiming>;
+      bodyAdmissionWait: ReturnType<typeof createPhaseTiming>;
+      controllerPermits: number;
+      inFlightAtPermit: ReturnType<typeof createSampleTiming>;
+      runInFlightAtDispatch?: ReturnType<typeof createSampleTiming>;
+      targetRequestsPerSecond: Ewma;
+      minimumRttMs: Ewma;
+      latency: Ewma;
+      retryAfter: Ewma;
+      provider429Count: number;
+    },
+    observation: RuntimeResourceObservation,
+  ) => {
+    stats.admission.observe(observation.providerAdmissionWaitMs);
+    stats.residence.observe(observation.providerLatencyMs);
+    stats.fixtureDelay.observe(observation.fixtureDelayMs);
+    stats.transportSlotWait.observe(observation.transportSlotWaitMs);
+    stats.fetchToHeaders.observe(observation.fetchToHeadersMs);
+    stats.bodyRead.observe(observation.bodyReadMs);
+    stats.bodyAdmissionWait.observe(observation.providerBodyAdmissionWaitMs);
+    const pacingGrant =
+      observation.providerPacingGrant ?? observation.providerConcurrencyGrant;
+    if (pacingGrant) {
+      stats.controllerPermits += 1;
+      stats.targetRequestsPerSecond.observe(
+        pacingGrant.targetRequestsPerSecond,
+      );
+    }
+    const concurrencyGrant = observation.providerConcurrencyGrant;
+    if (concurrencyGrant) {
+      stats.inFlightAtPermit.observe(concurrencyGrant.inFlightAtStart);
+      stats.minimumRttMs.observe(concurrencyGrant.minimumRttMs);
+    }
+    stats.runInFlightAtDispatch?.observe(
+      observation.providerRunInFlightAtDispatch,
+    );
+    stats.latency.observe(observation.providerLatencyMs);
+    stats.retryAfter.observe(observation.retryAfterMs);
+    if (observation.provider429) {
+      stats.provider429Count += 1;
+    }
+  };
+
+  let eventLoopLagTimer: ReturnType<typeof setInterval> | null = null;
+  let eventLoopLagTickedAt: number | null = null;
+  const startEventLoopLagSampler = (): void => {
+    if (eventLoopLagTimer !== null) return;
+    eventLoopLagTickedAt = Date.now();
+    eventLoopLagTimer = setInterval(() => {
+      const now = Date.now();
+      const dueAt =
+        (eventLoopLagTickedAt ?? now) + EVENT_LOOP_LAG_SAMPLE_INTERVAL_MS;
+      eventLoopLagTickedAt = now;
+      phases.eventLoopLag.observe(Math.max(0, now - dueAt));
+    }, EVENT_LOOP_LAG_SAMPLE_INTERVAL_MS);
+    // Measurement must never hold a runner open past its work.
+    const handle = eventLoopLagTimer as { unref?: () => void };
+    if (typeof handle.unref === 'function') {
+      handle.unref();
+    }
+  };
+  const stopEventLoopLagSampler = (): void => {
+    if (eventLoopLagTimer === null) return;
+    clearInterval(eventLoopLagTimer);
+    eventLoopLagTimer = null;
+    eventLoopLagTickedAt = null;
+  };
+
   const observe = (observation: RuntimeResourceObservation): void => {
+    startEventLoopLagSampler();
     rowAdmissionWait.observe(observation.rowAdmissionWaitMs);
     toolAdmissionWait.observe(observation.toolAdmissionWaitMs);
     sheetFlushLatency.observe(observation.sheetFlushLatencyMs);
+    phases.rowAdmission.observe(observation.rowAdmissionWaitMs);
+    phases.providerAdmission.observe(observation.providerAdmissionWaitMs);
+    phases.externalExecution.observe(observation.externalExecutionWaitMs);
+    phases.providerResidence.observe(observation.providerLatencyMs);
+    phases.fixtureDelay.observe(observation.fixtureDelayMs);
+    phases.transportSlotWait.observe(observation.transportSlotWaitMs);
+    phases.fetchToHeaders.observe(observation.fetchToHeadersMs);
+    const executeRouteTiming = observation.executeServerTiming;
+    // The response writer emits every named stage. Refuse a partial header so
+    // this compact run aggregate has one honest denominator rather than four
+    // incomparable ones from a rolling app/runtime skew.
+    if (
+      executeRouteTiming != null &&
+      typeof executeRouteTiming.total === 'number' &&
+      typeof executeRouteTiming.charge_open === 'number' &&
+      typeof executeRouteTiming.fixture_load === 'number' &&
+      typeof executeRouteTiming.execute === 'number'
+    ) {
+      executeRoute.count += 1;
+      executeRoute.totalMs += executeRouteTiming.total;
+      executeRoute.chargeOpenMs += executeRouteTiming.charge_open;
+      executeRoute.fixtureLoadMs += executeRouteTiming.fixture_load;
+      executeRoute.executeMs += executeRouteTiming.execute;
+      // Same rule as the gateway block below: require the complete substage
+      // set this app version emits, so an older build that reports only
+      // `charge_open` does not silently contribute a partial split.
+      if (
+        typeof executeRouteTiming.charge_eligibility === 'number' &&
+        typeof executeRouteTiming.charge_cap_preflight === 'number' &&
+        typeof executeRouteTiming.charge_open_mutation === 'number' &&
+        typeof executeRouteTiming.charge_retry_wait === 'number'
+      ) {
+        executeChargeOpen.count += 1;
+        executeChargeOpen.eligibilityMs +=
+          executeRouteTiming.charge_eligibility;
+        executeChargeOpen.capPreflightMs +=
+          executeRouteTiming.charge_cap_preflight;
+        executeChargeOpen.openMutationMs +=
+          executeRouteTiming.charge_open_mutation;
+        executeChargeOpen.retryWaitMs += executeRouteTiming.charge_retry_wait;
+      }
+      // Gateway timing is a separate request-owner clock, but it is retained
+      // only for the exact handler population above. Some routed tools have
+      // the relay header but no app execute split; mixing them would make
+      // `upstream_headers - handler.total` mathematically meaningless.
+      // Require the complete set that this gateway version emits too, so a
+      // rolling deploy cannot create a misleading sum over a different
+      // population.
+      if (
+        typeof executeRouteTiming.auth_launch === 'number' &&
+        typeof executeRouteTiming.auth_verify === 'number' &&
+        typeof executeRouteTiming.body_parse === 'number' &&
+        typeof executeRouteTiming.dispatch_pool === 'number' &&
+        typeof executeRouteTiming.dispatch_callback === 'number' &&
+        typeof executeRouteTiming.upstream_headers === 'number' &&
+        typeof executeRouteTiming.upstream_body === 'number'
+      ) {
+        executeGateway.count += 1;
+        executeGateway.authLaunchMs += executeRouteTiming.auth_launch;
+        executeGateway.authVerifyMs += executeRouteTiming.auth_verify;
+        executeGateway.bodyParseMs += executeRouteTiming.body_parse;
+        executeGateway.dispatchPoolMs += executeRouteTiming.dispatch_pool;
+        executeGateway.dispatchCallbackMs +=
+          executeRouteTiming.dispatch_callback;
+        executeGateway.upstreamHeadersMs += executeRouteTiming.upstream_headers;
+        executeGateway.upstreamBodyMs += executeRouteTiming.upstream_body;
+      }
+    }
+    phases.bodyRead.observe(observation.bodyReadMs);
+    phases.receiptSettlement.observe(observation.receiptLatencyMs);
+    phases.receiptClaim.observe(observation.receiptClaimMs);
+    phases.receiptHydrationGateWait.observe(
+      observation.receiptHydrationGateWaitMs,
+    );
+    phases.receiptCompletionQueue.observe(observation.receiptCompletionQueueMs);
+    phases.receiptCompletionFlight.observe(
+      observation.receiptCompletionFlightMs,
+    );
+    phases.receiptCompletionReadBack.observe(
+      observation.receiptCompletionReadBackMs,
+    );
+    phases.rowPersistence.observe(observation.sheetFlushLatencyMs);
+    phases.dispatchQueueWait.observe(observation.dispatchQueueWaitMs);
+    phases.rowResolverGap.observe(observation.rowResolverGapMs);
+    phases.toolCallLogicalWall.observe(observation.toolCallLogicalWallMs);
+    phases.resultDelivery.observe(observation.resultDeliveryMs);
+    phases.deliveryWrap.observe(observation.deliveryWrapMs);
+    phases.deliveryPublishWait.observe(observation.deliveryPublishWaitMs);
+    phases.deliveryResolve.observe(observation.deliveryResolveMs);
+    phases.flightSerialize.observe(observation.flightSerializeMs);
+    phases.flightTransport.observe(observation.flightTransportMs);
+    phases.flightDecode.observe(observation.flightDecodeMs);
+    phases.gatewayAuthLaunch.observe(observation.gatewayAuthLaunchMs);
+    phases.gatewayAuthVerify.observe(observation.gatewayAuthVerifyMs);
+    phases.gatewayBodyParse.observe(observation.gatewayBodyParseMs);
+    phases.gatewayBodyInflate.observe(observation.gatewayBodyInflateMs);
+    phases.gatewayPoolWait.observe(observation.gatewayPoolWaitMs);
+    phases.gatewayReceiptValuePersist.observe(
+      observation.gatewayReceiptValuePersistMs,
+    );
+    phases.gatewayCallback.observe(observation.gatewayCallbackMs);
+    phases.gatewayRoundTrip.observe(observation.gatewayRoundTripMs);
+    phases.gatewayRequestSerialize.observe(
+      observation.gatewayRequestSerializeMs,
+    );
+    phases.gatewayRequestPack.observe(observation.gatewayRequestPackMs);
+    if (observation.gatewayAuthSession != null) {
+      gatewayAuthSessionCounters[observation.gatewayAuthSession] += 1;
+    }
+    // Raw is the authority for the count: every request has serialized bytes,
+    // so a missing wire size (an older transport) adds nothing rather than
+    // silently reporting a request that moved zero bytes.
+    if (observation.gatewayRequestRawBytes != null) {
+      gatewayRequestBodyCounters.count += 1;
+      gatewayRequestBodyCounters.rawBytes += Math.max(
+        0,
+        Math.floor(observation.gatewayRequestRawBytes),
+      );
+      gatewayRequestBodyCounters.wireBytes += Math.max(
+        0,
+        Math.floor(
+          observation.gatewayRequestWireBytes ??
+            observation.gatewayRequestRawBytes,
+        ),
+      );
+    }
+    if (observation.receiptCompletionReadBacks != null) {
+      resultEgressCounters.readBacks += Math.max(
+        0,
+        Math.floor(observation.receiptCompletionReadBacks),
+      );
+    }
+    if (observation.receiptCompletionLiveResultReuses != null) {
+      resultEgressCounters.liveResultReuses += Math.max(
+        0,
+        Math.floor(observation.receiptCompletionLiveResultReuses),
+      );
+    }
+    if (observation.receiptCompletionLivePublicationResults != null) {
+      resultEgressCounters.livePublicationResults += Math.max(
+        0,
+        Math.floor(observation.receiptCompletionLivePublicationResults),
+      );
+    }
+    if (observation.receiptCompletionExistingWinners != null) {
+      resultEgressCounters.existingWinners += Math.max(
+        0,
+        Math.floor(observation.receiptCompletionExistingWinners),
+      );
+    }
+    if (observation.receiptCompletionLegacyAcknowledgements != null) {
+      resultEgressCounters.legacyAcknowledgements += Math.max(
+        0,
+        Math.floor(observation.receiptCompletionLegacyAcknowledgements),
+      );
+    }
+    if (observation.receiptCompletionMissingAcknowledgements != null) {
+      resultEgressCounters.missingAcknowledgements += Math.max(
+        0,
+        Math.floor(observation.receiptCompletionMissingAcknowledgements),
+      );
+    }
+    if (observation.receiptCompletionNonterminalAcknowledgements != null) {
+      resultEgressCounters.nonterminalAcknowledgements += Math.max(
+        0,
+        Math.floor(observation.receiptCompletionNonterminalAcknowledgements),
+      );
+    }
+    if (observation.receiptCompletionReadBackRecovered != null) {
+      resultEgressCounters.readBackRecovered += Math.max(
+        0,
+        Math.floor(observation.receiptCompletionReadBackRecovered),
+      );
+    }
+    if (observation.receiptCompletionReadBackMissing != null) {
+      resultEgressCounters.readBackMissing += Math.max(
+        0,
+        Math.floor(observation.receiptCompletionReadBackMissing),
+      );
+    }
     if (observation.sheetFlushLatencyMs != null) {
       sheetFlushCounters.acquired += 1;
     }
@@ -165,17 +1439,72 @@ export function createRuntimeResourceGovernor(input: {
         Math.floor(observation.sheetFlushBytes),
       );
     }
-    if (
+    if (observation.receiptEgressBatchSize != null) {
+      resultEgressCounters.batches += 1;
+      resultEgressCounters.receipts += Math.max(
+        0,
+        Math.floor(observation.receiptEgressBatchSize),
+      );
+    }
+    if (observation.receiptEgressBytes != null) {
+      const bytes = Math.max(0, Math.floor(observation.receiptEgressBytes));
+      resultEgressCounters.bytes += bytes;
+      resultEgressCounters.maxBatchBytes =
+        resultEgressCounters.maxBatchBytes === null
+          ? bytes
+          : Math.max(resultEgressCounters.maxBatchBytes, bytes);
+    }
+    if (observation.receiptCompletionWriterInFlightBatches != null) {
+      resultEgressCounters.writerPeakInFlightBatches = Math.max(
+        resultEgressCounters.writerPeakInFlightBatches,
+        Math.max(
+          0,
+          Math.floor(observation.receiptCompletionWriterInFlightBatches),
+        ),
+      );
+    }
+    if (observation.receiptCompletionWriterQueued != null) {
+      resultEgressCounters.writerPeakQueued = Math.max(
+        resultEgressCounters.writerPeakQueued,
+        Math.max(0, Math.floor(observation.receiptCompletionWriterQueued)),
+      );
+    }
+    if (observation.receiptCompletionWriterBufferedItems != null) {
+      resultEgressCounters.writerPeakBufferedItems = Math.max(
+        resultEgressCounters.writerPeakBufferedItems,
+        Math.max(
+          0,
+          Math.floor(observation.receiptCompletionWriterBufferedItems),
+        ),
+      );
+    }
+    if (observation.receiptCompletionWriterBufferedBytes != null) {
+      resultEgressCounters.writerPeakBufferedBytes = Math.max(
+        resultEgressCounters.writerPeakBufferedBytes,
+        Math.max(
+          0,
+          Math.floor(observation.receiptCompletionWriterBufferedBytes),
+        ),
+      );
+    }
+    if (observation.concurrencyShedDelayMs != null) {
+      concurrencyShedCounters.count += 1;
+      concurrencyShedDelay.observe(observation.concurrencyShedDelayMs);
+    }
+    const hasProviderObservation =
       observation.providerResourceKey ||
+      observation.providerTelemetryKey ||
       observation.providerLatencyMs != null ||
       observation.provider429 ||
-      observation.retryAfterMs != null
-    ) {
+      observation.retryAfterMs != null;
+    if (hasProviderObservation) {
       const stats = providerStats(observation.providerResourceKey ?? 'unknown');
-      stats.latency.observe(observation.providerLatencyMs);
-      stats.retryAfter.observe(observation.retryAfterMs);
-      if (observation.provider429) {
-        stats.provider429Count += 1;
+      observeProviderStats(stats, observation);
+      if (observation.providerTelemetryKey) {
+        observeProviderStats(
+          providerAttributionStats(observation.providerTelemetryKey),
+          observation,
+        );
       }
       if (
         observation.providerSuccess === true &&
@@ -226,11 +1555,90 @@ export function createRuntimeResourceGovernor(input: {
       return lease;
     },
 
-    acquireProviderPermit(providerInput) {
-      return input.executionGovernor.acquireProviderPermit(
+    async acquireExternalExecutionSlot(slotInput) {
+      const startedAt = Date.now();
+      const lease = await input.executionGovernor.acquireToolExecutionSlot({
+        signal: slotInput?.signal,
+      });
+      toolCounters.acquired += 1;
+      observe({
+        providerResourceKey: slotInput?.providerResourceKey ?? null,
+        externalExecutionWaitMs: elapsedSince(startedAt),
+      });
+      return lease;
+    },
+
+    tryAcquireExternalExecutionSlot(slotInput) {
+      const lease = input.executionGovernor.tryAcquireToolExecutionSlot();
+      if (!lease) return null;
+      toolCounters.acquired += 1;
+      observe({
+        providerResourceKey: slotInput?.providerResourceKey ?? null,
+        externalExecutionWaitMs: 0,
+      });
+      return lease;
+    },
+
+    chargeToolCall: () => input.executionGovernor.chargeBudget('toolCall'),
+
+    async acquireProviderPermit(providerInput) {
+      const startedAt = Date.now();
+      const lease = await input.executionGovernor.acquireProviderPermit(
         providerInput.toolId,
         { signal: providerInput.signal },
       );
+      observe({
+        providerResourceKey: lease.provider,
+        providerTelemetryKey: lease.provider,
+        providerAdmissionWaitMs: elapsedSince(startedAt),
+      });
+      return lease;
+    },
+
+    tryAcquireProviderPermit(providerInput) {
+      const lease = input.executionGovernor.tryAcquireProviderPermit(
+        providerInput.toolId,
+      );
+      if (!lease) return null;
+      observe({
+        providerResourceKey: lease.provider,
+        providerTelemetryKey: lease.provider,
+        providerAdmissionWaitMs: 0,
+      });
+      return lease;
+    },
+
+    beginProviderExecution(providerInput) {
+      const providerTelemetryKey = providerAttributionKey(
+        providerInput.providerTelemetryKey ??
+          providerInput.providerResourceKey ??
+          'unknown',
+      );
+      const inFlightAtDispatch =
+        activeProviderExecutions.get(providerTelemetryKey) ?? 0;
+      activeProviderExecutions.set(
+        providerTelemetryKey,
+        inFlightAtDispatch + 1,
+      );
+      let released = false;
+      return {
+        providerTelemetryKey,
+        inFlightAtDispatch,
+        release() {
+          if (released) return;
+          released = true;
+          const active = activeProviderExecutions.get(providerTelemetryKey);
+          if (!active || active <= 1) {
+            activeProviderExecutions.delete(providerTelemetryKey);
+            return;
+          }
+          activeProviderExecutions.set(providerTelemetryKey, active - 1);
+        },
+      };
+    },
+
+    tryAcquireIntegrationRequestSlot() {
+      return input.executionGovernor.tryAcquireIntegrationRequestSlot();
     },
 
     suggestedToolParallelism(toolId, fallback) {
@@ -259,8 +1667,91 @@ export function createRuntimeResourceGovernor(input: {
 
     observe,
 
+    stopSampling: stopEventLoopLagSampler,
+    eventLoopLagEwmaMs: () => phases.eventLoopLag.snapshot().ewmaMs,
+
+    recordMapAdmission(mapName, snapshot) {
+      // The ledger is per-process, not per-map: the runner publishes it once
+      // under `memory` below. Repeating it inside every map's admission
+      // snapshot only spends the terminal metadata budget, and a
+      // runtimeResources record over that budget is dropped whole.
+      mapAdmission[resourceKey(mapName)] = { ...snapshot, memory: null };
+    },
+
+    memoryLedger: input.memoryLedger ?? null,
+
     snapshot() {
       return {
+        // At the capped mixed-provider maximum, preserve the controller and
+        // residence table rather than risking the terminal envelope for a
+        // secondary diagnostic. Normal fixture shapes retain this aggregate.
+        ...(executeRoute.count > 0 &&
+        providerAttribution.size < MAX_PROVIDER_ATTRIBUTION_BUCKETS
+          ? {
+              executeRoute: {
+                ...executeRoute,
+                ...(executeChargeOpen.count > 0
+                  ? { chargeOpen: { ...executeChargeOpen } }
+                  : {}),
+                ...(executeGateway.count > 0
+                  ? { gateway: { ...executeGateway } }
+                  : {}),
+              },
+            }
+          : {}),
+        process: readProcessUsage(),
+        mapAdmission: { ...mapAdmission },
+        memory: readMemorySnapshot(),
+        // Distributions ride only on the run-level phases. Per-provider
+        // timings stay lean counters: the provider map is unbounded, and the
+        // terminal metadata record is dropped whole once it passes its budget.
+        phases: {
+          rowAdmission: phases.rowAdmission.distribution(),
+          providerAdmission: phases.providerAdmission.distribution(),
+          externalExecution: phases.externalExecution.distribution(),
+          providerResidence: phases.providerResidence.distribution(),
+          fixtureDelay: phases.fixtureDelay.distribution(),
+          transportSlotWait: phases.transportSlotWait.distribution(),
+          fetchToHeaders: phases.fetchToHeaders.distribution(),
+          bodyRead: phases.bodyRead.distribution(),
+          eventLoopLag: phases.eventLoopLag.distribution(),
+          receiptSettlement: phases.receiptSettlement.distribution(),
+          receiptClaim: phases.receiptClaim.distribution(),
+          receiptHydrationGateWait:
+            phases.receiptHydrationGateWait.distribution(),
+          receiptCompletionQueue: phases.receiptCompletionQueue.distribution(),
+          receiptCompletionFlight:
+            phases.receiptCompletionFlight.distribution(),
+          receiptCompletionReadBack:
+            phases.receiptCompletionReadBack.distribution(),
+          rowPersistence: phases.rowPersistence.distribution(),
+          dispatchQueueWait: phases.dispatchQueueWait.distribution(),
+          rowResolverGap: phases.rowResolverGap.distribution(),
+          toolCallLogicalWall: phases.toolCallLogicalWall.distribution(),
+          resultDelivery: phases.resultDelivery.distribution(),
+          deliveryWrap: phases.deliveryWrap.distribution(),
+          deliveryPublishWait: phases.deliveryPublishWait.distribution(),
+          deliveryResolve: phases.deliveryResolve.distribution(),
+          flightSerialize: phases.flightSerialize.distribution(),
+          flightTransport: phases.flightTransport.distribution(),
+          flightDecode: phases.flightDecode.distribution(),
+          gatewayAuthLaunch: phases.gatewayAuthLaunch.distribution(),
+          gatewayAuthVerify: phases.gatewayAuthVerify.distribution(),
+          gatewayBodyParse: phases.gatewayBodyParse.distribution(),
+          gatewayBodyInflate: phases.gatewayBodyInflate.distribution(),
+          gatewayPoolWait: phases.gatewayPoolWait.distribution(),
+          gatewayReceiptValuePersist:
+            phases.gatewayReceiptValuePersist.distribution(),
+          gatewayCallback: phases.gatewayCallback.distribution(),
+          gatewayRoundTrip: phases.gatewayRoundTrip.distribution(),
+          gatewayRequestSerialize:
+            phases.gatewayRequestSerialize.distribution(),
+          gatewayRequestPack: phases.gatewayRequestPack.distribution(),
+        },
+        gateway: {
+          authSession: { ...gatewayAuthSessionCounters },
+          requestBody: { ...gatewayRequestBodyCounters },
+        },
         rows: {
           acquired: rowCounters.acquired,
           estimatedBytes: rowCounters.estimatedBytes,
@@ -275,10 +1766,43 @@ export function createRuntimeResourceGovernor(input: {
           bytes: sheetFlushCounters.bytes,
           latencyMsEwma: sheetFlushLatency.value,
         },
+        resultEgress: resultEgressCounters,
+        concurrencyShed: {
+          count: concurrencyShedCounters.count,
+          delayMsEwma: concurrencyShedDelay.value,
+        },
         providers: Object.fromEntries(
           [...providers.entries()].map(([key, stats]) => [
             key,
             {
+              admission: stats.admission.snapshot(),
+              residence: stats.residence.snapshot(),
+              fetchToHeaders: stats.fetchToHeaders.snapshot(),
+              latencyMsEwma: stats.latency.value,
+              retryAfterMsEwma: stats.retryAfter.value,
+              provider429Count: stats.provider429Count,
+            },
+          ]),
+        ),
+        providerAttribution: Object.fromEntries(
+          [...providerAttribution.entries()].map(([key, stats]) => [
+            key,
+            {
+              admission: stats.admission.snapshot(),
+              residence: stats.residence.snapshot(),
+              fixtureDelay: stats.fixtureDelay.snapshot(),
+              transportSlotWait: stats.transportSlotWait.snapshot(),
+              fetchToHeaders: stats.fetchToHeaders.snapshot(),
+              bodyRead: stats.bodyRead.snapshot(),
+              gateMs: stats.bodyAdmissionWait.snapshot().totalMs,
+              controller: {
+                permits: stats.controllerPermits,
+                inFlightAtPermit: stats.inFlightAtPermit.snapshot(),
+                runInFlightAtDispatch: stats.runInFlightAtDispatch.snapshot(),
+                targetRequestsPerSecondEwma:
+                  stats.targetRequestsPerSecond.value,
+                minimumRttMsEwma: stats.minimumRttMs.value,
+              },
               latencyMsEwma: stats.latency.value,
               retryAfterMsEwma: stats.retryAfter.value,
               provider429Count: stats.provider429Count,