deepline 0.3.43 → 0.3.45

package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts

@@ -59,6 +59,11 @@ export interface RowState {
 
 export interface ToolCallRequest {
   callId: string;
+  /**
+   * Stable per-run call identity used to fence a forced provider operation
+   * when receipt coordination deliberately has no active lease.
+   */
+  logicalCallId?: string;
   cacheKey: string;
   /** Stable external-operation identity, independent of receipt serialization. */
   providerIdempotencyKeyBase?: string | null;
@@ -723,6 +728,12 @@ export interface ContextOptions {
   }) => Promise<void | {
     updated: number;
     staleDroppedKeys?: string[];
+    /**
+     * Keys initially fenced by a terminal write but verified by the
+     * runner-owned sheet session as terminal rows for this same run. These are
+     * idempotent settlements, not output that belongs to a newer run.
+     */
+    recoveredStaleKeys?: string[];
   }>;
   /**
    * Persists coalesced, non-terminal row patches before a map suspends.

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-session-execution.ts

@@ -358,6 +358,14 @@ export function prepareDetachedDaytonaRunner(input: {
   sessionId: string;
   readiness: DetachedRunnerReadinessPort;
   cancellation?: Promise<never>;
+  /** Invoked immediately after Daytona accepts the detached command. */
+  onCommandAccepted?: (
+    state: Extract<DetachedDaytonaRunnerState, { phase: 'command_accepted' }>,
+  ) => Promise<void> | void;
+  /** Invoked after scheduler-owned liveness is confirmed. */
+  onReady?: (
+    state: Extract<DetachedDaytonaRunnerState, { phase: 'ready' }>,
+  ) => Promise<void> | void;
 }): DetachedDaytonaRunnerSupervisor {
   const cancellation = input.cancellation ?? new Promise<never>(() => {});
   const sessionCreation = input.sandbox.process
@@ -409,6 +417,7 @@ export function prepareDetachedDaytonaRunner(input: {
         cmdId,
         baselineHeartbeatAt: baseline.heartbeatAt,
       };
+      await input.onCommandAccepted?.(state);
       await Promise.race([
         confirmDetachedDaytonaRunnerReady({
           sandbox: input.sandbox,
@@ -422,6 +431,7 @@ export function prepareDetachedDaytonaRunner(input: {
         cancellation,
       ]);
       state = { ...state, phase: 'ready' };
+      await input.onReady?.(state);
       return state;
     },
   };

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona.ts

@@ -8,6 +8,7 @@ import type {
 import {
   isRuntimeSandboxCapacityLimitError,
   RuntimeResourceFenceLostError,
+  SandboxRunnerPreCodeDeferralError,
 } from '../types';
 import { buildPlayRunnerBundle } from '../bundle';
 import { findPlayRunnerResult, parsePlayRunnerEvents } from '../runner-events';
@@ -1197,11 +1198,29 @@ export const daytonaPlayRunnerBackend: PlayRunnerBackend = {
           // Session allocation is independent of payload staging. Start it
           // now so Daytona control-plane latency overlaps compression/upload.
           const sessionId = `deepline-play-${randomUUID()}`;
+          const runnerAttempt = Math.max(
+            0,
+            Math.floor(config.context.runAttempt ?? 0),
+          );
           const detachedRunner = prepareDetachedDaytonaRunner({
             sandbox,
             sessionId,
             readiness: readRunnerReadiness,
             cancellation: cancellationPromise,
+            onCommandAccepted: async () => {
+              await callbacks?.onRunnerCommandAccepted?.({
+                provider: 'daytona',
+                sandboxId: sandbox.id,
+              });
+            },
+            onReady: async (ready) => {
+              await callbacks?.onDetachedRunnerReady?.({
+                provider: 'daytona',
+                sandboxId: sandbox.id,
+                boundaryId: `detached-runner:${push.runId}:${runnerAttempt}`,
+                baselineHeartbeatAt: ready.baselineHeartbeatAt,
+              });
+            },
           });
 
           const uploadStartedAt = Date.now();
@@ -1310,10 +1329,6 @@ export const daytonaPlayRunnerBackend: PlayRunnerBackend = {
             // classification below decide fresh-sandbox retry vs loud failure.
             throw error;
           }
-          const runnerAttempt = Math.max(
-            0,
-            Math.floor(config.context.runAttempt ?? 0),
-          );
           emitDaytonaStage(callbacks, config.context, 'execute:detached', {
             sandboxId: sandbox.id,
             sessionId: start.sessionId,
@@ -1435,6 +1450,9 @@ export const daytonaPlayRunnerBackend: PlayRunnerBackend = {
       if (isRuntimeSandboxCapacityLimitError(error)) {
         throw error;
       }
+      if (error instanceof SandboxRunnerPreCodeDeferralError) {
+        throw error;
+      }
       if (error instanceof DaytonaSandboxAcquisitionUnavailableError) {
         throw error;
       }

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/modal.ts

@@ -3,6 +3,7 @@ import type { PlayRunnerBackend, PlayRunnerCallbacks } from '../types';
 import {
   isRuntimeSandboxCapacityLimitError,
   RuntimeResourceFenceLostError,
+  SandboxRunnerPreCodeDeferralError,
 } from '../types';
 import { buildPlayRunnerBundle } from '../bundle';
 import type {
@@ -618,6 +619,10 @@ export const modalPlayRunnerBackend: PlayRunnerBackend = {
           cancellationPromise,
         ]);
         runtimeTiming.modalExecuteMs = Date.now() - executeStartedAt;
+        await callbacks?.onRunnerCommandAccepted?.({
+          provider: 'modal',
+          sandboxId: sandbox.sandboxId,
+        });
         // A readiness observation after the command is accepted is ambiguous:
         // the detached runner may already have received its durable park and
         // started customer code while this worker cannot read the scheduler.
@@ -627,16 +632,22 @@ export const modalPlayRunnerBackend: PlayRunnerBackend = {
           baselineHeartbeatAt,
           cancellation: cancellationPromise,
         });
+        const runnerAttempt = Math.max(
+          0,
+          Math.floor(config.context.runAttempt ?? 0),
+        );
+        await callbacks?.onDetachedRunnerReady?.({
+          provider: 'modal',
+          sandboxId: sandbox.sandboxId,
+          boundaryId: `detached-runner:${push.runId}:${runnerAttempt}`,
+          baselineHeartbeatAt,
+        });
         if (callbacks?.cancellationSignal?.aborted) {
           throw new Error('Modal play runner cancelled');
         }
 
         detached = true;
         sandbox.detach();
-        const runnerAttempt = Math.max(
-          0,
-          Math.floor(config.context.runAttempt ?? 0),
-        );
         emitModalStage(config.context, 'execute:detached', {
           sandboxId: sandbox.sandboxId,
           runnerAttempt,
@@ -716,6 +727,7 @@ export const modalPlayRunnerBackend: PlayRunnerBackend = {
       if (
         error === runtimeResourceRegistrationError ||
         error instanceof RuntimeResourceFenceLostError ||
+        error instanceof SandboxRunnerPreCodeDeferralError ||
         isRuntimeSandboxCapacityLimitError(error) ||
         isPlayRunRecoveryError(error)
       ) {

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/types.ts

@@ -79,6 +79,26 @@ export type PlayRunnerRuntimeLifecycleEvent = {
   errorClass?: 'timeout' | 'capacity' | 'rate_limit' | 'other';
 };
 
+/**
+ * The provider has accepted the detached runner command. This is deliberately
+ * smaller than a runner payload: the scheduler needs only the physical
+ * resource identity to cross the no-replay boundary.
+ */
+export type PlayRunnerCommandAcceptance = {
+  provider: 'daytona' | 'modal';
+  sandboxId: string;
+};
+
+/**
+ * Scheduler-owned liveness was observed after a detached command was
+ * accepted. A backend must emit this only immediately before it returns a
+ * detached suspension.
+ */
+export type PlayRunnerDetachedRunnerReady = PlayRunnerCommandAcceptance & {
+  boundaryId: string;
+  baselineHeartbeatAt: string | null;
+};
+
 export class RuntimeResourceFenceLostError extends Error {
   constructor(message: string) {
     super(message);
@@ -94,6 +114,27 @@ export class RuntimeResourceFenceLostError extends Error {
 export const RUNTIME_SANDBOX_CAPACITY_LIMIT_ERROR_NAME =
   'RuntimeSandboxCapacityLimitError';
 
+/**
+ * A scheduler admission decision reached the legacy runner protocol before a
+ * provider create. Backends rethrow it verbatim so the Sandbox Runs Adapter can
+ * preserve a retry-safe `pre_code_deferred` outcome instead of manufacturing a
+ * runner failure.
+ */
+export class SandboxRunnerPreCodeDeferralError extends Error {
+  constructor(
+    readonly reason:
+      | 'capacity'
+      | 'provider_unavailable'
+      | 'rate_limited'
+      | 'startup_timeout',
+  ) {
+    super(
+      `Sandbox Runs deferred fresh execution before provider create: ${reason}.`,
+    );
+    this.name = 'SandboxRunnerPreCodeDeferralError';
+  }
+}
+
 export function isRuntimeSandboxCapacityLimitError(
   error: unknown,
 ): error is Error {
@@ -155,6 +196,21 @@ export interface PlayRunnerCallbacks {
   onRuntimeLifecycleEvent?: (
     event: PlayRunnerRuntimeLifecycleEvent,
   ) => Promise<void>;
+  /**
+   * Marks the command acceptance no-replay boundary. This is separate from a
+   * resource acquisition because a recorded sandbox can still fail staging
+   * before customer code is accepted.
+   */
+  onRunnerCommandAccepted?: (
+    acceptance: PlayRunnerCommandAcceptance,
+  ) => void | Promise<void>;
+  /**
+   * Marks the scheduler-owned readiness that makes a detached suspension safe
+   * to park. It is never a provider heartbeat or a runner payload callback.
+   */
+  onDetachedRunnerReady?: (
+    readiness: PlayRunnerDetachedRunnerReady,
+  ) => void | Promise<void>;
   /**
    * Scheduler-owned readiness read for a detached runner attempt. Daytona uses
    * this direct control-plane port before parking; it is never serialized into

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';
+  }
+}