deepline 0.3.150 → 0.3.151

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.150',
+  version: '0.3.151',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/shared_libs/play-runtime/app-runtime-api.ts

@@ -1,5 +1,5 @@
 import { createWriteStream } from 'node:fs';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { stat } from 'node:fs/promises';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
@@ -47,6 +47,7 @@ import {
   LEGACY_RUNTIME_RECEIPT_WIRE_HEADER,
 } from './/runtime-contract';
 import { PLAY_RUNTIME_API_COMPAT_PATH } from './/runtime-api-paths';
+import { buildRunLedgerEventsIdempotencyKey } from './run-ledger-projection-contract';
 import {
   RUNTIME_API_ACCEPTS_HEADER,
   gzipRuntimeApiRequestBody,
@@ -157,15 +158,21 @@ type RuntimeApiRequest =
       action: 'create_db_session';
     } & CreateDbSessionRequest)
   | {
-      action: 'append_run_events';
+      action: 'append_run_events' | 'project_run_events';
       playId: string;
       events: PlayRunLedgerIngressEvent[];
       idempotencyKey?: string;
+      deliveryIdempotencyKey?: string;
+      deliveryLeaseOwner?: string;
     }
   | {
       action: 'start_run';
+      deliveryLeaseOwner?: string;
       idempotencyKey?: string;
       playName: string;
+      playReference?: string | null;
+      definitionScope?: 'org' | 'system';
+      revisionId?: string | null;
       runId: string;
       artifactStorageKey?: string | null;
       artifactHash?: string | null;
@@ -200,6 +207,7 @@ type RuntimeApiRequest =
     }
   | {
       action: 'project_run_created';
+      deliveryLeaseOwner?: string;
       idempotencyKey: string;
       playName: string;
       playReference?: string | null;
@@ -736,7 +744,8 @@ function isRetryableAppRuntimeResponse(input: {
   // projection. Do not make every 403 retryable: only this exact Vercel HTML
   // response on a replay-safe action is an intermediary failure.
   if (
-    input.action === 'append_run_events' &&
+    (input.action === 'append_run_events' ||
+      input.action === 'project_run_events') &&
     isVercelSecurityCheckpointResponse(input)
   ) {
     return true;
@@ -964,6 +973,9 @@ function isRetryableAppRuntimeAction(
 ): boolean {
   return (
     action === 'append_run_events' ||
+    // Classification remains replay-safe for the durable outbox even though
+    // projectRunEventsViaAppRuntime disables in-process transport retries.
+    action === 'project_run_events' ||
     action === 'apply_row_updates' ||
     action === 'compute_billing_finalize' ||
     action === 'compute_billing_record_item' ||
@@ -2312,6 +2324,85 @@ async function appendRunEventsViaAppRuntimeRaw(
   });
 }
 
+/** Leased delivery only. Every transport piece has its own stable receipt. */
+export async function projectRunEventsViaAppRuntime(
+  context: WorkerRuntimeApiContext,
+  input: {
+    playId: string;
+    events: PlayRunLedgerIngressEvent[];
+    idempotencyKey: string;
+    deliveryLeaseOwner: string;
+    beforeBatch: () => Promise<void>;
+  },
+): Promise<void> {
+  const batches = partitionRunEventsForAppRuntime(input.events);
+  const receiptBatch = runLedgerReceiptBatchIndex(batches);
+  for (const [index, events] of batches.entries()) {
+    await input.beforeBatch();
+    // Retain the original receipt for the terminal (or final) piece so an acknowledged
+    // legacy delivery stays acknowledged across the reader rollout.
+    const idempotencyKey =
+      index === receiptBatch
+        ? input.idempotencyKey
+        : buildRunLedgerEventsIdempotencyKey({
+            runId: input.playId,
+            deliveryDigest: createHash('sha256')
+              .update(JSON.stringify([input.idempotencyKey, index, events]))
+              .digest('hex'),
+          });
+    const request = {
+      playId: input.playId,
+      events,
+      idempotencyKey,
+      deliveryIdempotencyKey: input.idempotencyKey,
+      deliveryLeaseOwner: input.deliveryLeaseOwner,
+    };
+    // The durable outbox owns recovery; this helper does not retry OCCs or
+    // other delivery failures inside an already-leased invocation.
+    const deliveryContext = { ...context, retryPolicy: 'none' as const };
+    try {
+      await postAppRuntimeApi(deliveryContext, {
+        action: 'project_run_events',
+        ...request,
+      });
+    } catch (error) {
+      if (
+        !(error instanceof AppRuntimeApiResponseError) ||
+        !isLegacyProjectRunCreatedUnsupportedActionResponse({
+          status: error.status,
+          body: error.detail,
+        })
+      )
+        throw error;
+      // Launch-pinned old apps already implement equivalent keyed projection.
+      // A real auth refusal never selects this compatibility adapter.
+      // The capability probe was a network round trip. Re-check ownership
+      // before the legacy request too; reclamation must stop a stale sender.
+      await input.beforeBatch();
+      await postAppRuntimeApi(deliveryContext, {
+        action: 'append_run_events',
+        ...request,
+      });
+    }
+  }
+}
+
+function runLedgerReceiptBatchIndex(
+  batches: PlayRunLedgerIngressEvent[][],
+): number {
+  for (let index = batches.length - 1; index >= 0; index -= 1) {
+    if (
+      batches[index]!.some((event) =>
+        ['run.completed', 'run.failed', 'run.cancelled'].includes(
+          event.key ?? event.type ?? '',
+        ),
+      )
+    )
+      return index;
+  }
+  return batches.length - 1;
+}
+
 /**
  * Append Run Ledger events through the bounded transport used by every runtime
  * producer. Scheduler terminal outbox events can carry a complete log replay,
@@ -2368,7 +2459,11 @@ export async function appendRunEventsViaAppRuntime(
 export async function startRunViaAppRuntime(
   context: WorkerRuntimeApiContext,
   input: {
+    deliveryLeaseOwner?: string;
     playName: string;
+    playReference?: string | null;
+    definitionScope?: 'org' | 'system';
+    revisionId?: string | null;
     runId: string;
     artifactStorageKey?: string | null;
     artifactHash?: string | null;

package/dist/bundling-sources/shared_libs/play-runtime/run-ledger-projection-contract.ts

@@ -10,6 +10,13 @@ const UUID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/i;
 
+export class RunLedgerProjectionLeaseLostError extends Error {
+  constructor() {
+    super('Run Ledger projection requires the current outbox delivery lease.');
+    this.name = 'RunLedgerProjectionLeaseLostError';
+  }
+}
+
 function requireRunId(runId: string): void {
   if (!runId.trim()) {
     throw new Error('Run Ledger projection idempotency key requires a run id.');

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

@@ -760,6 +760,12 @@ function mergeMonotonicStepProgress(input: {
 }): PlayRunLedgerStepProgress {
   const current = input.current ?? {};
   const next = input.next;
+  const supersededRows = maxProgressNumber(
+    current.supersededRows,
+    next.supersededRows === undefined
+      ? undefined
+      : Math.max(0, next.supersededRows),
+  );
   return {
     ...current,
     ...next,
@@ -786,11 +792,7 @@ function mergeMonotonicStepProgress(input: {
           ),
         }
       : {}),
-    ...(next.supersededRows !== undefined
-      ? { supersededRows: Math.max(0, next.supersededRows) }
-      : current.supersededRows !== undefined
-        ? { supersededRows: current.supersededRows }
-        : {}),
+    ...(supersededRows !== undefined ? { supersededRows } : {}),
   };
 }
 

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

@@ -35,6 +35,7 @@ export const RUNTIME_OPERATION_CAPABILITIES = {
   create_db_session: 'db.session',
   repair_runtime_storage_grants: 'sheet.write',
   append_run_events: 'run.progress',
+  project_run_events: 'run.progress',
   save_results: 'run.progress',
   start_run: 'run.progress',
   record_first_claim_latency: 'run.progress',
@@ -56,6 +57,10 @@ export const RUNTIME_OPERATION_CONTRACT: DeployedOperationContract =
     id: 'runtime-api-actions',
     actions: RUNTIME_OPERATION_CAPABILITIES,
     olderReceiver: {
+      project_run_events: {
+        kind: 'equivalent-fallback',
+        action: 'append_run_events',
+      },
       // The runner retains the complete result before attempting this
       // compact completion. An older app receiver reports the action as
       // unsupported, and the adapter retries the established full-payload

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

@@ -250,7 +250,7 @@ export type PlaySchedulerRunHandle = {
     signal?: AbortSignal;
   }): AsyncIterable<PlaySchedulerProgressEvent>;
   /** Cooperatively cancel the run. */
-  cancel(): Promise<void>;
+  cancel(reason?: string): Promise<void>;
   /** Inject an external event (HITL, webhook). */
   signal(payload: PlaySchedulerSignalPayload): Promise<void>;
   /** Block until terminal state and return final envelope. */

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

@@ -216,14 +216,14 @@ function absurdRunHandle(input: {
     return error;
   };
 
-  const requestCancellation = async () => {
+  const requestCancellation = async (reason?: string) => {
     await runCancellationSingleFlight(cancellationKey, async () => {
       // First move the durable engine task into its cancellation lane. If the
       // scheduler tables are briefly locked, the worker reconciler can finish
       // the terminal write later without another user request piling up.
       await cancelAbsurdTask();
       try {
-        await delegate.cancel();
+        await delegate.cancel(reason);
       } catch (error) {
         throw cancellationPendingError(error);
       }

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

@@ -77,9 +77,11 @@ import {
 import type { PlayStaticPipeline } from '../../plays/static-pipeline';
 import {
   LOG_TAIL_LIMIT,
+  type AcceptedPlayRunLedgerEvent,
   type PlayRunLedgerEvent,
   type PlayRunLedgerIngressEvent,
 } from '../run-ledger';
+import { stableStringify } from '../../plays/row-identity';
 import {
   isCtxFetchHttpFailureDiagnostic,
   parseCtxFetchHttpFailureDiagnostic,
@@ -88,6 +90,7 @@ import {
 } from '../log-provenance';
 import {
   buildRunLedgerEventsIdempotencyKey,
+  RunLedgerProjectionLeaseLostError,
   buildRunLedgerStartIdempotencyKey,
   buildRunLedgerTerminalIdempotencyKey,
 } from '../run-ledger-projection-contract';
@@ -101,7 +104,7 @@ import {
 import {
   AppRuntimeApiResponseError,
   AppRuntimeApiTransportError,
-  appendRunEventsViaAppRuntime,
+  projectRunEventsViaAppRuntime,
   finalizeComputeBillingSessionViaAppRuntime,
   recordComputeBillingItemViaAppRuntime,
   upsertComputeBillingSessionViaAppRuntime,
@@ -15092,15 +15095,221 @@ function isMissingOutboxDeliveryBatchMarker(error: unknown): boolean {
 }
 
 /**
- * v34's terminal-batch marker is a delivery-consistency improvement. A v33
- * lane cannot expose that column, so the query has an explicit temporary
- * compatibility Adapter rather than making the whole runtime refuse work.
- *
- * New databases optimistically use the current query. If the database reports
- * the additive column absent, retry the untouched v33 operation once and
- * cache that fact briefly. After an in-flight expansion completes the current
- * query is automatically retried; there is no permanent downgrade or process
- * restart requirement.
+ * Persist a validated event batch without modifying the mutable run snapshot.
+ * Reader-first: deploy the run.events decoder to both projectors before any
+ * ingress adapter calls this function. The existing INSERT trigger wakes them.
+ */
+export async function appendPostgresRunLedgerEvents(
+  client: PostgresSchedulerQueryClient,
+  input: {
+    orgId: string;
+    runId: string;
+    events: readonly AcceptedPlayRunLedgerEvent[];
+  },
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<PostgresSchedulerLifecycleOutboxEvent> {
+  if (
+    input.events.length === 0 ||
+    input.events.some((event) => event.runId !== input.runId)
+  ) {
+    throw new Error(
+      'Run Ledger ingress requires a nonempty batch for exactly one run.',
+    );
+  }
+  const payload = stableStringify({ events: input.events });
+  // The HTTP adapters own the existing request limits. Postgres intake must
+  // not impose Convex's document limit on a batch: projection partitions its
+  // transport pieces and stores individual events separately.
+  // Stable across a lost response. The complete event identity (including log
+  // channel offsets and original timestamps) participates in the digest.
+  const eventId = `run-events:${input.runId}:${createHash('sha256').update(payload).digest('hex')}`;
+  return appendRunLedgerOutboxFact(
+    client,
+    { ...input, eventId, eventType: 'run.events', payload },
+    options,
+  );
+}
+
+export type RunLedgerStartCallback = Omit<
+  Parameters<typeof startRunViaAppRuntime>[1],
+  'idempotencyKey' | 'deliveryLeaseOwner'
+>;
+
+/** Preserve the legacy start/create operation, but deliver it under one lease. */
+export async function appendPostgresRunLedgerStart(
+  client: PostgresSchedulerQueryClient,
+  input: { orgId: string; runId: string; start: RunLedgerStartCallback },
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<PostgresSchedulerLifecycleOutboxEvent> {
+  if (input.start.runId !== input.runId) {
+    throw new Error('Run Ledger start must belong to exactly one run.');
+  }
+  return appendRunLedgerOutboxFact(
+    client,
+    {
+      orgId: input.orgId,
+      runId: input.runId,
+      eventId: `run-start-callback:${input.runId}`,
+      eventType: 'run.started',
+      payload: stableStringify(input.start),
+    },
+    options,
+  );
+}
+
+async function appendRunLedgerOutboxFact(
+  client: PostgresSchedulerQueryClient,
+  input: {
+    orgId: string;
+    runId: string;
+    eventId: string;
+    eventType: 'run.events' | 'run.started';
+    payload: string;
+  },
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<PostgresSchedulerLifecycleOutboxEvent> {
+  const result = await client.query<{ run_id: string }>(
+    `
+    WITH admitted AS MATERIALIZED (
+      SELECT run_id FROM ${tableName('runs', options)}
+      WHERE run_id = $1 AND org_id = $2
+    ), recorded AS (
+      INSERT INTO ${tableName('outbox', options)}
+        (event_id, run_id, event_type, payload_json, created_at)
+      SELECT $3, run_id, $5, $4::jsonb,
+             ${causalOutboxCreatedAt('admitted.run_id', options)}
+      FROM admitted
+      ON CONFLICT (event_id) DO NOTHING
+    )
+    SELECT run_id FROM admitted
+  `,
+    [input.runId, input.orgId, input.eventId, input.payload, input.eventType],
+  );
+  if (result.rows.length !== 1) {
+    throw new Error(
+      'Run Ledger ingress run is missing or outside the organization scope.',
+    );
+  }
+  return { runId: input.runId, eventId: input.eventId };
+}
+
+export { RunLedgerProjectionLeaseLostError } from '../run-ledger-projection-contract';
+
+/** Extend only our still-live lease before another bounded transport piece. */
+export async function renewPostgresRunLedgerDelivery(
+  client: PostgresSchedulerQueryClient,
+  input: { eventIds: string[]; leaseOwner: string; leaseSeconds: number },
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<void> {
+  const result = await client.query<{ event_id: string }>(
+    `
+    UPDATE ${tableName('outbox', options)}
+    SET lease_expires_at = now() + make_interval(secs => $3::integer)
+    WHERE event_id = ANY($1::text[]) AND lease_owner = $2
+      AND delivered_at IS NULL AND failed_at IS NULL AND lease_expires_at > now()
+    RETURNING event_id
+  `,
+    [
+      input.eventIds,
+      input.leaseOwner,
+      Math.max(5, Math.min(300, input.leaseSeconds)),
+    ],
+  );
+  if (result.rows.length !== input.eventIds.length)
+    throw new RunLedgerProjectionLeaseLostError();
+}
+
+/** Only a currently claimed outbox batch may use the projection write path. */
+export async function assertPostgresRunLedgerDelivery(
+  client: PostgresSchedulerQueryClient,
+  input: {
+    orgId: string;
+    runId: string;
+    idempotencyKey: string;
+    leaseOwner?: string;
+  },
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<void> {
+  const result = await client.query<{
+    delivery_key: string;
+    event_type: string;
+    lease_owner: string;
+  }>(
+    `
+    SELECT outbox.delivery_key, outbox.event_type, outbox.lease_owner
+    FROM ${tableName('outbox', options)} AS outbox
+    JOIN ${tableName('runs', options)} AS runs ON runs.run_id = outbox.run_id
+    WHERE outbox.run_id = $1 AND runs.org_id = $2
+      AND outbox.delivered_at IS NULL AND outbox.failed_at IS NULL
+      AND outbox.lease_owner IS NOT NULL AND outbox.lease_expires_at > now()
+      AND ($3::text IS NULL OR outbox.lease_owner = $3)
+    ORDER BY outbox.created_at, outbox.event_id
+  `,
+    [input.runId, input.orgId, input.leaseOwner ?? null],
+  );
+  const groups = new Map<string, typeof result.rows>();
+  for (const row of result.rows) {
+    const group = groups.get(row.lease_owner) ?? [];
+    group.push(row);
+    groups.set(row.lease_owner, group);
+  }
+  for (const rows of groups.values()) {
+    const digest = createHash('sha256')
+      .update(rows.map((row) => row.delivery_key).join('\n'))
+      .digest('hex');
+    const batchKey = buildRunLedgerEventsIdempotencyKey({
+      runId: input.runId,
+      deliveryDigest: digest,
+    });
+    const terminal = [...rows]
+      .reverse()
+      .find((row) =>
+        ['run.completed', 'run.failed', 'run.cancelled'].includes(
+          row.event_type,
+        ),
+      );
+    // The old one-row dispatcher uses run-terminal for nonterminal facts too.
+    const single = rows.length === 1 ? rows[0] : terminal;
+    const terminalKey = single
+      ? buildRunLedgerTerminalIdempotencyKey({
+          runId: input.runId,
+          deliveryKey: single.delivery_key,
+        })
+      : null;
+    const startKey =
+      rows.length === 1 &&
+      single &&
+      ['run.created', 'run.started'].includes(single.event_type)
+        ? buildRunLedgerStartIdempotencyKey({
+            runId: input.runId,
+            deliveryKey: single.delivery_key,
+          })
+        : null;
+    if (
+      input.idempotencyKey === batchKey ||
+      input.idempotencyKey === terminalKey ||
+      input.idempotencyKey === startKey
+    )
+      return;
+  }
+  throw new RunLedgerProjectionLeaseLostError();
+}
+
+/** Snapshot-creating facts precede progress, even when their intake was late. */
+function runLedgerPrecedesSql(
+  predecessor: string,
+  successor: string,
+  inclusive = false,
+): string {
+  const position = (alias: string) =>
+    `(CASE ${alias}.event_type WHEN 'run.created' THEN 0 WHEN 'run.started' THEN 1 ELSE 2 END, ${alias}.created_at, ${alias}.event_id)`;
+  return `${position(predecessor)} ${inclusive ? '<=' : '<'} ${position(successor)}`;
+}
+
+/**
+ * Claim a causal prefix, preserving the v33 adapter while the additive batch
+ * marker is absent. An enclosing transaction uses a savepoint so the missing
+ * column does not leave the compatibility claim in an aborted transaction.
  */
 export async function readPendingPostgresSchedulerOutboxEvents(
   client: PostgresSchedulerQueryClient,
@@ -15109,6 +15318,8 @@ export async function readPendingPostgresSchedulerOutboxEvents(
     runId?: string | null;
     leaseOwner?: string | null;
     leaseSeconds?: number;
+    /** The dispatcher owns a short, exclusive claim transaction. */
+    inTransaction?: boolean;
   } = {},
   options?: Pick<PostgresSchedulerOptions, 'schema'>,
 ): Promise<PostgresSchedulerOutboxEvent[]> {
@@ -15137,6 +15348,16 @@ export async function readPendingPostgresSchedulerOutboxEvents(
           AND coalesce(candidate.next_attempt_at, candidate.created_at) <= now()
           AND ($2::text IS NULL OR candidate.run_id = $2)
           AND ($3::text IS NULL OR candidate.lease_expires_at IS NULL OR candidate.lease_expires_at <= now())
+          -- A producer transaction may commit an older timestamp after a
+          -- delivery has started. Ownership covers the run, not just the
+          -- current oldest row: that late predecessor must wait as well.
+          AND NOT EXISTS (
+            SELECT 1 FROM ${tableName('outbox', options)} AS active
+            WHERE active.run_id = candidate.run_id
+              AND active.delivered_at IS NULL
+              AND active.lease_owner IS NOT NULL
+              AND active.lease_expires_at > now()
+          )
           -- Competing projectors acquire one run through its oldest event.
           -- Locking this head prevents another projector from splitting the
           -- run while still letting it skip to unrelated runs.
@@ -15145,13 +15366,7 @@ export async function readPendingPostgresSchedulerOutboxEvents(
             FROM ${tableName('outbox', options)} AS predecessor
             WHERE predecessor.run_id = candidate.run_id
               AND predecessor.delivered_at IS NULL
-              AND (
-                predecessor.created_at < candidate.created_at
-                OR (
-                  predecessor.created_at = candidate.created_at
-                  AND predecessor.event_id < candidate.event_id
-                )
-              )
+              AND ${runLedgerPrecedesSql('predecessor', 'candidate')}
           )
         -- A new durable admission has no causal dependency on unrelated
         -- terminal facts. Project it first so a lifecycle backlog cannot make
@@ -15173,9 +15388,12 @@ export async function readPendingPostgresSchedulerOutboxEvents(
           -- Admission is causally first and must be projected alone. A later
           -- start/terminal append may not leapfrog a delayed queued row.
           AND (
-            head.event_type NOT IN ('run.created', 'run.started')
+            head.event_type NOT IN ('run.created', 'run.started', 'run.events')
             OR outbox.event_id = head.event_id
           )
+          -- An ingress row already contains a producer's bounded batch. Keep
+          -- its receipt stable independently of the recovery caller's limit.
+          AND (outbox.event_type <> 'run.events' OR outbox.event_id = head.event_id)
           AND coalesce(outbox.next_attempt_at, outbox.created_at) <= now()
           AND ($3::text IS NULL OR outbox.lease_expires_at IS NULL OR outbox.lease_expires_at <= now())
           -- A started terminal batch is deliberately stable across a retry.
@@ -15202,13 +15420,7 @@ export async function readPendingPostgresSchedulerOutboxEvents(
               AND terminal_predecessor.event_type IN (
                 'run.completed', 'run.failed', 'run.cancelled'
               )
-              AND (
-                terminal_predecessor.created_at < outbox.created_at
-                OR (
-                  terminal_predecessor.created_at = outbox.created_at
-                  AND terminal_predecessor.event_id < outbox.event_id
-                )
-              )
+              AND ${runLedgerPrecedesSql('terminal_predecessor', 'outbox')}
           )
           -- Claim only the contiguous due prefix. A delayed, leased, or failed
           -- predecessor retains ownership of everything that follows it.
@@ -15217,15 +15429,10 @@ export async function readPendingPostgresSchedulerOutboxEvents(
             FROM ${tableName('outbox', options)} AS predecessor
             WHERE predecessor.run_id = outbox.run_id
               AND predecessor.delivered_at IS NULL
+              AND ${runLedgerPrecedesSql('predecessor', 'outbox')}
               AND (
-                predecessor.created_at < outbox.created_at
-                OR (
-                  predecessor.created_at = outbox.created_at
-                  AND predecessor.event_id < outbox.event_id
-                )
-              )
-              AND (
-                predecessor.failed_at IS NOT NULL
+                predecessor.event_type = 'run.events'
+                OR predecessor.failed_at IS NOT NULL
                 OR coalesce(predecessor.next_attempt_at, predecessor.created_at) > now()
                 OR (
                   $3::text IS NOT NULL
@@ -15275,17 +15482,22 @@ export async function readPendingPostgresSchedulerOutboxEvents(
       [limit, runId, leaseOwner, leaseSeconds],
     );
   let result;
+  if (input.inTransaction) await client.query('SAVEPOINT run_ledger_claim');
   if (supportsOutboxDeliveryBatchMarker(options)) {
     try {
       result = await claim(true);
     } catch (error) {
       if (!isMissingOutboxDeliveryBatchMarker(error)) throw error;
+      if (input.inTransaction)
+        await client.query('ROLLBACK TO SAVEPOINT run_ledger_claim');
       markOutboxDeliveryBatchMarkerUnavailable(options);
       result = await claim(false);
     }
   } else {
     result = await claim(false);
   }
+  if (input.inTransaction)
+    await client.query('RELEASE SAVEPOINT run_ledger_claim');
   return result.rows.map((row) => {
     if (!row.delivery_key) {
       throw new Error(
@@ -15317,13 +15529,18 @@ export async function readPostgresSchedulerOutboxNextDueAt(
 ): Promise<Date | null> {
   const result = await client.query<{ due_at: Date | string | null }>(
     `
-      SELECT min(
+      SELECT min(greatest(
         CASE
           WHEN lease_expires_at IS NOT NULL AND lease_expires_at > now()
             THEN lease_expires_at
           ELSE coalesce(next_attempt_at, created_at)
-        END
-      ) AS due_at
+        END,
+        (SELECT max(active.lease_expires_at)
+         FROM ${tableName('outbox', options)} AS active
+         WHERE active.run_id = candidate.run_id
+           AND active.delivered_at IS NULL AND active.lease_owner IS NOT NULL
+           AND active.lease_expires_at > now())
+      )) AS due_at
       FROM ${tableName('outbox', options)} AS candidate
       WHERE candidate.delivered_at IS NULL
         AND candidate.failed_at IS NULL
@@ -15334,13 +15551,7 @@ export async function readPostgresSchedulerOutboxNextDueAt(
           FROM ${tableName('outbox', options)} AS predecessor
           WHERE predecessor.run_id = candidate.run_id
             AND predecessor.delivered_at IS NULL
-            AND (
-              predecessor.created_at < candidate.created_at
-              OR (
-                predecessor.created_at = candidate.created_at
-                AND predecessor.event_id < candidate.event_id
-              )
-            )
+            AND ${runLedgerPrecedesSql('predecessor', 'candidate')}
         )
     `,
   );
@@ -15376,13 +15587,7 @@ export async function readPostgresSchedulerOutboxDeliveryStatus(
               FROM ${tableName('outbox', options)} predecessor
               WHERE predecessor.run_id = target.run_id
                 AND predecessor.failed_at IS NOT NULL
-                AND (
-                  predecessor.created_at < target.created_at
-                  OR (
-                    predecessor.created_at = target.created_at
-                    AND predecessor.event_id <= target.event_id
-                  )
-                )
+                AND ${runLedgerPrecedesSql('predecessor', 'target', true)}
             ) AS blocked
      FROM ${tableName('outbox', options)} target
      WHERE target.run_id = $1 AND target.event_id = $2`,
@@ -15783,6 +15988,30 @@ export function buildRunLedgerEventsFromPostgresSchedulerOutbox(
   event: PostgresSchedulerOutboxEvent,
 ): PlayRunLedgerIngressEvent[] {
   const occurredAt = event.createdAt.getTime();
+  if (event.eventType === 'run.events') {
+    const events = payloadField(event.payload, 'events');
+    if (
+      !Array.isArray(events) ||
+      events.length === 0 ||
+      events.some(
+        (value) =>
+          !recordPayload(value) ||
+          value.runId !== event.runId ||
+          typeof value.type !== 'string',
+      )
+    ) {
+      throw new AppRuntimeApiResponseError({
+        action: 'project_run_events',
+        status: 422,
+        code: 'run_ledger_ingress_invalid',
+        retryable: false,
+        detail: `Invalid Run Ledger ingress batch ${event.eventId}.`,
+      });
+    }
+    // Preserve event time, source, opaque payloads and positional log identity;
+    // the outbox timestamp orders delivery, not the customer's execution trace.
+    return events as AcceptedPlayRunLedgerEvent[];
+  }
   if (event.eventType === 'run.started') {
     return [
       {
@@ -15964,6 +16193,7 @@ export type PostgresSchedulerOutboxMaterializationPlan = {
 };
 
 const RUN_LEDGER_KNOWN_OUTBOX_EVENT_TYPES = new Set([
+  'run.events',
   'run.started',
   'run.completed',
   'run.failed',
@@ -16272,18 +16502,58 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
 ): Promise<PostgresSchedulerOutboxProjectionResult> {
   const leaseOwner =
     input.leaseOwner?.trim() || `run-ledger-outbox-dispatch:${randomUUID()}`;
-  const events = await withClient((client) =>
-    readPendingPostgresSchedulerOutboxEvents(
-      client,
-      {
-        limit: input.limit ?? 1,
-        runId: input.runId,
-        leaseOwner,
-        leaseSeconds: input.leaseSeconds ?? 120,
-      },
-      options,
-    ),
-  );
+  const events = await withClient(async (client) => {
+    // The checkout is exclusive. Hold the existing scheduler run's row lock
+    // only while choosing/claiming its outbox prefix, never over HTTP. A
+    // second statement takes a fresh READ COMMITTED snapshot after the lock:
+    // late producer commits cannot split one run between different heads.
+    await client.query('BEGIN');
+    try {
+      const selected = await client.query<{ run_id: string }>(
+        `
+        SELECT runs.run_id
+        FROM ${tableName('outbox', options)} AS head
+        JOIN ${tableName('runs', options)} AS runs ON runs.run_id = head.run_id
+        WHERE ($1::text IS NULL OR runs.run_id = $1)
+          AND head.delivered_at IS NULL AND head.failed_at IS NULL
+          AND coalesce(head.next_attempt_at, head.created_at) <= now()
+          AND NOT EXISTS (
+            SELECT 1 FROM ${tableName('outbox', options)} AS predecessor
+            WHERE predecessor.run_id = head.run_id AND predecessor.delivered_at IS NULL
+              AND ${runLedgerPrecedesSql('predecessor', 'head')}
+          )
+          AND NOT EXISTS (
+            SELECT 1 FROM ${tableName('outbox', options)} AS active
+            WHERE active.run_id = runs.run_id AND active.delivered_at IS NULL
+              AND active.lease_owner IS NOT NULL AND active.lease_expires_at > now()
+          )
+        ORDER BY CASE WHEN head.event_type = 'run.created' THEN 0 ELSE 1 END,
+                 head.created_at, runs.run_id
+        FOR UPDATE OF runs SKIP LOCKED LIMIT 1
+      `,
+        [input.runId?.trim() || null],
+      );
+      const runId = selected.rows[0]?.run_id;
+      const claimed = runId
+        ? await readPendingPostgresSchedulerOutboxEvents(
+            client,
+            {
+              limit: input.limit ?? 1,
+              runId,
+              leaseOwner,
+              leaseSeconds: input.leaseSeconds ?? 120,
+              inTransaction: true,
+            },
+            options,
+          )
+        : [];
+      await client.query('COMMIT');
+      return claimed;
+    } catch (error) {
+      await client.query('ROLLBACK');
+      throw error;
+    }
+  });
   if (events.length === 0) {
     return {
       attempted: 0,
@@ -16298,7 +16568,7 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
 
   try {
     const first = events[0]!;
-    const runtimeApi =
+    const resolvedRuntimeApi =
       input.runtimeApi ??
       (await withClient((client) =>
         loadPostgresSchedulerRuntimeApiForRun(
@@ -16311,6 +16581,20 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
           options,
         ),
       ));
+    const runtimeApi = { ...resolvedRuntimeApi, retryPolicy: 'none' as const };
+    const renewDelivery = () =>
+      withClient((client) =>
+        renewPostgresRunLedgerDelivery(
+          client,
+          {
+            eventIds: events.map((event) => event.eventId),
+            leaseOwner,
+            leaseSeconds: input.leaseSeconds ?? 120,
+          },
+          options,
+        ),
+      );
+    await renewDelivery();
     // A pending start is always claimed alone because later events require its
     // snapshot. It cannot share the append endpoint, so retain that mutation
     // as its own exact delivery.
@@ -16347,9 +16631,11 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
         const batchDeliveryKey = createHash('sha256')
           .update(events.map((event) => event.deliveryKey).join('\n'))
           .digest('hex');
-        await appendRunEventsViaAppRuntime(runtimeApi, {
+        await projectRunEventsViaAppRuntime(runtimeApi, {
           playId: first.runId,
           events: ledgerEvents,
+          deliveryLeaseOwner: leaseOwner,
+          beforeBatch: renewDelivery,
           idempotencyKey: terminal
             ? buildRunLedgerTerminalIdempotencyKey({
                 runId: first.runId,
@@ -16431,6 +16717,7 @@ async function projectPostgresSchedulerCreatedEvent(
   const replayedFromRunId = value('replayedFromRunId');
   const asyncAncestryPlayIds = raw('asyncAncestryPlayIds');
   await projectRunCreatedViaAppRuntime(runtimeApi, {
+    deliveryLeaseOwner: event.leaseOwner ?? undefined,
     idempotencyKey: buildRunLedgerStartIdempotencyKey({
       runId: event.runId,
       deliveryKey: event.deliveryKey,
@@ -16504,11 +16791,15 @@ async function projectPostgresSchedulerStartEvent(
   launch: (PlaySchedulerSubmitInput & { firstClaimLatencyMs?: number }) | null,
 ): Promise<void> {
   await startRunViaAppRuntime(runtimeApi, {
+    deliveryLeaseOwner: event.leaseOwner ?? undefined,
     idempotencyKey: buildRunLedgerStartIdempotencyKey({
       runId: event.runId,
       deliveryKey: event.deliveryKey,
     }),
     playName: stringPayloadField(event.payload, 'playName') ?? event.runId,
+    playReference: stringPayloadField(event.payload, 'playReference'),
+    definitionScope: launch?.definitionScope ?? undefined,
+    revisionId: launch?.revisionId,
     runId: event.runId,
     artifactStorageKey: stringPayloadField(event.payload, 'artifactStorageKey'),
     artifactHash: stringPayloadField(event.payload, 'artifactHash'),
@@ -16517,6 +16808,7 @@ async function projectPostgresSchedulerStartEvent(
     schedulerBackend: stringPayloadField(event.payload, 'schedulerBackend'),
     schedulerSchema: stringPayloadField(event.payload, 'schedulerSchema'),
     executionProfile: stringPayloadField(event.payload, 'executionProfile'),
+    maxCreditsPerRun: numberPayloadField(event.payload, 'maxCreditsPerRun'),
     staticPipeline: payloadField(event.payload, 'staticPipeline'),
     source: sourcePayloadField(event.payload, 'source'),
     inputFileId:
@@ -16534,7 +16826,10 @@ async function projectPostgresSchedulerStartEvent(
     replayedFromRunId:
       launch?.replayedFromRunId ??
       stringPayloadField(event.payload, 'replayedFromRunId'),
-    firstClaimLatencyMs: launch?.firstClaimLatencyMs,
+    firstClaimLatencyMs:
+      launch?.firstClaimLatencyMs ??
+      numberPayloadField(event.payload, 'firstClaimLatencyMs') ??
+      undefined,
   });
 }
 
@@ -17063,7 +17358,7 @@ export function postgresSchedulerRunHandle(
         hubLease?.release();
       }
     },
-    cancel: async () => {
+    cancel: async (reason) => {
       const poolOptions = resolve();
       await withRuntimeSchedulerTransaction(
         poolOptions,
@@ -17071,7 +17366,8 @@ export function postgresSchedulerRunHandle(
           lockTimeoutMs: RUNTIME_SCHEDULER_CANCEL_LOCK_TIMEOUT_MS,
           statementTimeoutMs: RUNTIME_SCHEDULER_CANCEL_STATEMENT_TIMEOUT_MS,
         },
-        (client) => cancelPostgresSchedulerRun(client, { runId }, options),
+        (client) =>
+          cancelPostgresSchedulerRun(client, { runId, reason }, options),
         {
           runId,
           phase: 'cancel_run',

package/dist/cli/index.js

@@ -3068,7 +3068,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.150",
+  version: "0.3.151",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/cli/index.mjs

@@ -3063,7 +3063,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.150",
+  version: "0.3.151",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/index.js

@@ -864,7 +864,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.150",
+  version: "0.3.151",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/index.mjs

@@ -768,7 +768,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.150",
+  version: "0.3.151",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/release.d.mts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.150";
+    readonly version: "0.3.151";
     readonly updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.d.ts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.150";
+    readonly version: "0.3.151";
     readonly updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.js

@@ -74,7 +74,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.150",
+  version: "0.3.151",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/release.mjs

@@ -48,7 +48,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.150",
+  version: "0.3.151",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.3.150",
+  "version": "0.3.151",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",