deepline 0.3.88 → 0.3.90

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

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

@@ -0,0 +1,108 @@
+import type {
+  PlayRunAttemptClaim,
+  PlayRunAttemptLaunch,
+  PlayRunAttemptLifecycle,
+} from '../../play-runs/attempts/contracts';
+import type { PlayRunAttemptStore } from '../../play-runs/attempts/ports';
+import type { PlayExecutionSuspension } from '../../suspension';
+
+/**
+ * The durable task engine is an Adapter, not Attempt policy. It maps a
+ * persisted Play suspension to a sleep/event/heartbeat primitive and reports
+ * whether the primitive parked this handler or resolved on this invocation.
+ *
+ * An Absurd Adapter retains the actual control signal until its ingress has
+ * handled the semantic `parked` outcome, then rethrows it. This separates the
+ * engine's transport exception from the Attempt Module's transition law.
+ */
+export type PlayRunAttemptEngineSuspensionPort = {
+  resolve(input: {
+    run: PlayRunAttemptLaunch;
+    attempt: PlayRunAttemptClaim;
+    checkpoint: unknown;
+    suspension: PlayExecutionSuspension;
+  }): Promise<{ kind: 'parked' } | { kind: 'resolved'; checkpoint: unknown }>;
+  /** Re-emit the engine-specific park signal captured by `resolve`. */
+  rethrowParked(): never;
+};
+
+export type PlayRunAttemptSuspensionOutcome =
+  | { kind: 'fence_lost'; stage: 'park' | 'resume' | 'handoff' }
+  | { kind: 'parked' }
+  | { kind: 'resumed'; checkpoint: unknown }
+  | { kind: 'continuation_handed_off'; checkpoint: unknown };
+
+/**
+ * Owns the durable transition law around an engine suspension:
+ *
+ *   running -> waiting -> engine park|wake -> running|fresh continuation
+ *
+ * A detached runner which itself reaches a normal Play suspension cannot
+ * reuse its terminal slot; it is handed off to a fresh attempt. All other
+ * wakes retain their exact fence.
+ */
+export function createPlayRunAttemptSuspensionJob(ports: {
+  store: PlayRunAttemptStore;
+  engine: PlayRunAttemptEngineSuspensionPort;
+  lifecycle?: {
+    waiting(lifecycle: PlayRunAttemptLifecycle): Promise<void>;
+    resumed(lifecycle: PlayRunAttemptLifecycle): Promise<void>;
+  };
+}) {
+  return {
+    async resolve(input: {
+      run: PlayRunAttemptLaunch;
+      attempt: PlayRunAttemptClaim;
+      checkpoint: unknown;
+      suspension: PlayExecutionSuspension;
+      /** The current runner result was read from a previously detached runner. */
+      fromDetachedRunner: boolean;
+    }): Promise<PlayRunAttemptSuspensionOutcome> {
+      const parked = await ports.store.park({
+        claim: input.attempt,
+        checkpoint: input.checkpoint,
+        suspension: input.suspension,
+      });
+      if (parked.kind === 'fence_lost') {
+        return { kind: 'fence_lost', stage: 'park' };
+      }
+      await ports.lifecycle?.waiting(parked.lifecycle);
+
+      const engineOutcome = await ports.engine.resolve({
+        run: input.run,
+        attempt: input.attempt,
+        checkpoint: input.checkpoint,
+        suspension: input.suspension,
+      });
+      if (engineOutcome.kind === 'parked') return engineOutcome;
+
+      if (
+        input.fromDetachedRunner &&
+        input.suspension.kind !== 'detached_runner'
+      ) {
+        const handedOff = await ports.store.handoffDetachedContinuation({
+          claim: input.attempt,
+          checkpoint: engineOutcome.checkpoint,
+        });
+        if (handedOff.kind === 'fence_lost') {
+          return { kind: 'fence_lost', stage: 'handoff' };
+        }
+        await ports.lifecycle?.resumed(handedOff.lifecycle);
+        return {
+          kind: 'continuation_handed_off',
+          checkpoint: engineOutcome.checkpoint,
+        };
+      }
+
+      const resumed = await ports.store.resumeAfterPark({
+        claim: input.attempt,
+        suspension: input.suspension,
+      });
+      if (resumed.kind === 'fence_lost') {
+        return { kind: 'fence_lost', stage: 'resume' };
+      }
+      await ports.lifecycle?.resumed(resumed.lifecycle);
+      return { kind: 'resumed', checkpoint: engineOutcome.checkpoint };
+    },
+  };
+}

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

@@ -0,0 +1,36 @@
+export { createPlayRunAttemptJob } from '../../play-runs/attempts/job';
+export {
+  createPlayRunAttemptSuspensionJob,
+  type PlayRunAttemptEngineSuspensionPort,
+  type PlayRunAttemptSuspensionOutcome,
+} from '../../play-runs/attempts/engine-suspension';
+export {
+  createPlayRunAttemptWorkerTerminalProjection,
+  type PlayRunAttemptTerminalCommit,
+  type PlayRunAttemptWorkerTerminalProjectionPort,
+  type PlayRunAttemptWorkerTerminalProjectionPorts,
+} from '../../play-runs/attempts/worker-terminal-projection';
+export {
+  createPostgresPlayRunAttemptFence,
+  createPostgresPlayRunAttemptStore,
+  type PostgresPlayRunAttemptStore,
+} from '../../play-runs/attempts/postgres-fence-adapter';
+export type {
+  PlayRunAttemptClaim,
+  PlayRunAttemptInput,
+  PlayRunAttemptJob,
+  PlayRunAttemptLaunch,
+  PlayRunAttemptLifecycle,
+  PlayRunAttemptOutcome,
+  PlayRunAttemptPreCodeDeferral,
+  PlayRunAttemptSandboxOutcome,
+  PlayRunAttemptTerminal,
+  PlayRunAttemptTerminalEnvelope,
+  PlayRunAttemptTerminalHandoff,
+} from '../../play-runs/attempts/contracts';
+export type {
+  PlayRunAttemptPorts,
+  PlayRunAttemptStore,
+  PlayRunTerminalPort,
+  SandboxRunsPort,
+} from '../../play-runs/attempts/ports';

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

@@ -0,0 +1,97 @@
+import type {
+  PlayRunAttemptInput,
+  PlayRunAttemptJob,
+  PlayRunAttemptOutcome,
+} from '../../play-runs/attempts/contracts';
+import type { PlayRunAttemptPorts } from '../../play-runs/attempts/ports';
+
+/**
+ * Builds the Play Run Attempt job.
+ *
+ * The ordering is the contract:
+ *
+ *   terminal read -> fenced claim -> Sandbox Runs -> Terminal | park | defer
+ *
+ * A post-code-unknown outcome is intentionally returned to the caller rather
+ * than converted to a retry.  A later recovery leg must resolve durable
+ * runner/resource facts; replaying here risks duplicate provider work.
+ */
+export function createPlayRunAttemptJob(
+  ports: PlayRunAttemptPorts,
+): PlayRunAttemptJob {
+  return {
+    async execute(input: PlayRunAttemptInput): Promise<PlayRunAttemptOutcome> {
+      validate(input);
+      const terminal = await ports.store.readTerminal({
+        runId: input.run.runId,
+      });
+      if (terminal) return { kind: 'already_terminal', terminal };
+
+      // A detached runner owns an attempt-scoped executor token. Its heartbeat
+      // wake must see that exact claim before ordinary allocation is allowed.
+      const claim =
+        (await ports.store.resumeDetached(input.run)) ??
+        (await ports.store.claim(input.run));
+      if (claim === null) return { kind: 'claim_rejected' };
+
+      const sandbox = await ports.sandboxRuns.execute({
+        run: input.run,
+        attempt: claim,
+      });
+      switch (sandbox.kind) {
+        case 'pre_code_deferred':
+          const deferred = await ports.store.deferBeforeCode({
+            claim,
+            deferral: sandbox.deferral,
+          });
+          if (deferred.kind === 'deferred') return sandbox;
+          if (deferred.kind === 'fence_lost') return { kind: 'claim_rejected' };
+          const terminalResult = await ports.terminal.accept({
+            attempt: claim,
+            result: deferred.terminal,
+          });
+          return terminalResult.kind === 'committed'
+            ? { kind: 'terminal_committed' }
+            : terminalResult.kind === 'already_terminal'
+              ? { kind: 'terminal_already_committed' }
+              : { kind: 'terminal_fence_lost' };
+        case 'suspended': {
+          const parked = await ports.store.park({
+            claim,
+            checkpoint: sandbox.checkpoint,
+            suspension: sandbox.suspension,
+          });
+          return parked.kind === 'parked'
+            ? {
+                kind: 'parked',
+                checkpoint: sandbox.checkpoint,
+                suspension: sandbox.suspension,
+              }
+            : { kind: 'claim_rejected' };
+        }
+        case 'post_code_unknown':
+          return sandbox;
+        case 'terminal': {
+          const terminalResult = await ports.terminal.accept({
+            attempt: claim,
+            result: sandbox.result,
+          });
+          switch (terminalResult.kind) {
+            case 'committed':
+              return { kind: 'terminal_committed' };
+            case 'already_terminal':
+              return { kind: 'terminal_already_committed' };
+            case 'fence_lost':
+              return { kind: 'terminal_fence_lost' };
+          }
+        }
+      }
+    },
+  };
+}
+
+function validate(input: PlayRunAttemptInput): void {
+  if (!input.run.runId.trim()) {
+    throw new Error('Play Run Attempt requires a non-empty run id.');
+  }
+}

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

@@ -0,0 +1,104 @@
+import type {
+  PlayRunAttemptClaim,
+  PlayRunAttemptLaunch,
+  PlayRunAttemptLifecycle,
+  PlayRunAttemptPreCodeDeferral,
+  PlayRunAttemptSandboxOutcome,
+  PlayRunAttemptTerminalEnvelope,
+  PlayRunAttemptTerminal,
+  PlayRunAttemptTerminalHandoff,
+} from '../../play-runs/attempts/contracts';
+import type { PlayExecutionSuspension } from '../../suspension';
+
+/**
+ * Scheduler state belongs on this seam.  It intentionally combines allocate
+ * and assign: an attempt number without its write fence is not usable work.
+ */
+export type PlayRunAttemptStore = {
+  readTerminal(input: {
+    runId: string;
+  }): Promise<PlayRunAttemptTerminal | null>;
+  claim(input: PlayRunAttemptLaunch): Promise<PlayRunAttemptClaim | null>;
+  /**
+   * Reuses the fence held by a parked detached runner. This read is separate
+   * from `claim` because every other parked suspension must receive a fresh
+   * generation after its engine wake.
+   */
+  resumeDetached(
+    input: PlayRunAttemptLaunch,
+  ): Promise<PlayRunAttemptClaim | null>;
+  /** Only proven pre-code work may be returned to scheduler admission. */
+  deferBeforeCode(input: {
+    claim: PlayRunAttemptClaim;
+    deferral: PlayRunAttemptPreCodeDeferral;
+  }): Promise<
+    | { kind: 'deferred' }
+    | { kind: 'exhausted'; terminal: PlayRunAttemptTerminalEnvelope }
+    | { kind: 'fence_lost' }
+  >;
+  /**
+   * Stores a safe continuation without inventing a new attempt generation.
+   * The store, rather than callers, derives detached-runner heartbeat rules
+   * from the typed suspension.
+   */
+  park(input: {
+    claim: PlayRunAttemptClaim;
+    checkpoint: unknown;
+    suspension: PlayExecutionSuspension;
+  }): Promise<
+    | { kind: 'parked'; lifecycle: PlayRunAttemptLifecycle }
+    | { kind: 'fence_lost' }
+  >;
+  /** Transition a non-detached parked attempt back to running. */
+  resumeAfterPark(input: {
+    claim: PlayRunAttemptClaim;
+    suspension: PlayExecutionSuspension;
+  }): Promise<
+    | { kind: 'resumed'; lifecycle: PlayRunAttemptLifecycle }
+    | { kind: 'fence_lost' }
+  >;
+  /**
+   * A detached runner that produces another suspension cannot reuse its
+   * terminal slot. Retire it and return its checkpoint to durable admission.
+   */
+  handoffDetachedContinuation(input: {
+    claim: PlayRunAttemptClaim;
+    checkpoint: unknown;
+  }): Promise<
+    | { kind: 'handed_off'; lifecycle: PlayRunAttemptLifecycle }
+    | { kind: 'fence_lost' }
+  >;
+};
+
+/**
+ * The physical execution-resource Module; it never settles the Play Run.
+ *
+ * This is the proposed live-worker routing seam. An Absurd Adapter will own
+ * one complete runner leg: config/materialization, resource facts, runner
+ * start or detached-terminal observation, and engine-context suspension
+ * resolution. It reports only these semantic outcomes here. In particular it
+ * must report `pre_code_deferred` only with proof that no runner/customer code
+ * could have started, and must report `post_code_unknown` rather than replay
+ * an ambiguous runner command. The Attempt Module then owns the only durable
+ * transition allowed for each outcome.
+ */
+export type SandboxRunsPort = {
+  execute(input: {
+    run: PlayRunAttemptLaunch;
+    attempt: PlayRunAttemptClaim;
+  }): Promise<PlayRunAttemptSandboxOutcome>;
+};
+
+/** The durable terminal Module; it owns first-write-wins terminal truth. */
+export type PlayRunTerminalPort = {
+  accept(input: {
+    attempt: PlayRunAttemptClaim;
+    result: PlayRunAttemptTerminalEnvelope;
+  }): Promise<PlayRunAttemptTerminalHandoff>;
+};
+
+export type PlayRunAttemptPorts = {
+  store: PlayRunAttemptStore;
+  sandboxRuns: SandboxRunsPort;
+  terminal: PlayRunTerminalPort;
+};