deepline 0.3.43 → 0.3.45

package/dist/bundling-sources/shared_libs/play-runtime/sandbox-runs/index.ts

@@ -0,0 +1,452 @@
+import type {
+  SandboxExecutionDependencies,
+  SandboxExecutionInput,
+  SandboxExecutionJob,
+  SandboxExecutionLifecycle,
+  SandboxExecutionOutcome,
+  SandboxExecutionPortOutcome,
+  SandboxExecutionResource,
+  SandboxRunDependencies,
+  SandboxRunInput,
+  SandboxRunsJob,
+} from './contract';
+import { SandboxResourceFenceLostError } from './contract';
+
+export type {
+  SandboxAcquisition,
+  SandboxCreateIntent,
+  SandboxExecutionAdmission,
+  SandboxExecutionCreateIntents,
+  SandboxExecutionDependencies,
+  SandboxExecutionInput,
+  SandboxExecutionJob,
+  SandboxExecutionLifecycle,
+  SandboxExecutionLifecycleEvents,
+  SandboxExecutionMode,
+  SandboxExecutionOutcome,
+  SandboxExecutionPort,
+  SandboxExecutionPortOutcome,
+  SandboxExecutionResource,
+  SandboxExecutionResourceFacts,
+  SandboxProviderLifecycleEvent,
+  SandboxPreCodeDeferralReason,
+  SandboxProvider,
+  SandboxResourceFacts,
+  SandboxRunDependencies,
+  SandboxRunInput,
+  SandboxRunOutcome,
+  SandboxRunResource,
+  SandboxRunnerObservation,
+  SandboxRunnerObserver,
+  SandboxRunnerStart,
+  SandboxRunsJob,
+} from './contract';
+
+export { SandboxResourceFenceLostError } from './contract';
+export {
+  createPlayRunnerBackendSandboxExecutionAdapter,
+  playRunnerRuntimeResourceFromSandboxExecutionResource,
+  type SandboxRunnerBackendAdapterDependencies,
+  type SandboxRunnerProgress,
+  type SandboxRunnerReadiness,
+  type SandboxRunnerResultInterpreter,
+} from './runner-backend-adapter';
+export { SandboxRunnerPreCodeDeferralError } from '../runner-backends/types';
+
+/**
+ * Creates the runner-portable Sandbox Runs job.
+ *
+ * The only sequencing decision hidden here is resource-fact-before-command:
+ * provider adapters may acquire, and scheduler adapters may fence/record, but
+ * neither can cause the runner command to start out of order.  Cleanup and
+ * attempt retry policy remain their own jobs because they have different
+ * durable authority.
+ */
+export function createSandboxRuns<Handle>(
+  dependencies: SandboxRunDependencies<Handle>,
+): SandboxRunsJob {
+  return {
+    async execute(input: SandboxRunInput) {
+      validateInput(input);
+      const acquisition = await dependencies.acquire.acquire(input);
+      if (acquisition.kind === 'pre_code_deferred') {
+        return acquisition;
+      }
+      if (acquisition.kind === 'acquisition_unknown') {
+        return acquisition;
+      }
+
+      validateResource(acquisition.resource);
+      const recorded = await dependencies.resourceFacts.record({
+        attempt: input.attempt,
+        authority: input.authority,
+        resource: acquisition.resource,
+      });
+      if (recorded.kind === 'fence_lost') {
+        return {
+          kind: 'resource_recording_rejected',
+          resource: acquisition.resource,
+        };
+      }
+
+      const started = await dependencies.runner.start({
+        attempt: input.attempt,
+        resource: acquisition.resource,
+        handle: acquisition.handle,
+      });
+      if (started.kind === 'not_started') {
+        return {
+          kind: 'post_record_start_failed',
+          resource: acquisition.resource,
+          reason: started.reason,
+        };
+      }
+      if (started.kind === 'start_unknown') {
+        return {
+          kind: 'runner_start_unknown',
+          resource: acquisition.resource,
+          reason: started.reason,
+        };
+      }
+
+      const observed = await dependencies.observer.observe({
+        attempt: input.attempt,
+        resource: acquisition.resource,
+        observation: started.observation,
+      });
+      if (observed.kind === 'heartbeat_observed') {
+        return {
+          kind: 'parked',
+          resource: acquisition.resource,
+          observation: started.observation,
+          heartbeatAt: observed.heartbeatAt,
+        };
+      }
+      if (observed.kind === 'terminal_observed') {
+        return {
+          kind: 'terminal_observed',
+          resource: acquisition.resource,
+          terminal: observed.terminal,
+        };
+      }
+      return {
+        kind: 'runner_start_unconfirmed',
+        resource: acquisition.resource,
+        observation: started.observation,
+        reason: observed.reason,
+      };
+    },
+  };
+}
+
+/**
+ * Creates the production-shaped Sandbox Runs job.
+ *
+ * The execution Adapter is deliberately one-shot: it wraps one invocation of
+ * a provider runner backend and reports durable lifecycle facts through the
+ * supplied capability. Splitting that Adapter into synthetic `acquire` and
+ * `start` calls would move the resource-fact fence after a provider boundary
+ * for the existing Daytona and Modal implementations.
+ */
+export function createSandboxExecutionJob<
+  Launch,
+  Checkpoint,
+  Suspension,
+  RunnerResult,
+>(
+  dependencies: SandboxExecutionDependencies<
+    Launch,
+    Checkpoint,
+    Suspension,
+    RunnerResult
+  >,
+): SandboxExecutionJob<Launch, Checkpoint, Suspension, RunnerResult> {
+  return {
+    async execute(input) {
+      validateInput(input);
+      const state = createExecutionLifecycle(input, dependencies);
+      try {
+        const outcome = await dependencies.execution.execute({
+          execution: input,
+          lifecycle: state.lifecycle,
+        });
+        return normalizeExecutionOutcome(outcome, state, input.mode.kind);
+      } catch (error) {
+        if (error instanceof SandboxResourceFenceLostError) {
+          return {
+            kind: 'resource_recording_rejected',
+            resources: state.resources(),
+          };
+        }
+        throw error;
+      }
+    },
+  };
+}
+
+function createExecutionLifecycle<Launch, Checkpoint, Suspension, RunnerResult>(
+  input: SandboxExecutionInput<Launch, Checkpoint, Suspension>,
+  dependencies: SandboxExecutionDependencies<
+    Launch,
+    Checkpoint,
+    Suspension,
+    RunnerResult
+  >,
+): {
+  lifecycle: SandboxExecutionLifecycle;
+  resources(): readonly SandboxExecutionResource[];
+  commandAccepted(): boolean;
+  runnerReady(): boolean;
+} {
+  const resources = new Map<string, SandboxExecutionResource>();
+  const acceptedResources = new Set<string>();
+  const commandAcceptedResources = new Set<string>();
+  let commandAccepted = false;
+  let runnerReady = false;
+
+  const requireAdmission = () => {
+    if (!dependencies.admission) {
+      throw new Error(
+        'Sandbox Runs execution Adapter requested scheduler admission, but no admission Adapter is configured.',
+      );
+    }
+    return dependencies.admission;
+  };
+  const requireCreateIntents = () => {
+    if (!dependencies.createIntents) {
+      throw new Error(
+        'Sandbox Runs execution Adapter crossed the Modal create boundary, but no create-intent Adapter is configured.',
+      );
+    }
+    return dependencies.createIntents;
+  };
+  const requireLifecycleEvents = () => {
+    if (!dependencies.lifecycleEvents) {
+      throw new Error(
+        'Sandbox Runs execution Adapter emitted a provider lifecycle event, but no lifecycle-event Adapter is configured.',
+      );
+    }
+    return dependencies.lifecycleEvents;
+  };
+  const recordResult = (
+    result: { kind: 'recorded' | 'resolved' } | { kind: 'fence_lost' },
+  ) => {
+    if (result.kind === 'fence_lost') throw new SandboxResourceFenceLostError();
+  };
+  const rememberResource = (resource: SandboxExecutionResource) => {
+    validateResource(resource);
+    resources.set(resourceIdentity(resource), resource);
+  };
+
+  return {
+    lifecycle: {
+      beforeFirstProviderCreate: async () =>
+        await requireAdmission().beforeFirstProviderCreate({
+          attempt: input.attempt,
+          authority: input.authority,
+        }),
+      reserveCapacity: async (value) =>
+        await requireAdmission().reserveCapacity(value),
+      releaseCapacity: async (value) =>
+        await requireAdmission().releaseCapacity(value),
+      claimProviderCircuit: async (value) =>
+        await requireAdmission().claimProviderCircuit(value),
+      markProviderHealthy: async (value) =>
+        await requireAdmission().markProviderHealthy(value),
+      recordCreateIntent: async (intent) => {
+        validateCreateIntent(intent);
+        recordResult(
+          await requireCreateIntents().record({
+            attempt: input.attempt,
+            authority: input.authority,
+            intent,
+          }),
+        );
+      },
+      resolveCreateIntent: async () => {
+        recordResult(
+          await requireCreateIntents().resolve({
+            attempt: input.attempt,
+            authority: input.authority,
+          }),
+        );
+      },
+      recordProviderLifecycleEvent: async (event) => {
+        validateLifecycleEvent(event);
+        recordResult(
+          await requireLifecycleEvents().record({
+            attempt: input.attempt,
+            authority: input.authority,
+            event,
+          }),
+        );
+      },
+      recordResource: async (resource) => {
+        rememberResource(resource);
+        recordResult(
+          await dependencies.resourceFacts.record({
+            attempt: input.attempt,
+            authority: input.authority,
+            resource,
+          }),
+        );
+        acceptedResources.add(resourceIdentity(resource));
+      },
+      recordLateResource: async (resource) => {
+        rememberResource(resource);
+        recordResult(
+          await dependencies.resourceFacts.recordLate({
+            attempt: input.attempt,
+            authority: input.authority,
+            resource,
+          }),
+        );
+      },
+      commandAccepted: ({ provider, resource }) => {
+        if (provider === 'local') {
+          if (resource) {
+            throw new Error(
+              'Sandbox Runs local command acceptance must not carry a physical sandbox resource.',
+            );
+          }
+          commandAccepted = true;
+          return;
+        }
+        if (!resource) {
+          throw new Error(
+            'Sandbox Runs requires a recorded physical resource before a remote command is accepted.',
+          );
+        }
+        const identity = resourceIdentity(resource);
+        if (!acceptedResources.has(identity)) {
+          throw new Error(
+            `Sandbox Runs cannot accept a ${provider} command before resource ${resource.resourceId} is durably recorded.`,
+          );
+        }
+        commandAccepted = true;
+        commandAcceptedResources.add(identity);
+      },
+      runnerReady: ({ provider, resource }) => {
+        const identity = resourceIdentity(resource);
+        if (
+          !acceptedResources.has(identity) ||
+          !commandAcceptedResources.has(identity)
+        ) {
+          throw new Error(
+            'Sandbox Runs cannot record detached-runner readiness before command acceptance and a durable resource fact.',
+          );
+        }
+        if (!commandAccepted) {
+          throw new Error(
+            'Sandbox Runs cannot record detached-runner readiness before command acceptance.',
+          );
+        }
+        runnerReady = true;
+      },
+    },
+    resources: () => [...resources.values()],
+    commandAccepted: () => commandAccepted,
+    runnerReady: () => runnerReady,
+  };
+}
+
+function normalizeExecutionOutcome<RunnerResult>(
+  outcome: SandboxExecutionPortOutcome<RunnerResult>,
+  state: {
+    resources(): readonly SandboxExecutionResource[];
+    commandAccepted(): boolean;
+    runnerReady(): boolean;
+  },
+  mode: 'fresh' | 'continuation' | 'detached_observation',
+): SandboxExecutionOutcome<RunnerResult> {
+  if (mode === 'detached_observation') {
+    if (state.commandAccepted() || state.resources().length > 0) {
+      throw new Error(
+        'Sandbox Runs detached observation must resolve persisted runner state before any resource create or command start.',
+      );
+    }
+  }
+  if (outcome.kind === 'pre_code_deferred') {
+    if (state.commandAccepted() || state.resources().length > 0) {
+      throw new Error(
+        'Sandbox Runs Adapter returned a pre-code deferral after a resource or command lifecycle boundary.',
+      );
+    }
+    return outcome;
+  }
+  if (outcome.kind === 'acquisition_unknown') return outcome;
+  if (outcome.kind === 'post_code_unknown') {
+    return { ...outcome, resources: state.resources() };
+  }
+  if (outcome.kind === 'suspended') {
+    if (outcome.requiresDetachedRunnerReadiness && !state.runnerReady()) {
+      throw new Error(
+        'Sandbox Runs Adapter returned a suspension without scheduler-owned detached-runner readiness.',
+      );
+    }
+    return { ...outcome, resources: state.resources() };
+  }
+  return { ...outcome, resources: state.resources() };
+}
+
+function resourceIdentity(resource: SandboxExecutionResource): string {
+  return `${resource.provider}:${resource.routingDomain ?? ''}:${resource.resourceId}`;
+}
+
+function validateCreateIntent(
+  intent: import('./contract').SandboxCreateIntent,
+): void {
+  required(intent.routingDomain, 'sandbox create intent routing domain');
+  for (const [key, value] of Object.entries(intent.correlation)) {
+    required(key, 'sandbox create intent correlation key');
+    required(value, 'sandbox create intent correlation value');
+  }
+}
+
+function validateLifecycleEvent(
+  event: import('./contract').SandboxProviderLifecycleEvent,
+): void {
+  if (
+    !Number.isSafeInteger(event.providerAttempt) ||
+    event.providerAttempt < 0
+  ) {
+    throw new Error('Sandbox Runs requires a non-negative provider attempt.');
+  }
+  if (!Number.isFinite(event.occurredAtMs) || event.occurredAtMs < 0) {
+    throw new Error(
+      'Sandbox Runs requires a non-negative lifecycle timestamp.',
+    );
+  }
+  if (event.resourceId !== undefined)
+    required(event.resourceId, 'sandbox lifecycle resource id');
+}
+
+function validateInput(input: SandboxRunInput): void {
+  required(input.attempt.runId, 'attempt run id');
+  if (!Number.isSafeInteger(input.attempt.number) || input.attempt.number < 0) {
+    throw new Error('Sandbox Runs requires a non-negative attempt number.');
+  }
+  required(input.authority.fenceId, 'attempt fence id');
+}
+
+function validateResource(resource: {
+  resourceId: string;
+  billingStartedAtMs: number;
+  routingDomain: string | null;
+}): void {
+  required(resource.resourceId, 'sandbox resource id');
+  if (
+    !Number.isFinite(resource.billingStartedAtMs) ||
+    resource.billingStartedAtMs < 0
+  ) {
+    throw new Error('Sandbox Runs requires a non-negative billing start time.');
+  }
+  if (resource.routingDomain !== null)
+    required(resource.routingDomain, 'sandbox routing domain');
+}
+
+function required(value: string, name: string): void {
+  if (!value?.trim()) {
+    throw new Error(`Sandbox Runs requires a non-empty ${name}.`);
+  }
+}