deepline 0.3.482 → 0.3.484

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

@@ -205,7 +205,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.482',
+  version: '0.3.484',
   updateSummary: {
     introducedIn: '0.3.90',
     summary:

package/dist/bundling-sources/shared_libs/monitors/signal-radars/inbound-dead-letter.ts

@@ -22,6 +22,72 @@ export type InboundPgClient = {
 
 export type InboundFailureClass = 'transient' | 'permanent';
 
+/** Persisted states for `dl_meta.signal_radar_inbound_dead_letter`. */
+export const SIGNAL_RADAR_INBOUND_DEAD_LETTER_STATUS = {
+  open: 'open',
+  replaying: 'replaying',
+  replayed: 'replayed',
+  discarded: 'discarded',
+} as const;
+
+export type SignalRadarInboundDeadLetterStatus =
+  (typeof SIGNAL_RADAR_INBOUND_DEAD_LETTER_STATUS)[keyof typeof SIGNAL_RADAR_INBOUND_DEAD_LETTER_STATUS];
+
+export type ClaimableSignalRadarInboundDeadLetterStatus = Extract<
+  SignalRadarInboundDeadLetterStatus,
+  'open' | 'replaying'
+>;
+
+/** Durable transition edges. Database predicates remain the atomic fences. */
+export type SignalRadarInboundDeadLetterTransition =
+  | { event: 'claim'; from: 'open'; to: 'replaying' }
+  | { event: 'stale_claim_reclaimed'; from: 'replaying'; to: 'replaying' }
+  | { event: 'enqueue_failed'; from: 'replaying'; to: 'open' }
+  | { event: 'worker_unprocessed'; from: 'replaying'; to: 'open' }
+  | {
+      event: 'worker_processed';
+      from: 'open' | 'replaying';
+      to: 'replayed';
+    }
+  | { event: 'malformed_payload'; from: 'replaying'; to: 'discarded' }
+  | {
+      event: 'dead_letter_recorded';
+      from: 'open' | 'replaying' | 'replayed';
+      to: 'open';
+    }
+  | { event: 'dead_letter_recorded'; from: 'discarded'; to: 'discarded' };
+
+/** Parse a value read from persisted storage; unknown future values fail closed. */
+export function parseSignalRadarInboundDeadLetterStatus(
+  value: unknown,
+): SignalRadarInboundDeadLetterStatus | null {
+  switch (value) {
+    case SIGNAL_RADAR_INBOUND_DEAD_LETTER_STATUS.open:
+    case SIGNAL_RADAR_INBOUND_DEAD_LETTER_STATUS.replaying:
+    case SIGNAL_RADAR_INBOUND_DEAD_LETTER_STATUS.replayed:
+    case SIGNAL_RADAR_INBOUND_DEAD_LETTER_STATUS.discarded:
+      return value;
+    default:
+      return null;
+  }
+}
+
+/** A failed redrive returns an in-flight/completed delivery to review. */
+export function transitionSignalRadarInboundDeadLetterStatus(
+  value: unknown,
+  event: 'dead_letter_recorded',
+): SignalRadarInboundDeadLetterStatus {
+  const current = parseSignalRadarInboundDeadLetterStatus(value);
+  if (!current) {
+    throw new Error(
+      `Unknown signal radar dead-letter status '${String(value)}'.`,
+    );
+  }
+  return current === SIGNAL_RADAR_INBOUND_DEAD_LETTER_STATUS.discarded
+    ? SIGNAL_RADAR_INBOUND_DEAD_LETTER_STATUS.discarded
+    : SIGNAL_RADAR_INBOUND_DEAD_LETTER_STATUS.open;
+}
+
 function errorMessage(error: unknown): string {
   if (error instanceof Error && error.message.trim()) return error.message;
   if (typeof error === 'string' && error.trim()) return error;
@@ -211,17 +277,42 @@ export async function recordSignalRadarDeadLetter(input: {
   };
 
   if (message.deadLetterId) {
-    const reopened = await client.query(
-      `UPDATE dl_meta.signal_radar_inbound_dead_letter
-          SET status = CASE WHEN status = 'discarded' THEN status ELSE 'open' END,
-              attempts = attempts + $2,
-              last_error = $3,
-              updated_at = now()
+    const prior = await client.query(
+      `SELECT status
+         FROM dl_meta.signal_radar_inbound_dead_letter
         WHERE dead_letter_id = $1
-        RETURNING dead_letter_id`,
-      [message.deadLetterId, input.attempts, lastError.slice(0, 8000)],
+        FOR UPDATE`,
+      [message.deadLetterId],
     );
-    if ((reopened.rows ?? []).length > 0) {
+    const existing = (prior.rows ?? [])[0] as
+      | { status?: unknown }
+      | undefined;
+    if (existing) {
+      const nextStatus = transitionSignalRadarInboundDeadLetterStatus(
+        existing.status,
+        'dead_letter_recorded',
+      );
+      const reopened = await client.query(
+        `UPDATE dl_meta.signal_radar_inbound_dead_letter
+            SET status = $2,
+                attempts = attempts + $3,
+                last_error = $4,
+                updated_at = now()
+          WHERE dead_letter_id = $1 AND status = $5
+          RETURNING dead_letter_id`,
+        [
+          message.deadLetterId,
+          nextStatus,
+          input.attempts,
+          lastError.slice(0, 8000),
+          existing.status,
+        ],
+      );
+      if ((reopened.rows ?? []).length === 0) {
+        throw new Error(
+          'Signal radar dead-letter status changed while recording a failure.',
+        );
+      }
       if (eventIdempotencyKey) {
         await markCapturedRawWriteFailed(
           client,

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/ambiguous-modal-create-state.ts

@@ -0,0 +1,21 @@
+/** Persisted in ambiguous_modal_creates.status. */
+export const AmbiguousModalCreateStatus = {
+  Pending: 'pending',
+  Resolved: 'resolved',
+} as const;
+
+export type AmbiguousModalCreateStatus =
+  (typeof AmbiguousModalCreateStatus)[keyof typeof AmbiguousModalCreateStatus];
+
+/** Decode database text at the scheduler boundary; unknown states fail closed. */
+export function readAmbiguousModalCreateStatus(
+  value: unknown,
+): AmbiguousModalCreateStatus {
+  if (
+    value === AmbiguousModalCreateStatus.Pending ||
+    value === AmbiguousModalCreateStatus.Resolved
+  ) {
+    return value;
+  }
+  throw new Error(`Unknown ambiguous Modal create status: ${String(value)}.`);
+}

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/compute-billing-job-state.ts

@@ -0,0 +1,23 @@
+/** Persisted in compute_billing_jobs_v2.status. */
+export const ComputeBillingJobStatus = {
+  Pending: 'pending',
+  Settling: 'settling',
+  Settled: 'settled',
+} as const;
+
+export type ComputeBillingJobStatus =
+  (typeof ComputeBillingJobStatus)[keyof typeof ComputeBillingJobStatus];
+
+/** Decode database text at the scheduler boundary; unknown states fail closed. */
+export function readComputeBillingJobStatus(
+  value: unknown,
+): ComputeBillingJobStatus {
+  if (
+    value === ComputeBillingJobStatus.Pending ||
+    value === ComputeBillingJobStatus.Settling ||
+    value === ComputeBillingJobStatus.Settled
+  ) {
+    return value;
+  }
+  throw new Error(`Unknown compute billing job status: ${String(value)}.`);
+}

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/integration-operation-value-retirement-state.ts

@@ -0,0 +1,25 @@
+/** Persisted in runtime_integration_operation_value_retirements.state. */
+export const IntegrationOperationValueRetirementState = {
+  Pending: 'pending',
+  Deleting: 'deleting',
+  Deleted: 'deleted',
+  Cancelled: 'cancelled',
+} as const;
+
+export type IntegrationOperationValueRetirementState =
+  (typeof IntegrationOperationValueRetirementState)[keyof typeof IntegrationOperationValueRetirementState];
+
+/** Decode database text at the scheduler boundary; unknown states fail closed. */
+export function readIntegrationOperationValueRetirementState(
+  value: unknown,
+): IntegrationOperationValueRetirementState {
+  if (
+    value === IntegrationOperationValueRetirementState.Pending ||
+    value === IntegrationOperationValueRetirementState.Deleting ||
+    value === IntegrationOperationValueRetirementState.Deleted ||
+    value === IntegrationOperationValueRetirementState.Cancelled
+  ) {
+    return value;
+  }
+  throw new Error(`Unknown Integration Operation value retirement state: ${String(value)}.`);
+}

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/integration-operation-value-retirement.ts

@@ -4,6 +4,10 @@ import {
   isIntegrationOperationValueReference,
   type IntegrationOperationValueReference,
 } from './integration-operation-value-reference';
+import {
+  IntegrationOperationValueRetirementState,
+  readIntegrationOperationValueRetirementState,
+} from './integration-operation-value-retirement-state';
 
 /**
  * The value-retirement journal needs only the scheduler client's query
@@ -50,6 +54,7 @@ type RetirementRow = {
   object_digest: string;
   reference_json: unknown;
   claim_token: string;
+  state: unknown;
 };
 
 export type ClaimedIntegrationOperationValueRetirement = {
@@ -59,6 +64,7 @@ export type ClaimedIntegrationOperationValueRetirement = {
   objectDigest: string;
   reference: IntegrationOperationValueReference;
   claimToken: string;
+  state: typeof IntegrationOperationValueRetirementState.Deleting;
 };
 
 /**
@@ -102,7 +108,8 @@ export async function claimPostgresIntegrationOperationValueRetirements(input: {
       WHERE retirements.ctid = candidates.ctid
       RETURNING retirements.org_id, retirements.operation_key,
                 retirements.object_key, retirements.object_digest,
-                retirements.reference_json, retirements.claim_token`,
+                retirements.reference_json, retirements.claim_token,
+                retirements.state`,
     [limit(input.limit), claimToken],
   );
   return claimed.rows.map((row) => {
@@ -119,6 +126,12 @@ export async function claimPostgresIntegrationOperationValueRetirements(input: {
         `Integration Operation value retirement ${row.object_key} does not match its immutable reference.`,
       );
     }
+    const state = readIntegrationOperationValueRetirementState(row.state);
+    if (state !== IntegrationOperationValueRetirementState.Deleting) {
+      throw new Error(
+        `Integration Operation value retirement ${row.object_key} was claimed in ${state} state.`,
+      );
+    }
     return {
       orgId: row.org_id,
       operationKey: row.operation_key,
@@ -126,6 +139,7 @@ export async function claimPostgresIntegrationOperationValueRetirements(input: {
       objectDigest: row.object_digest,
       reference: row.reference_json,
       claimToken: row.claim_token,
+      state,
     };
   });
 }

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/outbox-repair-operation-state.ts

@@ -0,0 +1,30 @@
+/** Persisted in outbox_repair_operations.state. */
+export const OutboxRepairOperationState = {
+  Planned: 'planned',
+  Applied: 'applied',
+} as const;
+
+export type OutboxRepairOperationState =
+  (typeof OutboxRepairOperationState)[keyof typeof OutboxRepairOperationState];
+
+/** Decode database text at the scheduler boundary; unknown states fail closed. */
+export function readOutboxRepairOperationState(
+  value: unknown,
+): OutboxRepairOperationState {
+  if (
+    value === OutboxRepairOperationState.Planned ||
+    value === OutboxRepairOperationState.Applied
+  ) {
+    return value;
+  }
+  throw new Error(`Unknown outbox repair operation state: ${String(value)}.`);
+}
+
+/** A repair is planned once, then durably applied; applied is terminal. */
+export function canTransitionOutboxRepairOperation(
+  from: OutboxRepairOperationState,
+  to: OutboxRepairOperationState,
+): boolean {
+  return from === OutboxRepairOperationState.Planned &&
+    to === OutboxRepairOperationState.Applied;
+}

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

@@ -59,6 +59,24 @@ import {
   type RuntimeSandboxProvider,
   runtimeSandboxProviderForResourceKind,
 } from './runtime-sandbox-operation';
+import {
+  AmbiguousModalCreateStatus,
+  readAmbiguousModalCreateStatus,
+} from './ambiguous-modal-create-state';
+import {
+  ComputeBillingJobStatus,
+  readComputeBillingJobStatus,
+} from './compute-billing-job-state';
+import {
+  SandboxCleanupJobStatus,
+  readSandboxCleanupJobStatus,
+} from './sandbox-cleanup-job-state';
+export {
+  OutboxRepairOperationState,
+  canTransitionOutboxRepairOperation,
+  readOutboxRepairOperationState,
+} from './outbox-repair-operation-state';
+export type { OutboxRepairOperationState as OutboxRepairOperationStateType } from './outbox-repair-operation-state';
 import {
   TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
   type ToolExecutionErrorSchemaVersion,
@@ -10245,7 +10263,7 @@ export async function recordPostgresSchedulerAmbiguousModalCreateIntent(
   },
   options?: Pick<PostgresSchedulerOptions, 'schema'>,
 ): Promise<boolean> {
-  const recorded = await client.query<{ run_id: string }>(
+  const recorded = await client.query<{ run_id: string; status: unknown }>(
     `
       INSERT INTO ${tableName('ambiguous_modal_creates', options)} (
         run_id, attempt, modal_app_id, environment, tags_json, sandbox_capacity_lease_id
@@ -10263,7 +10281,7 @@ export async function recordPostgresSchedulerAmbiguousModalCreateIntent(
             sandbox_capacity_lease_id = EXCLUDED.sandbox_capacity_lease_id,
             status = 'pending',
             resolved_at = NULL
-      RETURNING run_id
+      RETURNING run_id, status
     `,
     [
       input.runId,
@@ -10275,6 +10293,14 @@ export async function recordPostgresSchedulerAmbiguousModalCreateIntent(
       input.sandboxCapacityLeaseId?.trim() || null,
     ],
   );
+  for (const row of recorded.rows) {
+    if (
+      readAmbiguousModalCreateStatus(row.status) !==
+      AmbiguousModalCreateStatus.Pending
+    ) {
+      throw new Error('Recorded ambiguous Modal create intent was not pending.');
+    }
+  }
   return recorded.rows.length > 0;
 }
 
@@ -10302,6 +10328,7 @@ export async function resolvePostgresSchedulerAmbiguousModalCreateIntent(
 }
 
 export type PostgresSchedulerAmbiguousModalCreateIntent = {
+  status: typeof AmbiguousModalCreateStatus.Pending;
   runId: string;
   attempt: number;
   modalAppId: string;
@@ -10329,6 +10356,7 @@ export async function listPostgresSchedulerAmbiguousModalCreateIntents(
   const minimumAgeMs = Math.max(0, Math.floor(input.minimumAgeMs));
   const rows = await client.query<{
     run_id: string;
+    status: unknown;
     attempt: number;
     modal_app_id: string;
     environment: 'preview' | 'production';
@@ -10337,7 +10365,7 @@ export async function listPostgresSchedulerAmbiguousModalCreateIntents(
     created_at_ms: number;
   }>(
     `
-      SELECT run_id, attempt, modal_app_id, environment, tags_json, sandbox_capacity_lease_id,
+      SELECT run_id, status, attempt, modal_app_id, environment, tags_json, sandbox_capacity_lease_id,
              floor(extract(epoch FROM created_at) * 1000)::bigint AS created_at_ms
       FROM ${tableName('ambiguous_modal_creates', options)}
       WHERE status = 'pending'
@@ -10348,15 +10376,24 @@ export async function listPostgresSchedulerAmbiguousModalCreateIntents(
     `,
     [input.environment, minimumAgeMs, limit],
   );
-  return rows.rows.map((row) => ({
-    runId: row.run_id,
-    attempt: Number(row.attempt),
-    modalAppId: row.modal_app_id,
-    environment: row.environment,
-    tags: row.tags_json,
-    sandboxCapacityLeaseId: row.sandbox_capacity_lease_id,
-    createdAtMs: Number(row.created_at_ms),
-  }));
+  return rows.rows.map((row) => {
+    const status = readAmbiguousModalCreateStatus(row.status);
+    if (status !== AmbiguousModalCreateStatus.Pending) {
+      throw new Error(
+        `Ambiguous Modal create intent ${row.run_id} was listed in ${status} state.`,
+      );
+    }
+    return {
+      status,
+      runId: row.run_id,
+      attempt: Number(row.attempt),
+      modalAppId: row.modal_app_id,
+      environment: row.environment,
+      tags: row.tags_json,
+      sandboxCapacityLeaseId: row.sandbox_capacity_lease_id,
+      createdAtMs: Number(row.created_at_ms),
+    };
+  });
 }
 
 /** Provider-confirmed absence is terminal for one pre-create selector. */
@@ -11743,6 +11780,7 @@ export async function directCompletePostgresSchedulerRunnerTerminal(
 }
 
 export type PostgresSchedulerComputeBillingJob = {
+  status: typeof ComputeBillingJobStatus.Settling;
   runId: string;
   attemptCount: number;
   failureCount: number;
@@ -11994,6 +12032,7 @@ export async function claimPostgresSchedulerComputeBillingJobs(
   );
   const claimed = await client.query<{
     run_id: string;
+    status: unknown;
     attempt_count: number;
     failure_count: number;
     run_status: string;
@@ -12045,6 +12084,7 @@ export async function claimPostgresSchedulerComputeBillingJobs(
         WHERE job.run_id = candidates.run_id
         RETURNING
           job.run_id,
+          job.status,
           job.attempt_count,
             job.failure_count,
             job.session_bootstrap_approved_at,
@@ -12052,6 +12092,7 @@ export async function claimPostgresSchedulerComputeBillingJobs(
       )
       SELECT
         claimed.run_id,
+        claimed.status,
         claimed.attempt_count,
         claimed.failure_count,
         claimed.session_bootstrap_approved_at,
@@ -12063,15 +12104,24 @@ export async function claimPostgresSchedulerComputeBillingJobs(
     `,
     [input.leaseOwner, limit, leaseSeconds],
   );
-  return claimed.rows.map((row) => ({
-    runId: row.run_id,
-    attemptCount: row.attempt_count,
-    failureCount: row.failure_count,
-    success: row.run_status === 'completed',
-    bootstrapSessionPending:
-      row.session_bootstrap_approved_at !== null &&
-      row.session_bootstrap_completed_at === null,
-  }));
+  return claimed.rows.map((row) => {
+    const status = readComputeBillingJobStatus(row.status);
+    if (status !== ComputeBillingJobStatus.Settling) {
+      throw new Error(
+        `Compute billing job ${row.run_id} was claimed in ${status} state.`,
+      );
+    }
+    return {
+      status,
+      runId: row.run_id,
+      attemptCount: row.attempt_count,
+      failureCount: row.failure_count,
+      success: row.run_status === 'completed',
+      bootstrapSessionPending:
+        row.session_bootstrap_approved_at !== null &&
+        row.session_bootstrap_completed_at === null,
+    };
+  });
 }
 
 /**
@@ -12476,6 +12526,7 @@ function protectedDetachedResourceSql(
 }
 
 export type PostgresSchedulerSandboxCleanupJob = {
+  status: typeof SandboxCleanupJobStatus.Deleting;
   provider: 'daytona' | 'modal';
   sandboxId: string;
   runId: string;
@@ -12951,6 +13002,7 @@ export async function claimPostgresSchedulerSandboxCleanupJobs(
   if (!adoptionWork.rows[0].pending && !adoptionWork.rows[0].claimable)
     return [];
   const claimed = await client.query<{
+    status: unknown;
     provider: 'daytona' | 'modal';
     sandbox_id: string;
     run_id: string;
@@ -13031,6 +13083,7 @@ export async function claimPostgresSchedulerSandboxCleanupJobs(
           target.run_id,
           target.attempt,
           target.environment,
+          target.status,
           target.routing_domain,
           target.attempt_count,
           target.failure_count,
@@ -13108,18 +13161,27 @@ export async function claimPostgresSchedulerSandboxCleanupJobs(
       input.throughAttempt ?? null,
     ],
   );
-  return claimed.rows.map((row) => ({
-    provider: row.provider,
-    sandboxId: row.sandbox_id,
-    runId: row.run_id,
-    attempt: row.attempt,
-    environment: row.environment,
-    routingDomain: row.routing_domain,
-    attemptCount: row.attempt_count,
-    failureCount: row.failure_count,
-    runStatusAtClaim: row.terminal_status,
-    diagnostic: row.diagnostic_json,
-  }));
+  return claimed.rows.map((row) => {
+    const status = readSandboxCleanupJobStatus(row.status);
+    if (status !== SandboxCleanupJobStatus.Deleting) {
+      throw new Error(
+        `Sandbox cleanup job ${row.sandbox_id} was claimed in ${status} state.`,
+      );
+    }
+    return {
+      status,
+      provider: row.provider,
+      sandboxId: row.sandbox_id,
+      runId: row.run_id,
+      attempt: row.attempt,
+      environment: row.environment,
+      routingDomain: row.routing_domain,
+      attemptCount: row.attempt_count,
+      failureCount: row.failure_count,
+      runStatusAtClaim: row.terminal_status,
+      diagnostic: row.diagnostic_json,
+    };
+  });
 }
 
 /**

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

@@ -13,6 +13,8 @@ import {
   RuntimeSandboxOperationState,
   RuntimeSandboxProvider,
 } from './runtime-sandbox-operation';
+import type { ComputeBillingJobStatus } from './compute-billing-job-state';
+import { readComputeBillingJobStatus } from './compute-billing-job-state';
 
 /**
  * The baseline when an organization has no current override. It sits above
@@ -1437,7 +1439,7 @@ export type RuntimeSandboxCapacityTestEvidence = {
     cleanupJobs: number;
     confirmedCleanupJobs: number;
     pendingCleanup: number;
-    computeJobStatus: string | null;
+    computeJobStatus: ComputeBillingJobStatus | null;
     hasComputeIntent: boolean;
     recordedResources: number;
     firstAcquiredAtMs: number | null;
@@ -1544,5 +1546,11 @@ export async function readRuntimeSandboxCapacityTestEvidence(
   const evidence = result.rows[0]?.evidence;
   if (!evidence)
     throw new Error('Sandbox capacity evidence query returned no snapshot.');
+  if (evidence.run) {
+    evidence.run.computeJobStatus =
+      evidence.run.computeJobStatus === null
+        ? null
+        : readComputeBillingJobStatus(evidence.run.computeJobStatus);
+  }
   return input.runId && evidence.run === null ? null : evidence;
 }

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/sandbox-cleanup-job-state.ts

@@ -0,0 +1,23 @@
+/** Persisted in sandbox_cleanup_jobs_v2.status. */
+export const SandboxCleanupJobStatus = {
+  Pending: 'pending',
+  Deleting: 'deleting',
+  Deleted: 'deleted',
+} as const;
+
+export type SandboxCleanupJobStatus =
+  (typeof SandboxCleanupJobStatus)[keyof typeof SandboxCleanupJobStatus];
+
+/** Decode database text at the scheduler boundary; unknown states fail closed. */
+export function readSandboxCleanupJobStatus(
+  value: unknown,
+): SandboxCleanupJobStatus {
+  if (
+    value === SandboxCleanupJobStatus.Pending ||
+    value === SandboxCleanupJobStatus.Deleting ||
+    value === SandboxCleanupJobStatus.Deleted
+  ) {
+    return value;
+  }
+  throw new Error(`Unknown sandbox cleanup job status: ${String(value)}.`);
+}

package/dist/bundling-sources/shared_libs/product-notifications/destination-state.ts

@@ -0,0 +1,93 @@
+/** Persisted product notification destination lifecycle. */
+export const PRODUCT_NOTIFICATION_DESTINATION_STATUS = {
+  pendingVerification: 'pending_verification',
+  active: 'active',
+  disabled: 'disabled',
+  needsAttention: 'needs_attention',
+} as const;
+
+export type ProductNotificationDestinationStatus =
+  (typeof PRODUCT_NOTIFICATION_DESTINATION_STATUS)[keyof typeof PRODUCT_NOTIFICATION_DESTINATION_STATUS];
+
+export const PRODUCT_NOTIFICATION_DESTINATION_TRANSITIONS = {
+  pending_verification: ['active', 'disabled', 'needs_attention'],
+  active: ['pending_verification', 'disabled', 'needs_attention'],
+  disabled: ['pending_verification', 'active'],
+  needs_attention: ['pending_verification', 'active', 'disabled'],
+} as const satisfies Record<
+  ProductNotificationDestinationStatus,
+  readonly ProductNotificationDestinationStatus[]
+>;
+
+export type StoredProductNotificationDestinationStatus =
+  | { kind: 'known'; status: ProductNotificationDestinationStatus }
+  | { kind: 'unknown'; value: string };
+
+export function readProductNotificationDestinationStatus(
+  value: string,
+): StoredProductNotificationDestinationStatus {
+  switch (value) {
+    case PRODUCT_NOTIFICATION_DESTINATION_STATUS.pendingVerification:
+    case PRODUCT_NOTIFICATION_DESTINATION_STATUS.active:
+    case PRODUCT_NOTIFICATION_DESTINATION_STATUS.disabled:
+    case PRODUCT_NOTIFICATION_DESTINATION_STATUS.needsAttention:
+      return { kind: 'known', status: value };
+    default:
+      return { kind: 'unknown', value };
+  }
+}
+
+export function requireProductNotificationDestinationStatus(
+  value: string,
+): ProductNotificationDestinationStatus {
+  const stored = readProductNotificationDestinationStatus(value);
+  if (stored.kind === 'unknown') {
+    throw new Error(
+      `Unsupported product notification destination status: ${stored.value}`,
+    );
+  }
+  return stored.status;
+}
+
+export function isProductNotificationDestinationDeliverable(
+  value: string,
+): boolean {
+  return (
+    readProductNotificationDestinationStatus(value).kind === 'known' &&
+    value === PRODUCT_NOTIFICATION_DESTINATION_STATUS.active
+  );
+}
+
+export function canTransitionProductNotificationDestination(
+  current: string,
+  next: ProductNotificationDestinationStatus,
+): boolean {
+  const stored = readProductNotificationDestinationStatus(current);
+  return (
+    stored.kind === 'known' &&
+    (
+      PRODUCT_NOTIFICATION_DESTINATION_TRANSITIONS[
+        stored.status
+      ] as readonly string[]
+    ).includes(next)
+  );
+}
+
+/** Validate a destination lifecycle write without narrowing persisted schema. */
+export function nextProductNotificationDestinationStatus(
+  current: string,
+  next: ProductNotificationDestinationStatus,
+): ProductNotificationDestinationStatus {
+  const stored = readProductNotificationDestinationStatus(current);
+  if (stored.kind === 'unknown') {
+    throw new Error(
+      `Cannot transition product notification destination from unknown status: ${stored.value}`,
+    );
+  }
+  if (!canTransitionProductNotificationDestination(current, next)) {
+    throw new Error(
+      `Invalid product notification destination transition: ${current} -> ${next}`,
+    );
+  }
+  return next;
+}