deepline 0.3.128 → 0.3.129

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

@@ -4,10 +4,13 @@ import {
   releaseRateStateViaAppRuntime,
   type WorkerRuntimeApiContext,
 } from '../app-runtime-api';
+import { randomUUID } from 'node:crypto';
 import {
   DEFAULT_ADVISORY_PROVIDER_MAX_RPS,
   noopPacingPermit,
   type PacingPermit,
+  type ProviderConcurrencyGrant,
+  type ProviderPacingGrant,
   type PacingRule,
   type RateStateBackend,
   type RateStateBackendKind,
@@ -29,6 +32,13 @@ import {
  * so keep their sleep-toward-it behavior byte-for-byte.
  */
 export const PROVIDER_EXHAUSTED_MAX_WAIT_MS = 60_000;
+/**
+ * Total time one acquirer may spend cycling through window-exhausted refills.
+ * Each refill's sleep is bounded, but nothing bounded how many of them a row
+ * could take; with several runs sharing one org's provider window a late
+ * starter parked here for twenty minutes with its core idle.
+ */
+export const RATE_ACQUIRE_MAX_WAIT_MS = 300_000;
 
 /**
  * Permits leased per app-runtime round trip for the direct Node substrate.
@@ -73,6 +83,12 @@ export const APP_RUNTIME_RATE_STATE_LEASE_BLOCK_SIZE = 8;
 const LEASE_BLOCK_MIN_TTL_MS = 250;
 const LEASE_BLOCK_MAX_TTL_MS = 5_000;
 const MAX_ACQUIRE_SLEEP_MS = 5_000;
+/**
+ * Horizon used to size the next lease block from the rate actually in force.
+ * Kept short so a block stays inside its own TTL and a stalled runner can never
+ * hold more than a moment of a shared provider window.
+ */
+const RATE_BLOCK_HORIZON_MS = 1_000;
 const STORE_FAILURE_RETRY_DELAYS_MS = [100, 250] as const;
 /**
  * Jitter fraction applied to a server-supplied `waitMs` so a synchronized wave
@@ -90,13 +106,30 @@ export interface RateStateCooldown {
 }
 
 interface LeasedBlock {
-  permits: Array<[scheduledAtMs: number, leaseId: string | null]>;
+  permits: Array<
+    [
+      scheduledAtMs: number,
+      leaseId: string | null,
+      reservationId: string | null,
+      concurrencyGrant: ProviderConcurrencyGrant | null,
+      pacingGrant: ProviderPacingGrant | null,
+    ]
+  >;
   rateScopeToken: string | null;
   expiresAt: number;
   rulesKey: string;
   rules: PacingRule[];
 }
 
+type PendingConcurrencyObservations = {
+  batch: {
+    observerId: string;
+    laneId: string;
+    sequence: number;
+  };
+  observations: Array<{ kind: 'success'; latencyMs: number }>;
+};
+
 interface PendingRelease {
   bucketId: string;
   rateScopeToken: string | null;
@@ -148,6 +181,21 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
   private readonly cooldowns = new Map<string, RateStateCooldown>();
   private readonly effectiveRps = new Map<string, number>();
   private readonly pendingSuccesses = new Map<string, number>();
+  /**
+   * Completion samples travel with the next lease refill. This keeps the
+   * Gradient2 checkpoint current without adding one gateway request per row.
+   */
+  private readonly pendingConcurrencyObservations = new Map<
+    string,
+    PendingConcurrencyObservations
+  >();
+  /** One opaque identity per runtime backend; never derived from customer data. */
+  private readonly concurrencyObserverId = randomUUID();
+  private readonly concurrencyObservationLanes = new Map<string, string>();
+  private readonly nextConcurrencyObservationSequence = new Map<
+    string,
+    number
+  >();
   private pendingReleaseFailure: Error | null = null;
 
   constructor(context: WorkerRuntimeApiContext, options: Options = {}) {
@@ -184,11 +232,16 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
    * otherwise reports `coolUntilMs`. No-op when the bucket has no live hold.
    */
   private throwIfPacerExhausted(bucketId: string): void {
+    const exhausted = this.pacerExhaustion(bucketId);
+    if (exhausted) throw exhausted;
+  }
+
+  private pacerExhaustion(bucketId: string): ProviderExhaustedError | null {
     const cooldown = this.cooldowns.get(bucketId);
-    if (!cooldown) return;
+    if (!cooldown) return null;
     const now = this.now();
     const coolActive = cooldown.coolUntilMs - now > 0;
-    if (!coolActive) return;
+    if (!coolActive) return null;
     const coolWait = cooldown.coolUntilMs - now;
     const claimActive = cooldown.claimedRetryAtMs - now > 0;
     // Duration alone decides. Neither hold is over threshold → let it sleep.
@@ -199,7 +252,7 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
         cooldown.claimedRetryAtMs - now > PROVIDER_EXHAUSTED_MAX_WAIT_MS
       )
     ) {
-      return;
+      return null;
     }
     // Retry deadline: the server Retry-After verbatim when present, else the
     // pacer's own cooldown deadline.
@@ -207,12 +260,36 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
       cooldown.claimedRetryAtMs > 0
         ? cooldown.claimedRetryAtMs
         : cooldown.coolUntilMs;
-    throw new ProviderExhaustedError({
+    return new ProviderExhaustedError({
       provider: providerNameFromBucketId(bucketId),
       retryAtMs,
     });
   }
 
+  tryAcquire(input: {
+    bucketId: string;
+    rateScopeToken?: string | null;
+    rules: readonly PacingRule[];
+  }): PacingPermit | null {
+    const { bucketId, rules } = input;
+    if (rules.length === 0) return noopPacingPermit();
+    // A probe reports nothing and repairs nothing: a pending release failure
+    // or an exhausted pacer surfaces from the next blocking acquire instead.
+    if (this.pendingReleaseFailure || this.pacerExhaustion(bucketId)) {
+      return null;
+    }
+    const laneKey = rateLaneKey(
+      bucketId,
+      rulesSignature([...rules].sort((a, b) => a.ruleId.localeCompare(b.ruleId))),
+    );
+    const block = this.liveBlock(bucketId, laneKey);
+    if (!block) return null;
+    const next = block.permits[0];
+    if (!next || next[0] > this.now()) return null;
+    block.permits.shift();
+    return this.permitFor(bucketId, laneKey, block, next);
+  }
+
   async acquire(input: {
     bucketId: string;
     rateScopeToken?: string | null;
@@ -239,6 +316,7 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
     // sleep) serves the whole matching wave, then everyone re-draws. This replaces the old
     // per-bucket lock that held across the RPC + up-to-5s sleep and thereby
     // serialized every map row behind one sleeping acquirer.
+    const acquireStartedAt = this.now();
     while (true) {
       if (signal?.aborted) {
         throw signal.reason instanceof Error
@@ -257,6 +335,13 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
         }
         return localPermit.permit;
       }
+      const waitedMs = this.now() - acquireStartedAt;
+      if (waitedMs >= RATE_ACQUIRE_MAX_WAIT_MS) {
+        throw new ProviderExhaustedError({
+          provider: providerNameFromBucketId(bucketId),
+          retryAtMs: this.now() + MAX_ACQUIRE_SLEEP_MS,
+        });
+      }
       // Count this acquirer as waiting on the refill so the single-flight refill
       // can size its block to the live wave. Decremented once a block lands (or
       // the refill errors) — see the finally in `refillBlock`.
@@ -291,37 +376,24 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
     laneKey: string,
     rules: readonly PacingRule[],
   ): number {
+    const floor = APP_RUNTIME_RATE_STATE_LEASE_BLOCK_SIZE;
     const configuredRps = Math.min(
       ...rules.map((rule) => (rule.requestsPerWindow / rule.windowMs) * 1_000),
     );
-    const effectiveRps = Math.max(
-      1,
-      this.effectiveRps.get(laneKey) ?? configuredRps,
-    );
-    // Catalogued rates are advisory exploration seeds. At a low seed, a
-    // normal eight-permit prefetch books tens of seconds of dispatch time
-    // before the first healthy response can authorize AIMD recovery. Start
-    // with only the rate that can be spent within the short lease horizon;
-    // ordinary and explicitly capped rules retain the bounded prefetch floor.
-    const hasAdvisoryExplorationCeiling = rules.some((rule) => {
-      const baseRps = (rule.requestsPerWindow / rule.windowMs) * 1_000;
-      return rule.adaptiveMaxRps != null && rule.adaptiveMaxRps > baseRps;
-    });
-    const floor = hasAdvisoryExplorationCeiling
-      ? Math.min(
-          APP_RUNTIME_RATE_STATE_LEASE_BLOCK_SIZE,
-          Math.max(1, Math.ceil(effectiveRps)),
-        )
-      : APP_RUNTIME_RATE_STATE_LEASE_BLOCK_SIZE;
-    const horizonBudget = Math.max(
+    // Size the block from the rate ACTUALLY in force (the store's learned
+    // `refill_per_sec`, falling back to the declared rate) over a short horizon,
+    // and never past what this block's own TTL can spend at that rate — a permit
+    // the block cannot hand out before it expires is a provider token burned for
+    // nothing. Clamping to `requestsPerWindow` instead pinned a ramped lane
+    // (10 rps declared, 100 rps learned) to ten permits per round trip, which on
+    // a hot map is a round trip per permit. The store's own token floor, not
+    // this number, is what bounds the grant.
+    const horizonMs = Math.min(RATE_BLOCK_HORIZON_MS, leasedBlockTtlMs(rules));
+    const rateBudget = Math.max(
       1,
-      Math.ceil(effectiveRps),
-    );
-    const rateBudget = Math.min(
-      horizonBudget,
-      ...rules
-        .map((rule) => rule.requestsPerWindow)
-        .filter((value) => Number.isFinite(value) && value > 0),
+      Math.floor(
+        ((this.effectiveRps.get(laneKey) ?? configuredRps) * horizonMs) / 1_000,
+      ),
     );
     if (!Number.isFinite(rateBudget) || rateBudget <= 0) return floor;
     const waiters = this.waiters.get(laneKey) ?? 1;
@@ -461,20 +533,25 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
       try {
         const successKey = pendingSuccessKey(bucketId, ordered);
         const observedSuccesses = this.pendingSuccesses.get(successKey) ?? 0;
-        // Use the same prepared rules for local lease sizing and the durable
-        // controller. Catalogued rules receive their advisory AIMD ceiling in
-        // this step, so inspecting the raw rule here would retain the fixed
-        // eight-permit floor for exactly the provider lanes that need fast
-        // feedback to recover.
-        const rateRules = withAdaptiveMaxRps(ordered);
+        const pendingConcurrency =
+          this.pendingConcurrencyObservations.get(successKey);
+        const concurrencyObservations = [
+          ...(pendingConcurrency?.observations ?? []),
+        ];
         const response = await this.port.acquire({
           bucketId,
           rateScopeToken,
-          // Stamp the advisory ceiling so the durable DB row uses the same
-          // catalogued-rate AIMD range as this in-memory controller.
-          rules: rateRules,
-          requested: this.requestedForBucket(laneKey, rateRules),
+          // Stamp adaptiveMaxRps on default-pacing rules so the DB row's ceiling
+          // matches the old in-memory AIMD range.
+          rules: withAdaptiveMaxRps(ordered),
+          requested: this.requestedForBucket(laneKey, ordered),
           observedSuccesses,
+          ...(pendingConcurrency
+            ? {
+                concurrencyObservations,
+                concurrencyObservationBatch: pendingConcurrency.batch,
+              }
+            : {}),
           schedulerSchema: this.schedulerSchema,
         });
         if (observedSuccesses > 0) {
@@ -485,6 +562,40 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
           if (remaining > 0) this.pendingSuccesses.set(successKey, remaining);
           else this.pendingSuccesses.delete(successKey);
         }
+        if (pendingConcurrency) {
+          const pending = this.pendingConcurrencyObservations.get(successKey);
+          const remainingSuccesses = this.pendingSuccesses.get(successKey) ?? 0;
+          if (
+            pending &&
+            pending.batch.sequence === pendingConcurrency.batch.sequence
+          ) {
+            const remaining = pending.observations.slice(
+              concurrencyObservations.length,
+            );
+            if (remainingSuccesses > 0 || remaining.length > 0) {
+              // Observations that arrived while this acquire was in flight need
+              // a new identity. Reusing the acknowledged sequence would make
+              // the gateway correctly discard their rate and Gradient2 input.
+              this.pendingConcurrencyObservations.set(
+                successKey,
+                this.newPendingConcurrencyObservations(successKey, remaining),
+              );
+            } else {
+              this.pendingConcurrencyObservations.delete(successKey);
+            }
+          } else if (
+            pending &&
+            pending.observations.length > concurrencyObservations.length
+          ) {
+            const remaining = pending.observations.slice(
+              concurrencyObservations.length,
+            );
+            this.pendingConcurrencyObservations.set(
+              successKey,
+              this.newPendingConcurrencyObservations(successKey, remaining),
+            );
+          }
+        }
         this.recordCooldown(bucketId, response);
         if (
           Number.isFinite(response.effectiveRequestsPerSecond) &&
@@ -568,6 +679,9 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
     response: {
       granted: number;
       leaseIds?: unknown;
+      reservationIds?: unknown;
+      concurrencyGrants?: unknown;
+      effectiveRequestsPerSecond?: unknown;
       serverNowMs?: unknown;
       scheduledAtMs?: unknown;
     },
@@ -589,6 +703,35 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
         `Rate-state store returned ${leaseIds.length} lease tokens for pure-rate bucket ${bucketId}.`,
       );
     }
+    const concurrencyGrants = normalizeConcurrencyGrants({
+      value: response.concurrencyGrants,
+      granted: response.granted,
+      hasConcurrency,
+      bucketId,
+    });
+    const effectiveRequestsPerSecond = Number(
+      response.effectiveRequestsPerSecond,
+    );
+    const pacingGrant: ProviderPacingGrant | null =
+      Number.isFinite(effectiveRequestsPerSecond) &&
+      effectiveRequestsPerSecond > 0
+        ? { targetRequestsPerSecond: effectiveRequestsPerSecond }
+        : null;
+    const reservationIds = Array.isArray(response.reservationIds)
+      ? response.reservationIds.filter(
+          (reservationId): reservationId is string =>
+            typeof reservationId === 'string' &&
+            reservationId.trim().length > 0,
+        )
+      : [];
+    if (
+      reservationIds.length > 0 &&
+      reservationIds.length !== response.granted
+    ) {
+      throw new Error(
+        `Rate-state store granted ${response.granted} permits for ${bucketId} with ${reservationIds.length} refundable reservation ids.`,
+      );
+    }
     // Rolling deploy compatibility: an older gateway returns no schedule. It
     // has already debited the block under the legacy token-bucket contract, so
     // keep those permits immediately usable until every gateway serves the new
@@ -598,11 +741,20 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
       : Array.from({ length: response.granted }, () => this.now());
     const serverNowMs = Number(response.serverNowMs);
     const receivedAtMs = this.now();
+    let firstGatewayScheduledAtMs = Number.POSITIVE_INFINITY;
+    for (const scheduledAtMs of gatewayScheduledAtMs) {
+      firstGatewayScheduledAtMs = Math.min(
+        firstGatewayScheduledAtMs,
+        scheduledAtMs,
+      );
+    }
     const scheduledAtMs =
       Number.isFinite(serverNowMs) && serverNowMs >= 0
         ? gatewayScheduledAtMs.map(
             (scheduledAtMs) =>
-              receivedAtMs + Math.max(0, scheduledAtMs - serverNowMs),
+              receivedAtMs +
+              Math.max(0, firstGatewayScheduledAtMs - serverNowMs) +
+              (scheduledAtMs - firstGatewayScheduledAtMs),
           )
         : gatewayScheduledAtMs;
     if (
@@ -616,10 +768,24 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
     this.mergeBlock(
       bucketId,
       rateScopeToken,
-      scheduledAtMs.map((scheduledAtMs, index): [number, string | null] => [
-        scheduledAtMs,
-        hasConcurrency ? (leaseIds[index] ?? null) : null,
-      ]),
+      scheduledAtMs.map(
+        (
+          scheduledAtMs,
+          index,
+        ): [
+          number,
+          string | null,
+          string | null,
+          ProviderConcurrencyGrant | null,
+          ProviderPacingGrant | null,
+        ] => [
+          scheduledAtMs,
+          hasConcurrency ? (leaseIds[index] ?? null) : null,
+          reservationIds[index] ?? null,
+          concurrencyGrants[index] ?? null,
+          pacingGrant,
+        ],
+      ),
       rulesKey,
       laneKey,
       ordered,
@@ -630,6 +796,9 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
     bucketId: string;
     rateScopeToken?: string | null;
     cooldownMs: number;
+    rules?: readonly PacingRule[];
+    latencyMs?: number | null;
+    concurrencyGrant?: ProviderConcurrencyGrant | null;
   }): Promise<void> {
     if (input.cooldownMs <= 0) return;
     this.drainBlocksForBucket(input.bucketId);
@@ -638,6 +807,11 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
         bucketId: input.bucketId,
         rateScopeToken: input.rateScopeToken?.trim() || null,
         cooldownMs: input.cooldownMs,
+        ...(input.rules ? { rules: [...input.rules] } : {}),
+        ...(input.latencyMs != null ? { latencyMs: input.latencyMs } : {}),
+        ...(input.concurrencyGrant
+          ? { concurrencyGrant: input.concurrencyGrant }
+          : {}),
         schedulerSchema: this.schedulerSchema,
       });
     } catch (error) {
@@ -655,28 +829,91 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
   observeSuccess(input: {
     bucketId: string;
     rules: readonly PacingRule[];
+    latencyMs?: number | null;
   }): void {
     const key = pendingSuccessKey(input.bucketId, input.rules);
     this.pendingSuccesses.set(
       key,
       Math.min(1_000_000, (this.pendingSuccesses.get(key) ?? 0) + 1),
     );
+    const pending =
+      this.pendingConcurrencyObservations.get(key) ??
+      this.newPendingConcurrencyObservations(key);
+    if (
+      input.latencyMs != null &&
+      Number.isFinite(input.latencyMs) &&
+      input.latencyMs > 0
+    ) {
+      // This is only an amortization buffer. It has an explicit byte-equivalent
+      // item cap; overflowing samples remain successful rate observations but
+      // cannot grow sandbox memory indefinitely.
+      if (pending.observations.length < 4_096) {
+        pending.observations.push({
+          kind: 'success',
+          latencyMs: input.latencyMs,
+        });
+      }
+    }
+    // The same batch identity also protects the rate-success observation.
+    // A provider can report a valid success without a usable residence time;
+    // retaining an empty Gradient2 list still makes a lost acquire response
+    // unable to replay that rate recovery signal.
+    this.pendingConcurrencyObservations.set(key, pending);
+  }
+
+  private newPendingConcurrencyObservations(
+    key: string,
+    observations: Array<{ kind: 'success'; latencyMs: number }> = [],
+  ): PendingConcurrencyObservations {
+    const laneId =
+      this.concurrencyObservationLanes.get(key) ??
+      (() => {
+        const created = randomUUID();
+        this.concurrencyObservationLanes.set(key, created);
+        return created;
+      })();
+    const sequence =
+      (this.nextConcurrencyObservationSequence.get(key) ?? 0) + 1;
+    this.nextConcurrencyObservationSequence.set(key, sequence);
+    return {
+      batch: {
+        observerId: this.concurrencyObserverId,
+        laneId,
+        sequence,
+      },
+      observations,
+    };
   }
 
   private permitFor(
     bucketId: string,
-    rateScopeToken: string | null,
-    rules: PacingRule[],
-    leaseId: string | null,
+    laneKey: string,
+    block: LeasedBlock,
+    scheduled: LeasedBlock['permits'][number],
   ): PacingPermit {
-    if (!rules.some((rule) => rule.maxConcurrency != null)) {
-      return noopPacingPermit();
-    }
-    let released = false;
+    const { rateScopeToken, rules } = block;
+    const [, leaseId, reservationId, concurrencyGrant, pacingGrant] = scheduled;
+    let settled = false;
+    const refund = async (): Promise<void> => {
+      if (!reservationId) {
+        throw new Error(
+          `Rate-state gateway returned an unrefundable permit for ${bucketId}.`,
+        );
+      }
+      await this.cancelReserved({
+        bucketId,
+        rateScopeToken,
+        rules,
+        leaseIds: leaseId ? [leaseId] : [],
+        reservationId,
+      });
+    };
     return {
+      concurrencyGrant,
+      pacingGrant,
       release: () => {
-        if (released) return;
-        released = true;
+        if (settled) return;
+        settled = true;
         this.releaseReserved(
           bucketId,
           rateScopeToken,
@@ -684,6 +921,24 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
           leaseId ? [leaseId] : [],
         );
       },
+      cancel: async () => {
+        if (settled) return;
+        settled = true;
+        await refund();
+      },
+      park: async () => {
+        if (settled) return;
+        settled = true;
+        // Only the block this permit was drawn from may take it back: a lane
+        // whose block expired, was drained by a penalty, or was replaced has
+        // already given up its grant, and the permit must be refunded instead.
+        if (this.blocks.get(laneKey) === block && block.expiresAt > this.now()) {
+          block.permits.push(scheduled);
+          block.permits.sort((a, b) => a[0] - b[0]);
+          return;
+        }
+        await refund();
+      },
     };
   }
 
@@ -725,10 +980,8 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
     });
   }
 
-  private drawFromBlock(
-    bucketId: string,
-    laneKey: string,
-  ): { permit: PacingPermit; scheduledAtMs: number } | null {
+  /** The lane's block, evicting (and releasing the leases of) an expired one. */
+  private liveBlock(bucketId: string, laneKey: string): LeasedBlock | null {
     const block = this.blocks.get(laneKey);
     if (!block) return null;
     if (block.expiresAt <= this.now()) {
@@ -745,19 +998,21 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
       );
       return null;
     }
+    return block;
+  }
+
+  private drawFromBlock(
+    bucketId: string,
+    laneKey: string,
+  ): { permit: PacingPermit; scheduledAtMs: number } | null {
+    const block = this.liveBlock(bucketId, laneKey);
+    if (!block) return null;
+    // An emptied block stays until it expires: the next refill merges into it,
+    // and a parked permit can only return to the block it was drawn from.
     const scheduled = block.permits.shift();
-    if (!scheduled) {
-      this.blocks.delete(laneKey);
-      return null;
-    }
-    if (block.permits.length === 0) this.blocks.delete(laneKey);
+    if (!scheduled) return null;
     return {
-      permit: this.permitFor(
-        bucketId,
-        block.rateScopeToken,
-        block.rules,
-        scheduled[1],
-      ),
+      permit: this.permitFor(bucketId, laneKey, block, scheduled),
       scheduledAtMs: scheduled[0],
     };
   }
@@ -776,6 +1031,40 @@ export class AppRuntimeRateStateBackend implements RateStateBackend {
     }
   }
 
+  /**
+   * Return one permit that never reached the provider. This is deliberately a
+   * synchronous acknowledgement boundary: the caller must not re-admit until
+   * the original reservation is durably refunded, or a saturated local slot can
+   * still turn into unbounded rate-token loss.
+   */
+  private async cancelReserved(input: {
+    bucketId: string;
+    rateScopeToken: string | null;
+    rules: readonly PacingRule[];
+    leaseIds: readonly string[];
+    reservationId: string;
+  }): Promise<void> {
+    try {
+      await this.port.release({
+        bucketId: input.bucketId,
+        rateScopeToken: input.rateScopeToken,
+        rules: [...input.rules],
+        leaseIds: [...input.leaseIds],
+        refundReservationIds: [input.reservationId],
+        schedulerSchema: this.schedulerSchema,
+      });
+    } catch (error) {
+      const normalized = normalizeError(error);
+      this.onStoreFailure({
+        bucketId: input.bucketId,
+        error: normalized.message,
+      });
+      throw new Error(
+        `Rate-state cancellation failed for ${input.bucketId}: ${normalized.message}`,
+      );
+    }
+  }
+
   private releaseReserved(
     bucketId: string,
     rateScopeToken: string | null,
@@ -887,6 +1176,71 @@ function pendingSuccessKey(
   return rateLaneKey(bucketId, rulesSignature(rules));
 }
 
+function normalizeConcurrencyGrants(input: {
+  value: unknown;
+  granted: number;
+  hasConcurrency: boolean;
+  bucketId: string;
+}): Array<ProviderConcurrencyGrant | null> {
+  if (!input.hasConcurrency) {
+    if (Array.isArray(input.value) && input.value.length > 0) {
+      throw new Error(
+        `Rate-state store returned concurrency attribution for pure-rate bucket ${input.bucketId}.`,
+      );
+    }
+    return Array.from({ length: input.granted }, () => null);
+  }
+  // The field is additive. A pre-expand gateway cannot provide attribution, so
+  // keep its declared-cap behavior and decline to infer a throttle dimension.
+  if (input.value === undefined) {
+    return Array.from({ length: input.granted }, () => null);
+  }
+  if (!Array.isArray(input.value) || input.value.length !== input.granted) {
+    throw new Error(
+      `Rate-state store granted ${input.granted} concurrency permits for ${input.bucketId} with invalid attribution tokens.`,
+    );
+  }
+  return input.value.map((value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new Error(
+        `Rate-state store returned an invalid concurrency attribution token for ${input.bucketId}.`,
+      );
+    }
+    const candidate = value as Record<string, unknown>;
+    const admissionId =
+      typeof candidate.admissionId === 'string'
+        ? candidate.admissionId.trim()
+        : '';
+    const inFlightAtStart = Number(candidate.inFlightAtStart);
+    const targetRequestsPerSecond = candidate.targetRequestsPerSecond;
+    const minimumRttMs = candidate.minimumRttMs;
+    if (
+      !admissionId ||
+      admissionId.length > 64 ||
+      !Number.isSafeInteger(inFlightAtStart) ||
+      inFlightAtStart < 1 ||
+      (targetRequestsPerSecond !== null &&
+        (!Number.isFinite(targetRequestsPerSecond) ||
+          Number(targetRequestsPerSecond) <= 0)) ||
+      (minimumRttMs !== null &&
+        (!Number.isFinite(minimumRttMs) || Number(minimumRttMs) <= 0))
+    ) {
+      throw new Error(
+        `Rate-state store returned an invalid concurrency attribution token for ${input.bucketId}.`,
+      );
+    }
+    return {
+      admissionId,
+      inFlightAtStart,
+      targetRequestsPerSecond:
+        targetRequestsPerSecond === null
+          ? null
+          : Number(targetRequestsPerSecond),
+      minimumRttMs: minimumRttMs === null ? null : Number(minimumRttMs),
+    };
+  });
+}
+
 function leasedBlockTtlMs(rules: readonly PacingRule[]): number {
   const shortestWindowMs = Math.min(
     ...rules