deepline 0.3.113 → 0.3.114

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/postgres.ts

@@ -159,6 +159,11 @@ import {
 } from './scheduler-launch-read-observability';
 import { emitPlayTelemetry } from '../runtime-telemetry';
 import { buildAbsurdPlayRunTask } from './absurd-play-run-task';
+import {
+  buildAbsurdCronFireTask,
+  buildCronFireRunIdentity,
+} from './absurd-cron-fire-task';
+import { advanceWorkflowCronSchedule } from '@deepline/workflows/scheduler';
 
 type QueryResult<
   Row extends Record<string, unknown> = Record<string, unknown>,
@@ -212,16 +217,23 @@ const POSTGRES_SCHEDULER_SCHEMA_INIT_STATEMENT_TIMEOUT_MS = 60_000;
  * interrupted deployment cannot claim a newer version without its required
  * objects.
  */
-// v36 adds a blocked-outbox oldest-first index. It bounds the operator health
-// probe even when permanently failed projection facts accumulate, while the
-// existing dead-letter index remains optimized for repair recency.
-export const POSTGRES_SCHEDULER_SCHEMA_VERSION = 36;
+// v37 adds the runtime-owned cron schedule cursor and its due-time index. The
+// table is additive: v36 admission and outbox projection remain valid while a
+// deploy expands the shared schema, then the marker records the completed
+// runtime-cron capability for deployment tooling.
+export const POSTGRES_SCHEDULER_SCHEMA_VERSION = 37;
 const POSTGRES_SCHEDULER_SCHEMA_MIGRATIONS_TABLE =
   'scheduler_schema_migrations';
 export const POSTGRES_SCHEDULER_OPEN_RECOVERY_INDEX =
   'runtime_scheduler_runs_open_recovery_idx';
 const POSTGRES_SCHEDULER_DEPENDENCY_CIRCUITS_TABLE =
   'runtime_dependency_circuits';
+/**
+ * Runtime-owned cursor for a scheduled Play. Convex remains the authored
+ * control-plane projection; this row is the execution owner once a binding is
+ * cut over, so a Run and its successor can commit together.
+ */
+const POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE = 'cron_schedules';
 const RECOVERY_CIRCUIT_OPEN_MS =
   RUNTIME_RELIABILITY_POLICY.recovery.circuitOpenMs;
 const RECOVERY_CIRCUIT_PROBE_LEASE_MS =
@@ -992,6 +1004,7 @@ export type PostgresSchedulerSchemaShapeRequirements = Readonly<{
   admissionPriorityIndex?: boolean;
   terminalComputeBillingOutboxTrigger?: boolean;
   outboxWakeTrigger?: boolean;
+  cronScheduleSchema?: boolean;
 }>;
 
 export async function hasCurrentPostgresSchedulerSchemaShape(
@@ -1240,6 +1253,49 @@ export async function hasCurrentPostgresSchedulerSchemaShape(
         AND to_regclass($20) IS NOT NULL
         AND to_regclass($21) IS NOT NULL
         AND to_regclass($22) IS NOT NULL
+        AND (
+          $25::boolean = false
+          OR (
+            to_regclass($26) IS NOT NULL
+            AND (
+              SELECT count(DISTINCT column_name)
+              FROM information_schema.columns
+              WHERE table_schema = $1
+                AND table_name = '${POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE}'
+                AND column_name IN (
+                  'schedule_id',
+                  'generation',
+                  'state',
+                  'cron',
+                  'timezone',
+                  'current_due_at',
+                  'current_fire_task_id',
+                  'current_fire_generation',
+                  'current_fire_queue_name',
+                  'last_fired_at',
+                  'block_reason',
+                  'cancellation_reason',
+                  'source_pin_json',
+                  'launch_json',
+                  'created_at',
+                  'updated_at'
+                )
+            ) = 16
+            AND EXISTS (
+              SELECT 1
+              FROM pg_index AS index_row
+              JOIN pg_class AS index_class
+                ON index_class.oid = index_row.indexrelid
+              JOIN pg_namespace AS index_namespace
+                ON index_namespace.oid = index_class.relnamespace
+              WHERE index_namespace.nspname = $1
+                AND index_class.relname = 'runtime_scheduler_cron_schedules_due_idx'
+                AND index_row.indrelid = to_regclass($26)
+                AND index_row.indisready
+                AND index_row.indisvalid
+            )
+          )
+        )
         -- Canonical Integration Operation outcomes are additive to the
         -- transport receipt. Old byte-only rows remain readable by the
         -- gateway, but can never be mistaken for a canonical operation.
@@ -1483,6 +1539,8 @@ export async function hasCurrentPostgresSchedulerSchemaShape(
       `${quotedSchema}.${quoteIdent('outbox_repair_operations')}`,
       requirements.outboxWakeTrigger !== false,
       requirements.admissionPriorityIndex !== false,
+      requirements.cronScheduleSchema !== false,
+      `${quotedSchema}.${quoteIdent(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE)}`,
     ],
   );
   if (currentShape.rows[0]?.ready !== true) return false;
@@ -1712,6 +1770,68 @@ async function ensurePostgresSchedulerOutboxWakeTrigger(
   `);
 }
 
+/**
+ * Additive, independent schema for the cron successor owner. It intentionally
+ * does not participate in the global scheduler schema marker: older app and
+ * worker builds neither read nor write this table, and making ordinary Run
+ * admission wait on this rollout would turn an additive timer deployment into
+ * an availability dependency.
+ */
+async function ensurePostgresSchedulerCronScheduleSchema(
+  client: PostgresSchedulerQueryClient,
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<void> {
+  await client.query(`
+    CREATE TABLE IF NOT EXISTS ${tableName(
+      POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE,
+      options,
+    )} (
+      schedule_id text PRIMARY KEY,
+      generation bigint NOT NULL CHECK (generation > 0),
+      state text NOT NULL CHECK (state IN ('active', 'blocked', 'cancelled')),
+      cron text NOT NULL,
+      timezone text,
+      current_due_at timestamptz NOT NULL,
+      current_fire_task_id text,
+      current_fire_generation bigint NOT NULL DEFAULT 1 CHECK (current_fire_generation > 0),
+      current_fire_queue_name text,
+      last_fired_at timestamptz,
+      block_reason text,
+      cancellation_reason text,
+      source_pin_json jsonb,
+      launch_json jsonb NOT NULL,
+      created_at timestamptz NOT NULL DEFAULT now(),
+      updated_at timestamptz NOT NULL DEFAULT now()
+    )
+  `);
+  await client.query(`
+    ALTER TABLE ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)}
+      ADD COLUMN IF NOT EXISTS block_reason text
+  `);
+  await client.query(`
+    ALTER TABLE ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)}
+      ADD COLUMN IF NOT EXISTS current_fire_generation bigint NOT NULL DEFAULT 1
+  `);
+  await client.query(`
+    ALTER TABLE ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)}
+      ADD COLUMN IF NOT EXISTS current_fire_queue_name text
+  `);
+  await client.query(`
+    ALTER TABLE ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)}
+      ADD COLUMN IF NOT EXISTS cancellation_reason text
+  `);
+  await client.query(`
+    ALTER TABLE ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)}
+      ADD COLUMN IF NOT EXISTS source_pin_json jsonb
+  `);
+  await client.query(`
+    CREATE INDEX IF NOT EXISTS runtime_scheduler_cron_schedules_due_idx
+      ON ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)}
+        (current_due_at, schedule_id)
+      WHERE state = 'active'
+  `);
+}
+
 export async function ensurePostgresSchedulerSchema(
   client: PostgresSchedulerQueryClient,
   options?: Pick<PostgresSchedulerOptions, 'schema'> & {
@@ -1817,7 +1937,7 @@ export async function ensurePostgresSchedulerSchema(
     // trigger as a narrow migration: replaying historical schema DDL in one
     // transaction against a live worker fleet can invert table-lock order with
     // terminal writers.
-    const schemaIsCurrentWithoutAdditiveOutboxTriggers =
+    const schemaIsCurrentWithoutAdditiveFastPathObjects =
       !schemaIsCurrent &&
       (await hasCurrentPostgresSchedulerSchemaShape(client, options, {
         openRecoveryIndex: !options?.deferOpenRecoveryIndex,
@@ -1825,17 +1945,10 @@ export async function ensurePostgresSchedulerSchema(
         admissionPriorityIndex: !options?.deferRuntimeAdminIndexes,
         terminalComputeBillingOutboxTrigger: false,
         outboxWakeTrigger: false,
-      }));
-    const schemaIsCurrentWithoutTerminalComputeBillingOutboxTrigger =
-      !schemaIsCurrent &&
-      (await hasCurrentPostgresSchedulerSchemaShape(client, options, {
-        openRecoveryIndex: !options?.deferOpenRecoveryIndex,
-        runtimeAdminIndexes: !options?.deferRuntimeAdminIndexes,
-        admissionPriorityIndex: !options?.deferRuntimeAdminIndexes,
-        terminalComputeBillingOutboxTrigger: false,
+        cronScheduleSchema: false,
       }));
     const schemaCoreIsCurrent =
-      schemaIsCurrent || schemaIsCurrentWithoutAdditiveOutboxTriggers;
+      schemaIsCurrent || schemaIsCurrentWithoutAdditiveFastPathObjects;
     // Older workers can still create a release-only fence after the current
     // schema marker has been written. The metadata is current, but the data
     // must be copied before a new worker trusts the fast path.
@@ -1853,13 +1966,14 @@ export async function ensurePostgresSchedulerSchema(
     const hasLegacyAdmissionRows =
       legacyAdmissionRows?.rows[0]?.present === true;
     if (schemaCoreIsCurrent) {
-      if (schemaIsCurrentWithoutTerminalComputeBillingOutboxTrigger) {
+      if (!schemaIsCurrent) {
         await ensurePostgresSchedulerTerminalComputeBillingOutboxTrigger(
           client,
           options,
         );
       }
       await ensurePostgresSchedulerOutboxWakeTrigger(client, options);
+      await ensurePostgresSchedulerCronScheduleSchema(client, options);
       if (hasLegacyAdmissionRows) {
         await migrateLegacyReleaseAdmissionRows(client, options);
       }
@@ -3111,6 +3225,7 @@ export async function ensurePostgresSchedulerSchema(
       )} (version) VALUES ($1) ON CONFLICT (version) DO NOTHING`,
       [POSTGRES_SCHEDULER_SCHEMA_VERSION],
     );
+    await ensurePostgresSchedulerCronScheduleSchema(client, options);
     if (hadOutbox.rows[0]?.present !== true) {
       await client.query(
         `
@@ -3518,17 +3633,24 @@ export async function ensureAbsurdSchema(
   client: PostgresSchedulerQueryClient,
 ): Promise<void> {
   const [lockClassId, lockObjectId] = absurdSchemaInitAdvisoryLockKey();
-  await client.query('BEGIN');
+  let stage = 'begin transaction';
+  let transactionStarted = false;
   let committed = false;
   try {
+    await client.query('BEGIN');
+    transactionStarted = true;
+
+    stage = 'set bootstrap statement timeout';
     await client.query(
       `SELECT set_config('statement_timeout', '${POSTGRES_SCHEDULER_SCHEMA_INIT_STATEMENT_TIMEOUT_MS}', true)`,
     );
+    stage = 'acquire Absurd schema bootstrap advisory lock';
     await client.query(
       `SELECT pg_advisory_xact_lock($1::integer, $2::integer)`,
       [lockClassId, lockObjectId],
     );
 
+    stage = 'read Absurd schema catalog marker';
     const present = await client.query<{ present: boolean }>(
       `SELECT EXISTS (
          SELECT 1
@@ -3540,11 +3662,13 @@ export async function ensureAbsurdSchema(
     );
 
     if (present.rows[0]?.present) {
+      stage = 'read installed Absurd schema version';
       const versionRow = await client.query<{ v: string | null }>(
         `SELECT absurd.get_schema_version() AS v`,
       );
       const installed = versionRow.rows[0]?.v ?? null;
       if (installed === ABSURD_SCHEMA_VERSION) {
+        stage = 'read Absurd compatibility marker catalog entry';
         const marker = await client.query<{ present: boolean }>(
           `SELECT EXISTS (
              SELECT 1
@@ -3554,6 +3678,7 @@ export async function ensureAbsurdSchema(
                AND p.proname = 'deepline_no_scheduler_org_cap_compatibility_version'
            ) AS present`,
         );
+        stage = 'read Absurd compatibility marker version';
         const markerVersion = marker.rows[0]?.present
           ? await client.query<{ v: string | null }>(
               `SELECT absurd.deepline_no_scheduler_org_cap_compatibility_version() AS v`,
@@ -3563,13 +3688,16 @@ export async function ensureAbsurdSchema(
           markerVersion?.rows[0]?.v !==
           ABSURD_NO_SCHEDULER_ORG_CAP_COMPATIBILITY_VERSION
         ) {
+          stage = 'apply Absurd no-org-cap compatibility function patch';
           await client.query(
             readAbsurdSchemaNoSchedulerOrgCapCompatibilitySql(),
           );
+          stage = 'apply Absurd no-org-cap compatibility marker patch';
           await client.query(
             readAbsurdSchemaNoSchedulerOrgCapCompatibilityMarkerSql(),
           );
         }
+        stage = 'commit verified Absurd schema bootstrap';
         await client.query('COMMIT');
         committed = true;
         return;
@@ -3579,32 +3707,42 @@ export async function ensureAbsurdSchema(
           `"${ABSURD_SCHEMA_VERSION}". Continuing; the next SQL operation ` +
           'will report any missing relation, column, or function.',
       );
+      stage = 'commit non-current Absurd schema marker';
       await client.query('COMMIT');
       committed = true;
       return;
     }
 
+    stage = 'apply full Absurd schema';
     await client.query(readAbsurdSchemaSql());
+    stage = 'apply Absurd no-org-cap compatibility function patch';
     await client.query(readAbsurdSchemaNoSchedulerOrgCapCompatibilitySql());
+    stage = 'apply Absurd no-org-cap compatibility marker patch';
     await client.query(
       readAbsurdSchemaNoSchedulerOrgCapCompatibilityMarkerSql(),
     );
+    stage = 'commit newly initialized Absurd schema';
     await client.query('COMMIT');
     committed = true;
   } catch (error) {
-    if (!committed) {
+    const primaryError = new Error(
+      `Failed to initialize Absurd schema during ${stage}. ` +
+        `Primary error: ${errorMessage(error)}.`,
+      { cause: error },
+    );
+    if (transactionStarted && !committed) {
       try {
         await client.query('ROLLBACK');
       } catch (rollbackError) {
         throw new AggregateError(
-          [error, rollbackError],
+          [primaryError, rollbackError],
           'Failed to initialize absurd schema and roll back the failed transaction. ' +
-            `Primary error: ${errorMessage(error)}. ` +
+            `${primaryError.message} ` +
             `Rollback error: ${errorMessage(rollbackError)}.`,
         );
       }
     }
-    throw error;
+    throw primaryError;
   }
 }
 
@@ -3629,7 +3767,12 @@ export async function submitPostgresAbsurdPlayRun(
   taskRecoveryRequired: boolean;
 }> {
   const task = buildAbsurdPlayRunTask({
-    launch: input,
+    // This fence applies to admission only. A repaired historic task must
+    // retain the persisted launch envelope, not the one-shot retry policy.
+    launch: (() => {
+      const { existingOnly: _existingOnly, ...launch } = input;
+      return launch;
+    })(),
     schedulerSchema: options?.schema,
   });
   const submitted = await submitPostgresSchedulerRunTransaction(
@@ -3689,9 +3832,11 @@ async function submitPostgresSchedulerRunTransaction(
     asyncParentRunAttempt: _asyncParentRunAttempt,
     asyncParentRunLeaseToken: _asyncParentRunLeaseToken,
     asyncParentAttemptRequired: _asyncParentAttemptRequired,
+    existingOnly: requestedExistingOnly,
     ...durableInput
   } = input;
   input = durableInput;
+  const existingOnlySql = requestedExistingOnly === true ? 'true' : 'false';
   const releaseId = input.absurdReleaseId?.trim() || null;
   const legacyPreviewRelease =
     releaseId === 'dev' || releaseId?.startsWith('dev-') === true;
@@ -3734,6 +3879,7 @@ async function submitPostgresSchedulerRunTransaction(
           NOT admission.existing_run
           AND admission.accepting_new
           AND admission.parent_accepting
+          AND NOT ${existingOnlySql}
         ) OR (
           ${recoverExistingTaskSql}
           AND admission.existing_run
@@ -3921,6 +4067,7 @@ async function submitPostgresSchedulerRunTransaction(
         WHERE NOT existing_run
           AND accepting_new
           AND parent_accepting
+          AND NOT ${existingOnlySql}
         ON CONFLICT (run_id) DO NOTHING
         RETURNING run_id, absurd_task_id
       ), run_recovery AS (
@@ -4000,7 +4147,7 @@ async function submitPostgresSchedulerRunTransaction(
       )
       SELECT (
                (NOT admission.existing_run AND admission.accepting_new
-                 AND admission.parent_accepting)
+                 AND admission.parent_accepting AND NOT ${existingOnlySql})
                OR admission.matching_existing
              ) AS accepted,
              admission.accepting_new,
@@ -4085,6 +4232,11 @@ async function submitPostgresSchedulerRunTransaction(
       `Play run "${input.runId}" already exists with a different launch.`,
     );
   }
+  if (row?.accepted === false && !row?.existing_run && requestedExistingOnly) {
+    throw new Error(
+      `Play run "${input.runId}" does not exist for an existing-only admission.`,
+    );
+  }
   if (row?.accepted === false) {
     throw new Error(
       `Absurd runtime release "${releaseId}" no longer accepts new launches.`,
@@ -4098,6 +4250,1140 @@ async function submitPostgresSchedulerRunTransaction(
   };
 }
 
+/** Immutable Runtime Postgres state for an Absurd-owned Play cron timer. */
+export type PostgresSchedulerCronSchedule = {
+  scheduleId: string;
+  generation: number;
+  state: 'active' | 'blocked' | 'cancelled';
+  cron: string;
+  timezone: string | null;
+  dueAtMs: number;
+  currentFireTaskId: string | null;
+  currentFireGeneration: number;
+  currentFireQueueName: string | null;
+  /** Immutable source identity only; no executor token or release lane. */
+  sourcePin: PostgresSchedulerCronSourcePin;
+};
+
+export type PostgresSchedulerCronFireTaskState =
+  | 'pending'
+  | 'running'
+  | 'sleeping'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+/**
+ * Read-only health view for the Runtime-owned cron successor contract.
+ *
+ * A schedule is the source-of-truth cursor. Its current fire task is merely
+ * the durable delivery vehicle for that cursor, so a missing or terminal task
+ * on an active row is an operator-visible integrity failure rather than a
+ * reason to silently advance or recreate an occurrence.
+ */
+export type PostgresSchedulerCronHealth = {
+  observedAtMs: number;
+  activeSchedules: number;
+  blockedSchedules: number;
+  cancelledSchedules: number;
+  overdueSchedules: number;
+  oldestOverdueDueAtMs: number | null;
+  missingCurrentFireTasks: number;
+  terminalCurrentFireTasks: number;
+  issues: Array<{
+    scheduleId: string;
+    generation: number;
+    state: 'active' | 'blocked' | 'cancelled';
+    dueAtMs: number;
+    currentFireGeneration: number;
+    currentFireTaskId: string | null;
+    currentFireQueueName: string | null;
+    fireTaskState: PostgresSchedulerCronFireTaskState | null;
+    overdue: boolean;
+    missingCurrentFireTask: boolean;
+    terminalCurrentFireTask: boolean;
+  }>;
+};
+
+type PostgresSchedulerCronHealthQueryRow = {
+  schedule_id: string;
+  generation: number | string;
+  state: 'active' | 'blocked' | 'cancelled';
+  due_at_ms: number | string;
+  current_fire_generation: number | string;
+  current_fire_task_id: string | null;
+  current_fire_queue_name: string | null;
+  fire_task_state: string | null;
+  overdue: boolean;
+  missing_current_fire_task: boolean;
+  terminal_current_fire_task: boolean;
+};
+
+const POSTGRES_SCHEDULER_CRON_FIRE_TASK_STATES =
+  new Set<PostgresSchedulerCronFireTaskState>([
+    'pending',
+    'running',
+    'sleeping',
+    'completed',
+    'failed',
+    'cancelled',
+  ]);
+
+function postgresSchedulerCronFireTaskState(
+  value: string | null,
+): PostgresSchedulerCronFireTaskState | null {
+  return value &&
+    POSTGRES_SCHEDULER_CRON_FIRE_TASK_STATES.has(
+      value as PostgresSchedulerCronFireTaskState,
+    )
+    ? (value as PostgresSchedulerCronFireTaskState)
+    : null;
+}
+
+function postgresSchedulerCronHealthInteger(
+  value: number | string | null | undefined,
+): number {
+  const parsed = Number(value ?? 0);
+  return Number.isSafeInteger(parsed) ? parsed : 0;
+}
+
+function assertPostgresSchedulerCronHealthInput(input: {
+  nowMs?: number;
+  limit?: number;
+}): { nowMs: number; limit: number } {
+  const nowMs = input.nowMs ?? Date.now();
+  if (!Number.isSafeInteger(nowMs) || nowMs <= 0) {
+    throw new Error('Cron health nowMs must be a positive safe integer.');
+  }
+  const limit = input.limit ?? 50;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
+    throw new Error(
+      'Cron health limit must be a safe integer from 1 through 100.',
+    );
+  }
+  return { nowMs, limit };
+}
+
+/**
+ * Read a bounded, non-mutating cron integrity report.
+ *
+ * The query joins only registered Absurd queues before asking the engine for a
+ * task. A retired/missing queue therefore becomes a `missingCurrentFireTask`
+ * signal instead of causing this diagnostic endpoint to fail while it is most
+ * needed. Repair remains an explicit, separately fenced operation.
+ */
+export async function readPostgresSchedulerCronHealth(
+  client: PostgresSchedulerQueryClient,
+  input: { nowMs?: number; limit?: number } = {},
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<PostgresSchedulerCronHealth> {
+  const { nowMs, limit } = assertPostgresSchedulerCronHealthInput(input);
+  const schedules = tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options);
+  const healthRowsSql = `
+    WITH schedules AS MATERIALIZED (
+      SELECT schedule_id,
+             generation,
+             state,
+             floor(extract(epoch FROM current_due_at) * 1000)::bigint AS due_at_ms,
+             current_fire_task_id,
+             current_fire_generation,
+             current_fire_queue_name
+      FROM ${schedules}
+    ), valid_timer_references AS MATERIALIZED (
+      SELECT schedule.schedule_id,
+             schedule.current_fire_task_id,
+             schedule.current_fire_queue_name
+      FROM schedules AS schedule
+      JOIN absurd.queues AS queue
+        ON queue.queue_name = schedule.current_fire_queue_name
+      WHERE schedule.current_fire_task_id ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+    ), timer_states AS MATERIALIZED (
+      SELECT reference.schedule_id,
+             task.state AS fire_task_state
+      FROM valid_timer_references AS reference
+      CROSS JOIN LATERAL absurd.get_task_result(
+        reference.current_fire_queue_name,
+        reference.current_fire_task_id::uuid
+      ) AS task
+    ), health_rows AS MATERIALIZED (
+      SELECT schedule.schedule_id,
+             schedule.generation,
+             schedule.state,
+             schedule.due_at_ms,
+             schedule.current_fire_generation,
+             schedule.current_fire_task_id,
+             schedule.current_fire_queue_name,
+             timer.fire_task_state,
+             (schedule.state = 'active' AND schedule.due_at_ms <= $1::bigint) AS overdue,
+             (
+               schedule.state = 'active'
+               AND (
+                 schedule.current_fire_task_id IS NULL
+                 OR schedule.current_fire_queue_name IS NULL
+                 OR NOT COALESCE(
+                   schedule.current_fire_task_id ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$',
+                   false
+                 )
+                 OR timer.fire_task_state IS NULL
+               )
+             ) AS missing_current_fire_task,
+             (
+               schedule.state = 'active'
+               AND timer.fire_task_state IN ('completed', 'failed', 'cancelled')
+             ) AS terminal_current_fire_task
+      FROM schedules AS schedule
+      LEFT JOIN timer_states AS timer
+        ON timer.schedule_id = schedule.schedule_id
+    )`;
+  const summary = await client.query<{
+    active_schedules: number | string;
+    blocked_schedules: number | string;
+    cancelled_schedules: number | string;
+    overdue_schedules: number | string;
+    oldest_overdue_due_at_ms: number | string | null;
+    missing_current_fire_tasks: number | string;
+    terminal_current_fire_tasks: number | string;
+  }>(
+    `${healthRowsSql}
+      SELECT count(*) FILTER (WHERE state = 'active')::text AS active_schedules,
+             count(*) FILTER (WHERE state = 'blocked')::text AS blocked_schedules,
+             count(*) FILTER (WHERE state = 'cancelled')::text AS cancelled_schedules,
+             count(*) FILTER (WHERE overdue)::text AS overdue_schedules,
+             min(due_at_ms) FILTER (WHERE overdue) AS oldest_overdue_due_at_ms,
+             count(*) FILTER (WHERE missing_current_fire_task)::text AS missing_current_fire_tasks,
+             count(*) FILTER (WHERE terminal_current_fire_task)::text AS terminal_current_fire_tasks
+      FROM health_rows`,
+    [nowMs],
+  );
+  const issueRows = await client.query<PostgresSchedulerCronHealthQueryRow>(
+    `${healthRowsSql}
+      SELECT schedule_id,
+             generation,
+             state,
+             due_at_ms,
+             current_fire_generation,
+             current_fire_task_id,
+             current_fire_queue_name,
+             fire_task_state,
+             overdue,
+             missing_current_fire_task,
+             terminal_current_fire_task
+      FROM health_rows
+      WHERE state = 'blocked'
+         OR overdue
+         OR missing_current_fire_task
+         OR terminal_current_fire_task
+      ORDER BY
+        (state = 'blocked') DESC,
+        missing_current_fire_task DESC,
+        terminal_current_fire_task DESC,
+        overdue DESC,
+        due_at_ms ASC,
+        schedule_id ASC
+      LIMIT $2::int`,
+    [nowMs, limit],
+  );
+  const row = summary.rows[0];
+  return {
+    observedAtMs: nowMs,
+    activeSchedules: postgresSchedulerCronHealthInteger(row?.active_schedules),
+    blockedSchedules: postgresSchedulerCronHealthInteger(
+      row?.blocked_schedules,
+    ),
+    cancelledSchedules: postgresSchedulerCronHealthInteger(
+      row?.cancelled_schedules,
+    ),
+    overdueSchedules: postgresSchedulerCronHealthInteger(
+      row?.overdue_schedules,
+    ),
+    oldestOverdueDueAtMs:
+      row?.oldest_overdue_due_at_ms == null
+        ? null
+        : postgresSchedulerCronHealthInteger(row.oldest_overdue_due_at_ms),
+    missingCurrentFireTasks: postgresSchedulerCronHealthInteger(
+      row?.missing_current_fire_tasks,
+    ),
+    terminalCurrentFireTasks: postgresSchedulerCronHealthInteger(
+      row?.terminal_current_fire_tasks,
+    ),
+    issues: issueRows.rows.map((issue) => ({
+      scheduleId: issue.schedule_id,
+      generation: postgresSchedulerCronHealthInteger(issue.generation),
+      state: issue.state,
+      dueAtMs: postgresSchedulerCronHealthInteger(issue.due_at_ms),
+      currentFireGeneration: postgresSchedulerCronHealthInteger(
+        issue.current_fire_generation,
+      ),
+      currentFireTaskId: issue.current_fire_task_id,
+      currentFireQueueName: issue.current_fire_queue_name,
+      fireTaskState: postgresSchedulerCronFireTaskState(issue.fire_task_state),
+      overdue: issue.overdue === true,
+      missingCurrentFireTask: issue.missing_current_fire_task === true,
+      terminalCurrentFireTask: issue.terminal_current_fire_task === true,
+    })),
+  };
+}
+
+/** A pinned schedule can never become valid by retrying its same fire task. */
+export class PostgresSchedulerCronScheduleConfigurationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PostgresSchedulerCronScheduleConfigurationError';
+  }
+}
+
+/**
+ * The timer stores the facts needed to reconstruct a pinned admission, not a
+ * previously prepared launch. Executor tokens, preloaded session keys,
+ * callback URLs, and release lanes are all intentionally absent: Vercel
+ * creates them at the fire instant.
+ */
+export type PostgresSchedulerCronSourcePin = {
+  orgId: string;
+  userId: string | null;
+  playName: string;
+  revisionId: string | null;
+  artifactStorageKey: string;
+  artifactKind: 'cjs_node20' | null;
+  artifactHash: string | null;
+  graphHash: string | null;
+  staticPipeline: unknown | null;
+  input: PlaySchedulerSubmitInput['input'];
+  source: 'published' | 'draft';
+  schedulerSchema: string | null;
+};
+
+export function postgresSchedulerCronSourcePinFromLaunch(
+  launch: PlaySchedulerSubmitInput,
+): PostgresSchedulerCronSourcePin {
+  const artifactKind =
+    launch.runtimeArtifact &&
+    typeof launch.runtimeArtifact === 'object' &&
+    (launch.runtimeArtifact as { artifactKind?: unknown }).artifactKind ===
+      'cjs_node20'
+      ? 'cjs_node20'
+      : null;
+  return {
+    orgId: launch.orgId,
+    userId: launch.userId ?? null,
+    playName: launch.playName,
+    revisionId: launch.revisionId ?? null,
+    artifactStorageKey: launch.artifactStorageKey,
+    artifactKind,
+    artifactHash: launch.artifactHash || null,
+    graphHash: launch.graphHash || null,
+    staticPipeline: launch.staticPipeline ?? null,
+    input: launch.input,
+    source: launch.source === 'draft' ? 'draft' : 'published',
+    schedulerSchema: launch.schedulerSchema ?? null,
+  };
+}
+
+export type SeedPostgresSchedulerCronScheduleInput = {
+  scheduleId: string;
+  generation: number;
+  dueAtMs: number;
+  cron: string;
+  timezone?: string | null;
+  sourcePin: PostgresSchedulerCronSourcePin;
+  queueName: string;
+  /** Explicit release registration gate; absence is never treated as ready. */
+  releaseId: string;
+  releaseEnvironment: 'preview' | 'production';
+};
+
+function assertPostgresSchedulerCronScheduleInput(input: {
+  scheduleId: string;
+  generation: number;
+  fireGeneration?: number;
+  dueAtMs: number;
+  cron?: string;
+}): void {
+  if (!input.scheduleId.trim()) {
+    throw new Error('Cron schedule requires a non-empty scheduleId.');
+  }
+  if (!Number.isSafeInteger(input.generation) || input.generation <= 0) {
+    throw new Error(
+      'Cron schedule generation must be a positive safe integer.',
+    );
+  }
+  if (
+    input.fireGeneration !== undefined &&
+    (!Number.isSafeInteger(input.fireGeneration) || input.fireGeneration <= 0)
+  ) {
+    throw new Error(
+      'Cron schedule fireGeneration must be a positive safe integer.',
+    );
+  }
+  if (!Number.isSafeInteger(input.dueAtMs) || input.dueAtMs <= 0) {
+    throw new Error('Cron schedule dueAtMs must be a positive safe integer.');
+  }
+  if (input.cron !== undefined && !input.cron.trim()) {
+    throw new Error('Cron schedule requires a non-empty cron expression.');
+  }
+}
+
+/**
+ * Persist (or generation-replace) one Runtime-owned cron cursor and its first
+ * Absurd timer in a single statement. A caller must leave Convex as the owner
+ * until this returns: the cross-store ownership flip is deliberately separate
+ * from this durable timer primitive.
+ */
+export async function seedPostgresSchedulerCronSchedule(
+  client: PostgresSchedulerQueryClient,
+  input: SeedPostgresSchedulerCronScheduleInput,
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<{
+  created: boolean;
+  scheduleId: string;
+  fireTaskId: string | null;
+}> {
+  assertPostgresSchedulerCronScheduleInput(input);
+  if (!input.releaseId?.trim()) {
+    throw new Error(
+      'Cron schedule requires an explicitly registered releaseId.',
+    );
+  }
+  const sourcePin = input.sourcePin;
+  const task = buildAbsurdCronFireTask({
+    scheduleId: input.scheduleId.trim(),
+    generation: input.generation,
+    fireGeneration: 1,
+    dueAtMs: input.dueAtMs,
+    schedulerSchema: options?.schema ?? sourcePin.schedulerSchema ?? null,
+    orgId: sourcePin.orgId,
+  });
+  const releaseAdmissionKey = `${input.releaseEnvironment}:${input.releaseId.trim()}`;
+  const result = await client.query<{
+    accepted: boolean;
+    created: boolean;
+    existing_generation: number | null;
+    existing_matches_input: boolean | null;
+    fire_task_id: string | null;
+  }>(
+    `
+      WITH schedule_lock AS MATERIALIZED (
+        SELECT pg_advisory_xact_lock(
+          ${POSTGRES_SCHEDULER_RELEASE_ADMISSION_LOCK_NAMESPACE},
+          ${quoteIdent(schemaName(options))}.runtime_release_admission_lock_id(
+            'cron-schedule:' || $1::text
+          )
+        )
+      ), existing AS MATERIALIZED (
+        SELECT schedule.generation,
+               (
+                 schedule.cron = $4::text
+                 AND schedule.timezone IS NOT DISTINCT FROM $5::text
+                 AND schedule.current_due_at = to_timestamp($3::double precision / 1000.0)
+                 AND schedule.source_pin_json = $6::jsonb
+               ) AS matches_input
+        FROM schedule_lock
+        JOIN ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)} AS schedule
+          ON schedule.schedule_id = $1::text
+        FOR UPDATE
+      ), release_gate AS MATERIALIZED (
+        SELECT accepting
+        FROM ${tableName('runtime_release_admission', options)}
+        WHERE release_id = $11::text
+      ), task_request AS (
+        SELECT $7::text AS queue_name,
+               $8::text AS task_name,
+               $9::jsonb AS params,
+               $10::jsonb AS options
+        WHERE (
+          NOT EXISTS (SELECT 1 FROM existing)
+          OR (SELECT generation FROM existing) < $2::bigint
+        )
+          AND coalesce((SELECT accepting FROM release_gate), false)
+      ), task_spawn AS MATERIALIZED (
+        SELECT spawned.task_id::text AS task_id
+        FROM task_request
+        CROSS JOIN LATERAL absurd.spawn_task(
+          task_request.queue_name,
+          task_request.task_name,
+          task_request.params,
+          task_request.options
+        ) AS spawned
+      ), schedule_upsert AS (
+        INSERT INTO ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)} AS schedule (
+          schedule_id, generation, state, cron, timezone, current_due_at,
+          current_fire_task_id, current_fire_generation, current_fire_queue_name,
+          source_pin_json, launch_json
+        )
+        SELECT $1::text, $2::bigint, 'active', $4::text, $5::text,
+               to_timestamp($3::double precision / 1000.0),
+               (SELECT task_id FROM task_spawn), 1, $7::text, $6::jsonb, $6::jsonb
+        WHERE (
+          NOT EXISTS (SELECT 1 FROM existing)
+          OR (SELECT generation FROM existing) < $2::bigint
+        )
+          AND coalesce((SELECT accepting FROM release_gate), false)
+        ON CONFLICT (schedule_id) DO UPDATE
+        SET generation = excluded.generation,
+            state = excluded.state,
+            cron = excluded.cron,
+            timezone = excluded.timezone,
+            current_due_at = excluded.current_due_at,
+            current_fire_task_id = excluded.current_fire_task_id,
+            current_fire_generation = excluded.current_fire_generation,
+            current_fire_queue_name = excluded.current_fire_queue_name,
+            source_pin_json = excluded.source_pin_json,
+            -- Keep the legacy non-null column free of credentials while old
+            -- schedules drain. New readers use source_pin_json exclusively.
+            launch_json = excluded.launch_json,
+            last_fired_at = NULL,
+            updated_at = now()
+        WHERE schedule.generation < excluded.generation
+        RETURNING schedule_id
+      )
+      SELECT
+        (EXISTS (SELECT 1 FROM schedule_upsert) OR EXISTS (SELECT 1 FROM existing))
+          AS accepted,
+        EXISTS (SELECT 1 FROM schedule_upsert) AS created,
+        (SELECT generation FROM existing) AS existing_generation,
+        (SELECT matches_input FROM existing) AS existing_matches_input,
+        coalesce((SELECT accepting FROM release_gate), false) AS release_accepting,
+        (SELECT task_id FROM task_spawn) AS fire_task_id
+    `,
+    [
+      input.scheduleId.trim(),
+      input.generation,
+      input.dueAtMs,
+      input.cron.trim(),
+      input.timezone?.trim() || null,
+      stringifyPostgresJson(sourcePin),
+      input.queueName,
+      task.taskName,
+      stringifyPostgresJson(task.params),
+      stringifyPostgresJson(task.options),
+      releaseAdmissionKey,
+    ],
+  );
+  const row = result.rows[0];
+  if (!row?.accepted) {
+    throw new Error(
+      `Cron schedule "${input.scheduleId}" was not accepted for generation ${input.generation}.`,
+    );
+  }
+  if (
+    typeof row.existing_generation === 'number' &&
+    row.existing_generation > input.generation
+  ) {
+    throw new Error(
+      `Cron schedule "${input.scheduleId}" is already owned by newer generation ${row.existing_generation}.`,
+    );
+  }
+  if (
+    row.existing_generation === input.generation &&
+    row.existing_matches_input !== true
+  ) {
+    throw new Error(
+      `Cron schedule "${input.scheduleId}" generation ${input.generation} already exists with a different immutable configuration.`,
+    );
+  }
+  return {
+    created: row.created === true,
+    scheduleId: input.scheduleId.trim(),
+    fireTaskId: row.fire_task_id ?? null,
+  };
+}
+
+export async function readPostgresSchedulerCronSchedule(
+  client: PostgresSchedulerQueryClient,
+  scheduleId: string,
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<PostgresSchedulerCronSchedule | null> {
+  const result = await client.query<{
+    schedule_id: string;
+    generation: number;
+    state: 'active' | 'blocked' | 'cancelled';
+    cron: string;
+    timezone: string | null;
+    due_at_ms: number;
+    current_fire_task_id: string | null;
+    current_fire_generation: number;
+    current_fire_queue_name: string | null;
+    source_pin_json: unknown;
+    launch_json: unknown;
+  }>(
+    `
+      SELECT schedule_id,
+             generation,
+             state,
+             cron,
+             timezone,
+             floor(extract(epoch FROM current_due_at) * 1000)::bigint AS due_at_ms,
+             current_fire_task_id,
+             current_fire_generation,
+             current_fire_queue_name,
+             source_pin_json,
+             launch_json
+      FROM ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)}
+      WHERE schedule_id = $1::text
+    `,
+    [scheduleId.trim()],
+  );
+  const row = result.rows[0];
+  if (!row) return null;
+  let sourcePin: PostgresSchedulerCronSourcePin;
+  try {
+    sourcePin = row.source_pin_json
+      ? parsePostgresSchedulerCronSourcePin(row.source_pin_json)
+      : postgresSchedulerCronSourcePinFromLaunch(
+          parseLaunchJson(row.launch_json),
+        );
+  } catch (error) {
+    throw new PostgresSchedulerCronScheduleConfigurationError(
+      `Cron schedule "${row.schedule_id}" has malformed pinned source data: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+  return {
+    scheduleId: row.schedule_id,
+    generation: Number(row.generation),
+    state: row.state,
+    cron: row.cron,
+    timezone: row.timezone,
+    dueAtMs: Number(row.due_at_ms),
+    currentFireTaskId: row.current_fire_task_id ?? null,
+    currentFireGeneration: Number(row.current_fire_generation),
+    currentFireQueueName: row.current_fire_queue_name ?? null,
+    sourcePin,
+  };
+}
+
+function cronOccurrenceLaunch(input: {
+  schedule: PostgresSchedulerCronSchedule;
+  launch: PlaySchedulerSubmitInput;
+  schedulerSchema?: string | null;
+  absurdReleaseId?: string | null;
+}): PlaySchedulerSubmitInput {
+  const identity = buildCronFireRunIdentity({
+    scheduleId: input.schedule.scheduleId,
+    generation: input.schedule.generation,
+    dueAtMs: input.schedule.dueAtMs,
+    playName: input.schedule.sourcePin.playName,
+  });
+  const authority = input.launch.runtimeAuthority;
+  if (
+    !authority ||
+    input.launch.runId !== identity.runId ||
+    authority.workflowId !== identity.workflowId ||
+    authority.runId !== identity.runId
+  ) {
+    throw new PostgresSchedulerCronScheduleConfigurationError(
+      `Cron schedule "${input.schedule.scheduleId}" did not receive a fresh authority for its pinned occurrence.`,
+    );
+  }
+  return {
+    ...input.launch,
+    schedulerSchema:
+      input.schedulerSchema ?? input.launch.schedulerSchema ?? null,
+    ...(input.absurdReleaseId?.trim()
+      ? { absurdReleaseId: input.absurdReleaseId.trim() }
+      : {}),
+    runtimeAuthority: authority,
+    runtimeProtocolVersion: protocolForNewPlayRuntimeLaunch(
+      input.launch.runtimeProtocolVersion,
+    ),
+    triggerSource: 'cron',
+    requiresRunCreatedProjection: true,
+  };
+}
+
+export type FirePostgresSchedulerCronScheduleInput = {
+  scheduleId: string;
+  generation: number;
+  /** Matches the durable timer-repair fence for this exact occurrence. */
+  fireGeneration: number;
+  dueAtMs: number;
+  queueName: string;
+  /** Built at the due instant by Vercel; never reuse the seed-time authority. */
+  launch: PlaySchedulerSubmitInput;
+  /** Current accepting lane, resolved by the waking worker rather than seed. */
+  absurdReleaseId?: string | null;
+  /** Environment scopes the release-admission fence. */
+  releaseEnvironment?: 'preview' | 'production';
+};
+
+/**
+ * The cron OCC boundary. The matching schedule row is locked while this one
+ * CTE inserts the immutable Run, its play-run task, run.created fact, next
+ * cron-fire task, and next cursor. A task replay after commit sees a changed
+ * cursor and is a harmless `superseded` no-op.
+ */
+export async function firePostgresSchedulerCronSchedule(
+  client: PostgresSchedulerQueryClient,
+  input: FirePostgresSchedulerCronScheduleInput,
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<
+  | { status: 'admitted'; runId: string; successorDueAtMs: number }
+  | { status: 'superseded' }
+> {
+  assertPostgresSchedulerCronScheduleInput(input);
+  const schedule = await readPostgresSchedulerCronSchedule(
+    client,
+    input.scheduleId,
+    options,
+  );
+  if (
+    !schedule ||
+    schedule.state !== 'active' ||
+    schedule.generation !== input.generation ||
+    schedule.dueAtMs !== input.dueAtMs ||
+    schedule.currentFireGeneration !== input.fireGeneration
+  ) {
+    return { status: 'superseded' };
+  }
+  let successorDueAtMs: number;
+  try {
+    successorDueAtMs = advanceWorkflowCronSchedule(
+      schedule.cron,
+      Math.max(Date.now(), schedule.dueAtMs),
+      schedule.timezone,
+    );
+  } catch (error) {
+    throw new PostgresSchedulerCronScheduleConfigurationError(
+      `Cron schedule "${schedule.scheduleId}" has an invalid pinned expression or timezone: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+  if (
+    !Number.isSafeInteger(successorDueAtMs) ||
+    successorDueAtMs <= schedule.dueAtMs
+  ) {
+    throw new PostgresSchedulerCronScheduleConfigurationError(
+      `Cron schedule "${schedule.scheduleId}" did not produce a future successor occurrence.`,
+    );
+  }
+  const launch = cronOccurrenceLaunch({
+    schedule,
+    launch: input.launch,
+    schedulerSchema: options?.schema,
+    absurdReleaseId: input.absurdReleaseId,
+  });
+  const releaseId = launch.absurdReleaseId?.trim();
+  if (!releaseId) {
+    throw new PostgresSchedulerCronScheduleConfigurationError(
+      `Cron schedule "${schedule.scheduleId}" has no fresh Absurd release lane.`,
+    );
+  }
+  const releaseEnvironment =
+    input.releaseEnvironment ?? launch.absurdReleaseEnvironment ?? 'production';
+  const releaseAdmissionKey = `${releaseEnvironment}:${releaseId}`;
+  const playTask = buildAbsurdPlayRunTask({
+    launch,
+    schedulerSchema: options?.schema,
+  });
+  const successorTask = buildAbsurdCronFireTask({
+    scheduleId: schedule.scheduleId,
+    generation: schedule.generation,
+    fireGeneration: 1,
+    dueAtMs: successorDueAtMs,
+    schedulerSchema: options?.schema ?? launch.schedulerSchema ?? null,
+    orgId: launch.orgId,
+  });
+  const result = await client.query<{
+    admitted: boolean;
+    release_accepting: boolean;
+  }>(
+    `
+      WITH schedule_lock AS MATERIALIZED (
+        SELECT pg_advisory_xact_lock(
+          ${POSTGRES_SCHEDULER_RELEASE_ADMISSION_LOCK_NAMESPACE},
+          ${quoteIdent(schemaName(options))}.runtime_release_admission_lock_id(
+            'cron-schedule:' || $1::text
+          )
+        )
+      ), matching_schedule AS MATERIALIZED (
+        SELECT schedule.schedule_id
+        FROM schedule_lock
+        JOIN ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)} AS schedule
+          ON schedule.schedule_id = $1::text
+        JOIN ${tableName('runtime_release_admission', options)} AS release_gate
+          ON release_gate.release_id = $16::text
+        WHERE schedule.generation = $2::bigint
+          AND schedule.state = 'active'
+          AND schedule.current_due_at = to_timestamp($3::double precision / 1000.0)
+          AND schedule.current_fire_generation = $15::bigint
+          AND release_gate.accepting
+        FOR UPDATE
+      ), existing_run AS MATERIALIZED (
+        SELECT runs.run_id
+        FROM matching_schedule
+        JOIN ${tableName('runs', options)} AS runs ON runs.run_id = $5::text
+      ), play_task_request AS (
+        SELECT $7::text AS queue_name,
+               $8::text AS task_name,
+               $9::jsonb AS params,
+               $10::jsonb AS options
+        WHERE EXISTS (SELECT 1 FROM matching_schedule)
+          AND NOT EXISTS (SELECT 1 FROM existing_run)
+      ), play_task_spawn AS MATERIALIZED (
+        SELECT spawned.task_id::text AS task_id
+        FROM play_task_request
+        CROSS JOIN LATERAL absurd.spawn_task(
+          play_task_request.queue_name,
+          play_task_request.task_name,
+          play_task_request.params,
+          play_task_request.options
+        ) AS spawned
+      ), run_insert AS (
+        INSERT INTO ${tableName('runs', options)} (
+          run_id, org_id, play_id, play_name, graph_hash, runtime_profile,
+          artifact_storage_key, launch_json, input_json, status,
+          absurd_task_id, admission_json
+        )
+        SELECT $5::text,
+               $6::jsonb ->> 'orgId',
+               NULLIF($6::jsonb ->> 'playId', ''),
+               $6::jsonb ->> 'playName',
+               $6::jsonb ->> 'graphHash',
+               $6::jsonb ->> 'runtimeBackend',
+               $6::jsonb ->> 'artifactStorageKey',
+               $6::jsonb,
+               coalesce($6::jsonb -> 'input', '{}'::jsonb),
+               'queued',
+               (SELECT task_id FROM play_task_spawn),
+               $6::jsonb - ARRAY[
+                 'executorToken',
+                 'preloadedDbSessionUnwrapKey',
+                 'preloadedDbSessions',
+                 'submittedAtMs',
+                 'runtimeDeployVersion',
+                 'coordinatorInternalToken',
+                 'vercelProtectionBypassToken'
+               ]::text[]
+        WHERE EXISTS (SELECT 1 FROM matching_schedule)
+          AND NOT EXISTS (SELECT 1 FROM existing_run)
+        RETURNING run_id
+      ), successor_task_request AS (
+        SELECT $11::text AS queue_name,
+               $12::text AS task_name,
+               $13::jsonb AS params,
+               $14::jsonb AS options
+        WHERE EXISTS (SELECT 1 FROM run_insert)
+      ), successor_task_spawn AS MATERIALIZED (
+        SELECT spawned.task_id::text AS task_id
+        FROM successor_task_request
+        CROSS JOIN LATERAL absurd.spawn_task(
+          successor_task_request.queue_name,
+          successor_task_request.task_name,
+          successor_task_request.params,
+          successor_task_request.options
+        ) AS spawned
+      ), outbox_insert AS (
+        INSERT INTO ${tableName('outbox', options)} (
+          event_id, run_id, event_type, payload_json, created_at
+        )
+        SELECT
+          'run-created:' || run_insert.run_id,
+          run_insert.run_id,
+          'run.created',
+          jsonb_strip_nulls(jsonb_build_object(
+            'orgId', $6::jsonb ->> 'orgId',
+            'playId', $6::jsonb ->> 'playId',
+            'playName', $6::jsonb ->> 'playName',
+            'definitionName', $6::jsonb ->> 'definitionName',
+            'playReference', $6::jsonb ->> 'playReference',
+            'definitionScope', $6::jsonb ->> 'definitionScope',
+            'revisionId', $6::jsonb ->> 'revisionId',
+            'workflowFamilyKey', $6::jsonb ->> 'workflowFamilyKey',
+            'artifactStorageKey', $6::jsonb ->> 'artifactStorageKey',
+            'artifactHash', $6::jsonb ->> 'artifactHash',
+            'graphHash', $6::jsonb ->> 'graphHash',
+            'runtimeBackend', $6::jsonb ->> 'runtimeBackend',
+            'schedulerBackend', $6::jsonb ->> 'schedulerBackend',
+            'schedulerSchema', $6::jsonb ->> 'schedulerSchema',
+            'executionProfile', $6::jsonb ->> 'executionProfile',
+            'runtimeReleaseId', $6::jsonb ->> 'runtimeReleaseId',
+            'runtimeDeployVersion', $6::jsonb ->> 'runtimeDeployVersion',
+            'runtimeCallbackBaseUrl', $6::jsonb ->> 'runtimeCallbackBaseUrl',
+            'coordinatorUrl', $6::jsonb ->> 'coordinatorUrl',
+            'coordinatorWorkerName', $6::jsonb ->> 'coordinatorWorkerName',
+            'runtimeWorkflowName', $6::jsonb ->> 'runtimeWorkflowName',
+            'runtimeHarnessWorkerName', $6::jsonb ->> 'runtimeHarnessWorkerName',
+            'maxCreditsPerRun', $6::jsonb -> 'maxCreditsPerRun',
+            'triggerSource', $6::jsonb ->> 'triggerSource',
+            'source', $6::jsonb ->> 'source',
+            'staticPipeline', $6::jsonb -> 'staticPipeline',
+            'inputFileId', $6::jsonb ->> 'inputFileId',
+            'inputBytes', $6::jsonb -> 'inputBytes',
+            'inputSha256', $6::jsonb ->> 'inputSha256',
+            'replayedFromRunId', $6::jsonb ->> 'replayedFromRunId',
+            'parentRunId', $6::jsonb ->> 'parentRunId',
+            'rootRunId', $6::jsonb ->> 'rootRunId',
+            'asyncLaunchKey', $6::jsonb ->> 'asyncLaunchKey',
+            'asyncInvocationKey', $6::jsonb ->> 'asyncInvocationKey',
+            'asyncRequestFingerprint', $6::jsonb ->> 'asyncRequestFingerprint',
+            'asyncAncestryPlayIds', $6::jsonb -> 'asyncAncestryPlayIds',
+            'secretRefs', $6::jsonb -> 'secretRefs',
+            'inputSummary', $6::jsonb -> 'inputSummary'
+          )),
+          ${causalOutboxCreatedAt('run_insert.run_id', options)}
+        FROM run_insert
+        ON CONFLICT (event_id) DO NOTHING
+      ), schedule_advance AS (
+        UPDATE ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)} AS schedule
+        SET current_due_at = to_timestamp($4::double precision / 1000.0),
+            current_fire_task_id = (SELECT task_id FROM successor_task_spawn),
+            current_fire_generation = 1,
+            current_fire_queue_name = $11::text,
+            last_fired_at = clock_timestamp(),
+            updated_at = now()
+        WHERE schedule.schedule_id = $1::text
+          AND schedule.generation = $2::bigint
+          AND schedule.state = 'active'
+          AND schedule.current_due_at = to_timestamp($3::double precision / 1000.0)
+          AND schedule.current_fire_generation = $15::bigint
+          AND EXISTS (SELECT 1 FROM run_insert)
+        RETURNING schedule_id
+      )
+      SELECT EXISTS (SELECT 1 FROM schedule_advance) AS admitted,
+             coalesce(
+               (SELECT accepting
+                  FROM ${tableName('runtime_release_admission', options)}
+                 WHERE release_id = $16::text),
+               false
+             ) AS release_accepting
+    `,
+    [
+      schedule.scheduleId,
+      schedule.generation,
+      schedule.dueAtMs,
+      successorDueAtMs,
+      launch.runId,
+      stringifyPostgresJson(launch),
+      input.queueName,
+      playTask.taskName,
+      stringifyPostgresJson(playTask.params),
+      stringifyPostgresJson(playTask.options),
+      input.queueName,
+      successorTask.taskName,
+      stringifyPostgresJson(successorTask.params),
+      stringifyPostgresJson(successorTask.options),
+      schedule.currentFireGeneration,
+      releaseAdmissionKey,
+    ],
+  );
+  if (result.rows[0]?.release_accepting !== true) {
+    throw new Error(
+      `Cron schedule "${schedule.scheduleId}" cannot fire because Absurd release "${releaseAdmissionKey}" is not accepting admissions.`,
+    );
+  }
+  if (result.rows[0]?.admitted !== true) {
+    return { status: 'superseded' };
+  }
+  return {
+    status: 'admitted',
+    runId: launch.runId,
+    successorDueAtMs,
+  };
+}
+
+/** Fence a malformed/invalid timer so it cannot repeatedly consume workers. */
+export async function blockPostgresSchedulerCronSchedule(
+  client: PostgresSchedulerQueryClient,
+  input: Pick<
+    FirePostgresSchedulerCronScheduleInput,
+    'scheduleId' | 'generation' | 'fireGeneration' | 'dueAtMs'
+  > & {
+    reason: string;
+  },
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<boolean> {
+  const result = await client.query<{ schedule_id: string }>(
+    `
+      UPDATE ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)}
+      SET state = 'blocked',
+          block_reason = left($4::text, 1_000),
+          updated_at = now()
+      WHERE schedule_id = $1::text
+        AND generation = $2::bigint
+        AND state = 'active'
+        AND current_due_at = to_timestamp($3::double precision / 1000.0)
+        AND current_fire_generation = $5::bigint
+      RETURNING schedule_id
+    `,
+    [
+      input.scheduleId,
+      input.generation,
+      input.dueAtMs,
+      input.reason,
+      input.fireGeneration,
+    ],
+  );
+  return result.rows.length > 0;
+}
+
+/**
+ * Fence a Runtime-owned schedule before its source binding is disabled,
+ * archived, suspended, or replaced. The advisory lock is shared with fire and
+ * seed, so an already-sleeping task either commits before the lifecycle write
+ * (a run valid at that instant) or observes `cancelled` and becomes a
+ * superseded no-op. It can never admit after this mutation commits.
+ */
+export async function cancelPostgresSchedulerCronSchedule(
+  client: PostgresSchedulerQueryClient,
+  input: {
+    scheduleId: string;
+    generation: number;
+    reason: string;
+  },
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<boolean> {
+  if (!input.scheduleId.trim()) {
+    throw new Error(
+      'Cron schedule cancellation requires a non-empty scheduleId.',
+    );
+  }
+  if (!Number.isSafeInteger(input.generation) || input.generation <= 0) {
+    throw new Error(
+      'Cron schedule cancellation requires a positive generation.',
+    );
+  }
+  const result = await client.query<{ schedule_id: string }>(
+    `
+      WITH schedule_lock AS MATERIALIZED (
+        SELECT pg_advisory_xact_lock(
+          ${POSTGRES_SCHEDULER_RELEASE_ADMISSION_LOCK_NAMESPACE},
+          ${quoteIdent(schemaName(options))}.runtime_release_admission_lock_id(
+            'cron-schedule:' || $1::text
+          )
+        )
+      )
+      UPDATE ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)} AS schedule
+      SET state = 'cancelled',
+          cancellation_reason = left($3::text, 1_000),
+          updated_at = now()
+      FROM schedule_lock
+      WHERE schedule.schedule_id = $1::text
+        AND schedule.generation = $2::bigint
+        AND schedule.state = 'active'
+      RETURNING schedule.schedule_id
+    `,
+    [input.scheduleId.trim(), input.generation, input.reason],
+  );
+  return result.rows.length > 0;
+}
+
+/**
+ * Replace an observed missing, cancelled, or exhausted timer without changing
+ * its scheduled occurrence. Callers must first inspect the engine task and
+ * pass the observed `fireGeneration`; the CTE then advances that fence and
+ * spawns the replacement in one transaction. A late old timer is superseded
+ * by the generation comparison in `firePostgresSchedulerCronSchedule`.
+ */
+export async function repairPostgresSchedulerCronFire(
+  client: PostgresSchedulerQueryClient,
+  input: {
+    scheduleId: string;
+    generation: number;
+    fireGeneration: number;
+    dueAtMs: number;
+    queueName: string;
+  },
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<{
+  repaired: boolean;
+  fireTaskId: string | null;
+  fireGeneration: number | null;
+}> {
+  assertPostgresSchedulerCronScheduleInput(input);
+  const schedule = await readPostgresSchedulerCronSchedule(
+    client,
+    input.scheduleId,
+    options,
+  );
+  if (
+    !schedule ||
+    schedule.state !== 'active' ||
+    schedule.generation !== input.generation ||
+    schedule.dueAtMs !== input.dueAtMs ||
+    schedule.currentFireGeneration !== input.fireGeneration
+  ) {
+    return { repaired: false, fireTaskId: null, fireGeneration: null };
+  }
+  const replacementGeneration = schedule.currentFireGeneration + 1;
+  const task = buildAbsurdCronFireTask({
+    scheduleId: schedule.scheduleId,
+    generation: schedule.generation,
+    fireGeneration: replacementGeneration,
+    dueAtMs: schedule.dueAtMs,
+    schedulerSchema:
+      options?.schema ?? schedule.sourcePin.schedulerSchema ?? null,
+    orgId: schedule.sourcePin.orgId,
+  });
+  const result = await client.query<{
+    repaired: boolean;
+    fire_task_id: string | null;
+  }>(
+    `
+      WITH schedule_lock AS MATERIALIZED (
+        SELECT pg_advisory_xact_lock(
+          ${POSTGRES_SCHEDULER_RELEASE_ADMISSION_LOCK_NAMESPACE},
+          ${quoteIdent(schemaName(options))}.runtime_release_admission_lock_id(
+            'cron-schedule:' || $1::text
+          )
+        )
+      ), matching_schedule AS MATERIALIZED (
+        SELECT schedule.schedule_id
+        FROM schedule_lock
+        JOIN ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)} AS schedule
+          ON schedule.schedule_id = $1::text
+        WHERE schedule.generation = $2::bigint
+          AND schedule.state = 'active'
+          AND schedule.current_due_at = to_timestamp($4::double precision / 1000.0)
+          AND schedule.current_fire_generation = $3::bigint
+        FOR UPDATE
+      ), task_spawn AS MATERIALIZED (
+        SELECT spawned.task_id::text AS task_id
+        FROM matching_schedule
+        CROSS JOIN LATERAL absurd.spawn_task(
+          $5::text,
+          $6::text,
+          $7::jsonb,
+          $8::jsonb
+        ) AS spawned
+      ), repaired_schedule AS (
+        UPDATE ${tableName(POSTGRES_SCHEDULER_CRON_SCHEDULES_TABLE, options)} AS schedule
+        SET current_fire_task_id = (SELECT task_id FROM task_spawn),
+            current_fire_generation = $9::bigint,
+            current_fire_queue_name = $5::text,
+            updated_at = now()
+        WHERE schedule.schedule_id = $1::text
+          AND schedule.generation = $2::bigint
+          AND schedule.state = 'active'
+          AND schedule.current_due_at = to_timestamp($4::double precision / 1000.0)
+          AND schedule.current_fire_generation = $3::bigint
+          AND EXISTS (SELECT 1 FROM task_spawn)
+        RETURNING schedule.schedule_id
+      )
+      SELECT EXISTS (SELECT 1 FROM repaired_schedule) AS repaired,
+             (SELECT task_id FROM task_spawn) AS fire_task_id
+    `,
+    [
+      schedule.scheduleId,
+      schedule.generation,
+      schedule.currentFireGeneration,
+      schedule.dueAtMs,
+      input.queueName,
+      task.taskName,
+      stringifyPostgresJson(task.params),
+      stringifyPostgresJson(task.options),
+      replacementGeneration,
+    ],
+  );
+  const row = result.rows[0];
+  return {
+    repaired: row?.repaired === true,
+    fireTaskId: row?.fire_task_id ?? null,
+    fireGeneration: row?.repaired === true ? replacementGeneration : null,
+  };
+}
+
 export async function setPostgresSchedulerRuntimeReleaseAdmission(
   client: PostgresSchedulerQueryClient,
   input: {
@@ -5923,6 +7209,58 @@ export async function readPostgresSchedulerLaunch(
   }
 }
 
+/**
+ * One round-trip replay inspection for externally retried admissions. The
+ * caller uses this only to return an already-committed Run without rebuilding
+ * mutable launch dependencies; it is never an admission authority.
+ */
+export type PostgresSchedulerAdmissionSnapshot = {
+  runId: string;
+  /** Empty only for historic rows that predate an owning organization. */
+  orgId: string;
+  status: string;
+  absurdTaskId: string | null;
+  launch: PlaySchedulerSubmitInput;
+};
+
+export async function readPostgresSchedulerAdmission(
+  client: PostgresSchedulerQueryClient,
+  runId: string,
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<PostgresSchedulerAdmissionSnapshot | null> {
+  const result = await client.query<{
+    run_id: string;
+    org_id: string | null;
+    status: string;
+    absurd_task_id: string | null;
+    launch_json: unknown;
+  }>(
+    `
+      SELECT runs.run_id,
+             runs.org_id,
+             runs.status,
+             runs.absurd_task_id,
+             runs.launch_json || coalesce(runs.admission_json, '{}'::jsonb)
+               AS launch_json
+      FROM ${tableName('runs', options)} AS runs
+      WHERE runs.run_id = $1
+    `,
+    [runId],
+  );
+  const row = result.rows[0] ?? null;
+  if (!row) return null;
+  return {
+    runId: row.run_id,
+    orgId: row.org_id ?? '',
+    status: row.status,
+    absurdTaskId:
+      typeof row.absurd_task_id === 'string' && row.absurd_task_id.trim()
+        ? row.absurd_task_id
+        : null,
+    launch: parseLaunchJson(row.launch_json),
+  };
+}
+
 /**
  * Resolve the immutable launch only when the caller proves ownership of the
  * currently live scheduler attempt. Used by the Vercel token issuer so a Fly
@@ -14411,6 +15749,40 @@ function parseLaunchJson(value: unknown): PlaySchedulerSubmitInput {
   return launch as PlaySchedulerSubmitInput;
 }
 
+function parsePostgresSchedulerCronSourcePin(
+  value: unknown,
+): PostgresSchedulerCronSourcePin {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Cron source pin is not an object.');
+  }
+  const pin = value as Partial<PostgresSchedulerCronSourcePin>;
+  if (
+    typeof pin.orgId !== 'string' ||
+    typeof pin.playName !== 'string' ||
+    typeof pin.artifactStorageKey !== 'string' ||
+    !('input' in pin) ||
+    (pin.source !== 'published' && pin.source !== 'draft')
+  ) {
+    throw new Error('Cron source pin is missing required immutable fields.');
+  }
+  return {
+    orgId: pin.orgId,
+    userId: typeof pin.userId === 'string' ? pin.userId : null,
+    playName: pin.playName,
+    revisionId: typeof pin.revisionId === 'string' ? pin.revisionId : null,
+    artifactStorageKey: pin.artifactStorageKey,
+    artifactKind: pin.artifactKind === 'cjs_node20' ? 'cjs_node20' : null,
+    artifactHash:
+      typeof pin.artifactHash === 'string' ? pin.artifactHash : null,
+    graphHash: typeof pin.graphHash === 'string' ? pin.graphHash : null,
+    staticPipeline: pin.staticPipeline ?? null,
+    input: pin.input as PlaySchedulerSubmitInput['input'],
+    source: pin.source,
+    schedulerSchema:
+      typeof pin.schedulerSchema === 'string' ? pin.schedulerSchema : null,
+  };
+}
+
 function errorMessage(error: unknown): string {
   if (error && typeof error === 'object') {
     const message = (error as { message?: unknown }).message;