deepline 0.3.128 → 0.3.129

package/dist/bundling-sources/shared_libs/play-runtime/provider-capacity/gradient2-concurrency-controller.ts

@@ -0,0 +1,214 @@
+export type Gradient2ConcurrencyControllerOptions = Readonly<{
+  initialLimit: number;
+  minimumLimit: number;
+  maximumLimit: number;
+  smoothing: number;
+  longWindowSmoothing: number;
+  rttTolerance: number;
+  /** Bounded cold-start probe; one or below preserves ordinary Gradient2. */
+  startupProbeMultiplier?: number;
+}>;
+
+export type Gradient2Observation = Readonly<{
+  kind: 'success' | 'throttled' | 'transport_error';
+  latencyMs: number;
+  inFlightAtStart?: number;
+}>;
+
+export type Gradient2ConcurrencyControllerSnapshot = Readonly<{
+  limit: number;
+  shortRttMs: number | null;
+  longRttMs: number | null;
+  minimumRttMs: number | null;
+}>;
+
+export type Gradient2ConcurrencyControllerCheckpoint =
+  Gradient2ConcurrencyControllerSnapshot &
+    Readonly<{
+      successfulSamplesInWindow: number;
+      windowStartedAtLimit: number;
+      /** A real 429 permanently ends exponential startup probing. */
+      hasObservedThrottle?: boolean;
+    }>;
+
+function positive(value: number, label: string): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${label} must be finite and greater than zero.`);
+  }
+  return value;
+}
+
+function openFraction(value: number, label: string): number {
+  if (!Number.isFinite(value) || value <= 0 || value >= 1) {
+    throw new Error(`${label} must be between zero and one.`);
+  }
+  return value;
+}
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  return Math.min(maximum, Math.max(minimum, value));
+}
+
+/**
+ * Small Gradient2-style concurrency controller.
+ *
+ * The short RTT follows current pressure. The long RTT follows the provider's
+ * uncongested baseline slowly. The controller changes concurrent occupancy,
+ * never the requests-per-second target.
+ */
+export class Gradient2ConcurrencyController {
+  readonly #minimumLimit: number;
+  readonly #maximumLimit: number;
+  readonly #smoothing: number;
+  readonly #longWindowSmoothing: number;
+  readonly #rttTolerance: number;
+  readonly #startupProbeMultiplier: number;
+  #limit: number;
+  #shortRttMs: number | null = null;
+  #longRttMs: number | null = null;
+  #minimumRttMs: number | null = null;
+  #successfulSamplesInWindow = 0;
+  #windowStartedAtLimit: number;
+  #hasObservedThrottle = false;
+
+  constructor(
+    options: Gradient2ConcurrencyControllerOptions,
+    checkpoint?: Gradient2ConcurrencyControllerCheckpoint,
+  ) {
+    this.#minimumLimit = positive(options.minimumLimit, 'Minimum concurrency');
+    this.#maximumLimit = positive(options.maximumLimit, 'Maximum concurrency');
+    if (this.#maximumLimit < this.#minimumLimit) {
+      throw new Error('Maximum concurrency cannot be below the minimum.');
+    }
+    this.#limit = clamp(
+      positive(options.initialLimit, 'Initial concurrency'),
+      this.#minimumLimit,
+      this.#maximumLimit,
+    );
+    this.#smoothing = openFraction(options.smoothing, 'Gradient smoothing');
+    this.#longWindowSmoothing = openFraction(
+      options.longWindowSmoothing,
+      'Long-window smoothing',
+    );
+    this.#rttTolerance = positive(options.rttTolerance, 'RTT tolerance');
+    this.#startupProbeMultiplier = Math.max(
+      1,
+      positive(options.startupProbeMultiplier ?? 1, 'Startup probe multiplier'),
+    );
+    this.#windowStartedAtLimit = this.#limit;
+    if (checkpoint) {
+      this.#limit = clamp(
+        positive(checkpoint.limit, 'Checkpoint concurrency'),
+        this.#minimumLimit,
+        this.#maximumLimit,
+      );
+      this.#shortRttMs = checkpoint.shortRttMs;
+      this.#longRttMs = checkpoint.longRttMs;
+      this.#minimumRttMs = checkpoint.minimumRttMs;
+      this.#successfulSamplesInWindow = Math.max(
+        0,
+        Math.floor(checkpoint.successfulSamplesInWindow),
+      );
+      this.#windowStartedAtLimit = clamp(
+        positive(
+          checkpoint.windowStartedAtLimit,
+          'Checkpoint window concurrency',
+        ),
+        this.#minimumLimit,
+        this.#maximumLimit,
+      );
+      this.#hasObservedThrottle = checkpoint.hasObservedThrottle === true;
+    }
+  }
+
+  observe(observation: Gradient2Observation): void {
+    const latencyMs = positive(observation.latencyMs, 'Observed latency');
+    if (observation.kind !== 'success') {
+      // A transport failure is not provider-capacity evidence. It may still
+      // warrant the existing short-term occupancy reduction, but must not
+      // permanently prevent an unknown lane from finding its capacity.
+      if (observation.kind === 'throttled') {
+        this.#hasObservedThrottle = true;
+      }
+      const signalledCeiling =
+        observation.inFlightAtStart === undefined
+          ? this.#limit
+          : Math.max(this.#minimumLimit, observation.inFlightAtStart - 1);
+      const decreaseFactor = observation.kind === 'throttled' ? 0.7 : 0.85;
+      this.#limit = clamp(
+        Math.min(this.#limit * decreaseFactor, signalledCeiling),
+        this.#minimumLimit,
+        this.#maximumLimit,
+      );
+      this.#successfulSamplesInWindow = 0;
+      this.#windowStartedAtLimit = this.#limit;
+      return;
+    }
+
+    this.#shortRttMs =
+      this.#shortRttMs === null
+        ? latencyMs
+        : this.#shortRttMs * (1 - this.#smoothing) +
+          latencyMs * this.#smoothing;
+    this.#longRttMs =
+      this.#longRttMs === null
+        ? latencyMs
+        : this.#longRttMs * (1 - this.#longWindowSmoothing) +
+          latencyMs * this.#longWindowSmoothing;
+    this.#minimumRttMs =
+      this.#minimumRttMs === null
+        ? latencyMs
+        : Math.min(this.#minimumRttMs, latencyMs);
+    this.#successfulSamplesInWindow += 1;
+    if (
+      this.#successfulSamplesInWindow < Math.ceil(this.#windowStartedAtLimit)
+    ) {
+      return;
+    }
+
+    const gradient = clamp(
+      (this.#rttTolerance * this.#longRttMs) / this.#shortRttMs,
+      0.5,
+      1,
+    );
+    const probeHealthy =
+      !this.#hasObservedThrottle &&
+      this.#startupProbeMultiplier > 1 &&
+      gradient >= 1 - this.#smoothing;
+    if (probeHealthy) {
+      this.#limit = clamp(
+        this.#limit * this.#startupProbeMultiplier,
+        this.#minimumLimit,
+        this.#maximumLimit,
+      );
+    } else {
+      const queueAllowance = Math.sqrt(this.#limit);
+      const estimatedLimit = gradient * this.#limit + queueAllowance;
+      this.#limit = clamp(
+        this.#limit * (1 - this.#smoothing) + estimatedLimit * this.#smoothing,
+        this.#minimumLimit,
+        this.#maximumLimit,
+      );
+    }
+    this.#successfulSamplesInWindow = 0;
+    this.#windowStartedAtLimit = this.#limit;
+  }
+
+  snapshot(): Gradient2ConcurrencyControllerSnapshot {
+    return Object.freeze({
+      limit: this.#limit,
+      shortRttMs: this.#shortRttMs,
+      longRttMs: this.#longRttMs,
+      minimumRttMs: this.#minimumRttMs,
+    });
+  }
+
+  checkpoint(): Gradient2ConcurrencyControllerCheckpoint {
+    return Object.freeze({
+      ...this.snapshot(),
+      successfulSamplesInWindow: this.#successfulSamplesInWindow,
+      windowStartedAtLimit: this.#windowStartedAtLimit,
+      hasObservedThrottle: this.#hasObservedThrottle,
+    });
+  }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Canonical production provider-capacity policy.
+ *
+ * The topology is deliberately exact: every physical provider start spends
+ * shared rate and concurrency authority in one Postgres admission operation.
+ * AIMD and Gradient2 are pure transition laws over that shared checkpoint.
+ *
+ * Keep experimental policy variants in the simulation lab. Production,
+ * shadow evaluation, and the winning simulator candidate import this object
+ * so tuning cannot drift between the model and the enforced algorithm.
+ */
+export const PROVIDER_CAPACITY_POLICY = Object.freeze({
+  id: 'fast_probe_aimd_gradient2',
+  admission: 'exact_postgres_per_start',
+  rate: Object.freeze({
+    epochMs: 1_000,
+    recoveryFraction: 0.025,
+    // A scope with an explicit exploration ceiling starts with bounded
+    // exponential probes. The first authoritative throttle ends probing; all
+    // later recovery uses the conservative additive law above.
+    startupProbeMultiplier: 2,
+    decreaseFactor: 0.4,
+    minimumRateFraction: 1 / 16,
+    utilizationThreshold: 0.9,
+  }),
+  concurrency: Object.freeze({
+    minimumLimit: 1,
+    safetyLimit: 256,
+    smoothing: 0.12,
+    longWindowSmoothing: 0.03,
+    rttTolerance: 1.25,
+    startupProbeMultiplier: 2,
+  }),
+} as const);
+
+export type ProviderCapacityPolicy = typeof PROVIDER_CAPACITY_POLICY;
+
+/**
+ * Cold-start ceiling for an undeclared provider scope. This is a discovery
+ * guardrail, not an inferred provider limit; declared rules keep their own
+ * hard or advisory ceilings.
+ */
+export const DEFAULT_UNDECLARED_PROVIDER_ADAPTIVE_MAX_RPS = 1_000;

package/dist/bundling-sources/shared_libs/play-runtime/provider-capacity/provider-concurrency-policy.ts

@@ -0,0 +1,30 @@
+import type { Gradient2ConcurrencyControllerOptions } from './gradient2-concurrency-controller';
+import { PROVIDER_CAPACITY_POLICY } from './provider-capacity-policy';
+
+export const PROVIDER_CONCURRENCY_SAFETY_LIMIT =
+  PROVIDER_CAPACITY_POLICY.concurrency.safetyLimit;
+
+export const PROVIDER_CONCURRENCY_CONTROLLER_TUNING = Object.freeze({
+  minimumLimit: PROVIDER_CAPACITY_POLICY.concurrency.minimumLimit,
+  smoothing: PROVIDER_CAPACITY_POLICY.concurrency.smoothing,
+  longWindowSmoothing: PROVIDER_CAPACITY_POLICY.concurrency.longWindowSmoothing,
+  rttTolerance: PROVIDER_CAPACITY_POLICY.concurrency.rttTolerance,
+  startupProbeMultiplier:
+    PROVIDER_CAPACITY_POLICY.concurrency.startupProbeMultiplier,
+});
+
+/**
+ * The one Gradient2 policy used by Postgres enforcement, shadow evaluation,
+ * and simulations. Callers choose only the server-authored initial and maximum
+ * limits; algorithm tuning must not drift by deployment surface.
+ */
+export function providerConcurrencyControllerOptions(input: {
+  initialLimit: number;
+  maximumLimit?: number;
+}): Gradient2ConcurrencyControllerOptions {
+  return Object.freeze({
+    ...PROVIDER_CONCURRENCY_CONTROLLER_TUNING,
+    initialLimit: input.initialLimit,
+    maximumLimit: input.maximumLimit ?? PROVIDER_CONCURRENCY_SAFETY_LIMIT,
+  });
+}

package/dist/bundling-sources/shared_libs/play-runtime/provider-capacity/provider-rate-policy.ts

@@ -0,0 +1,95 @@
+import { PROVIDER_CAPACITY_POLICY } from './provider-capacity-policy';
+
+export const PROVIDER_RATE_CONTROLLER_TUNING = PROVIDER_CAPACITY_POLICY.rate;
+
+export type ProviderRateTargetTransitionInput = Readonly<{
+  currentRequestsPerSecond: number;
+  minimumRequestsPerSecond: number;
+  maximumRequestsPerSecond: number;
+  event: 'healthy_epoch' | 'rate_limited';
+  additiveIncrease: number;
+  decreaseFactor: number;
+}>;
+
+function positive(value: number, label: string): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${label} must be finite and greater than zero.`);
+  }
+  return value;
+}
+
+/**
+ * Pure transition law for the shared provider start-rate target.
+ *
+ * Adapters decide when an observation is authoritative. The simulator closes
+ * utilization epochs in memory; Postgres applies a healthy-wave transition
+ * while holding the credential-scoped rate row and applies a 429 transition
+ * only after idempotently recording the physical ticket outcome.
+ */
+export function transitionProviderRateTarget(
+  input: ProviderRateTargetTransitionInput,
+): number {
+  const minimum = positive(
+    input.minimumRequestsPerSecond,
+    'Minimum requests per second',
+  );
+  const maximum = positive(
+    input.maximumRequestsPerSecond,
+    'Maximum requests per second',
+  );
+  if (maximum < minimum) {
+    throw new Error('Maximum requests per second cannot be below the minimum.');
+  }
+  const current = Math.min(
+    maximum,
+    positive(input.currentRequestsPerSecond, 'Current requests per second'),
+  );
+  const additiveIncrease = positive(
+    input.additiveIncrease,
+    'Additive increase',
+  );
+  const decreaseFactor = input.decreaseFactor;
+  if (
+    !Number.isFinite(decreaseFactor) ||
+    decreaseFactor <= 0 ||
+    decreaseFactor > 1
+  ) {
+    throw new Error(
+      'Decrease factor must be greater than zero and at most one.',
+    );
+  }
+  if (input.event === 'healthy_epoch') {
+    return Math.min(maximum, current + additiveIncrease);
+  }
+  return Math.max(minimum, current * decreaseFactor);
+}
+
+export function providerRateControllerOptions(input: {
+  declaredRequestsPerSecond: number;
+  initialRequestsPerSecond?: number;
+  minimumRequestsPerSecond?: number;
+  maximumRequestsPerSecond?: number;
+}) {
+  const declared = positive(
+    input.declaredRequestsPerSecond,
+    'Declared requests per second',
+  );
+  const maximum = positive(
+    input.maximumRequestsPerSecond ?? declared,
+    'Maximum requests per second',
+  );
+  return Object.freeze({
+    initialRequestsPerSecond: input.initialRequestsPerSecond ?? declared,
+    minimumRequestsPerSecond:
+      input.minimumRequestsPerSecond ??
+      declared * PROVIDER_RATE_CONTROLLER_TUNING.minimumRateFraction,
+    maximumRequestsPerSecond: maximum,
+    epochMs: PROVIDER_RATE_CONTROLLER_TUNING.epochMs,
+    additiveIncrease:
+      declared * PROVIDER_RATE_CONTROLLER_TUNING.recoveryFraction,
+    startupProbeMultiplier:
+      PROVIDER_RATE_CONTROLLER_TUNING.startupProbeMultiplier,
+    decreaseFactor: PROVIDER_RATE_CONTROLLER_TUNING.decreaseFactor,
+    utilizationThreshold: PROVIDER_RATE_CONTROLLER_TUNING.utilizationThreshold,
+  });
+}

package/dist/bundling-sources/shared_libs/play-runtime/provider-capacity/provider-throttle-classifier.ts

@@ -0,0 +1,40 @@
+type ProviderConcurrencyGrantToken = Readonly<{
+  targetRequestsPerSecond?: number;
+  minimumRttMs?: number | null;
+}>;
+
+/**
+ * Classifies one provider 429 from shared rate and RTT evidence.
+ *
+ * An opaque 429 at more than one in-flight call cannot prove which provider
+ * dimension fired. Occupancy materially above the bandwidth-delay product is
+ * strong concurrency evidence; lower occupancy remains ambiguous rather than
+ * being mislabeled as rate pressure. The caller applies one cautious
+ * transition to both controllers for that ambiguous generation.
+ */
+export function classifyProviderThrottle(
+  input: Readonly<{
+    grant: ProviderConcurrencyGrantToken;
+    inFlightAtStart: number;
+  }>,
+): 'rate' | 'concurrency' | 'ambiguous' {
+  const rate = input.grant.targetRequestsPerSecond;
+  const minimumRttMs = input.grant.minimumRttMs;
+  if (
+    rate === undefined ||
+    minimumRttMs === undefined ||
+    minimumRttMs === null
+  ) {
+    // A provider rejecting its only active call cannot be proving a positive
+    // concurrent-request ceiling. At larger cold occupancies the signal is
+    // genuinely ambiguous, so both controllers take one cautious transition.
+    return input.inFlightAtStart <= 1 ? 'rate' : 'ambiguous';
+  }
+  const bandwidthDelayOccupancy = (rate * minimumRttMs) / 1_000;
+  const queueAllowance = Math.sqrt(Math.max(1, bandwidthDelayOccupancy));
+  return input.inFlightAtStart > bandwidthDelayOccupancy + queueAllowance
+    ? 'concurrency'
+    : input.inFlightAtStart <= 1
+      ? 'rate'
+      : 'ambiguous';
+}