deepline 0.3.114 → 0.3.115

package/dist/bundling-sources/shared_libs/observability/dlq.ts

@@ -0,0 +1,942 @@
+import type { Measured } from './scheduled-work-v2';
+import type { QueueObservation } from './queue-health';
+
+/**
+ * Scheduler-neutral dead-letter contract.
+ *
+ * A DLQ is durable work, not a log line. Adapters publish a point-in-time
+ * inventory, preserve measurement uncertainty, and expose only the actions
+ * their owning system can fence safely. The dashboard and admin CLI consume
+ * this contract; they never infer a delete/replay operation from a count.
+ */
+export const DLQ_CONTRACT_VERSION = 1 as const;
+/** Version for stable `<queue-id>.<verb>` path lookup keys. */
+export const DLQ_PATH_INDEX_VERSION = 1 as const;
+
+export type DlqMeasurement = Measured<number>;
+
+export type DlqDisposition =
+  | 'open'
+  | 'uncertain'
+  | 'cleared'
+  | 'not_applicable'
+  | 'unavailable';
+
+export type DlqAction = 'inspect' | 'redrive' | 'discard' | 'mark_done';
+
+/**
+ * A source-owned path through a DLQ state machine. `pathId` is the stable
+ * operator lookup key; `lookupIndex` is the bounded source index (when one is
+ * registered), so an operator can find the exact records without scanning a
+ * whole table. Paths describe authority and state transitions; they do not
+ * grant permission to mutate.
+ */
+export type DlqPathAction =
+  | DlqAction
+  | 'handoff'
+  | 'recover'
+  | 'reconcile'
+  | 'replay'
+  | 'retry'
+  | 'quarantine'
+  | 'release'
+  | 'settle';
+
+export type DlqLookupIndex = {
+  readonly table: string;
+  readonly index: string;
+  readonly key: string;
+  readonly bounded: true;
+};
+
+export type DlqTransitionPath = {
+  /** Stable path index: `<queue-id>.<verb>`. */
+  readonly pathId: string;
+  readonly action: DlqPathAction;
+  readonly fromStates: readonly string[];
+  readonly toState: string;
+  readonly owner: string;
+  readonly source: string;
+  readonly lookupIndex?: DlqLookupIndex;
+  /** Existing owner command, when one is already exposed. */
+  readonly command?: string;
+  readonly enabled: boolean;
+  readonly requiresApproval: boolean;
+  readonly reason: string;
+};
+
+export type DlqActionCapability = {
+  readonly action: DlqAction;
+  readonly enabled: boolean;
+  readonly reason: string;
+};
+
+export type DlqInventory = {
+  readonly contractVersion: typeof DLQ_CONTRACT_VERSION;
+  readonly queueId: string;
+  readonly environment: string;
+  readonly source: string;
+  readonly observedAt: number;
+  readonly size: DlqMeasurement;
+  readonly oldestAgeMs: DlqMeasurement;
+  readonly disposition: DlqDisposition;
+  readonly capabilities: readonly DlqActionCapability[];
+  /** Optional on the low-level adapter for additive wire compatibility. */
+  readonly paths?: readonly DlqTransitionPath[];
+};
+
+export type DlqSummaryEntry = {
+  readonly id: string;
+  readonly name: string;
+  readonly owner: string;
+  readonly kind: string;
+  readonly source: string;
+  readonly adapter?: string;
+  readonly observedAt?: number;
+  readonly unresolved: DlqMeasurement;
+  readonly oldestAgeMs: DlqMeasurement;
+  readonly disposition: DlqDisposition;
+  readonly capabilities: readonly DlqActionCapability[];
+  readonly paths: readonly DlqTransitionPath[];
+};
+
+export type DlqSummary = {
+  /** Optional for readers that still receive the pre-path-index payload. */
+  readonly pathIndexVersion?: typeof DLQ_PATH_INDEX_VERSION;
+  readonly total: DlqMeasurement;
+  readonly queuesWithUnresolved: number;
+  readonly queuesNeedingConfirmation: number;
+  readonly observedQueues: number;
+  readonly unavailableQueues: readonly {
+    id: string;
+    name: string;
+    reason: string;
+  }[];
+  readonly entries: readonly DlqSummaryEntry[];
+  readonly dispositionPolicy: {
+    kind: 'owner_defined';
+    label: string;
+    description: string;
+  };
+};
+
+export type DlqAdapterContext = {
+  readonly environment: string;
+  readonly now: number;
+  readonly limit: number;
+  readonly cursor?: string;
+};
+
+export type DlqApprovalActorKind = 'queue_owner' | 'deepline_employee';
+
+/**
+ * Short-lived, target-bound approval for a potentially mutating DLQ action.
+ * The actor identity must be authenticated by the admin/control-plane
+ * boundary; these fields are the durable hand-off between that boundary and
+ * the queue adapter, not a self-asserted permission check.
+ */
+export type DlqApproval = {
+  readonly approvalId: string;
+  readonly actorId: string;
+  readonly actorKind: DlqApprovalActorKind;
+  readonly reason: string;
+  readonly approvedAt: number;
+  readonly expiresAt: number;
+  readonly queueId: string;
+  readonly environment: string;
+  readonly action: Exclude<DlqAction, 'inspect'>;
+  readonly fingerprint?: string;
+};
+
+export type DlqApplyContext = DlqAdapterContext & {
+  /** Required even for the read-only adapter so mutating implementations
+   * cannot accidentally grow an approval-free call path. */
+  readonly approval: DlqApproval;
+};
+
+export type DlqPlan = {
+  readonly contractVersion: typeof DLQ_CONTRACT_VERSION;
+  readonly queueId: string;
+  readonly environment: string;
+  readonly action: Exclude<DlqAction, 'inspect'>;
+  readonly itemIds: readonly string[];
+  readonly snapshot: DlqInventory;
+  readonly allowed: boolean;
+  readonly requiresApproval: true;
+  readonly reason: string;
+  readonly fingerprint?: string;
+};
+
+export type DlqApplyResult = {
+  readonly contractVersion: typeof DLQ_CONTRACT_VERSION;
+  readonly queueId: string;
+  readonly environment: string;
+  readonly action: Exclude<DlqAction, 'inspect'>;
+  readonly applied: readonly string[];
+  readonly skipped: readonly { id: string; reason: string }[];
+  readonly verificationRequired: boolean;
+};
+
+/** Every backend—including Absurd—must implement this port at its boundary. */
+export type DlqAdapter = {
+  readonly id: string;
+  readonly queueId: string;
+  readonly source: string;
+  inspect(context: DlqAdapterContext): Promise<DlqInventory>;
+  plan(
+    context: DlqAdapterContext,
+    request: {
+      action: Exclude<DlqAction, 'inspect'>;
+      itemIds?: readonly string[];
+    },
+  ): Promise<DlqPlan>;
+  apply(context: DlqApplyContext, plan: DlqPlan): Promise<DlqApplyResult>;
+};
+
+export const DLQ_PLAN_MAX_SNAPSHOT_AGE_MS = 5 * 60 * 1_000;
+export const DLQ_APPROVAL_MAX_TTL_MS = 15 * 60 * 1_000;
+
+export type DlqApprovalExpectation = {
+  readonly queueId: string;
+  readonly environment: string;
+  readonly action: Exclude<DlqAction, 'inspect'>;
+  readonly fingerprint?: string;
+  readonly now: number;
+};
+
+/** Validate the durable approval hand-off before a queue adapter mutates. */
+export function validateDlqApproval(
+  approval: DlqApproval,
+  expected: DlqApprovalExpectation,
+): void {
+  for (const [label, value] of [
+    ['approvalId', approval.approvalId],
+    ['actorId', approval.actorId],
+    ['reason', approval.reason],
+    ['queueId', approval.queueId],
+    ['environment', approval.environment],
+  ] as const) {
+    if (!value.trim()) throw new Error(`DLQ approval ${label} is required.`);
+  }
+  if (
+    approval.actorKind !== 'queue_owner' &&
+    approval.actorKind !== 'deepline_employee'
+  ) {
+    throw new Error(
+      'DLQ approval actor must be a queue owner or Deepline employee.',
+    );
+  }
+  if (approval.queueId !== expected.queueId) {
+    throw new Error('DLQ approval queue does not match the plan.');
+  }
+  if (approval.environment !== expected.environment) {
+    throw new Error('DLQ approval environment does not match the plan.');
+  }
+  if (approval.action !== expected.action) {
+    throw new Error('DLQ approval action does not match the plan.');
+  }
+  if (
+    expected.fingerprint !== undefined &&
+    approval.fingerprint !== expected.fingerprint
+  ) {
+    throw new Error('DLQ approval fingerprint does not match the plan.');
+  }
+  if (
+    !Number.isFinite(approval.approvedAt) ||
+    !Number.isFinite(approval.expiresAt) ||
+    approval.expiresAt <= approval.approvedAt ||
+    approval.expiresAt - approval.approvedAt > DLQ_APPROVAL_MAX_TTL_MS
+  ) {
+    throw new Error('DLQ approval must have a valid short-lived expiry.');
+  }
+  if (
+    approval.approvedAt > expected.now ||
+    approval.expiresAt <= expected.now
+  ) {
+    throw new Error('DLQ approval is expired or not active yet.');
+  }
+}
+
+/**
+ * Common fail-closed guard for every mutating adapter. Implementations should
+ * call this immediately before their source-owned compare-and-set mutation.
+ */
+export function assertDlqApplyAuthorized(
+  context: DlqApplyContext,
+  plan: DlqPlan,
+): void {
+  if (plan.contractVersion !== DLQ_CONTRACT_VERSION) {
+    throw new Error('DLQ plan contract version is unsupported.');
+  }
+  if (!plan.allowed) throw new Error('DLQ plan is not allowed to mutate.');
+  if (!plan.requiresApproval) {
+    throw new Error('DLQ mutation plans must require explicit approval.');
+  }
+  if (plan.environment !== context.environment) {
+    throw new Error('DLQ apply environment does not match the plan.');
+  }
+  if (plan.queueId !== plan.snapshot.queueId) {
+    throw new Error('DLQ plan snapshot does not match the queue.');
+  }
+  if (plan.environment !== plan.snapshot.environment) {
+    throw new Error('DLQ plan snapshot does not match the environment.');
+  }
+  validateDlqInventory(plan.snapshot);
+  if (
+    plan.snapshot.disposition === 'unavailable' ||
+    plan.snapshot.disposition === 'uncertain'
+  ) {
+    throw new Error('DLQ plan snapshot is not trustworthy enough to mutate.');
+  }
+  if (
+    !Number.isFinite(context.now) ||
+    context.now < plan.snapshot.observedAt ||
+    context.now - plan.snapshot.observedAt > DLQ_PLAN_MAX_SNAPSHOT_AGE_MS
+  ) {
+    throw new Error(
+      'DLQ plan snapshot is stale; inspect again before applying.',
+    );
+  }
+  validateDlqApproval(context.approval, {
+    queueId: plan.queueId,
+    environment: plan.environment,
+    action: plan.action,
+    fingerprint: plan.fingerprint,
+    now: context.now,
+  });
+}
+
+export function dispositionForMeasurement(
+  measurement: DlqMeasurement,
+): DlqDisposition {
+  if (measurement.kind === 'unavailable') return 'unavailable';
+  if (measurement.kind === 'not_applicable') return 'not_applicable';
+  if (measurement.kind === 'lower_bound') {
+    return measurement.value > 0 ? 'open' : 'uncertain';
+  }
+  return measurement.value > 0 ? 'open' : 'cleared';
+}
+
+type DlqPathMetadata = {
+  readonly lookupIndex?: DlqLookupIndex;
+  readonly transitions?: readonly {
+    readonly action: Exclude<DlqPathAction, 'inspect'>;
+    readonly fromStates: readonly string[];
+    readonly toState: string;
+    readonly enabled: boolean;
+    readonly requiresApproval: boolean;
+    readonly command?: string;
+    readonly reason: string;
+  }[];
+};
+
+const DLQ_PATH_METADATA: Readonly<Record<string, DlqPathMetadata>> = {
+  'run-ledger-projector-outbox': {
+    lookupIndex: {
+      table: 'runtime_scheduler.outbox',
+      index: 'runtime_scheduler_outbox_dead_health_idx',
+      key: 'delivered_at IS NULL + failed_at',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'retry',
+        fromStates: ['failed'],
+        toState: 'pending',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'The runtime projector owner must verify the causal Run Ledger event and idempotency fence before retrying.',
+      },
+    ],
+  },
+  'compute-billing-jobs': {
+    lookupIndex: {
+      table: 'runtime_scheduler.compute_billing_jobs_v2',
+      index: 'runtime_scheduler_compute_billing_blocked_health_idx',
+      key: 'status <> settled + blocked_at',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'reconcile',
+        fromStates: ['blocked'],
+        toState: 'pending',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'Billing must prove run, ledger, and provider evidence before unblocking a financial settlement obligation.',
+      },
+    ],
+  },
+  'sandbox-cleanup-jobs': {
+    lookupIndex: {
+      table: 'runtime_scheduler.sandbox_cleanup_jobs_v2',
+      index: 'runtime_scheduler_sandbox_cleanup_v2_blocked_health_idx',
+      key: 'status <> deleted + blocked_at/status=deleting',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'retry',
+        fromStates: ['blocked', 'deleting'],
+        toState: 'pending',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'The runtime cleanup owner must verify provider resource identity and deletion idempotency before retrying.',
+      },
+    ],
+  },
+  'play-webhook-receipts': {
+    lookupIndex: {
+      table: 'playWebhookReceipts',
+      index: 'by_state_created_at',
+      key: 'state + createdAt',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'handoff',
+        fromStates: ['blocked', 'expired'],
+        toState: 'pending',
+        enabled: true,
+        requiresApproval: true,
+        command:
+          'deepline-admin runtime webhook-receipts handoff <receipt-id> --reason <reason> --environment production --dry-run',
+        reason:
+          'The owner has a target-deployment handoff command; it fences exact receipts before publishing wakes.',
+      },
+    ],
+  },
+  'workflow-cron-bindings': {
+    lookupIndex: {
+      table: 'workflowBindings',
+      index: 'by_type_status_nextScheduledAt',
+      key: 'type=cron + status=active + nextScheduledAt',
+      bounded: true,
+    },
+  },
+  'play-cron-bindings': {
+    lookupIndex: {
+      table: 'playTriggerBindings',
+      index: 'by_type_status_nextScheduledAt',
+      key: 'type=cron + status=active + nextScheduledAt',
+      bounded: true,
+    },
+  },
+  'ingestion-jobs': {
+    lookupIndex: {
+      table: 'tenantGraphAdoptionJobs',
+      index: 'by_status',
+      key: 'status',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'retry',
+        fromStates: ['failed'],
+        toState: 'queued',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'Retry is source-owned and not registered because these rows may be superseded legacy graph-adoption work.',
+      },
+    ],
+  },
+  'monitor-fleet-convergence': {
+    lookupIndex: {
+      table: 'providerMonitorDefinitions',
+      index: 'by_convergence_due',
+      key: 'convergence + dueAt',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'retry',
+        fromStates: ['failed', 'blocked'],
+        toState: 'pending',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'Provider convergence retries require the monitor owner to verify provider truth and the active binding first.',
+      },
+    ],
+  },
+  'monitor-deployment-jobs': {
+    lookupIndex: {
+      table: 'monitorDeploymentJobs',
+      index: 'by_state_updated',
+      key: 'state + updatedAt',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'retry',
+        fromStates: ['failed'],
+        toState: 'queued',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'Deployment retry is not a shared mutation; the monitor owner must confirm the desired definition and provider state.',
+      },
+    ],
+  },
+  'provider-monitor-reconciliation': {
+    lookupIndex: {
+      table: 'providerMonitorGlobalAuditRuns',
+      index: 'by_provider_updated',
+      key: 'provider + updatedAt',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'reconcile',
+        fromStates: ['failed', 'blocked'],
+        toState: 'pending',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'Reconciliation retry needs a fresh provider inventory and a named audit run; age alone is not a replay signal.',
+      },
+    ],
+  },
+  'signal-radar-inbound-dlq': {
+    lookupIndex: {
+      table: 'providerMonitorReconciliationSourceDeadLetters',
+      index: 'by_provider_last_seen',
+      key: 'provider + lastSeenAt',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'recover',
+        fromStates: ['dead_lettered', 'blocked'],
+        toState: 'pending',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'Recovery must prove upstream ownership, current monitor binding, and idempotent re-enqueue; no generic replay is allowed.',
+      },
+    ],
+  },
+  'charge-reconciliation-backlog': {
+    lookupIndex: {
+      table: 'chargeReservations',
+      index: 'by_status_deadline',
+      key: 'status + deadline',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'quarantine',
+        fromStates: ['open'],
+        toState: 'parked',
+        enabled: true,
+        requiresApproval: true,
+        command:
+          'deepline-admin billing-reservations park --older-than-days <days> --reason <reason> --environment production --dry-run',
+        reason:
+          'Billing owns an explicit, reversible parking path for open reservations with no customer funds held.',
+      },
+      {
+        action: 'settle',
+        fromStates: ['parked'],
+        toState: 'open',
+        enabled: true,
+        requiresApproval: true,
+        command:
+          'deepline-admin billing-reservations settle-parked --org-id <org-id> --reason <reason> --environment production --dry-run',
+        reason:
+          'Only the billing owner can return parked reservations to the settlement worker after provider truth is verified.',
+      },
+      {
+        action: 'release',
+        fromStates: ['parked'],
+        toState: 'released',
+        enabled: true,
+        requiresApproval: true,
+        command:
+          'deepline-admin billing-reservations release-parked --org-id <org-id> --reason <reason> --environment production --dry-run',
+        reason:
+          'Release is an audited write-off path; it must not be inferred from age or an unresolved count.',
+      },
+    ],
+  },
+  'metronome-usage-delivery': {
+    lookupIndex: {
+      table: 'billingUsageOutbox',
+      index: 'by_status_nextAttemptAt',
+      key: 'status + nextAttemptAt',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'retry',
+        fromStates: ['dead', 'needs_review'],
+        toState: 'pending',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'Retry requires a provider allocation check; the minute export cron is currently the source-owned recovery path.',
+      },
+    ],
+  },
+  'billing-operations': {
+    lookupIndex: {
+      table: 'billingOperations',
+      index: 'by_state_nextAttemptAt',
+      key: 'state + nextAttemptAt',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'reconcile',
+        fromStates: ['needs_review', 'failed'],
+        toState: 'applied_or_aborted',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'Billing review rows require immutable provider allocation/payment evidence before an applied or aborted outcome is written.',
+      },
+    ],
+  },
+  'stripe-financial-inbox': {
+    lookupIndex: {
+      table: 'stripeBillingEvents',
+      index: 'by_financialStatus_nextAttemptAt',
+      key: 'financialStatus + financialNextAttemptAt',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'reconcile',
+        fromStates: ['needs_review'],
+        toState: 'processed',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'Stripe review requires immutable event read-back and payment truth; never delete or blindly replay an event.',
+      },
+    ],
+  },
+  'async-usage-recovery': {
+    lookupIndex: {
+      table: 'chargeReservations',
+      index: 'by_mode_status_deadline',
+      key: 'mode + status + deadline',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'reconcile',
+        fromStates: ['open', 'parked'],
+        toState: 'settled_or_released',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'Provider callback truth must be reconciled per reservation; bulk release is unsafe.',
+      },
+    ],
+  },
+  'notification-deliveries': {
+    lookupIndex: {
+      table: 'productNotificationDeliveries',
+      index: 'by_state_next_attempt',
+      key: 'state + nextAttemptAt',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'retry',
+        fromStates: ['failed', 'dead_lettered'],
+        toState: 'pending',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'Notification retry is source-owned and must preserve recipient idempotency and delivery policy.',
+      },
+    ],
+  },
+  'play-deployment-jobs': {
+    lookupIndex: {
+      table: 'playDeployments',
+      index: 'by_status_createdAt',
+      key: 'status + createdAt',
+      bounded: true,
+    },
+    transitions: [
+      {
+        action: 'retry',
+        fromStates: ['failed', 'reconcile_failed'],
+        toState: 'queued',
+        enabled: false,
+        requiresApproval: true,
+        reason:
+          'Deployment repair must verify the artifact and active release before enqueueing a new build.',
+      },
+    ],
+  },
+};
+
+/** Return the stable, source-owned paths for one queue. */
+export function getDlqTransitionPaths(input: {
+  queueId: string;
+  owner: string;
+  source: string;
+}): readonly DlqTransitionPath[] {
+  const metadata = DLQ_PATH_METADATA[input.queueId] ?? {};
+  const inspect: DlqTransitionPath = {
+    pathId: `${input.queueId}.inspect`,
+    action: 'inspect',
+    fromStates: ['dead_lettered', 'blocked', 'uncertain'],
+    toState: 'unchanged',
+    owner: input.owner,
+    source: input.source,
+    ...(metadata.lookupIndex ? { lookupIndex: metadata.lookupIndex } : {}),
+    enabled: true,
+    requiresApproval: false,
+    reason:
+      'Read the bounded inventory and exact item evidence from the owning source.',
+  };
+  const transitions = (metadata.transitions ?? []).map((path) => ({
+    ...path,
+    pathId: `${input.queueId}.${path.action}`,
+    owner: input.owner,
+    source: input.source,
+    ...(metadata.lookupIndex ? { lookupIndex: metadata.lookupIndex } : {}),
+  }));
+  return [inspect, ...transitions];
+}
+
+export function validateDlqTransitionPaths(
+  paths: readonly DlqTransitionPath[],
+): void {
+  const ids = new Set<string>();
+  for (const path of paths) {
+    if (!path.pathId.trim()) throw new Error('DLQ pathId is required.');
+    if (ids.has(path.pathId))
+      throw new Error(`Duplicate DLQ pathId: ${path.pathId}`);
+    ids.add(path.pathId);
+    if (!path.owner.trim()) throw new Error('DLQ path owner is required.');
+    if (!path.source.trim()) throw new Error('DLQ path source is required.');
+    if (path.fromStates.length === 0)
+      throw new Error(`DLQ path ${path.pathId} needs a source state.`);
+    if (!path.toState.trim())
+      throw new Error(`DLQ path ${path.pathId} needs a target state.`);
+    if (path.lookupIndex && !path.lookupIndex.bounded)
+      throw new Error(`DLQ path ${path.pathId} lookup must be bounded.`);
+    if (path.enabled && path.action !== 'inspect' && !path.requiresApproval)
+      throw new Error(
+        `DLQ mutation path ${path.pathId} must require approval.`,
+      );
+  }
+}
+
+export function summarizeDlqInventories(
+  inventories: readonly (DlqInventory & {
+    readonly name: string;
+    readonly owner: string;
+    readonly kind: string;
+    readonly adapter?: string;
+  })[],
+): DlqSummary {
+  inventories.forEach(validateDlqInventory);
+  const entries: DlqSummaryEntry[] = inventories.map((inventory) => {
+    const paths =
+      inventory.paths ??
+      getDlqTransitionPaths({
+        queueId: inventory.queueId,
+        owner: inventory.owner,
+        source: inventory.source,
+      });
+    validateDlqTransitionPaths(paths);
+    return {
+      id: inventory.queueId,
+      name: inventory.name,
+      owner: inventory.owner,
+      kind: inventory.kind,
+      source: inventory.source,
+      ...(inventory.adapter ? { adapter: inventory.adapter } : {}),
+      observedAt: inventory.observedAt,
+      unresolved: inventory.size,
+      oldestAgeMs: inventory.oldestAgeMs,
+      disposition: inventory.disposition,
+      capabilities: inventory.capabilities,
+      paths,
+    };
+  });
+  const unavailableQueues = entries.flatMap((entry) =>
+    entry.unresolved.kind === 'unavailable'
+      ? [{ id: entry.id, name: entry.name, reason: entry.unresolved.reason }]
+      : [],
+  );
+  const measured = entries.flatMap((entry) =>
+    entry.unresolved.kind === 'exact' || entry.unresolved.kind === 'lower_bound'
+      ? [entry.unresolved]
+      : [],
+  );
+  const knownTotal = measured.reduce((sum, metric) => sum + metric.value, 0);
+  const hasLowerBound = measured.some(
+    (metric) => metric.kind === 'lower_bound',
+  );
+  const total: DlqMeasurement =
+    measured.length === 0 && unavailableQueues.length > 0
+      ? {
+          kind: 'unavailable',
+          reason: 'No DLQ adapter produced a measurable snapshot.',
+        }
+      : hasLowerBound || unavailableQueues.length > 0
+        ? { kind: 'lower_bound', value: knownTotal }
+        : { kind: 'exact', value: knownTotal };
+  return {
+    pathIndexVersion: DLQ_PATH_INDEX_VERSION,
+    total,
+    queuesWithUnresolved: entries.filter(
+      (entry) => entry.disposition === 'open',
+    ).length,
+    queuesNeedingConfirmation: entries.filter(
+      (entry) => entry.disposition === 'uncertain',
+    ).length,
+    observedQueues: entries.filter(
+      (entry) => entry.unresolved.kind !== 'unavailable',
+    ).length,
+    unavailableQueues,
+    entries,
+    dispositionPolicy: {
+      kind: 'owner_defined',
+      label: 'Source-owned terminal state',
+      description:
+        'Recovered, archived, released, or otherwise terminal rows leave the unresolved count. There is no cross-queue “mark done” mutation.',
+    },
+  };
+}
+
+/** Adapt the existing queue observation into the shared DLQ inventory port. */
+export function dlqInventoryFromQueueObservation(input: {
+  queueId: string;
+  environment: string;
+  source: string;
+  observation: Pick<QueueObservation, 'observedAt' | 'depth' | 'oldestAgeMs'>;
+  capabilities?: readonly DlqActionCapability[];
+  paths?: readonly DlqTransitionPath[];
+}): DlqInventory {
+  const size = input.observation.depth.deadLettered;
+  return {
+    contractVersion: DLQ_CONTRACT_VERSION,
+    queueId: input.queueId,
+    environment: input.environment,
+    source: input.source,
+    observedAt: input.observation.observedAt,
+    size,
+    oldestAgeMs: input.observation.oldestAgeMs.deadLettered,
+    disposition: dispositionForMeasurement(size),
+    capabilities: input.capabilities ?? [
+      {
+        action: 'inspect',
+        enabled: true,
+        reason: 'Read-only inventory is available.',
+      },
+      {
+        action: 'redrive',
+        enabled: false,
+        reason: 'The owning queue has not registered a fenced redrive path.',
+      },
+      {
+        action: 'discard',
+        enabled: false,
+        reason: 'Destructive discard is not a shared queue operation.',
+      },
+      {
+        action: 'mark_done',
+        enabled: false,
+        reason:
+          'Completion is source-owned; a global manual close would hide durable work.',
+      },
+    ],
+    ...(input.paths ? { paths: input.paths } : {}),
+  };
+}
+
+export function validateDlqInventory(inventory: DlqInventory): void {
+  if (inventory.contractVersion !== DLQ_CONTRACT_VERSION) {
+    throw new Error(
+      `Unsupported DLQ contract version: ${String(inventory.contractVersion)}`,
+    );
+  }
+  if (!inventory.queueId.trim()) throw new Error('DLQ queueId is required.');
+  if (!inventory.environment.trim())
+    throw new Error('DLQ environment is required.');
+  if (!inventory.source.trim()) throw new Error('DLQ source is required.');
+  if (!Number.isFinite(inventory.observedAt) || inventory.observedAt <= 0) {
+    throw new Error('DLQ observedAt must be a positive timestamp.');
+  }
+  for (const [label, metric] of [
+    ['size', inventory.size],
+    ['oldestAgeMs', inventory.oldestAgeMs],
+  ] as const) {
+    if (
+      (metric.kind === 'exact' || metric.kind === 'lower_bound') &&
+      (!Number.isFinite(metric.value) || metric.value < 0)
+    ) {
+      throw new Error(`DLQ ${label} must be a finite non-negative number.`);
+    }
+  }
+  if (inventory.disposition !== dispositionForMeasurement(inventory.size)) {
+    throw new Error('DLQ disposition does not match its size measurement.');
+  }
+  if (inventory.paths) validateDlqTransitionPaths(inventory.paths);
+}
+
+/** A plan-only adapter for queues whose owner has not exposed a mutation port. */
+export function readOnlyDlqAdapter(input: {
+  queueId: string;
+  source: string;
+  inspectInventory: (context: DlqAdapterContext) => Promise<DlqInventory>;
+}): DlqAdapter {
+  return {
+    id: `readonly:${input.queueId}`,
+    queueId: input.queueId,
+    source: input.source,
+    inspect: async (context) => {
+      const inventory = await input.inspectInventory(context);
+      validateDlqInventory(inventory);
+      return inventory;
+    },
+    plan: async (context, request) => {
+      const snapshot = await input.inspectInventory(context);
+      validateDlqInventory(snapshot);
+      return {
+        contractVersion: DLQ_CONTRACT_VERSION,
+        queueId: input.queueId,
+        environment: context.environment,
+        action: request.action,
+        itemIds: request.itemIds ?? [],
+        snapshot,
+        allowed: false,
+        requiresApproval: true,
+        reason:
+          'This queue is inspect-only until its owner registers a fenced mutation adapter.',
+      };
+    },
+    apply: async (_context, plan) => {
+      if (plan.allowed) {
+        throw new Error(
+          'Read-only DLQ adapter cannot apply an allowed mutation plan.',
+        );
+      }
+      return {
+        contractVersion: DLQ_CONTRACT_VERSION,
+        queueId: plan.queueId,
+        environment: plan.environment,
+        action: plan.action,
+        applied: [],
+        skipped: plan.itemIds.map((id) => ({
+          id,
+          reason: 'No mutation adapter is registered for this queue.',
+        })),
+        verificationRequired: false,
+      };
+    },
+  };
+}