deepline 0.3.251 → 0.3.253

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.251',
+  version: '0.3.253',
   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

@@ -6426,16 +6426,11 @@ export async function repairPostgresSchedulerCronFire(
   };
 }
 
-export async function setPostgresSchedulerRuntimeReleaseAdmission(
-  client: PostgresSchedulerQueryClient,
-  input: {
-    releaseId: string;
-    accepting: boolean;
-    admissionEpoch: number;
-    environment?: 'preview' | 'production';
-  },
-  options?: Pick<PostgresSchedulerOptions, 'schema'>,
-): Promise<void> {
+function runtimeReleaseAdmissionKeys(input: {
+  releaseId: string;
+  admissionEpoch: number;
+  environment?: 'preview' | 'production';
+}) {
   const releaseId = input.releaseId.trim();
   const environment = input.environment ?? 'production';
   const releaseAdmissionKey = `${environment}:${releaseId}`;
@@ -6458,6 +6453,21 @@ export async function setPostgresSchedulerRuntimeReleaseAdmission(
       'Runtime release admission requires a non-negative safe-integer admissionEpoch.',
     );
   }
+  return { releaseAdmissionLockKeys, releaseAdmissionWriteKeys };
+}
+
+export async function setPostgresSchedulerRuntimeReleaseAdmission(
+  client: PostgresSchedulerQueryClient,
+  input: {
+    releaseId: string;
+    accepting: boolean;
+    admissionEpoch: number;
+    environment?: 'preview' | 'production';
+  },
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<void> {
+  const { releaseAdmissionLockKeys, releaseAdmissionWriteKeys } =
+    runtimeReleaseAdmissionKeys(input);
   await client.query(
     `
       WITH admission_lock AS MATERIALIZED (
@@ -6493,6 +6503,61 @@ export async function setPostgresSchedulerRuntimeReleaseAdmission(
   );
 }
 
+/**
+ * Keep a retired lane's final PostgreSQL-only cleanup ordered with admission
+ * and Preview reclaim. The callback must not await remote control-plane work.
+ * A separate statement after the lock wait sees any epoch committed by the
+ * preceding owner; a lock and check in one CTE would retain the old snapshot.
+ */
+export async function withPostgresSchedulerClosedReleaseAdmission<T>(
+  client: PostgresSchedulerQueryClient,
+  input: {
+    releaseId: string;
+    admissionEpoch: number;
+    environment: 'preview' | 'production';
+  },
+  operation: () => Promise<T>,
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<{ guarded: false } | { guarded: true; value: T }> {
+  const { releaseAdmissionLockKeys } = runtimeReleaseAdmissionKeys(input);
+  await client.query('BEGIN ISOLATION LEVEL READ COMMITTED');
+  try {
+    await client.query(
+      `SELECT pg_advisory_xact_lock(
+                ${POSTGRES_SCHEDULER_RELEASE_ADMISSION_LOCK_NAMESPACE},
+                ${quoteIdent(schemaName(options))}.runtime_release_admission_lock_id(lock_key)
+              )
+         FROM unnest($1::text[]) AS lock_key
+        ORDER BY lock_key`,
+      [releaseAdmissionLockKeys],
+    );
+    const admission = await client.query<{ closed: boolean }>(
+      `SELECT count(*)::integer = cardinality($1::text[])
+              AND coalesce(bool_and(NOT accepting AND admission_epoch = $2::bigint), false) AS closed
+         FROM ${tableName('runtime_release_admission', options)}
+        WHERE release_id = ANY($1::text[])`,
+      [releaseAdmissionLockKeys, input.admissionEpoch],
+    );
+    if (admission.rows[0]?.closed !== true) {
+      await client.query('COMMIT');
+      return { guarded: false };
+    }
+    const value = await operation();
+    await client.query('COMMIT');
+    return { guarded: true, value };
+  } catch (error) {
+    try {
+      await client.query('ROLLBACK');
+    } catch (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        'Retired release cleanup failed and its transaction could not roll back.',
+      );
+    }
+    throw error;
+  }
+}
+
 /**
  * Scheduler-run statuses and suspension kinds a newer release lane may adopt.
  *
@@ -18026,6 +18091,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
@@ -18067,6 +18135,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`.
@@ -18328,7 +18398,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.251",
+  version: "0.3.253",
   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.251",
+  version: "0.3.253",
   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.251",
+  version: "0.3.253",
   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.251",
+  version: "0.3.253",
   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.251";
+    readonly version: "0.3.253";
     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.251";
+    readonly version: "0.3.253";
     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.251",
+  version: "0.3.253",
   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.251",
+  version: "0.3.253",
   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.251",
+  "version": "0.3.253",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",