deepline 0.3.185 → 0.3.186

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.185',
+  version: '0.3.186',
   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/sdk/src/types.ts

@@ -1331,6 +1331,8 @@ export interface PlayDefinitionDetail {
     cronTimezone?: string | null;
     nextScheduledAt?: number | null;
     lastScheduledAt?: number | null;
+    blockedAt?: number | null;
+    blockedReasonCode?: string | null;
     blockedReason?: string | null;
     [key: string]: unknown;
   } | null;
@@ -1403,6 +1405,8 @@ export interface PlayTriggerStatus {
   cron: string | null;
   webhook: string | null;
   blockedReason: string | null;
+  blockedReasonCode?: string;
+  blockedAt?: number;
 }
 
 export interface ProductNotificationEventDefinition {

package/dist/bundling-sources/shared_libs/play-runtime/launch-identity.ts

@@ -0,0 +1,229 @@
+import { sha256Hex, stableStringify } from '../plays/row-identity';
+import { LEGACY_MAX_CONCURRENT_EXTERNAL_CALLS } from './governor/policy';
+import type { PlaySchedulerSubmitInput } from './scheduler-backend';
+
+/** Optional launch-envelope field used by the mixed-release admission fence. */
+export const PLAY_LAUNCH_IDENTITY_DIGEST_FIELD = 'launchIdentityDigest';
+const PLAY_LAUNCH_IDENTITY_DIGEST_NAMESPACE = 'deepline:play-launch-identity';
+
+export type PlayLaunchFieldRole = 'identity' | 'detail';
+
+/**
+ * Keep this list exhaustive over the launch envelope. A newly added field must
+ * be classified before it can participate in launch admission.
+ */
+export const PLAY_LAUNCH_ENVELOPE_FIELD_ROLES: {
+  readonly [K in keyof PlaySchedulerSubmitInput]-?: PlayLaunchFieldRole;
+} = {
+  orgId: 'identity',
+  playName: 'identity',
+  playReference: 'identity',
+  definitionScope: 'identity',
+  revisionId: 'identity',
+  artifactStorageKey: 'identity',
+  artifactHash: 'identity',
+  graphHash: 'identity',
+  workflowFamilyKey: 'identity',
+  inputSha256: 'identity',
+  source: 'identity',
+  triggerSource: 'identity',
+  parentRunId: 'identity',
+  rootRunId: 'identity',
+  asyncLaunchKey: 'identity',
+  asyncInvocationKey: 'identity',
+  asyncRequestFingerprint: 'identity',
+  force: 'identity',
+  forceToolRefresh: 'identity',
+  maxConcurrentExternalCalls: 'identity',
+  maxConcurrentRows: 'identity',
+  integrationMode: 'identity',
+  runtimeSandboxPlacementPolicyId: 'identity',
+  input: 'identity',
+  inputFile: 'identity',
+  inlineInputFile: 'identity',
+  inlineCsv: 'identity',
+  packagedFiles: 'identity',
+  runId: 'detail',
+  existingOnly: 'detail',
+  asyncParentRunAttempt: 'detail',
+  asyncParentRunLeaseToken: 'detail',
+  asyncParentAttemptRequired: 'detail',
+  asyncAncestryPlayIds: 'detail',
+  playId: 'detail',
+  schedulerSchema: 'detail',
+  requiresRunCreatedProjection: 'detail',
+  runtimeArtifact: 'detail',
+  runtimeProtocolVersion: 'detail',
+  staticPipeline: 'detail',
+  inputSummary: 'detail',
+  inputBytes: 'detail',
+  inputFileId: 'detail',
+  replayedFromRunId: 'detail',
+  totalRows: 'detail',
+  contractSnapshot: 'detail',
+  executionPlan: 'detail',
+  preloadedDbSessions: 'detail',
+  preloadedDbSessionUnwrapKey: 'detail',
+  executorToken: 'detail',
+  runtimeAuthority: 'detail',
+  runtimeApiBaseUrl: 'detail',
+  runtimeTokenOrigin: 'detail',
+  baseUrl: 'detail',
+  coordinatorUrl: 'detail',
+  coordinatorInternalToken: 'detail',
+  runtimeDeployVersion: 'detail',
+  absurdReleaseId: 'detail',
+  absurdReleaseEnvironment: 'detail',
+  vercelProtectionBypassToken: 'detail',
+  preferredReceiptGatewayMachineId: 'detail',
+  runtimeTestFaultHeader: 'detail',
+  testPolicyOverrides: 'detail',
+  submittedAtMs: 'detail',
+  schedulerBackend: 'detail',
+  executionProfile: 'detail',
+  runtimeBackend: 'detail',
+  queueMaxDelaySeconds: 'detail',
+  queuePriority: 'detail',
+  userEmail: 'detail',
+  userId: 'detail',
+  launchIdentityDigest: 'detail',
+};
+
+export const PLAY_LAUNCH_IDENTITY_FIELDS_COMPARED_OUTSIDE_DIGEST: readonly string[] =
+  Object.freeze(['runtimeSandboxPlacementPolicyId']);
+
+export const PLAY_LAUNCH_IDENTITY_FIELDS: readonly string[] = Object.freeze(
+  Object.entries(PLAY_LAUNCH_ENVELOPE_FIELD_ROLES)
+    .filter(([, role]) => role === 'identity')
+    .map(([field]) => field)
+    .sort(),
+);
+
+export const PLAY_LAUNCH_DETAIL_FIELDS: readonly string[] = Object.freeze(
+  Object.entries(PLAY_LAUNCH_ENVELOPE_FIELD_ROLES)
+    .filter(([, role]) => role === 'detail')
+    .map(([field]) => field)
+    .sort(),
+);
+
+export type PlayLaunchIdentitySource = Readonly<
+  Partial<Record<keyof PlaySchedulerSubmitInput, unknown>>
+>;
+
+function text(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function flag(value: unknown): boolean {
+  return value === true;
+}
+
+function count(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function stagedFileIdentity(value: unknown): Record<string, unknown> | null {
+  const file = record(value);
+  if (!file) return null;
+  return {
+    logicalPath:
+      text(file.logicalPath) ?? text(file.path) ?? text(file.playPath),
+    fileName: text(file.fileName) ?? text(file.name),
+    contentType: text(file.contentType),
+    bytes: count(file.bytes),
+    contentDigest:
+      typeof file.contentBase64 === 'string'
+        ? sha256Hex(file.contentBase64)
+        : typeof file.inlineText === 'string'
+          ? sha256Hex(file.inlineText)
+          : null,
+  };
+}
+
+function stagedFileListIdentity(
+  value: unknown,
+): Array<Record<string, unknown>> {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((entry) => stagedFileIdentity(entry))
+    .filter((entry): entry is Record<string, unknown> => entry !== null)
+    .sort((left, right) =>
+      stableStringify(left).localeCompare(stableStringify(right)),
+    );
+}
+
+/** Return only customer intent; transport, authority, and release details are excluded. */
+export function buildPlayLaunchIdentity(
+  launch: PlayLaunchIdentitySource,
+): Record<string, unknown> {
+  const inlineCsv = record(launch.inlineCsv);
+  return {
+    orgId: text(launch.orgId),
+    playName: text(launch.playName),
+    playReference: text(launch.playReference) ?? text(launch.playName),
+    definitionScope: text(launch.definitionScope),
+    revisionId: text(launch.revisionId),
+    artifactStorageKey: text(launch.artifactStorageKey),
+    artifactHash: text(launch.artifactHash),
+    graphHash: text(launch.graphHash),
+    workflowFamilyKey: text(launch.workflowFamilyKey),
+    inputSha256: text(launch.inputSha256),
+    source: text(launch.source),
+    triggerSource: text(launch.triggerSource),
+    parentRunId: text(launch.parentRunId),
+    rootRunId: text(launch.rootRunId),
+    asyncLaunchKey: text(launch.asyncLaunchKey),
+    asyncInvocationKey: text(launch.asyncInvocationKey),
+    asyncRequestFingerprint: text(launch.asyncRequestFingerprint),
+    force: flag(launch.force),
+    forceToolRefresh: flag(launch.forceToolRefresh),
+    integrationMode: text(launch.integrationMode),
+    maxConcurrentExternalCalls:
+      count(launch.maxConcurrentExternalCalls) ??
+      LEGACY_MAX_CONCURRENT_EXTERNAL_CALLS,
+    maxConcurrentRows: count(launch.maxConcurrentRows),
+    inputDigest: sha256Hex(stableStringify(launch.input ?? {})),
+    inputFile: stagedFileIdentity(launch.inputFile),
+    inlineInputFile: stagedFileIdentity(launch.inlineInputFile),
+    inlineCsv: inlineCsv
+      ? {
+          name: text(inlineCsv.name),
+          rowsDigest: sha256Hex(stableStringify(inlineCsv.rows ?? [])),
+        }
+      : null,
+    packagedFiles: stagedFileListIdentity(launch.packagedFiles),
+  };
+}
+
+export const PLAY_LAUNCH_DIGESTED_IDENTITY_FIELDS: readonly string[] =
+  Object.freeze(
+    PLAY_LAUNCH_IDENTITY_FIELDS.filter(
+      (field) =>
+        !PLAY_LAUNCH_IDENTITY_FIELDS_COMPARED_OUTSIDE_DIGEST.includes(field),
+    ),
+  );
+
+export function buildPlayLaunchIdentityDigest(
+  launch: PlayLaunchIdentitySource,
+): string {
+  return sha256Hex(
+    `${PLAY_LAUNCH_IDENTITY_DIGEST_NAMESPACE}\0${stableStringify(
+      buildPlayLaunchIdentity(launch),
+    )}`,
+  );
+}
+
+export function withPlayLaunchIdentityDigest<
+  T extends PlaySchedulerSubmitInput,
+>(launch: T): T {
+  return {
+    ...launch,
+    launchIdentityDigest: buildPlayLaunchIdentityDigest(launch),
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/play-runs/admission/contracts.ts

@@ -42,16 +42,31 @@ export type PlayRunAdmissionJob = {
   admit(input: PlayRunAdmissionInput): Promise<PlayRunAdmissionOutcome>;
 };
 
+export type PlayRunLaunchConflictReason = 'launch_identity_mismatch';
+
 /** A stable, machine-readable rejection for a reused run id with new intent. */
 export class PlayRunLaunchConflictError extends Error {
   readonly code = 'PLAY_RUN_LAUNCH_CONFLICT';
+  readonly conflictReason: PlayRunLaunchConflictReason | undefined;
+  readonly conflictingFields: string[] | undefined;
 
-  constructor(runId: string, options?: { cause?: unknown }) {
+  constructor(
+    runId: string,
+    options?: {
+      cause?: unknown;
+      conflictReason?: PlayRunLaunchConflictReason;
+      conflictingFields?: readonly string[];
+    },
+  ) {
     super(
       `Play run "${runId}" already exists with a different launch.`,
       options,
     );
     this.name = 'PlayRunLaunchConflictError';
+    this.conflictReason = options?.conflictReason;
+    this.conflictingFields = options?.conflictingFields
+      ? [...options.conflictingFields]
+      : undefined;
   }
 }
 

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

@@ -54,6 +54,9 @@ export function createPostgresPlayRunAdmissionPorts(input: {
               artifactHash: admission.launch.artifactHash,
               graphHash: admission.launch.graphHash,
               inputSha256: admission.launch.inputSha256,
+              launchIdentityDigest: admission.launch.launchIdentityDigest,
+              conflictReason: conflict.conflictReason ?? null,
+              conflictingFields: conflict.conflictingFields ?? null,
               error: conflict,
             });
             throw conflict;

package/dist/bundling-sources/shared_libs/play-runtime/runtime-telemetry.ts

@@ -41,6 +41,12 @@ export type PlayRunLaunchConflictTelemetryInput = {
   artifactHash?: string | null;
   graphHash?: string | null;
   inputSha256?: string | null;
+  /** Named-intent digest of the incoming durable launch envelope. */
+  launchIdentityDigest?: string | null;
+  /** Admission-side conflict classification when available. */
+  conflictReason?: string | null;
+  /** Named launch-intent fields that differed, when the persisted envelope is available. */
+  conflictingFields?: readonly string[] | null;
   error?: unknown;
 };
 
@@ -113,6 +119,9 @@ export function buildPlayRunLaunchConflictTelemetry(
       revisionId: input.revisionId ?? null,
       artifactHash: input.artifactHash ?? null,
       graphHash: input.graphHash ?? null,
+      launchIdentityDigest: input.launchIdentityDigest ?? null,
+      conflictReason: input.conflictReason ?? null,
+      conflictingFields: input.conflictingFields ?? null,
       triage:
         level === 'error'
           ? {

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

@@ -216,6 +216,13 @@ export type PlaySchedulerSubmitInput = {
   runtimeTestFaultHeader?: string | null;
   /** Request-scoped, dev-only runtime policy overrides for black-box durability tests. */
   testPolicyOverrides?: RuntimeTestPolicyOverrides | null;
+  /**
+   * Digest of the named intent behind this launch. Runtime admission compares
+   * this optional field instead of treating transport and execution details as
+   * immutable identity. Older persisted rows omit it and keep the legacy
+   * comparison until they are gone.
+   */
+  launchIdentityDigest?: string | null;
   /** Millisecond epoch timestamp captured immediately before scheduler submit. */
   submittedAtMs?: number;
   /** Scheduler backend that owns orchestration for this run. */

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

@@ -157,6 +157,11 @@ import {
 import { LEGACY_MAX_CONCURRENT_EXTERNAL_CALLS } from '../governor/policy';
 import { requireRuntimeAuthorityDescriptor } from '../execution-capabilities';
 import { stringifyPostgresJson } from '../postgres-json';
+import {
+  buildPlayLaunchIdentity,
+  withPlayLaunchIdentityDigest,
+} from '../launch-identity';
+import { PlayRunLaunchConflictError } from '../play-runs/admission/contracts';
 import { mintPlayRunAttemptRuntimeToken } from '../runtime-authority';
 import { withActiveSpan } from '../../observability/tracing';
 import type {
@@ -2198,6 +2203,99 @@ async function ensurePostgresSchedulerCronScheduleSchema(
   `);
 }
 
+/**
+ * Install the launch-admission functions on every bootstrap path.
+ *
+ * These are function-body compatibility changes, not schema DDL. An already
+ * current scheduler schema takes the fast path below, so keeping these only in
+ * the full bootstrap leaves that estate with the old whole-envelope equality.
+ */
+async function ensurePostgresSchedulerLaunchAdmissionFunctions(
+  client: PostgresSchedulerQueryClient,
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): Promise<void> {
+  const quotedSchema = quoteIdent(schemaName(options));
+  await client.query(`
+    CREATE OR REPLACE FUNCTION ${quotedSchema}.runtime_launch_admission_identity(
+      launch_json jsonb
+    ) RETURNS jsonb
+    LANGUAGE sql
+    IMMUTABLE
+    STRICT
+    PARALLEL SAFE
+    AS $$
+      SELECT jsonb_set(
+        jsonb_set(
+          launch_json - ARRAY[
+            'launchIdentityDigest',
+            'executorToken',
+            'inputFileId',
+            'preloadedDbSessionUnwrapKey',
+            'preloadedDbSessions',
+            'submittedAtMs',
+            'runtimeDeployVersion',
+            'absurdReleaseId',
+            'absurdReleaseEnvironment',
+            'coordinatorUrl',
+            'coordinatorInternalToken',
+            'baseUrl',
+            'runtimeApiBaseUrl',
+            'vercelProtectionBypassToken'
+          ]::text[],
+          '{maxConcurrentExternalCalls}',
+          coalesce(
+            launch_json->'maxConcurrentExternalCalls',
+            to_jsonb(${LEGACY_MAX_CONCURRENT_EXTERNAL_CALLS}::integer)
+          ),
+          true
+        ),
+        '{maxConcurrentRows}',
+        coalesce(launch_json->'maxConcurrentRows', 'null'::jsonb),
+        true
+      )
+    $$
+  `);
+  await client.query(`
+    CREATE OR REPLACE FUNCTION ${quotedSchema}.runtime_launch_admission_matches(
+      existing_launch_json jsonb,
+      incoming_launch_json jsonb
+    ) RETURNS boolean
+    LANGUAGE sql
+    IMMUTABLE
+    STRICT
+    PARALLEL SAFE
+    AS $$
+      SELECT CASE
+        WHEN nullif(btrim(coalesce(existing_launch_json->>'launchIdentityDigest', '')), '') IS NOT NULL
+          AND nullif(btrim(coalesce(incoming_launch_json->>'launchIdentityDigest', '')), '') IS NOT NULL
+          THEN btrim(existing_launch_json->>'launchIdentityDigest')
+             = btrim(incoming_launch_json->>'launchIdentityDigest')
+            AND (
+              NOT (
+                existing_launch_json ? 'runtimeSandboxPlacementPolicyId'
+                AND incoming_launch_json ? 'runtimeSandboxPlacementPolicyId'
+              )
+              OR existing_launch_json->'runtimeSandboxPlacementPolicyId'
+                 IS NOT DISTINCT FROM incoming_launch_json->'runtimeSandboxPlacementPolicyId'
+            )
+        WHEN existing_launch_json ? 'runtimeSandboxPlacementPolicyId'
+          AND incoming_launch_json ? 'runtimeSandboxPlacementPolicyId'
+          THEN ${quotedSchema}.runtime_launch_admission_identity(
+            existing_launch_json - 'launchIdentityDigest'
+          ) = ${quotedSchema}.runtime_launch_admission_identity(
+            incoming_launch_json - 'launchIdentityDigest'
+          )
+        ELSE ${quotedSchema}.runtime_launch_admission_identity(
+          existing_launch_json - 'launchIdentityDigest'
+        ) - ARRAY['runtimeSandboxPlacementPolicyId', 'launchIdentityDigest']::text[] =
+          ${quotedSchema}.runtime_launch_admission_identity(
+            incoming_launch_json - 'launchIdentityDigest'
+          ) - ARRAY['runtimeSandboxPlacementPolicyId', 'launchIdentityDigest']::text[]
+      END
+    $$
+  `);
+}
+
 export async function ensurePostgresSchedulerSchema(
   client: PostgresSchedulerQueryClient,
   options?: Pick<PostgresSchedulerOptions, 'schema'> & {
@@ -2332,6 +2430,7 @@ export async function ensurePostgresSchedulerSchema(
     const hasLegacyAdmissionRows =
       legacyAdmissionRows?.rows[0]?.present === true;
     if (schemaCoreIsCurrent) {
+      await ensurePostgresSchedulerLaunchAdmissionFunctions(client, options);
       if (!schemaIsCurrent) {
         await ensurePostgresSchedulerTerminalComputeBillingOutboxTrigger(
           client,
@@ -3703,6 +3802,7 @@ export async function ensurePostgresSchedulerSchema(
       [POSTGRES_SCHEDULER_SCHEMA_VERSION],
     );
     await ensurePostgresSchedulerCronScheduleSchema(client, options);
+    await ensurePostgresSchedulerLaunchAdmissionFunctions(client, options);
     if (hadOutbox.rows[0]?.present !== true) {
       await client.query(
         `
@@ -4409,6 +4509,45 @@ export async function submitPostgresAbsurdPlayRun(
   };
 }
 
+function launchIdentityConflictFields(
+  existingLaunchJson: unknown,
+  incomingLaunch: PlaySchedulerSubmitInput,
+): string[] {
+  if (
+    !existingLaunchJson ||
+    typeof existingLaunchJson !== 'object' ||
+    Array.isArray(existingLaunchJson)
+  ) {
+    return [];
+  }
+  const existingIdentity = buildPlayLaunchIdentity(
+    existingLaunchJson as Record<string, unknown>,
+  );
+  const incomingIdentity = buildPlayLaunchIdentity(incomingLaunch);
+  const fields = Object.keys(incomingIdentity).filter(
+    (field) =>
+      stableStringify(existingIdentity[field]) !==
+      stableStringify(incomingIdentity[field]),
+  );
+  if (
+    Object.prototype.hasOwnProperty.call(
+      existingLaunchJson,
+      'runtimeSandboxPlacementPolicyId',
+    ) &&
+    Object.prototype.hasOwnProperty.call(
+      incomingLaunch,
+      'runtimeSandboxPlacementPolicyId',
+    ) &&
+    stableStringify(
+      (existingLaunchJson as Record<string, unknown>)
+        .runtimeSandboxPlacementPolicyId,
+    ) !== stableStringify(incomingLaunch.runtimeSandboxPlacementPolicyId)
+  ) {
+    fields.push('runtimeSandboxPlacementPolicyId');
+  }
+  return fields.sort();
+}
+
 async function submitPostgresSchedulerRunTransaction(
   client: PostgresSchedulerQueryClient,
   input: PlaySchedulerSubmitInput,
@@ -4447,7 +4586,10 @@ async function submitPostgresSchedulerRunTransaction(
     existingOnly: requestedExistingOnly,
     ...durableInput
   } = input;
-  input = durableInput;
+  // Every scheduler writer converges through this seam, including the cron
+  // successor path and Workpool retries. Stamp after ephemeral admission proof
+  // fields are removed so they can never change the durable launch identity.
+  input = withPlayLaunchIdentityDigest(durableInput);
   const existingOnlySql = requestedExistingOnly === true ? 'true' : 'false';
   const releaseId = input.absurdReleaseId?.trim() || null;
   const legacyPreviewRelease =
@@ -4531,6 +4673,7 @@ async function submitPostgresSchedulerRunTransaction(
     run_created: boolean;
     task_created: boolean | null;
     task_recovery_required: boolean;
+    existing_launch_json: unknown | null;
   }>(
     `
       WITH run_lock AS MATERIALIZED (
@@ -4578,6 +4721,7 @@ async function submitPostgresSchedulerRunTransaction(
             coalesce(runs.admission_json, runs.launch_json),
             $8::jsonb
           ) AS matches_launch,
+          coalesce(runs.admission_json, runs.launch_json) AS launch_json,
           runs.absurd_task_id,
           runs.status
         FROM admission_lock
@@ -4784,6 +4928,7 @@ async function submitPostgresSchedulerRunTransaction(
                    AND existing_run.absurd_task_id IS NULL
                )
              ) AS task_recovery_required,
+             (SELECT launch_json FROM existing_run) AS existing_launch_json,
              CASE WHEN EXISTS (SELECT 1 FROM run_insert)
                          OR EXISTS (SELECT 1 FROM run_recovery)
                THEN pg_notify($10, $11)
@@ -4840,9 +4985,13 @@ async function submitPostgresSchedulerRunTransaction(
     );
   }
   if (row?.accepted === false && row.existing_run && !row.matching_existing) {
-    throw new Error(
-      `Play run "${input.runId}" already exists with a different launch.`,
-    );
+    throw new PlayRunLaunchConflictError(input.runId, {
+      conflictReason: 'launch_identity_mismatch',
+      conflictingFields: launchIdentityConflictFields(
+        row.existing_launch_json,
+        input,
+      ),
+    });
   }
   if (row?.accepted === false && !row?.existing_run && requestedExistingOnly) {
     throw new Error(
@@ -5144,6 +5293,14 @@ export class PostgresSchedulerCronScheduleConfigurationError extends Error {
   }
 }
 
+/** A deterministic Run identity conflict cannot be repaired by retrying the same fire. */
+export class PostgresSchedulerCronLaunchConflictError extends PostgresSchedulerCronScheduleConfigurationError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PostgresSchedulerCronLaunchConflictError';
+  }
+}
+
 /**
  * The timer stores the facts needed to reconstruct a pinned admission, not a
  * previously prepared launch. Executor tokens, preloaded session keys,
@@ -5488,7 +5645,7 @@ function cronOccurrenceLaunch(input: {
       `Cron schedule "${input.schedule.scheduleId}" did not receive a fresh authority for its pinned occurrence.`,
     );
   }
-  return {
+  return withPlayLaunchIdentityDigest({
     ...input.launch,
     schedulerSchema:
       input.schedulerSchema ?? input.launch.schedulerSchema ?? null,
@@ -5501,7 +5658,7 @@ function cronOccurrenceLaunch(input: {
     ),
     triggerSource: 'cron',
     requiresRunCreatedProjection: true,
-  };
+  });
 }
 
 export type FirePostgresSchedulerCronScheduleInput = {
@@ -5524,14 +5681,26 @@ export type FirePostgresSchedulerCronScheduleInput = {
  * 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.
+ *
+ * A re-fire of the same occurrence whose deterministic Run already exists is
+ * an idempotent re-fire, not a no-op. The cursor advances when the existing
+ * launch identity matches, even if this statement did not create the Run.
+ * A genuine identity mismatch is returned as `stalled` so it cannot silently
+ * freeze the schedule behind an indistinguishable replay.
  */
 export async function firePostgresSchedulerCronSchedule(
   client: PostgresSchedulerQueryClient,
   input: FirePostgresSchedulerCronScheduleInput,
   options?: Pick<PostgresSchedulerOptions, 'schema'>,
 ): Promise<
-  | { status: 'admitted'; runId: string; successorDueAtMs: number }
+  | {
+      status: 'admitted';
+      runId: string;
+      successorDueAtMs: number;
+      reused: boolean;
+    }
   | { status: 'superseded' }
+  | { status: 'stalled'; runId: string; reason: string }
 > {
   assertPostgresSchedulerCronScheduleInput(input);
   const schedule = await readPostgresSchedulerCronSchedule(
@@ -5598,7 +5767,11 @@ export async function firePostgresSchedulerCronSchedule(
     orgId: launch.orgId,
   });
   const result = await client.query<{
-    admitted: boolean;
+    advanced: boolean;
+    run_created: boolean;
+    schedule_current: boolean;
+    existing_run: boolean;
+    matching_existing: boolean;
     release_accepting: boolean;
   }>(
     `
@@ -5623,16 +5796,28 @@ export async function firePostgresSchedulerCronSchedule(
           AND release_gate.accepting
         FOR UPDATE
       ), existing_run AS MATERIALIZED (
-        SELECT runs.run_id
+        SELECT runs.run_id,
+               ${quoteIdent(schemaName(options))}.runtime_launch_admission_matches(
+                 coalesce(runs.admission_json, runs.launch_json),
+                 $6::jsonb
+               ) AS matches_launch
         FROM matching_schedule
         JOIN ${tableName('runs', options)} AS runs ON runs.run_id = $5::text
+      ), occurrence AS MATERIALIZED (
+        SELECT EXISTS (SELECT 1 FROM matching_schedule) AS schedule_current,
+               EXISTS (SELECT 1 FROM existing_run) AS existing_run,
+               coalesce(
+                 (SELECT matches_launch FROM existing_run),
+                 false
+               ) AS matching_existing
       ), 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)
+        FROM occurrence
+        WHERE occurrence.schedule_current
+          AND NOT occurrence.existing_run
       ), play_task_spawn AS MATERIALIZED (
         SELECT spawned.task_id::text AS task_id
         FROM play_task_request
@@ -5668,15 +5853,25 @@ export async function firePostgresSchedulerCronSchedule(
                  'coordinatorInternalToken',
                  'vercelProtectionBypassToken'
                ]::text[]
-        WHERE EXISTS (SELECT 1 FROM matching_schedule)
-          AND NOT EXISTS (SELECT 1 FROM existing_run)
+        FROM occurrence
+        WHERE occurrence.schedule_current
+          AND NOT occurrence.existing_run
         RETURNING run_id
+      ), occurrence_admitted AS MATERIALIZED (
+        SELECT true AS admitted
+        FROM occurrence
+        WHERE EXISTS (SELECT 1 FROM run_insert)
+           OR (
+             occurrence.schedule_current
+             AND occurrence.existing_run
+             AND occurrence.matching_existing
+           )
       ), 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)
+        WHERE EXISTS (SELECT 1 FROM occurrence_admitted)
       ), successor_task_spawn AS MATERIALIZED (
         SELECT spawned.task_id::text AS task_id
         FROM successor_task_request
@@ -5750,10 +5945,14 @@ export async function firePostgresSchedulerCronSchedule(
           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)
+          AND EXISTS (SELECT 1 FROM occurrence_admitted)
         RETURNING schedule_id
       )
-      SELECT EXISTS (SELECT 1 FROM schedule_advance) AS admitted,
+      SELECT EXISTS (SELECT 1 FROM schedule_advance) AS advanced,
+             EXISTS (SELECT 1 FROM run_insert) AS run_created,
+             (SELECT schedule_current FROM occurrence) AS schedule_current,
+             (SELECT existing_run FROM occurrence) AS existing_run,
+             (SELECT matching_existing FROM occurrence) AS matching_existing,
              coalesce(
                (SELECT accepting
                   FROM ${tableName('runtime_release_admission', options)}
@@ -5780,19 +5979,34 @@ export async function firePostgresSchedulerCronSchedule(
       releaseAdmissionKey,
     ],
   );
-  if (result.rows[0]?.release_accepting !== true) {
+  const fired = result.rows[0];
+  if (fired?.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' };
+  if (fired.advanced === true) {
+    return {
+      status: 'admitted',
+      runId: launch.runId,
+      successorDueAtMs,
+      reused: fired.run_created !== true,
+    };
   }
-  return {
-    status: 'admitted',
-    runId: launch.runId,
-    successorDueAtMs,
-  };
+  if (
+    fired.schedule_current === true &&
+    fired.existing_run === true &&
+    fired.matching_existing !== true
+  ) {
+    return {
+      status: 'stalled',
+      runId: launch.runId,
+      reason:
+        `Cron schedule "${schedule.scheduleId}" generation ${schedule.generation} cannot advance past ` +
+        `occurrence ${schedule.dueAtMs}: Run "${launch.runId}" already exists with a different launch identity.`,
+    };
+  }
+  return { status: 'superseded' };
 }
 
 /** Fence a malformed/invalid timer so it cannot repeatedly consume workers. */

package/dist/cli/index.js

@@ -3051,7 +3051,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.185",
+  version: "0.3.186",
   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
@@ -27485,7 +27485,9 @@ function readLiveCronMetadata(play) {
   return {
     schedule: typeof metadata?.cronSchedule === "string" ? metadata.cronSchedule : null,
     timezone: typeof metadata?.cronTimezone === "string" ? metadata.cronTimezone : null,
-    nextScheduledAt: typeof metadata?.nextScheduledAt === "number" ? metadata.nextScheduledAt : null
+    nextScheduledAt: typeof metadata?.nextScheduledAt === "number" ? metadata.nextScheduledAt : null,
+    blockedAt: typeof metadata?.blockedAt === "number" ? metadata.blockedAt : null,
+    blockedReasonCode: typeof metadata?.blockedReasonCode === "string" ? metadata.blockedReasonCode : null
   };
 }
 function liveTriggerStatusLines(status, play) {
@@ -27504,6 +27506,18 @@ function liveTriggerStatusLines(status, play) {
     }
     if (status?.blockedReason) {
       lines.push(`  Schedule issue: ${status.blockedReason}`);
+      if (status.blockedReasonCode || cron.blockedReasonCode) {
+        lines.push(
+          `  Schedule issue code: ${status.blockedReasonCode ?? cron.blockedReasonCode}`
+        );
+      }
+      const blockedAt = status.blockedAt ?? cron.blockedAt;
+      if (blockedAt !== null && blockedAt !== void 0) {
+        lines.push(`  Schedule blocked at: ${formatTimestamp(blockedAt)}`);
+      }
+      lines.push(
+        "  Recovery: republish the live revision to re-arm this schedule after the platform issue is fixed."
+      );
     }
   }
   if (status?.webhook) {
@@ -27516,7 +27530,9 @@ function triggerStatusFromMetadata(value) {
   return {
     cron: typeof metadata?.cronStatus === "string" ? metadata.cronStatus : null,
     webhook: typeof metadata?.webhookStatus === "string" ? metadata.webhookStatus : null,
-    blockedReason: typeof metadata?.blockedReason === "string" ? metadata.blockedReason : null
+    blockedReason: typeof metadata?.blockedReason === "string" ? metadata.blockedReason : null,
+    blockedReasonCode: typeof metadata?.blockedReasonCode === "string" ? metadata.blockedReasonCode : null,
+    blockedAt: typeof metadata?.blockedAt === "number" ? metadata.blockedAt : null
   };
 }
 function printPublishReceipt(input2) {
@@ -29318,6 +29334,16 @@ async function handlePlayList(args) {
       );
       if (play.triggerStatus.blockedReason) {
         lines.push(`    schedule issue: ${play.triggerStatus.blockedReason}`);
+        if (play.triggerStatus.blockedReasonCode) {
+          lines.push(
+            `    schedule issue code: ${play.triggerStatus.blockedReasonCode}`
+          );
+        }
+        if (play.triggerStatus.blockedAt !== void 0) {
+          lines.push(
+            `    schedule blocked at: ${formatTimestamp(play.triggerStatus.blockedAt)}`
+          );
+        }
       }
     } else {
       lines.push("    scheduled execution: not configured");

package/dist/cli/index.mjs

@@ -3046,7 +3046,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.185",
+  version: "0.3.186",
   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
@@ -27557,7 +27557,9 @@ function readLiveCronMetadata(play) {
   return {
     schedule: typeof metadata?.cronSchedule === "string" ? metadata.cronSchedule : null,
     timezone: typeof metadata?.cronTimezone === "string" ? metadata.cronTimezone : null,
-    nextScheduledAt: typeof metadata?.nextScheduledAt === "number" ? metadata.nextScheduledAt : null
+    nextScheduledAt: typeof metadata?.nextScheduledAt === "number" ? metadata.nextScheduledAt : null,
+    blockedAt: typeof metadata?.blockedAt === "number" ? metadata.blockedAt : null,
+    blockedReasonCode: typeof metadata?.blockedReasonCode === "string" ? metadata.blockedReasonCode : null
   };
 }
 function liveTriggerStatusLines(status, play) {
@@ -27576,6 +27578,18 @@ function liveTriggerStatusLines(status, play) {
     }
     if (status?.blockedReason) {
       lines.push(`  Schedule issue: ${status.blockedReason}`);
+      if (status.blockedReasonCode || cron.blockedReasonCode) {
+        lines.push(
+          `  Schedule issue code: ${status.blockedReasonCode ?? cron.blockedReasonCode}`
+        );
+      }
+      const blockedAt = status.blockedAt ?? cron.blockedAt;
+      if (blockedAt !== null && blockedAt !== void 0) {
+        lines.push(`  Schedule blocked at: ${formatTimestamp(blockedAt)}`);
+      }
+      lines.push(
+        "  Recovery: republish the live revision to re-arm this schedule after the platform issue is fixed."
+      );
     }
   }
   if (status?.webhook) {
@@ -27588,7 +27602,9 @@ function triggerStatusFromMetadata(value) {
   return {
     cron: typeof metadata?.cronStatus === "string" ? metadata.cronStatus : null,
     webhook: typeof metadata?.webhookStatus === "string" ? metadata.webhookStatus : null,
-    blockedReason: typeof metadata?.blockedReason === "string" ? metadata.blockedReason : null
+    blockedReason: typeof metadata?.blockedReason === "string" ? metadata.blockedReason : null,
+    blockedReasonCode: typeof metadata?.blockedReasonCode === "string" ? metadata.blockedReasonCode : null,
+    blockedAt: typeof metadata?.blockedAt === "number" ? metadata.blockedAt : null
   };
 }
 function printPublishReceipt(input2) {
@@ -29390,6 +29406,16 @@ async function handlePlayList(args) {
       );
       if (play.triggerStatus.blockedReason) {
         lines.push(`    schedule issue: ${play.triggerStatus.blockedReason}`);
+        if (play.triggerStatus.blockedReasonCode) {
+          lines.push(
+            `    schedule issue code: ${play.triggerStatus.blockedReasonCode}`
+          );
+        }
+        if (play.triggerStatus.blockedAt !== void 0) {
+          lines.push(
+            `    schedule blocked at: ${formatTimestamp(play.triggerStatus.blockedAt)}`
+          );
+        }
       }
     } else {
       lines.push("    scheduled execution: not configured");

package/dist/index.d.mts

@@ -2207,6 +2207,8 @@ interface PlayDefinitionDetail {
         cronTimezone?: string | null;
         nextScheduledAt?: number | null;
         lastScheduledAt?: number | null;
+        blockedAt?: number | null;
+        blockedReasonCode?: string | null;
         blockedReason?: string | null;
         [key: string]: unknown;
     } | null;
@@ -2270,6 +2272,8 @@ interface PlayTriggerStatus {
     cron: string | null;
     webhook: string | null;
     blockedReason: string | null;
+    blockedReasonCode?: string;
+    blockedAt?: number;
 }
 interface ProductNotificationEventDefinition {
     id: string;

package/dist/index.d.ts

@@ -2207,6 +2207,8 @@ interface PlayDefinitionDetail {
         cronTimezone?: string | null;
         nextScheduledAt?: number | null;
         lastScheduledAt?: number | null;
+        blockedAt?: number | null;
+        blockedReasonCode?: string | null;
         blockedReason?: string | null;
         [key: string]: unknown;
     } | null;
@@ -2270,6 +2272,8 @@ interface PlayTriggerStatus {
     cron: string | null;
     webhook: string | null;
     blockedReason: string | null;
+    blockedReasonCode?: string;
+    blockedAt?: number;
 }
 interface ProductNotificationEventDefinition {
     id: string;

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.185",
+  version: "0.3.186",
   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.185",
+  version: "0.3.186",
   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/install-integrity.json

@@ -209,6 +209,7 @@
     "dist/bundling-sources/shared_libs/play-runtime/internal-bootstrap-token.ts",
     "dist/bundling-sources/shared_libs/play-runtime/internal-step-ids.ts",
     "dist/bundling-sources/shared_libs/play-runtime/lane-retirement-gate.ts",
+    "dist/bundling-sources/shared_libs/play-runtime/launch-identity.ts",
     "dist/bundling-sources/shared_libs/play-runtime/launch-source-policy.ts",
     "dist/bundling-sources/shared_libs/play-runtime/lease-policy.ts",
     "dist/bundling-sources/shared_libs/play-runtime/ledger-safe-payload.ts",

package/dist/release.d.mts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.185";
+    readonly version: "0.3.186";
     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.185";
+    readonly version: "0.3.186";
     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.185",
+  version: "0.3.186",
   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.185",
+  version: "0.3.186",
   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.185",
+  "version": "0.3.186",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",