deepline 0.3.44 → 0.3.46

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

@@ -0,0 +1,418 @@
+/**
+ * Sandbox Runs is the portable lifecycle boundary around a physical execution
+ * resource.  It is deliberately narrower than the scheduler attempt: it does
+ * not claim an attempt, choose retry policy, write a terminal, or delete a
+ * sandbox.  Its one non-negotiable rule is that a resource fact is durable
+ * before the runner command can be accepted.
+ */
+
+export type SandboxProvider = 'daytona' | 'modal' | 'local';
+
+/** A portable, credential-free description of one execution resource. */
+export type SandboxRunResource = {
+  provider: SandboxProvider;
+  resourceId: string;
+  billingStartedAtMs: number;
+  /** Provider ownership domain used later by the cleanup Adapter. */
+  routingDomain: string | null;
+  /** The scheduler's already-reserved soft-capacity slot, if managed. */
+  capacityLeaseId?: string;
+  maxBillingDurationSeconds?: number | null;
+};
+
+/** The scheduler's already claimed attempt; it is never a provider credential. */
+export type SandboxRunInput = {
+  attempt: {
+    runId: string;
+    number: number;
+  };
+  /** Opaque scheduler authority that the resource-fact Adapter fences. */
+  authority: {
+    fenceId: string;
+  };
+};
+
+/** A pre-code rejection is safe for the attempt policy to defer or retry. */
+export type SandboxPreCodeDeferralReason =
+  | 'capacity'
+  | 'provider_unavailable'
+  | 'rate_limited'
+  | 'startup_timeout';
+
+export type SandboxAcquisition<Handle> =
+  | {
+      kind: 'acquired';
+      resource: SandboxRunResource;
+      /** Private to the acquire/start Adapters; never persisted by this job. */
+      handle: Handle;
+    }
+  | { kind: 'pre_code_deferred'; reason: SandboxPreCodeDeferralReason }
+  /**
+   * A provider create may have crossed a local timeout. Its Adapter has kept
+   * a durable reconciliation obligation; this job must not acquire again.
+   */
+  | { kind: 'acquisition_unknown'; reason: string };
+
+/** The durable resource writer also binds capacity in the same fence. */
+export type SandboxResourceFacts = {
+  record(input: {
+    attempt: SandboxRunInput['attempt'];
+    authority: SandboxRunInput['authority'];
+    resource: SandboxRunResource;
+  }): Promise<{ kind: 'recorded' } | { kind: 'fence_lost' }>;
+};
+
+/** A scheduler-owned observation target, not a provider command or payload. */
+export type SandboxRunnerObservation = {
+  boundaryId: string;
+  baselineHeartbeatAt: string | null;
+};
+
+export type SandboxRunnerStart<Handle> = {
+  start(input: {
+    attempt: SandboxRunInput['attempt'];
+    resource: SandboxRunResource;
+    handle: Handle;
+  }): Promise<
+    | { kind: 'command_accepted'; observation: SandboxRunnerObservation }
+    /** The command is known not to have been accepted; cleanup owns resource release. */
+    | { kind: 'not_started'; reason: string }
+    /** Command acceptance cannot be proven either way; never acquire/replay. */
+    | { kind: 'start_unknown'; reason: string }
+  >;
+};
+
+export type SandboxRunnerObserver = {
+  observe(input: {
+    attempt: SandboxRunInput['attempt'];
+    resource: SandboxRunResource;
+    observation: SandboxRunnerObservation;
+  }): Promise<
+    | { kind: 'heartbeat_observed'; heartbeatAt: string }
+    | {
+        kind: 'terminal_observed';
+        terminal: 'completed' | 'failed' | 'cancelled';
+      }
+    /** The command could already be executing; caller must not replay it. */
+    | { kind: 'unconfirmed'; reason: string }
+  >;
+};
+
+export type SandboxRunDependencies<Handle> = {
+  acquire: {
+    acquire(input: SandboxRunInput): Promise<SandboxAcquisition<Handle>>;
+  };
+  resourceFacts: SandboxResourceFacts;
+  runner: SandboxRunnerStart<Handle>;
+  observer: SandboxRunnerObserver;
+};
+
+/** Canonical lifecycle outcomes consumed by the attempt policy. */
+export type SandboxRunOutcome =
+  | { kind: 'pre_code_deferred'; reason: SandboxPreCodeDeferralReason }
+  | { kind: 'acquisition_unknown'; reason: string }
+  /** A physical resource exists but the scheduler fence rejected its fact. */
+  | { kind: 'resource_recording_rejected'; resource: SandboxRunResource }
+  /** Resource fact exists; no command was accepted; cleanup is now authoritative. */
+  | {
+      kind: 'post_record_start_failed';
+      resource: SandboxRunResource;
+      reason: string;
+    }
+  /** Resource fact exists and command acceptance is ambiguous; no replay is safe. */
+  | {
+      kind: 'runner_start_unknown';
+      resource: SandboxRunResource;
+      reason: string;
+    }
+  | {
+      kind: 'parked';
+      resource: SandboxRunResource;
+      observation: SandboxRunnerObservation;
+      heartbeatAt: string;
+    }
+  | {
+      kind: 'terminal_observed';
+      resource: SandboxRunResource;
+      terminal: 'completed' | 'failed' | 'cancelled';
+    }
+  | {
+      kind: 'runner_start_unconfirmed';
+      resource: SandboxRunResource;
+      observation: SandboxRunnerObservation;
+      reason: string;
+    };
+
+export type SandboxRunsJob = {
+  execute(input: SandboxRunInput): Promise<SandboxRunOutcome>;
+};
+
+/**
+ * The rich Sandbox Runs boundary used by the real runner adapters.
+ *
+ * The legacy four-port contract above remains exported while callers migrate,
+ * but it cannot describe a production sandbox launch: Daytona may retire and
+ * recreate sandboxes, and Modal must record an ambiguity fence before create
+ * can begin.  This contract keeps those facts explicit without importing a
+ * scheduler, provider SDK, or runner payload into the portable library.
+ */
+
+export type SandboxExecutionMode<Checkpoint, Suspension> =
+  | { kind: 'fresh'; checkpoint: Checkpoint | null }
+  | {
+      kind: 'continuation';
+      checkpoint: Checkpoint;
+      /** A scheduler continuation can resume after a non-sandbox boundary. */
+      suspension: Suspension | null;
+    }
+  | {
+      /** Read persisted runner state; never create another sandbox first. */
+      kind: 'detached_observation';
+      checkpoint: Checkpoint;
+      suspension: Suspension;
+    };
+
+/** The launch is opaque here; only the runner/provider Adapter may interpret it. */
+export type SandboxExecutionInput<Launch, Checkpoint, Suspension> =
+  SandboxRunInput & {
+    launch: Launch;
+    mode: SandboxExecutionMode<Checkpoint, Suspension>;
+  };
+
+/**
+ * A resource fact has enough identity to be recovered and deleted safely. It
+ * deliberately excludes provider handles, commands, credentials, and payloads.
+ */
+export type SandboxExecutionResource = SandboxRunResource & {
+  kind: 'daytona_sandbox' | 'modal_sandbox' | 'local_process';
+  runtimeEnvironment?: 'preview' | 'production';
+  billingEndedAtMs?: number | null;
+  cpu?: number | null;
+  memoryGiB?: number | null;
+  diskGiB?: number | null;
+  /** A create settled after the launching attempt had already timed out. */
+  lateAcquired?: boolean;
+};
+
+export type SandboxCreateIntent = {
+  provider: 'modal';
+  routingDomain: string;
+  runtimeEnvironment: 'preview' | 'production';
+  /** Stable, non-secret provider correlation attributes only. */
+  correlation: Record<string, string>;
+  capacityLeaseId?: string;
+};
+
+export type SandboxProviderLifecycleEvent = {
+  provider: 'daytona' | 'modal';
+  type: 'create_call_started' | 'create_call_succeeded' | 'create_call_failed';
+  providerAttempt: number;
+  occurredAtMs: number;
+  resourceId?: string;
+  errorClass?: 'timeout' | 'capacity' | 'rate_limit' | 'other';
+};
+
+export type SandboxExecutionAdmission = {
+  beforeFirstProviderCreate(input: {
+    attempt: SandboxRunInput['attempt'];
+    authority: SandboxRunInput['authority'];
+  }): Promise<
+    | { kind: 'allowed' }
+    | { kind: 'pre_code_deferred'; reason: SandboxPreCodeDeferralReason }
+  >;
+  reserveCapacity(input: {
+    provider: Exclude<SandboxProvider, 'local'>;
+    /** Distinguishes provider retries within one scheduler attempt. */
+    providerAttempt?: number;
+  }): Promise<
+    | {
+        kind: 'reserved';
+        leaseId: string;
+        /** Stable provider correlation for operation-first managed creates. */
+        providerOperationToken?: string | null;
+      }
+    | { kind: 'pre_code_deferred'; reason: SandboxPreCodeDeferralReason }
+  >;
+  releaseCapacity(input: { leaseId: string }): Promise<void>;
+  claimProviderCircuit(input: {
+    provider: Exclude<SandboxProvider, 'local'>;
+  }): Promise<{ allowed: boolean; probeToken: string | null }>;
+  markProviderHealthy(input: {
+    provider: Exclude<SandboxProvider, 'local'>;
+    probeToken: string | null;
+  }): Promise<void>;
+};
+
+export type SandboxExecutionResourceFacts = {
+  record(input: {
+    attempt: SandboxRunInput['attempt'];
+    authority: SandboxRunInput['authority'];
+    resource: SandboxExecutionResource;
+  }): Promise<{ kind: 'recorded' } | { kind: 'fence_lost' }>;
+  /** A late create must become a cleanup obligation, never an invisible resource. */
+  recordLate(input: {
+    attempt: SandboxRunInput['attempt'];
+    authority: SandboxRunInput['authority'];
+    resource: SandboxExecutionResource;
+  }): Promise<{ kind: 'recorded' } | { kind: 'fence_lost' }>;
+};
+
+export type SandboxExecutionCreateIntents = {
+  record(input: {
+    attempt: SandboxRunInput['attempt'];
+    authority: SandboxRunInput['authority'];
+    intent: SandboxCreateIntent;
+  }): Promise<{ kind: 'recorded' } | { kind: 'fence_lost' }>;
+  resolve(input: {
+    attempt: SandboxRunInput['attempt'];
+    authority: SandboxRunInput['authority'];
+  }): Promise<{ kind: 'resolved' } | { kind: 'fence_lost' }>;
+};
+
+export type SandboxExecutionLifecycleEvents = {
+  record(input: {
+    attempt: SandboxRunInput['attempt'];
+    authority: SandboxRunInput['authority'];
+    event: SandboxProviderLifecycleEvent;
+  }): Promise<{ kind: 'recorded' } | { kind: 'fence_lost' }>;
+};
+
+/** The only capability a provider Adapter receives while executing a launch. */
+export type SandboxExecutionLifecycle = {
+  beforeFirstProviderCreate(): Promise<
+    | { kind: 'allowed' }
+    | { kind: 'pre_code_deferred'; reason: SandboxPreCodeDeferralReason }
+  >;
+  reserveCapacity(input: {
+    provider: Exclude<SandboxProvider, 'local'>;
+    /** Preserves one provider-create retry's durable operation identity. */
+    providerAttempt?: number;
+  }): Promise<
+    | {
+        kind: 'reserved';
+        leaseId: string;
+        /** Stable provider correlation for operation-first managed creates. */
+        providerOperationToken?: string | null;
+      }
+    | { kind: 'pre_code_deferred'; reason: SandboxPreCodeDeferralReason }
+  >;
+  releaseCapacity(input: { leaseId: string }): Promise<void>;
+  claimProviderCircuit(input: {
+    provider: Exclude<SandboxProvider, 'local'>;
+  }): Promise<{ allowed: boolean; probeToken: string | null }>;
+  markProviderHealthy(input: {
+    provider: Exclude<SandboxProvider, 'local'>;
+    probeToken: string | null;
+  }): Promise<void>;
+  recordCreateIntent(input: SandboxCreateIntent): Promise<void>;
+  resolveCreateIntent(): Promise<void>;
+  recordProviderLifecycleEvent(
+    input: SandboxProviderLifecycleEvent,
+  ): Promise<void>;
+  /** Must resolve before the Adapter can accept a command for this resource. */
+  recordResource(input: SandboxExecutionResource): Promise<void>;
+  /** Same durable rule for a create that settles after the caller timed out. */
+  recordLateResource(input: SandboxExecutionResource): Promise<void>;
+  /**
+   * Marks the non-replayable boundary. Remote providers require a previously
+   * recorded resource; local execution has no physical sandbox resource.
+   */
+  commandAccepted(input: {
+    provider: SandboxProvider;
+    resource?: SandboxExecutionResource;
+  }): void;
+  /** A detached runner cannot be parked until scheduler-owned readiness exists. */
+  runnerReady(input: {
+    provider: Exclude<SandboxProvider, 'local'>;
+    resource: SandboxExecutionResource;
+    observation: SandboxRunnerObservation;
+  }): void;
+};
+
+/** Outcome returned by the provider/runner Adapter after exactly one execution. */
+export type SandboxExecutionPortOutcome<RunnerResult> =
+  | { kind: 'pre_code_deferred'; reason: SandboxPreCodeDeferralReason }
+  | { kind: 'acquisition_unknown'; reason: string }
+  /** Provider or customer code may have started. The attempt must not replay. */
+  | { kind: 'post_code_unknown'; reason: string }
+  | {
+      kind: 'suspended';
+      runnerResult: RunnerResult;
+      /**
+       * Only a detached runner needs a scheduler-owned liveness proof before
+       * the worker parks. Ordinary Play boundaries (sleep, signal, etc.) do
+       * not create or observe a long-lived sandbox command.
+       */
+      requiresDetachedRunnerReadiness?: boolean;
+    }
+  | { kind: 'terminal'; runnerResult: RunnerResult };
+
+/**
+ * One invocation of the existing runner backend, not separate acquire/start
+ * calls. This preserves the provider boundary while moving its durable
+ * lifecycle callbacks behind the Sandbox Runs Module.
+ */
+export type SandboxExecutionPort<Launch, Checkpoint, Suspension, RunnerResult> =
+  {
+    execute(input: {
+      execution: SandboxExecutionInput<Launch, Checkpoint, Suspension>;
+      lifecycle: SandboxExecutionLifecycle;
+    }): Promise<SandboxExecutionPortOutcome<RunnerResult>>;
+  };
+
+export type SandboxExecutionDependencies<
+  Launch,
+  Checkpoint,
+  Suspension,
+  RunnerResult,
+> = {
+  execution: SandboxExecutionPort<Launch, Checkpoint, Suspension, RunnerResult>;
+  /** Every resource record binds its capacity lease in the scheduler fence. */
+  resourceFacts: SandboxExecutionResourceFacts;
+  /** Required when the Adapter crosses Modal's ambiguous-create boundary. */
+  createIntents?: SandboxExecutionCreateIntents;
+  /** Required when the Adapter emits provider-edge lifecycle evidence. */
+  lifecycleEvents?: SandboxExecutionLifecycleEvents;
+  /** Required when the Adapter opts into admission, capacity, or circuit policy. */
+  admission?: SandboxExecutionAdmission;
+};
+
+export type SandboxExecutionOutcome<RunnerResult> =
+  | { kind: 'pre_code_deferred'; reason: SandboxPreCodeDeferralReason }
+  | { kind: 'acquisition_unknown'; reason: string }
+  | {
+      kind: 'post_code_unknown';
+      reason: string;
+      resources: readonly SandboxExecutionResource[];
+    }
+  | {
+      kind: 'resource_recording_rejected';
+      resources: readonly SandboxExecutionResource[];
+    }
+  | {
+      kind: 'suspended';
+      runnerResult: RunnerResult;
+      resources: readonly SandboxExecutionResource[];
+    }
+  | {
+      kind: 'terminal';
+      runnerResult: RunnerResult;
+      resources: readonly SandboxExecutionResource[];
+    };
+
+export type SandboxExecutionJob<Launch, Checkpoint, Suspension, RunnerResult> =
+  {
+    execute(
+      input: SandboxExecutionInput<Launch, Checkpoint, Suspension>,
+    ): Promise<SandboxExecutionOutcome<RunnerResult>>;
+  };
+
+/** A fence loss must stop the Adapter before it can accept a provider command. */
+export class SandboxResourceFenceLostError extends Error {
+  constructor() {
+    super(
+      'Sandbox Runs lost its scheduler fence while recording a durable lifecycle fact.',
+    );
+    this.name = 'SandboxResourceFenceLostError';
+  }
+}