deepline 0.3.252 → 0.3.254

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.252',
+  version: '0.3.254',
   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/observability/scheduled-work-control.ts

@@ -7,7 +7,19 @@
  */
 export const SCHEDULED_WORK_CONTROL_CONTRACT_VERSION = 1 as const;
 
-export type ScheduledWorkControlAction = 'run';
+export const SCHEDULED_WORK_CONTROL_ACTIONS = [
+  'run',
+  'start',
+  'pause',
+  'resume',
+  'retry',
+  'verify',
+  'activate',
+  'rollback',
+] as const;
+
+export type ScheduledWorkControlAction =
+  (typeof SCHEDULED_WORK_CONTROL_ACTIONS)[number];
 
 export type ScheduledWorkControlContext = {
   readonly jobId: string;
@@ -38,6 +50,10 @@ export type ScheduledWorkControlConnector = {
   run?: (
     context: ScheduledWorkControlContext,
   ) => Promise<ScheduledWorkRunResult>;
+  execute?: (
+    context: ScheduledWorkControlContext,
+    action: Exclude<ScheduledWorkControlAction, 'run'>,
+  ) => Promise<ScheduledWorkRunResult>;
 };
 
 export type ScheduledWorkControlRegisterOptions = {
@@ -88,6 +104,14 @@ export class ScheduledWorkControlRegistry {
         `Scheduled-work connector ${connector.id} declares run without an implementation.`,
       );
     }
+    if (
+      connector.actions.some((action) => action !== 'run') &&
+      typeof connector.execute !== 'function'
+    ) {
+      throw new Error(
+        `Scheduled-work connector ${connector.id} declares lifecycle controls without an implementation.`,
+      );
+    }
     if (
       connector.actions.length === 0 &&
       Object.keys(connector.unavailableActions ?? {}).length === 0

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

@@ -7037,7 +7037,7 @@ export async function resumePostgresSchedulerDetachedRunnerAttempt(
             SELECT 1 FROM ${tableName('control', options)} AS control
             WHERE control.key = 'runtime_cancel:' || $1
           )
-        FOR UPDATE
+        FOR NO KEY UPDATE
       ), detached_attempt AS MATERIALIZED (
         SELECT attempt.run_id, attempt.attempt, attempt.status, attempt.lease_token
         FROM ${tableName('attempts', options)} AS attempt
@@ -7060,7 +7060,7 @@ export async function resumePostgresSchedulerDetachedRunnerAttempt(
         WHERE target.run_id = detached_attempt.run_id
           AND target.attempt = detached_attempt.attempt
           AND target.lease_token = detached_attempt.lease_token
-          AND target.status = 'running'
+          AND detached_attempt.status = 'running'
         RETURNING target.run_id
       ), restored_run AS (
         UPDATE ${tableName('runs', options)} AS target
@@ -7073,8 +7073,12 @@ export async function resumePostgresSchedulerDetachedRunnerAttempt(
                  (target.suspension_json ->> 'ceilingMs')::double precision) / 1000
               ) ELSE target.wait_deadline END,
             updated_at = now()
-        WHERE target.run_id IN (SELECT run_id FROM detached_attempt)
-          AND target.status = 'running'
+        -- The locked CTE may have followed a concurrent resume's new version.
+        -- Qualify by that version, not the UPDATE scan's earlier snapshot.
+        FROM detached_run
+        WHERE target.run_id = detached_run.run_id
+          AND target.run_id IN (SELECT run_id FROM detached_attempt)
+          AND detached_run.status = 'running'
         RETURNING target.run_id
       ), restored_outbox AS (
         INSERT INTO ${tableName('outbox', options)} (
@@ -7290,7 +7294,15 @@ export async function markPostgresSchedulerAttemptRunning(
   const outboxEventId = `run-resumed:${input.runId}:${randomUUID()}`;
   const running = await client.query<{ run_id: string; event_id: string }>(
     `
-      WITH running_attempt AS (
+      WITH waiting_run AS MATERIALIZED (
+        SELECT target.run_id, target.suspension_json
+        FROM ${tableName('runs', options)} AS target
+        WHERE target.run_id = $1 AND target.status = 'waiting'
+        -- Match detached restore's Run -> attempt order. NO KEY UPDATE also
+        -- allows the outbox reference while its trigger owns the log mutex.
+        FOR NO KEY UPDATE
+      ),
+      running_attempt AS (
         UPDATE ${tableName('attempts', options)} AS target
         SET status = 'running',
             heartbeat_at = CASE WHEN $5::boolean THEN heartbeat_at ELSE now() END,
@@ -7299,6 +7311,7 @@ export async function markPostgresSchedulerAttemptRunning(
           AND target.attempt = $2
           AND target.status = 'waiting'
           AND target.lease_token = $3
+          AND target.run_id IN (SELECT run_id FROM waiting_run)
           AND NOT EXISTS (
             SELECT 1
             FROM ${tableName('attempts', options)} AS newer
@@ -7308,13 +7321,6 @@ export async function markPostgresSchedulerAttemptRunning(
           )
         RETURNING run_id
       ),
-      waiting_run AS (
-        SELECT target.run_id, target.suspension_json
-        FROM ${tableName('runs', options)} AS target
-        WHERE target.run_id IN (SELECT run_id FROM running_attempt)
-          AND target.status = 'waiting'
-        FOR UPDATE
-      ),
       running_run AS (
         UPDATE ${tableName('runs', options)} AS target
         SET status = 'running',
@@ -7325,6 +7331,7 @@ export async function markPostgresSchedulerAttemptRunning(
             updated_at = now()
         FROM waiting_run
         WHERE target.run_id = waiting_run.run_id
+          AND target.run_id IN (SELECT run_id FROM running_attempt)
         RETURNING target.run_id, waiting_run.suspension_json
       ),
       resumed_outbox AS (
@@ -7392,7 +7399,7 @@ export async function claimPostgresSchedulerCompletedDetachedRunnerTerminal(
           AND status = 'waiting'
           AND suspension_json ->> 'kind' = 'detached_runner'
           AND suspension_json -> 'runnerAttempt' = to_jsonb($2::integer)
-        FOR UPDATE
+        FOR NO KEY UPDATE
       ),
       running_attempt AS (
         UPDATE ${tableName('attempts', options)} AS target
@@ -7540,7 +7547,8 @@ export async function claimPostgresSchedulerOverdueDetachedRunnerCeilings(
           END
         ) ASC, runs.run_id ASC
         LIMIT $2
-        FOR UPDATE OF runs, attempts SKIP LOCKED
+        FOR NO KEY UPDATE OF runs SKIP LOCKED
+        FOR UPDATE OF attempts SKIP LOCKED
       ),
       running_attempts AS (
         UPDATE ${tableName('attempts', options)} AS target
@@ -8277,7 +8285,13 @@ export async function handoffPostgresSchedulerAttemptContinuation(
   const outboxEventId = `run-resumed:${input.runId}:${randomUUID()}`;
   const handedOff = await client.query<{ run_id: string; event_id: string }>(
     `
-      WITH continuation_attempt AS (
+      WITH waiting_run AS MATERIALIZED (
+        SELECT target.run_id, target.suspension_json
+        FROM ${tableName('runs', options)} AS target
+        WHERE target.run_id = $1 AND target.status = 'waiting'
+        FOR NO KEY UPDATE
+      ),
+      continuation_attempt AS (
         UPDATE ${tableName('attempts', options)}
         SET status = 'stale',
             lease_expires_at = NULL,
@@ -8287,15 +8301,9 @@ export async function handoffPostgresSchedulerAttemptContinuation(
           AND attempt = $2
           AND status = 'waiting'
           AND lease_token = $3
+          AND run_id IN (SELECT run_id FROM waiting_run)
         RETURNING run_id
       ),
-      waiting_run AS (
-        SELECT target.run_id, target.suspension_json
-        FROM ${tableName('runs', options)} AS target
-        WHERE target.run_id IN (SELECT run_id FROM continuation_attempt)
-          AND target.status = 'waiting'
-        FOR UPDATE
-      ),
       continuation_run AS (
         UPDATE ${tableName('runs', options)} AS target
         SET status = 'queued',
@@ -8305,6 +8313,7 @@ export async function handoffPostgresSchedulerAttemptContinuation(
             updated_at = now()
         FROM waiting_run
         WHERE target.run_id = waiting_run.run_id
+          AND target.run_id IN (SELECT run_id FROM continuation_attempt)
         RETURNING target.run_id, waiting_run.suspension_json
       ),
       resumed_outbox AS (
@@ -18091,6 +18100,9 @@ export async function listPostgresSchedulerOutboxMaterializationPlans(
  */
 export type RunLedgerOutboxTokenAuthority = 'local_mint' | 'gateway';
 
+/** Cross-run service policy; causal order within a run is always unchanged. */
+export type RunLedgerOutboxHeadPriority = 'admission_first' | 'oldest_ready';
+
 const POSTGRES_SCHEDULER_CANCELLATION_OUTBOX_LEASE_SECONDS =
   // The direct projection can run for the full app-runtime request deadline.
   // Keep another 30 seconds for dispatch setup and acknowledgement so a
@@ -18132,6 +18144,8 @@ export type RunLedgerOutboxDispatchInput = {
   runId?: string | null;
   leaseOwner?: string | null;
   leaseSeconds?: number;
+  /** Defaults to the compatible admission-first claim order. */
+  headPriority?: RunLedgerOutboxHeadPriority;
   /**
    * Token authority for the outbox dispatch. Defaults to `local_mint` for the
    * app-side authoritative projector. The Fly worker MUST pass `gateway`.
@@ -18393,7 +18407,11 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
                   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,
+            ORDER BY ${
+              input.headPriority === 'oldest_ready'
+                ? ''
+                : "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
           `);

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/run-ledger-outbox-recovery.ts

@@ -14,6 +14,7 @@ import {
   readPostgresSchedulerOutboxNextDueAt,
   type PostgresSchedulerOptions,
   type PostgresSchedulerOutboxProjectionResult,
+  type RunLedgerOutboxHeadPriority,
 } from './postgres';
 import {
   acquirePgNotifyHub,
@@ -59,6 +60,11 @@ export const RUN_LEDGER_OUTBOX_RECOVERY_MAX_IN_FLIGHT = 32;
 // The higher exported ceiling remains available to isolated recovery callers,
 // but it is not the steady-state production setting.
 const RUN_LEDGER_OUTBOX_RECOVERY_PRODUCTION_IN_FLIGHT = 8;
+// Admissions retain three of four claim opportunities. The fourth selects
+// the oldest eligible causal head across all runs, preventing terminal work
+// from starving behind continuous new admissions. An empty class never costs
+// another query: either order can select any eligible run.
+const ADMISSION_TURNS_PER_OLDEST_READY_TURN = 3;
 
 type RecoveryTimer = ReturnType<typeof setTimeout>;
 
@@ -66,7 +72,9 @@ export type RunLedgerOutboxRecoveryLogger = Pick<Console, 'info' | 'warn'>;
 
 export type RunLedgerOutboxRecoveryDeps = {
   /** One bounded durable claim/delivery attempt. */
-  dispatchOnce: () => Promise<PostgresSchedulerOutboxProjectionResult>;
+  dispatchOnce: (
+    headPriority: RunLedgerOutboxHeadPriority,
+  ) => Promise<PostgresSchedulerOutboxProjectionResult>;
   /** Earliest pending retry time or active lease expiry in the durable outbox. */
   readNextDueAt: () => Promise<Date | null>;
   /** A direct LISTEN connection. It is a hint only; a null lease is safe. */
@@ -131,6 +139,14 @@ export function startRunLedgerOutboxRecovery(
   let unsubscribeNotify: (() => void) | undefined;
   let unsubscribeState: (() => void) | undefined;
   let requestDrain: (reason: string) => void = () => undefined;
+  let admissionTurns = 0;
+
+  const dispatchOnce = () => {
+    const oldestReady =
+      admissionTurns === ADMISSION_TURNS_PER_OLDEST_READY_TURN;
+    admissionTurns = oldestReady ? 0 : admissionTurns + 1;
+    return deps.dispatchOnce(oldestReady ? 'oldest_ready' : 'admission_first');
+  };
 
   const clearWakeTimer = () => {
     if (!timer) return;
@@ -254,7 +270,9 @@ export function startRunLedgerOutboxRecovery(
   const drain = async (reason: string): Promise<void> => {
     type Delivery = {
       id: symbol;
-      result: PromiseSettledResult<PostgresSchedulerOutboxProjectionResult> | { status: 'skipped' };
+      result:
+        | PromiseSettledResult<PostgresSchedulerOutboxProjectionResult>
+        | { status: 'skipped' };
     };
     const pending = new Set<symbol>();
     const deliveries: Delivery[] = [];
@@ -303,7 +321,7 @@ export function startRunLedgerOutboxRecovery(
           return;
         }
         try {
-          settle({ status: 'fulfilled', value: await deps.dispatchOnce() });
+          settle({ status: 'fulfilled', value: await dispatchOnce() });
         } catch (reason) {
           settle({ status: 'rejected', reason });
         }
@@ -410,10 +428,10 @@ export function startRunLedgerOutboxRecoveryController(input: {
               schedulerOptions,
             }),
           ),
-    dispatchOnce: () =>
+    dispatchOnce: (headPriority) =>
       dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
         (operation) => withRuntimeSchedulerClient(input.poolOptions, operation),
-        { tokenAuthority: 'gateway', limit: 8 },
+        { tokenAuthority: 'gateway', limit: 8, headPriority },
         schedulerOptions,
       ),
     // `dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope` releases each

package/dist/cli/index.js

@@ -3507,7 +3507,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.252",
+  version: "0.3.254",
   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

@@ -3502,7 +3502,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.252",
+  version: "0.3.254",
   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

@@ -1320,7 +1320,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.252",
+  version: "0.3.254",
   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

@@ -1224,7 +1224,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.252",
+  version: "0.3.254",
   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.252";
+    readonly version: "0.3.254";
     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.252";
+    readonly version: "0.3.254";
     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.252",
+  version: "0.3.254",
   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.252",
+  version: "0.3.254",
   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.252",
+  "version": "0.3.254",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",