deepline 0.3.89 → 0.3.90

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

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

@@ -0,0 +1,263 @@
+import { randomUUID } from 'node:crypto';
+
+import {
+  allocatePostgresSchedulerNextAttempt,
+  assignPostgresSchedulerRunAttempt,
+  deferPostgresSchedulerAttemptForCapacity,
+  deferPostgresSchedulerAttemptForRecovery,
+  handoffPostgresSchedulerAttemptContinuation,
+  markPostgresSchedulerAttemptRunning,
+  markPostgresSchedulerAttemptWaiting,
+  readPostgresSchedulerResult,
+  resumePostgresSchedulerDetachedRunnerAttempt,
+  type PostgresSchedulerOptions,
+  type PostgresSchedulerQueryClient,
+} from '../../scheduler-backends/postgres';
+import { PLAY_RUN_RECOVERY_DEFER_POLICY } from '../../play-run-recovery-policy';
+import type {
+  PlayRunAttemptClaim,
+  PlayRunAttemptTerminalEnvelope,
+} from '../../play-runs/attempts/contracts';
+import type { PlayRunAttemptStore } from '../../play-runs/attempts/ports';
+
+/**
+ * Runtime-Postgres Adapter for Play Run Attempt.
+ *
+ * The Adapter intentionally owns the scheduler's real transition vocabulary:
+ * fresh versus detached-fence claim, finite pre-code recovery, typed parking,
+ * ordinary wake, and detached continuation handoff. It does not execute
+ * sandboxes or shape runner-returned terminal output; those remain the
+ * Sandbox Runs and Terminal Modules behind their own seams. A bounded
+ * pre-code recovery exhaustion is the one scheduler-owned terminal envelope
+ * this Adapter constructs.
+ */
+export type PostgresPlayRunAttemptStore = PlayRunAttemptStore;
+
+export function createPostgresPlayRunAttemptStore(input: {
+  client: PostgresSchedulerQueryClient;
+  schedulerOptions?: Pick<PostgresSchedulerOptions, 'schema'>;
+  /** Injectable only to make Adapter conformance vectors deterministic. */
+  createFenceId?: () => string;
+  nowMs?: () => number;
+}): PostgresPlayRunAttemptStore {
+  const options = input.schedulerOptions;
+  const createFenceId = input.createFenceId ?? randomUUID;
+  const nowMs = input.nowMs ?? Date.now;
+  const freshClaim = async (run: { runId: string }) => {
+    // This intentionally retains the worker's allocate-then-assign law.
+    // Races may choose the same generation, but the assignment SQL admits
+    // only one of them; a loser observes null and must retire without work.
+    const number = await allocatePostgresSchedulerNextAttempt(
+      input.client,
+      run.runId,
+      options,
+    );
+    const fenceId = createFenceId();
+    const assigned = await assignPostgresSchedulerRunAttempt(
+      input.client,
+      { runId: run.runId, attempt: number, taskToken: fenceId },
+      options,
+    );
+    if (assigned === null) return null;
+    return {
+      runId: run.runId,
+      number,
+      fenceId,
+      checkpoint: assigned.checkpoint ?? null,
+      origin: 'fresh' as const,
+    };
+  };
+  return {
+    async readTerminal({ runId }) {
+      const terminal = await readPostgresSchedulerResult(
+        input.client,
+        runId,
+        options,
+      );
+      if (terminal === null) return null;
+      return {
+        status: terminal.status,
+        ...(Object.hasOwn(terminal, 'output')
+          ? { output: terminal.output }
+          : {}),
+        ...(Object.hasOwn(terminal, 'error') ? { error: terminal.error } : {}),
+      };
+    },
+    async resumeDetached(run) {
+      const resumed = await resumePostgresSchedulerDetachedRunnerAttempt(
+        input.client,
+        { runId: run.runId },
+        options,
+      );
+      if (!resumed) return null;
+      const suspension = detachedRunnerSuspension(resumed.suspension);
+      return {
+        runId: run.runId,
+        number: resumed.attempt,
+        fenceId: resumed.leaseToken,
+        checkpoint: resumed.checkpoint ?? null,
+        origin: 'detached_runner_resume' as const,
+        suspension,
+      };
+    },
+    claim: freshClaim,
+    async deferBeforeCode({ claim, deferral }) {
+      if (deferral.kind === 'capacity') {
+        const deferred = await deferPostgresSchedulerAttemptForCapacity(
+          input.client,
+          {
+            runId: claim.runId,
+            attempt: claim.number,
+            leaseToken: claim.fenceId,
+            reason: deferral.reason,
+          },
+          options,
+        );
+        return deferred
+          ? { kind: 'deferred' as const }
+          : { kind: 'fence_lost' as const };
+      }
+      const decision = deferral.decision;
+      if (decision.stage !== 'pre_code' || decision.action !== 'defer') {
+        throw new Error(
+          'Play Run Attempt recovery deferral requires a pre-code defer decision.',
+        );
+      }
+      const recovery = await deferPostgresSchedulerAttemptForRecovery(
+        input.client,
+        {
+          runId: claim.runId,
+          attempt: claim.number,
+          leaseToken: claim.fenceId,
+          reason: deferral.reason,
+          dependency: decision.dependency,
+          openCircuit:
+            decision.dependency === 'modal' &&
+            decision.reason !== 'modal_circuit_open_before_execution',
+          nowMs: nowMs(),
+          maxDefers: PLAY_RUN_RECOVERY_DEFER_POLICY.maxDefers,
+          horizonMs: PLAY_RUN_RECOVERY_DEFER_POLICY.horizonMs,
+          deferBaseMs: PLAY_RUN_RECOVERY_DEFER_POLICY.deferBaseSeconds * 1_000,
+          deferMaxMs: PLAY_RUN_RECOVERY_DEFER_POLICY.deferMaxSeconds * 1_000,
+        },
+        options,
+      );
+      if (recovery.deferred) return { kind: 'deferred' as const };
+      if (!recovery.exhausted) return { kind: 'fence_lost' as const };
+      return {
+        kind: 'exhausted' as const,
+        terminal: exhaustedRecoveryTerminal({
+          dependency: decision.dependency,
+          checkpoint: claim.checkpoint,
+        }),
+      };
+    },
+    async park({ claim, checkpoint, suspension }) {
+      const parked = await markPostgresSchedulerAttemptWaiting(
+        input.client,
+        {
+          runId: claim.runId,
+          attempt: claim.number,
+          leaseToken: claim.fenceId,
+          checkpoint,
+          suspension,
+          preserveHeartbeatAt: suspension.kind === 'detached_runner',
+        },
+        options,
+      );
+      return parked
+        ? { kind: 'parked', lifecycle: parked }
+        : { kind: 'fence_lost' };
+    },
+    async resumeAfterPark({ claim, suspension }) {
+      const resumed = await markPostgresSchedulerAttemptRunning(
+        input.client,
+        {
+          runId: claim.runId,
+          attempt: claim.number,
+          leaseToken: claim.fenceId,
+          preserveHeartbeatAt: suspension.kind === 'detached_runner',
+        },
+        options,
+      );
+      return resumed
+        ? { kind: 'resumed', lifecycle: resumed }
+        : { kind: 'fence_lost' };
+    },
+    async handoffDetachedContinuation({ claim, checkpoint }) {
+      if (claim.origin !== 'detached_runner_resume') {
+        throw new Error(
+          'Only a resumed detached-runner attempt may hand off a fresh continuation.',
+        );
+      }
+      const handedOff = await handoffPostgresSchedulerAttemptContinuation(
+        input.client,
+        {
+          runId: claim.runId,
+          attempt: claim.number,
+          leaseToken: claim.fenceId,
+          checkpoint,
+        },
+        options,
+      );
+      return handedOff
+        ? { kind: 'handed_off', lifecycle: handedOff }
+        : { kind: 'fence_lost' };
+    },
+  };
+}
+
+function detachedRunnerSuspension(
+  value: unknown,
+): NonNullable<PlayRunAttemptClaim['suspension']> {
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    Array.isArray(value) ||
+    (value as { kind?: unknown }).kind !== 'detached_runner'
+  ) {
+    throw new Error(
+      'Detached Attempt resume was selected without a detached_runner suspension.',
+    );
+  }
+  const candidate = value as Record<string, unknown>;
+  if (
+    !Number.isSafeInteger(candidate.runnerAttempt) ||
+    typeof candidate.boundaryId !== 'string' ||
+    typeof candidate.sandboxId !== 'string' ||
+    typeof candidate.sessionId !== 'string' ||
+    typeof candidate.cmdId !== 'string' ||
+    typeof candidate.outputPath !== 'string' ||
+    typeof candidate.exitCodePath !== 'string' ||
+    !Number.isFinite(candidate.startedAtMs) ||
+    !Number.isFinite(candidate.heartbeatTimeoutMs) ||
+    !Number.isFinite(candidate.ceilingMs)
+  ) {
+    throw new Error(
+      'Detached Attempt resume found an invalid persisted detached_runner suspension.',
+    );
+  }
+  return value as NonNullable<PlayRunAttemptClaim['suspension']>;
+}
+
+/** @deprecated Use `createPostgresPlayRunAttemptStore`; the old name retained
+ * for the migration while callers move from the claim-only Interface. */
+export const createPostgresPlayRunAttemptFence =
+  createPostgresPlayRunAttemptStore;
+
+function exhaustedRecoveryTerminal(input: {
+  dependency: 'modal' | 'runtime';
+  checkpoint: unknown;
+}): PlayRunAttemptTerminalEnvelope {
+  // The checkpoint is intentionally not returned to customer output. It is
+  // already durable on the run row; the Terminal Module only needs a typed
+  // failure envelope to settle first-write-wins truth.
+  void input.checkpoint;
+  return {
+    status: 'failed',
+    error:
+      `PLATFORM_RECOVERY_EXHAUSTED: ${input.dependency} remained unavailable ` +
+      'before customer execution began through the bounded recovery horizon. ' +
+      'No customer code was started; inspect and redrive this run after the dependency is healthy.',
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/play-runs/attempts/worker-terminal-projection.ts

@@ -0,0 +1,64 @@
+import type { PlayRunAttemptTerminalEnvelope } from '../../play-runs/attempts/contracts';
+
+/** The committed terminal fact used by worker-side read-model projection. */
+export type PlayRunAttemptTerminalCommit =
+  | { status: 'completed'; output: unknown }
+  | { status: 'failed'; error: string };
+
+/**
+ * Post-commit effects are deliberately separate from terminal truth. Terminal
+ * has already won first-write-wins before this Interface is invoked; these
+ * effects improve observability and release ephemeral receipt leases, but
+ * cannot alter customer-visible terminal state.
+ */
+export type PlayRunAttemptWorkerTerminalProjectionPort = {
+  observeFenceLost(): Promise<void>;
+  projectCommitted(input: {
+    runnerResult: PlayRunAttemptTerminalEnvelope;
+    terminal: PlayRunAttemptTerminalCommit;
+  }): Promise<void>;
+};
+
+export type PlayRunAttemptWorkerTerminalProjectionPorts = {
+  reconcileTerminalTruth(input: {
+    runnerResult: PlayRunAttemptTerminalEnvelope;
+    terminal: PlayRunAttemptTerminalCommit;
+  }): Promise<void>;
+  releaseFailedAttempt(input: {
+    runnerResult: PlayRunAttemptTerminalEnvelope;
+    terminal: Extract<PlayRunAttemptTerminalCommit, { status: 'failed' }>;
+  }): Promise<void>;
+  queueProgressFinalization(input: {
+    runnerResult: PlayRunAttemptTerminalEnvelope;
+    terminal: PlayRunAttemptTerminalCommit;
+  }): void;
+  requestTerminalProjection(input: {
+    terminal: PlayRunAttemptTerminalCommit;
+  }): void;
+  observeFenceLost(): Promise<void>;
+};
+
+/**
+ * Builds the worker projection Module. The ordering is its Interface:
+ * reconcile durable truth, release failed-attempt leases, then enqueue
+ * best-effort progress/outbox projection. A stale terminal fence observes the
+ * winner only; it never emits a second projection sequence.
+ */
+export function createPlayRunAttemptWorkerTerminalProjection(
+  ports: PlayRunAttemptWorkerTerminalProjectionPorts,
+): PlayRunAttemptWorkerTerminalProjectionPort {
+  return {
+    observeFenceLost: ports.observeFenceLost,
+    async projectCommitted(input) {
+      await ports.reconcileTerminalTruth(input);
+      if (input.terminal.status === 'failed') {
+        await ports.releaseFailedAttempt({
+          runnerResult: input.runnerResult,
+          terminal: input.terminal,
+        });
+      }
+      ports.queueProgressFinalization(input);
+      ports.requestTerminalProjection({ terminal: input.terminal });
+    },
+  };
+}