deepline 0.3.88 → 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

@@ -0,0 +1,189 @@
+/**
+ * The Absurd release-lane retirement gate, as dependency-free pure logic.
+ *
+ * This lives in its own module because three very different processes must
+ * reach exactly the same verdict and none of them may drag the others'
+ * dependencies in:
+ *
+ *   - 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
+ *     the release controller handed over, and whose Fly image does not contain
+ *     `packages/convex/`.
+ *
+ * The gate clears two ways:
+ *
+ *   1. **Empty.** No non-terminal task on the lane's queue and no non-terminal
+ *      run row referencing its release id.
+ *   2. **Adopted parked (lane handoff).** The lane has been marked not claiming,
+ *      nothing on it is claimable or running, and every remaining non-terminal
+ *      run is parked in a durable wait the newest lane adopts.
+ *
+ * Anything else is blocked, and `blockedBy` names which of the two halves is
+ * responsible so an operator is not left guessing at a bare depth count.
+ */
+
+/**
+ * The subset of a lane's depth the gate reads.
+ *
+ * Every field is optional because the gate is also evaluated against a lane
+ * view that crossed the wire from a control plane which may be older than its
+ * caller: the release-aware scaler is deployed from the same release as the
+ * app, but a scaler image can outlive the app deployment it polls. A fact that
+ * did not arrive is never guessed — see `adoption-facts-unavailable`.
+ */
+export type LaneRetirementGateFacts = {
+  /** Non-terminal tasks on `absurd.t_<queue>`. */
+  queuedTasks?: number;
+  claimableTasks?: number;
+  runningTasks?: number;
+  /** Non-terminal `runs` rows whose launch envelope pins this release id. */
+  nonTerminalRuns?: number;
+  /** Subset of `nonTerminalRuns` parked in a wait the newest lane adopts. */
+  adoptableParkedRuns?: number;
+  /** Whether this lane still claims work off its own queue. */
+  claiming?: boolean;
+  /** `queuedTasks === 0 && nonTerminalRuns === 0`. */
+  empty?: boolean;
+  /** `claimableTasks === 0 && runningTasks === 0 && nonTerminalRuns === adoptableParkedRuns`. */
+  emptyExceptAdoptableParked?: boolean;
+};
+
+export type LaneRetirementGateBasis = 'empty' | 'adopted-parked' | 'blocked';
+
+/**
+ * Why a blocked lane is blocked. This is the operator-facing half of the gate:
+ * each value maps to exactly one remediation.
+ */
+export type LaneRetirementBlockedReason =
+  /** Not blocked. */
+  | 'none'
+  /** Something on this lane is claimable or running right now. Wait. */
+  | 'executable-work'
+  /**
+   * The lane holds nothing but adoptable parked waits, and the ONLY thing
+   * keeping it alive is that its claiming switch was never flipped. The lane
+   * cannot flip it itself, so without an external write this lane is immortal.
+   */
+  | 'still-claiming'
+  /**
+   * Non-terminal runs this lane can no longer execute and no other lane can
+   * adopt: a `detached_runner` park whose sandbox is gone, or a run row with no
+   * engine task at all. Nothing will ever wake these; they need an explicit,
+   * evidence-gated terminal transition.
+   */
+  | 'unadoptable-non-terminal-runs'
+  /**
+   * The caller's lane view predates the adoption fields. The gate refuses to
+   * infer adoption from absent evidence and falls back to the strict `empty`
+   * half only.
+   */
+  | 'adoption-facts-unavailable';
+
+export type LaneRetirementGateResult = {
+  ok: boolean;
+  basis: LaneRetirementGateBasis;
+  blockedBy: LaneRetirementBlockedReason;
+};
+
+/**
+ * Evaluate the retirement gate.
+ *
+ * Deliberately conservative in one direction only: it never clears a lane on a
+ * fact it did not receive. It is safe for the caller to retire on `ok`, because
+ * retirement deletes Machines and flips the registry row; it does not drop the
+ * queue tables an adopting lane still claims from.
+ */
+export function laneRetirementGate(
+  depth: LaneRetirementGateFacts,
+): LaneRetirementGateResult {
+  if (depth.empty === true) {
+    return { ok: true, basis: 'empty', blockedBy: 'none' };
+  }
+  if (
+    typeof depth.claiming !== 'boolean' ||
+    typeof depth.emptyExceptAdoptableParked !== 'boolean' ||
+    typeof depth.adoptableParkedRuns !== 'number'
+  ) {
+    return {
+      ok: false,
+      basis: 'blocked',
+      blockedBy: 'adoption-facts-unavailable',
+    };
+  }
+  if (!depth.claiming && depth.emptyExceptAdoptableParked) {
+    return { ok: true, basis: 'adopted-parked', blockedBy: 'none' };
+  }
+  const executable =
+    (depth.claimableTasks ?? 0) > 0 || (depth.runningTasks ?? 0) > 0;
+  if (executable) {
+    return { ok: false, basis: 'blocked', blockedBy: 'executable-work' };
+  }
+  if (depth.claiming && depth.emptyExceptAdoptableParked) {
+    return { ok: false, basis: 'blocked', blockedBy: 'still-claiming' };
+  }
+  return {
+    ok: false,
+    basis: 'blocked',
+    blockedBy: 'unadoptable-non-terminal-runs',
+  };
+}
+
+/**
+ * The one operator-actionable sentence for a blocked lane.
+ *
+ * A depth count alone ("11 queued") has repeatedly sent operators looking for
+ * live work that is not there. Each reason below has exactly one next step.
+ */
+export function laneRetirementRemediation(
+  result: LaneRetirementGateResult,
+): string {
+  switch (result.blockedBy) {
+    case 'none':
+      return result.basis === 'adopted-parked'
+        ? 'Retirable: nothing here is claimable or running and every remaining run is a parked wait the newest lane adopts.'
+        : 'Retirable: this lane holds no non-terminal task and no non-terminal run.';
+    case 'executable-work':
+      return 'Wait. Work on this lane is claimable or running right now; the scaler keeps a version-matched machine for it.';
+    case 'still-claiming':
+      return 'Demote the lane. It holds only adoptable parked waits; the newest lane cannot adopt them until this lane stops claiming (lane handoff). The release-aware scaler converges this, or run `bun scripts/fly-absurd-lane.ts stop-claiming --release <id>`.';
+    case 'unadoptable-non-terminal-runs':
+      return 'Inspect the runs. This lane holds non-terminal runs it can no longer execute and no lane can adopt. Run `deepline-admin runtime stranded scan --release <id> --environment production --json`, then remediate the reviewed cohort with `runtime stranded plan` / `runtime stranded resolve --dry-run`.';
+    case 'adoption-facts-unavailable':
+      return 'The lane view did not carry the lane handoff adoption fields, so only the strict empty gate was evaluated. Re-read the lane against a control plane from this release.';
+  }
+}
+
+/**
+ * Should this lane's claiming switch be converged to `false`?
+ *
+ * The switch is written exactly once, by the release controller, as a
+ * `reclamation` effect whose failure is explicitly tolerated — a failed
+ * `stop-prior-lane-claiming` is logged and the release still SUCCEEDS. Absence
+ * of the control row reads as "claiming", so a lost write leaves a demoted lane
+ * claiming forever. With no machines the lane cannot make progress, and with
+ * `claiming` true the newest lane may not adopt it: a permanently unclaimable
+ * steady state.
+ *
+ * This predicate is intentionally narrow. It fires only for a lane whose gate
+ * is blocked by the lost write and nothing else, so it can never demote a lane
+ * that is still doing something, and it cannot fight `abort_retire` (which
+ * re-arms claiming for a lane that has real work, and therefore is not blocked
+ * by `still-claiming`).
+ */
+export function shouldConvergeLaneToNotClaiming(lane: {
+  active?: boolean;
+  status?: string;
+  queueDepth?: LaneRetirementGateFacts;
+}): boolean {
+  if (lane.active !== false) return false;
+  if (lane.status !== 'draining' && lane.status !== 'retiring') return false;
+  const depth = lane.queueDepth;
+  if (!depth) return false;
+  if ((depth.claimableTasks ?? 0) > 0 || (depth.runningTasks ?? 0) > 0) {
+    return false;
+  }
+  if ((depth.adoptableParkedRuns ?? 0) <= 0) return false;
+  return laneRetirementGate(depth).blockedBy === 'still-claiming';
+}

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