deepline 0.3.89 → 0.3.90

package/dist/bundling-sources/shared_libs/play-runtime/internal-step-ids.ts

@@ -4,9 +4,9 @@
  * Static analysis turns top-level play statements it cannot attribute to a
  * structured step into `run_javascript` glue substeps whose alias is a
  * machine-generated source line range (`lines_<startLine>_<endLine>`, built in
- * `src/lib/plays/static-analysis.ts` → `createCodeStageForStatements`). The
+ * `apps/deepline-api/src/lib/plays/static-analysis.ts` → `createCodeStageForStatements`). The
  * execution plan / runtime node ids namespace every substep by its type
- * (`getStaticSubstepNodeId` in `src/lib/plays/step-progress.ts`), so glue nodes are ALWAYS
+ * (`getStaticSubstepNodeId` in `packages/play-runtime/step-progress.ts`), so glue nodes are ALWAYS
  * `run_javascript:<alias>` on the wire (ledger stepsById, snapshot
  * nodeStates, `play.step.*` stream events).
  *

package/dist/bundling-sources/shared_libs/play-runtime/lane-retirement-gate.ts

@@ -5,7 +5,7 @@
  * reach exactly the same verdict and none of them may drag the others'
  * dependencies in:
  *
- *   - the Next.js app (`src/lib/plays/runtime-lanes.ts`, the admin and internal
+ *   - the Next.js app (`apps/deepline-api/src/lib/plays/runtime-lanes.ts`, the admin and internal
  *     lane endpoints), which also talks to Convex;
  *   - `scripts/fly-absurd-lane.ts` retire, run by the release controller; and
  *   - `apps/absurd-release-scaler/index.ts`, which owns retirement of every lane

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

@@ -0,0 +1,112 @@
+/**
+ * Queue-admission policy is about *how the run was invoked*, not whether its
+ * artifact is published, ad-hoc, or draft. A manual API run can launch a
+ * published artifact, while a webhook can launch a draft artifact.
+ */
+export type PlayLaunchTriggerSource =
+  | 'api'
+  | 'webhook'
+  | 'cron'
+  | 'sql_listener'
+  | 'async_child';
+
+export type PlayLaunchQueuePolicy = {
+  triggerSource: PlayLaunchTriggerSource;
+  /**
+   * Relative ordering within one scheduler queue. This only decides which
+   * runnable run gets a newly available worker/sandbox slot; it never
+   * preempts a running customer sandbox or bypasses cross-org fairness.
+   */
+  priority: number;
+  /**
+   * Absurd's maximum time waiting to be claimed, in seconds. `null` means the
+   * accepted launch is allowed to wait durably for capacity.
+   */
+  maxDelaySeconds: number | null;
+  /**
+   * Maximum total time an accepted run may wait for a live sandbox slot. This
+   * is evaluated by the worker after a claim, where Absurd's `max_delay`
+   * cannot help. Zero gives an interactive caller an immediate, typed
+   * capacity-full result instead of a stuck watch.
+   */
+  sandboxCapacityMaxWaitSeconds: number | null;
+};
+
+export function shouldTerminalizeSandboxCapacityRejection(input: {
+  triggerSource?: PlayLaunchTriggerSource | null;
+  submittedAtMs?: number | null;
+  nowMs?: number;
+}): boolean {
+  const policy = resolvePlayLaunchQueuePolicy(input.triggerSource);
+  const maxWaitSeconds = policy.sandboxCapacityMaxWaitSeconds;
+  if (maxWaitSeconds === 0) return true;
+  if (maxWaitSeconds === null) return false;
+  const submittedAtMs = input.submittedAtMs;
+  if (
+    typeof submittedAtMs !== 'number' ||
+    !Number.isFinite(submittedAtMs) ||
+    submittedAtMs <= 0
+  ) {
+    // Old launch rows did not persist submit time. Preserve their historical
+    // durable behavior rather than making an age guess at execution time.
+    return false;
+  }
+  return (input.nowMs ?? Date.now()) >= submittedAtMs + maxWaitSeconds * 1_000;
+}
+
+/**
+ * Resolve the single queue-admission policy for every top-level play launch.
+ *
+ * Missing source is deliberately manual/API for backwards-compatible direct
+ * callers of `startPlayRunExecution`; webhook and cron callers must opt into
+ * their durable trigger source explicitly.
+ */
+export function resolvePlayLaunchQueuePolicy(
+  triggerSource?: PlayLaunchTriggerSource | null,
+): PlayLaunchQueuePolicy {
+  switch (triggerSource ?? 'api') {
+    case 'api':
+      return {
+        triggerSource: 'api',
+        // A person waiting in the CLI/UI should get the next slot in their
+        // own organization rather than sitting behind that org's automation.
+        // The bounded deadline gives the caller a typed terminal outcome
+        // instead of an indefinite watch.
+        priority: 100,
+        maxDelaySeconds: 10,
+        sandboxCapacityMaxWaitSeconds: 0,
+      };
+    case 'webhook':
+      return {
+        triggerSource: 'webhook',
+        priority: 0,
+        // A 202 webhook response is a durable delivery promise. Capacity is
+        // not a delivery failure: retain it until it executes, is explicitly
+        // cancelled, or an operator terminalizes it. Interactive API launches
+        // remain separately bounded above.
+        maxDelaySeconds: null,
+        sandboxCapacityMaxWaitSeconds: null,
+      };
+    case 'cron':
+      return {
+        triggerSource: 'cron',
+        priority: -10,
+        maxDelaySeconds: 30 * 60,
+        sandboxCapacityMaxWaitSeconds: 30 * 60,
+      };
+    case 'sql_listener':
+      return {
+        triggerSource: 'sql_listener',
+        priority: -10,
+        maxDelaySeconds: 30 * 60,
+        sandboxCapacityMaxWaitSeconds: 30 * 60,
+      };
+    case 'async_child':
+      return {
+        triggerSource: 'async_child',
+        priority: 0,
+        maxDelaySeconds: null,
+        sandboxCapacityMaxWaitSeconds: null,
+      };
+  }
+}

package/dist/bundling-sources/shared_libs/play-runtime/map-execution-frame.ts

@@ -10,6 +10,14 @@ export function cloneMapFrame(frame: MapExecutionFrame): MapExecutionFrame {
     ...frame,
     completedRowKeys: [...frame.completedRowKeys],
     pendingRowKeys: [...frame.pendingRowKeys],
+    ...(frame.suspendedInputRows
+      ? {
+          suspendedInputRows: frame.suspendedInputRows.map((row) => ({
+            inputIndex: row.inputIndex,
+            data: { ...row.data },
+          })),
+        }
+      : {}),
   };
 }
 

package/dist/bundling-sources/shared_libs/play-runtime/perf-trace.ts

@@ -0,0 +1,127 @@
+/**
+ * Structured per-run perf trace for play execution.
+ *
+ * Each call emits a single line JSON object prefixed with `[perf-trace]` to
+ * stdout. Server-side callers (Next.js dev server) ALSO append the same JSON
+ * object to `logs/perf-<runId>.jsonl` so post-mortem aggregation works even
+ * when stdout has been multiplexed across many runs.
+ *
+ * This is intentionally additive — it does NOT replace the existing
+ * `[perf][plays.start_run]` console.info lines that other tooling parses.
+ *
+ * Benchmark trace map:
+ *   - `apps/deepline-api/src/app/api/v2/plays/run/route.ts` records start-route and watch/terminal
+ *     spans, including the old "terminal wait" bucket.
+ *   - `packages/play-runtime/scheduler-backends/*` and
+ *     the submit path records scheduler submit
+ *     and workflow-create spans.
+ *   - the runner records execution,
+ *     dataset, ledger, billing, and terminalization spans.
+ *   - `scripts/analyze-v2-sdk-cli-benchmark.ts` reads these from local
+ *     `logs/perf-*.jsonl`, dev logs, or exported Axiom JSONL.
+ *
+ * Design constraints:
+ *   - Workerd-safe (Cloudflare Workers can't touch the filesystem). When
+ *     `appendFileSync` isn't available we degrade silently to stdout-only.
+ *   - No new dependencies; just `node:fs`.
+ *   - Loud failures are NOT desired here — perf instrumentation must never
+ *     break a real play run. We swallow FS errors, but never silently drop
+ *     the stdout copy.
+ */
+
+import {
+  createTelemetry,
+  type TelemetryEvent,
+  type TelemetryFields,
+} from '../observability/telemetry';
+
+export type PerfTraceEvent = {
+  ts?: number;
+  source: 'server' | 'coordinator' | 'dynamic_worker' | 'runner';
+  runId: string;
+  orgId?: string | null;
+  phase: string;
+  ms: number;
+  playName?: string;
+  graphHash?: string | null;
+  workerUrl?: string | null;
+  bytes?: number;
+  extra?: Record<string, unknown>;
+};
+
+const PERF_TRACE_PREFIX = '[perf-trace]';
+
+let cachedAppendFile: ((path: string, data: string) => void) | null | undefined;
+
+function getAppendFile(): ((path: string, data: string) => void) | null {
+  if (cachedAppendFile !== undefined) return cachedAppendFile;
+  try {
+    // Avoid bundling this into edge runtime call paths. Synchronous CJS
+    // require() is the right tool here: workerd will throw on load and we
+    // fall through to the null branch, which keeps the stdout-only path.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const fs = require('node:fs') as typeof import('node:fs');
+    cachedAppendFile = (path: string, data: string) => {
+      try {
+        fs.mkdirSync('logs', { recursive: true });
+        fs.appendFileSync(path, data);
+      } catch {
+        // Filesystem unavailable (workerd / read-only FS). Drop the sidecar
+        // copy; the stdout JSON line is still emitted by recordPerfTrace.
+      }
+    };
+  } catch {
+    cachedAppendFile = null;
+  }
+  return cachedAppendFile;
+}
+
+const perfTraceTelemetry = createTelemetry({
+  service: 'play-runtime',
+  component: 'perf-trace',
+  adapter: {
+    emit(event: TelemetryEvent) {
+      const json = JSON.stringify(event);
+      console.log(`${PERF_TRACE_PREFIX} ${json}`);
+      if (event.source === 'server' && typeof event.runId === 'string') {
+        getAppendFile()?.(
+          `logs/perf-${sanitizeRunIdForFilename(event.runId)}.jsonl`,
+          `${json}\n`,
+        );
+      }
+    },
+  },
+});
+
+function perfTraceFields(event: PerfTraceEvent): TelemetryFields {
+  return {
+    ts: typeof event.ts === 'number' ? event.ts : Date.now(),
+    source: event.source,
+    phase: event.phase,
+    ms: event.ms,
+    graphHash: event.graphHash ?? null,
+    workerUrl: event.workerUrl ?? null,
+    bytes: event.bytes,
+    ...(event.extra ?? {}),
+  };
+}
+
+export function recordPerfTrace(event: PerfTraceEvent): void {
+  const { runId, phase } = event;
+  if (!runId || !phase) return;
+  const orgId =
+    event.orgId ??
+    (typeof event.extra?.orgId === 'string' ? event.extra.orgId : null);
+  void perfTraceTelemetry
+    .child({
+      component: event.source,
+      context: { runId, orgId, playName: event.playName ?? null },
+    })
+    .info(phase, perfTraceFields(event), { tag: PERF_TRACE_PREFIX });
+}
+
+function sanitizeRunIdForFilename(runId: string): string {
+  return runId.replace(/[^a-zA-Z0-9._-]+/g, '_');
+}
+
+export const PERF_TRACE_LINE_PREFIX = PERF_TRACE_PREFIX;

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

@@ -24,6 +24,8 @@ import {
  */
 export type PlayArtifactRuntimeContract = Readonly<{
   semantics: PlayRuntimeSemantics;
+  /** Additive artifact fact; missing persisted fields resolve to `park`. */
+  slackHitlTimeoutOutcome: 'park' | 'error';
   toolErrorSchemaVersion: ToolExecutionErrorSchemaVersion;
   toolResponseContract: ToolResponseContract;
   toolResponseReceiptRevision?: string;
@@ -31,6 +33,7 @@ export type PlayArtifactRuntimeContract = Readonly<{
 
 export type PlayArtifactRuntimeContractInput = {
   authoringContractEdition?: PlayAuthoringContractEdition | null;
+  slackHitlTimeoutOutcome?: 'park' | 'error' | null;
   toolResponseContract?: ToolResponseContract | null;
   toolResponseReceiptRevision?: string | null;
 };
@@ -50,6 +53,8 @@ export function resolvePlayArtifactRuntimeContract(
     semantics: resolvePlayRuntimeSemantics(
       input.authoringContractEdition ?? PLAY_AUTHORING_CONTRACT_EDITION,
     ),
+    slackHitlTimeoutOutcome:
+      input.slackHitlTimeoutOutcome === 'error' ? 'error' : 'park',
     // Historic string-only failures are deliberately upgraded at the runtime
     // boundary. Rehydrating an old artifact must not regress a structured
     // durable failure into an unbranchable string.

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

@@ -41,6 +41,7 @@ export type PlayRunRecoveryReason =
   | 'modal_circuit_open_before_execution'
   | 'modal_sandbox_unavailable_before_execution'
   | 'modal_runner_start_failed_before_execution'
+  | 'daytona_sandbox_transition_pending_before_execution'
   | 'runtime_initialization_transport_before_execution'
   | 'runtime_traffic_hold_before_execution'
   | 'runtime_traffic_throttled_before_execution';
@@ -209,6 +210,27 @@ export function recoveryForRuntimeTrafficPolicy(input: {
   });
 }
 
+/**
+ * Daytona acknowledged a named sandbox but has not finished creating it.
+ * Resume that durable provider operation after a bounded defer; another
+ * provider or a fresh Daytona create could execute the same Play twice.
+ */
+export function recoveryForDaytonaSandboxTransitionPending(
+  error: unknown,
+): PlayRunRecoveryError {
+  return new PlayRunRecoveryError({
+    decision: {
+      stage: 'pre_code',
+      action: 'defer',
+      reason: 'daytona_sandbox_transition_pending_before_execution',
+      dependency: 'runtime',
+    },
+    message:
+      'Daytona is still finishing a named sandbox create before customer execution began.',
+    cause: error,
+  });
+}
+
 /**
  * This is constructed only by the detached-runner readiness check.  That
  * check has not parked the runner or observed scheduler liveness, so it is a
@@ -241,7 +263,8 @@ export function recoveryForRuntimeInitializationTransportFailure(
     | 'runtime_postgres_connect'
     | 'runtime_api_transport'
     | 'runtime_receipt_gateway_transport'
-    | 'daytona_public_status',
+    | 'daytona_public_status'
+    | 'daytona_runner_startup_transport',
 ): PlayRunRecoveryError {
   return new PlayRunRecoveryError({
     decision: {

package/dist/bundling-sources/shared_libs/play-runtime/play-runs/admission/contracts.ts

@@ -0,0 +1,56 @@
+import type { PlaySchedulerSubmitInput } from '../../scheduler-backend';
+
+/**
+ * A fully prepared Play Run is ready to cross the one durable admission
+ * boundary.  Construction, artifact validation, token minting, and provider
+ * resolution are intentionally finished before this value exists.
+ */
+export type PlayRunAdmissionInput = {
+  launch: PlaySchedulerSubmitInput;
+  queueName: string;
+  recoverExistingTask?: boolean;
+};
+
+/** The durable facts returned by one atomic launch-row + queue-task commit. */
+export type PlayRunAdmissionReceipt = {
+  taskId: string | null;
+  runCreated: boolean;
+  taskCreated: boolean;
+  taskRecoveryRequired: boolean;
+};
+
+/**
+ * The outcome makes the three useful cases explicit to callers.  A retry may
+ * either observe its original queue task or repair the historical row-first
+ * crash window; it never creates a second Play Run.
+ */
+export type PlayRunAdmissionOutcome =
+  | {
+      kind: 'created';
+      receipt: PlayRunAdmissionReceipt;
+    }
+  | {
+      kind: 'recovered';
+      receipt: PlayRunAdmissionReceipt;
+    }
+  | {
+      kind: 'replayed';
+      receipt: PlayRunAdmissionReceipt;
+    };
+
+export type PlayRunAdmissionJob = {
+  admit(input: PlayRunAdmissionInput): Promise<PlayRunAdmissionOutcome>;
+};
+
+/** A stable, machine-readable rejection for a reused run id with new intent. */
+export class PlayRunLaunchConflictError extends Error {
+  readonly code = 'PLAY_RUN_LAUNCH_CONFLICT';
+
+  constructor(runId: string, options?: { cause?: unknown }) {
+    super(
+      `Play run "${runId}" already exists with a different launch.`,
+      options,
+    );
+    this.name = 'PlayRunLaunchConflictError';
+  }
+}

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

@@ -0,0 +1,13 @@
+export { createPlayRunAdmissionJob } from '../../play-runs/admission/job';
+export { createPostgresPlayRunAdmissionPorts } from '../../play-runs/admission/postgres-adapter';
+export { PlayRunLaunchConflictError } from '../../play-runs/admission/contracts';
+export type {
+  PlayRunAdmissionInput,
+  PlayRunAdmissionJob,
+  PlayRunAdmissionOutcome,
+  PlayRunAdmissionReceipt,
+} from '../../play-runs/admission/contracts';
+export type {
+  AtomicPlayRunQueueSubmitter,
+  PlayRunAdmissionPorts,
+} from '../../play-runs/admission/ports';

package/dist/bundling-sources/shared_libs/play-runtime/play-runs/admission/job.ts

@@ -0,0 +1,41 @@
+import {
+  type PlayRunAdmissionInput,
+  type PlayRunAdmissionJob,
+  type PlayRunAdmissionOutcome,
+} from '../../play-runs/admission/contracts';
+import type { PlayRunAdmissionPorts } from '../../play-runs/admission/ports';
+
+/**
+ * Play Run Admission owns the idempotency law for the launch boundary:
+ *
+ *   exact launch retry -> original task
+ *   existing queued row without task -> repair that row
+ *   same run id + changed launch -> reject
+ *
+ * The storage Adapter enforces identity and atomicity.  This job exposes the
+ * result without leaking SQL rows, scheduler queues, or task engine details.
+ */
+export function createPlayRunAdmissionJob(
+  ports: PlayRunAdmissionPorts,
+): PlayRunAdmissionJob {
+  return {
+    async admit(
+      input: PlayRunAdmissionInput,
+    ): Promise<PlayRunAdmissionOutcome> {
+      validate(input);
+      const receipt = await ports.atomicQueueSubmitter.submit(input);
+      if (receipt.runCreated) return { kind: 'created', receipt };
+      if (receipt.taskCreated) return { kind: 'recovered', receipt };
+      return { kind: 'replayed', receipt };
+    },
+  };
+}
+
+function validate(input: PlayRunAdmissionInput): void {
+  if (!input.launch.runId.trim()) {
+    throw new Error('Play Run Admission requires a non-empty run id.');
+  }
+  if (!input.queueName.trim()) {
+    throw new Error('Play Run Admission requires a non-empty queue name.');
+  }
+}

package/dist/bundling-sources/shared_libs/play-runtime/play-runs/admission/ports.ts

@@ -0,0 +1,17 @@
+import type {
+  PlayRunAdmissionInput,
+  PlayRunAdmissionReceipt,
+} from '../../play-runs/admission/contracts';
+
+/**
+ * This port is deliberately one operation.  Persisting a run and enqueueing
+ * it separately creates an unrepairable ambiguity: either can succeed after a
+ * lost reply.  The implementation must commit both facts atomically.
+ */
+export type AtomicPlayRunQueueSubmitter = {
+  submit(input: PlayRunAdmissionInput): Promise<PlayRunAdmissionReceipt>;
+};
+
+export type PlayRunAdmissionPorts = {
+  atomicQueueSubmitter: AtomicPlayRunQueueSubmitter;
+};

package/dist/bundling-sources/shared_libs/play-runtime/play-runs/admission/postgres-adapter.ts

@@ -0,0 +1,54 @@
+import {
+  submitPostgresAbsurdPlayRun,
+  type PostgresSchedulerQueryClient,
+} from '../../scheduler-backends/postgres';
+import {
+  PlayRunLaunchConflictError,
+  type PlayRunAdmissionInput,
+  type PlayRunAdmissionReceipt,
+} from '../../play-runs/admission/contracts';
+import type { PlayRunAdmissionPorts } from '../../play-runs/admission/ports';
+
+/**
+ * PostgreSQL/Absurd implementation of the admission seam.  The delegated
+ * statement persists `runs` and invokes `absurd.spawn_task` in one data-
+ * modifying CTE; no caller can observe a persisted runnable Play Run without
+ * its corresponding queue task.
+ */
+export function createPostgresPlayRunAdmissionPorts(input: {
+  client: PostgresSchedulerQueryClient;
+  schema?: string;
+}): PlayRunAdmissionPorts {
+  const options = input.schema ? { schema: input.schema } : undefined;
+  return {
+    atomicQueueSubmitter: {
+      async submit(
+        admission: PlayRunAdmissionInput,
+      ): Promise<PlayRunAdmissionReceipt> {
+        try {
+          return await submitPostgresAbsurdPlayRun(
+            input.client,
+            admission.launch,
+            options,
+            admission.queueName,
+            admission.recoverExistingTask === true,
+          );
+        } catch (error) {
+          if (isLaunchConflict(error)) {
+            throw new PlayRunLaunchConflictError(admission.launch.runId, {
+              cause: error,
+            });
+          }
+          throw error;
+        }
+      },
+    },
+  };
+}
+
+function isLaunchConflict(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    /already exists with a different launch/i.test(error.message)
+  );
+}

package/dist/bundling-sources/shared_libs/play-runtime/play-runs/attempts/contracts.ts

@@ -0,0 +1,114 @@
+/**
+ * Play Run Attempt is the controller for one fenced execution leg.
+ *
+ * It deliberately does not know how a sandbox is created, how a runner is
+ * started, or how a terminal transaction is committed.  Its only policy is
+ * the retry boundary: work known not to have crossed into user/provider code
+ * may be deferred; once that boundary may have been crossed, this job never
+ * asks Sandbox Runs to execute again.
+ */
+
+/** The already-persisted run details required by this leg. */
+export type PlayRunAttemptLaunch = {
+  runId: string;
+  /** Opaque to the attempt job; consumed by its execution implementation. */
+  launch: unknown;
+};
+
+import type { PlayExecutionSuspension } from '../../suspension';
+import type { PlayRunRecoveryDecision } from '../../play-run-recovery-policy';
+
+/** A scheduler fence granted to exactly one execution leg. */
+export type PlayRunAttemptClaim = {
+  runId: string;
+  number: number;
+  /** Opaque authority used by scheduler/resource/terminal Adapters. */
+  fenceId: string;
+  checkpoint: unknown;
+  /**
+   * A detached runner keeps its original attempt-scoped executor token.  A
+   * heartbeat wake must therefore reuse this claim rather than minting a
+   * successor that would fence its still-live runner out of heartbeats and
+   * terminal delivery.
+   */
+  origin: 'fresh' | 'detached_runner_resume';
+  /** Present only for an origin that resumed a detached runner. */
+  suspension?: Extract<PlayExecutionSuspension, { kind: 'detached_runner' }>;
+};
+
+/** A durable waiting/resumed lifecycle fact ready for read-model projection. */
+export type PlayRunAttemptLifecycle = {
+  runId: string;
+  eventId: string;
+};
+
+/** Durable truth read before a new attempt may be claimed. */
+export type PlayRunAttemptTerminal = {
+  status: 'completed' | 'failed' | 'cancelled';
+  output?: unknown;
+  error?: string;
+};
+
+export type PlayRunAttemptInput = {
+  run: PlayRunAttemptLaunch;
+};
+
+/**
+ * Sandbox Runs reports whether user/provider code was crossed.  The payload
+ * is opaque here because only the terminal job owns interpretation and
+ * persistence of a runner result.
+ */
+/**
+ * Evidence that no customer or provider code has begun.  It is intentionally
+ * distinct from an ordinary thrown error: only these outcomes may put a run
+ * back into durable admission.
+ */
+export type PlayRunAttemptPreCodeDeferral =
+  | { kind: 'capacity'; reason: string }
+  | {
+      kind: 'recovery';
+      reason: string;
+      decision: PlayRunRecoveryDecision;
+    };
+
+/**
+ * The runner-to-terminal transport envelope.  Attempt never interprets this
+ * result; Terminal owns first-write-wins persistence and result shaping.
+ */
+export type PlayRunAttemptTerminalEnvelope =
+  | { status: 'completed'; output: unknown }
+  | { status: 'failed'; error: string };
+
+export type PlayRunAttemptSandboxOutcome =
+  | { kind: 'pre_code_deferred'; deferral: PlayRunAttemptPreCodeDeferral }
+  | {
+      kind: 'suspended';
+      checkpoint: unknown;
+      suspension: PlayExecutionSuspension;
+    }
+  | { kind: 'terminal'; result: PlayRunAttemptTerminalEnvelope }
+  | { kind: 'post_code_unknown'; reason: string };
+
+export type PlayRunAttemptTerminalHandoff =
+  | { kind: 'committed' }
+  | { kind: 'already_terminal' }
+  | { kind: 'fence_lost' };
+
+/** Outcomes visible to the worker Adapter after one execution leg. */
+export type PlayRunAttemptOutcome =
+  | { kind: 'already_terminal'; terminal: PlayRunAttemptTerminal }
+  | { kind: 'claim_rejected' }
+  | { kind: 'pre_code_deferred'; deferral: PlayRunAttemptPreCodeDeferral }
+  | {
+      kind: 'parked';
+      checkpoint: unknown;
+      suspension: PlayExecutionSuspension;
+    }
+  | { kind: 'post_code_unknown'; reason: string }
+  | { kind: 'terminal_committed' }
+  | { kind: 'terminal_already_committed' }
+  | { kind: 'terminal_fence_lost' };
+
+export type PlayRunAttemptJob = {
+  execute(input: PlayRunAttemptInput): Promise<PlayRunAttemptOutcome>;
+};