deepline 0.3.128 → 0.3.130

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

@@ -7,19 +7,41 @@
  * and tests cannot independently invent concurrency or timeout budgets.
  */
 export const RUNTIME_CAPACITY_POLICY = {
+  runtimePostgres: {
+    /** One process-local scheduler pool budget for every control-plane lane. */
+    schedulerPoolMaxClients: 2,
+  },
   absurd: {
     /** Warm floor for availability and deploy rollovers. */
     activeLaneMachines: 2,
-    /** 32 Machines x 8 claim slots permits 256 concurrent launch/resume legs. */
-    maxActiveLaneMachines: 32,
+    /** Keep worker pools and direct wake listeners below the shared DB budget. */
+    maxActiveLaneMachines: 8,
     workerSlotsPerMachine: 8,
-    /** Queue age is an escape hatch for small-but-stuck backlogs. */
-    scaleUpQueueAgeMs: 10_000,
+    /** React within one control interval when a due backlog is not draining. */
+    scaleUpQueueAgeMs: 1_000,
     /** Bound one Fly reconciliation without turning backlog into a stampede. */
     maxScaleUpMachinesPerReconcile: 4,
     /** Do not tear down burst capacity on the first empty observation. */
     scaleDownQuietMs: 120_000,
   },
+  executionRelay: {
+    /** Keep two relay Machines available for deploys and one-machine faults. */
+    minimumMachines: 2,
+    /** Bound relay spend and the blast radius of a bad demand signal. */
+    maxMachines: 16,
+    /** The local admission gate's per-Machine upstream permit ceiling. */
+    upstreamSlotsPerMachine: 192,
+    /** Grow before the local queue reaches its hard shed boundary. */
+    scaleUpUtilization: 0.75,
+    /** Retain a larger safety margin before removing burst capacity. */
+    scaleDownUtilization: 0.35,
+    /** One observation may add only a small bounded number of Machines. */
+    maxScaleUpMachinesPerReconcile: 2,
+    /** Reclaim burst capacity gradually after a long quiet window. */
+    maxScaleDownMachinesPerReconcile: 2,
+    /** Empty relay capacity must be quiet before it is reclaimed. */
+    scaleDownQuietMs: 120_000,
+  },
   receiptGateway: {
     admissionTimeoutMs: 10_000,
     /** End identical receipt-row work before the caller can overlap a retry. */
@@ -33,6 +55,9 @@ export const RUNTIME_CAPACITY_POLICY = {
      * once started, all eight execution slots may run concurrently.
      */
     daytonaConcurrentStartsPerProcess: 1,
+    /** Fleet-wide AIMD start pacing, separate from execution-slot scaling. */
+    daytonaInitialStartsPerMinute: 120,
+    daytonaMaximumStartsPerMinute: 600,
   },
 } as const;
 
@@ -95,6 +120,55 @@ export function desiredAbsurdLaneMachines(input: {
   return desired;
 }
 
+/**
+ * Execution-relay demand is the exact upstream admission state, not request
+ * count. Active permits consume capacity and waiting requests are an early
+ * backpressure signal. Scale up before the local gate begins shedding, but
+ * only by a bounded amount per controller observation. Scale down only after
+ * the aggregate relay is empty for the quiet window; the controller applies
+ * its own per-pass stop bound when it materializes this target.
+ */
+export function desiredExecutionRelayMachines(input: {
+  currentMachines?: number;
+  inFlight: number;
+  waiting: number;
+  idleForMs?: number;
+}): number {
+  const policy = RUNTIME_CAPACITY_POLICY.executionRelay;
+  const currentMachines = Math.max(
+    policy.minimumMachines,
+    nonNegativeInteger(input.currentMachines ?? policy.minimumMachines),
+  );
+  const inFlight = nonNegativeInteger(input.inFlight);
+  const waiting = nonNegativeInteger(input.waiting);
+  const targetSlots =
+    policy.upstreamSlotsPerMachine * policy.scaleUpUtilization;
+  let desired = Math.max(
+    policy.minimumMachines,
+    Math.ceil((inFlight + waiting) / targetSlots),
+  );
+
+  // A waiter means at least one Machine is already at its local admission
+  // boundary. Aggregate active work may still look below the fleet target
+  // when the other Machine(s) are quiet, so give the queue one extra slot.
+  if (waiting > 0) desired = Math.max(desired, currentMachines + 1);
+
+  desired = Math.min(
+    desired,
+    currentMachines + policy.maxScaleUpMachinesPerReconcile,
+    policy.maxMachines,
+  );
+
+  if (
+    inFlight === 0 &&
+    waiting === 0 &&
+    nonNegativeNumber(input.idleForMs ?? 0) < policy.scaleDownQuietMs
+  ) {
+    desired = Math.max(desired, currentMachines);
+  }
+  return desired;
+}
+
 function nonNegativeInteger(value: number): number {
   return Math.max(0, Math.floor(nonNegativeNumber(value)));
 }
@@ -104,6 +178,16 @@ function nonNegativeNumber(value: number): number {
 }
 
 export function assertRuntimeCapacityPolicy(): void {
+  if (
+    !Number.isInteger(
+      RUNTIME_CAPACITY_POLICY.runtimePostgres.schedulerPoolMaxClients,
+    ) ||
+    RUNTIME_CAPACITY_POLICY.runtimePostgres.schedulerPoolMaxClients < 1
+  ) {
+    throw new Error(
+      'Runtime scheduler pool client cap must be a positive integer.',
+    );
+  }
   if (
     !Number.isInteger(
       RUNTIME_CAPACITY_POLICY.sandboxAcquisition
@@ -116,6 +200,19 @@ export function assertRuntimeCapacityPolicy(): void {
       'Daytona sandbox-start concurrency must be a positive integer.',
     );
   }
+  const sandboxAcquisition = RUNTIME_CAPACITY_POLICY.sandboxAcquisition;
+  if (
+    !Number.isInteger(sandboxAcquisition.daytonaInitialStartsPerMinute) ||
+    !Number.isInteger(sandboxAcquisition.daytonaMaximumStartsPerMinute) ||
+    sandboxAcquisition.daytonaInitialStartsPerMinute <= 0 ||
+    sandboxAcquisition.daytonaInitialStartsPerMinute >
+      sandboxAcquisition.daytonaMaximumStartsPerMinute ||
+    sandboxAcquisition.daytonaMaximumStartsPerMinute > 600
+  ) {
+    throw new Error(
+      'Daytona sandbox-start AIMD rates must be positive integers with initial <= maximum <= 600/minute.',
+    );
+  }
   if (
     RUNTIME_CAPACITY_POLICY.receiptGateway.requestTimeoutMs <=
     RUNTIME_CAPACITY_POLICY.receiptGateway.admissionTimeoutMs
@@ -140,6 +237,19 @@ export function assertRuntimeCapacityPolicy(): void {
       'Active-lane minimum Machines cannot exceed the active-lane maximum.',
     );
   }
+  const relay = RUNTIME_CAPACITY_POLICY.executionRelay;
+  if (
+    relay.minimumMachines > relay.maxMachines ||
+    relay.upstreamSlotsPerMachine <= 0 ||
+    relay.scaleUpUtilization <= 0 ||
+    relay.scaleUpUtilization > 1 ||
+    relay.scaleDownUtilization <= 0 ||
+    relay.scaleDownUtilization > relay.scaleUpUtilization
+  ) {
+    throw new Error(
+      'Execution-relay capacity policy has invalid floor, ceiling, or utilization bounds.',
+    );
+  }
 }
 
 assertRuntimeCapacityPolicy();

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

@@ -58,10 +58,11 @@ export function resolveLegacyRuntimeReceiptWireFormat(
 }
 
 export function runtimeReceiptCompletionResponse<
-  T extends { output?: unknown },
+  T extends { output?: unknown; outputRef?: unknown },
 >(wireFormat: LegacyRuntimeReceiptWireFormat, receipt: T | null): T | null {
   if (!receipt || wireFormat < 3) return receipt;
-  const { output, ...ack } = receipt;
+  const { output, outputRef, ...ack } = receipt;
   void output;
+  void outputRef;
   return ack as T;
 }

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

@@ -10,9 +10,13 @@ export type PlayRuntimeSelection = {
   namespace: string;
   /** Explicit managed-sandbox executor. Omission preserves Daytona compatibility. */
   backend?: Extract<PlayRuntimeBackendId, 'daytona' | 'modal'>;
+  /** Durable placement contract for the selected Preview worker lane. */
+  sandboxPlacementPolicy?: string;
 };
 
 const PLAY_RUNTIME_NAMESPACE_PATTERN = /^[a-z][a-z0-9-]{0,30}$/;
+const PLAY_RUNTIME_SANDBOX_PLACEMENT_POLICY_PATTERN =
+  /^[a-z][a-z0-9_]*@[1-9][0-9]*$/;
 
 export function normalizePlayRuntimeNamespace(value: unknown): string | null {
   if (typeof value !== 'string') return null;
@@ -20,6 +24,21 @@ export function normalizePlayRuntimeNamespace(value: unknown): string | null {
   return PLAY_RUNTIME_NAMESPACE_PATTERN.test(normalized) ? normalized : null;
 }
 
+/**
+ * Policy membership is owned by the server-side policy catalogue. The shared
+ * selector only accepts a stable versioned id shape, so unknown policies fail
+ * loudly at the authority that knows which worker releases support them.
+ */
+export function normalizePlayRuntimeSandboxPlacementPolicy(
+  value: unknown,
+): string | null {
+  if (typeof value !== 'string') return null;
+  const normalized = value.trim();
+  return PLAY_RUNTIME_SANDBOX_PLACEMENT_POLICY_PATTERN.test(normalized)
+    ? normalized
+    : null;
+}
+
 /** Validate the selector as one value so the SDK and server cannot drift. */
 export function normalizePlayRuntimeSelection(
   value: unknown,
@@ -29,7 +48,10 @@ export function normalizePlayRuntimeSelection(
   if (
     Object.keys(record).some(
       (key) =>
-        key !== 'environment' && key !== 'namespace' && key !== 'backend',
+        key !== 'environment' &&
+        key !== 'namespace' &&
+        key !== 'backend' &&
+        key !== 'sandboxPlacementPolicy',
     ) ||
     record.environment !== 'preview'
   ) {
@@ -37,16 +59,31 @@ export function normalizePlayRuntimeSelection(
   }
   const namespace = normalizePlayRuntimeNamespace(record.namespace);
   if (!namespace) return null;
-  if (record.backend === undefined) {
-    return { environment: 'preview', namespace };
+  const sandboxPlacementPolicy =
+    record.sandboxPlacementPolicy === undefined
+      ? undefined
+      : normalizePlayRuntimeSandboxPlacementPolicy(
+          record.sandboxPlacementPolicy,
+        );
+  if (
+    record.sandboxPlacementPolicy !== undefined &&
+    sandboxPlacementPolicy === null
+  ) {
+    return null;
   }
   if (
+    record.backend !== undefined &&
     record.backend !== PLAY_RUNTIME_BACKENDS.daytona &&
     record.backend !== PLAY_RUNTIME_BACKENDS.modal
   ) {
     return null;
   }
-  return { environment: 'preview', namespace, backend: record.backend };
+  return {
+    environment: 'preview',
+    namespace,
+    ...(record.backend === undefined ? {} : { backend: record.backend }),
+    ...(sandboxPlacementPolicy ? { sandboxPlacementPolicy } : {}),
+  };
 }
 
 export function normalizePlayRuntimeEnvironment(