@adcp/sdk 15.8.1 → 15.9.0

package/dist/lib/reporting/bigquery/index.mjs

@@ -2,6 +2,7 @@ import { createHash } from "crypto";
 import { promises as fs } from "fs";
 import { tmpdir } from "os";
 import * as path from "path";
+import { decodeReportingChangeCursorV1 } from "../ledger/change-feed.mjs";
 const REPORTING_WAREHOUSE_SINK_MIGRATION = `
 CREATE TABLE IF NOT EXISTS adcp_reporting_warehouse_sinks (
   sink_name TEXT PRIMARY KEY CHECK (sink_name ~ '^[A-Za-z0-9_.:-]{1,128}$'),
@@ -11,10 +12,15 @@ CREATE TABLE IF NOT EXISTS adcp_reporting_warehouse_sinks (
   planned_revisions JSONB,
   planned_rows_attempt INTEGER NOT NULL DEFAULT 0 CHECK (planned_rows_attempt >= 0),
   planned_revisions_attempt INTEGER NOT NULL DEFAULT 0 CHECK (planned_revisions_attempt >= 0),
+  reset_generation INTEGER NOT NULL DEFAULT 0 CHECK (reset_generation >= 0),
   updated_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
   CHECK ((planned_to_cursor IS NULL) = (planned_revisions IS NULL))
 );
+ALTER TABLE adcp_reporting_warehouse_sinks
+  ADD COLUMN IF NOT EXISTS reset_generation INTEGER NOT NULL DEFAULT 0 CHECK (reset_generation >= 0);
 `.trim();
+const MAX_LOAD_TIMEOUT = 6 * 36e5;
+let warnedLabelsIgnored = false;
 const PROJECT = /^[a-z][a-z0-9-]{4,61}[a-z0-9]$/;
 const DATASET_OR_TABLE = /^[A-Za-z_][A-Za-z0-9_]{0,1023}$/;
 const NAME = /^[A-Za-z0-9_.:-]{1,128}$/;
@@ -31,13 +37,20 @@ function createBigQueryReportingWarehouseSinkV1(options) {
     if (!DATASET_OR_TABLE.test(value)) throw new TypeError(`BigQuery ${label} is invalid`);
   }
   const loadTimeout = options.loadTimeoutMilliseconds ?? 6e5;
-  if (!Number.isSafeInteger(loadTimeout) || loadTimeout < 1e3 || loadTimeout > 6 * 36e5) {
+  if (!Number.isSafeInteger(loadTimeout) || loadTimeout < 1e3 || loadTimeout > MAX_LOAD_TIMEOUT) {
     throw new RangeError("loadTimeoutMilliseconds must be between 1 second and 6 hours");
   }
   const maxRevisions = options.maxRevisionsPerBatch ?? 200;
   if (!Number.isSafeInteger(maxRevisions) || maxRevisions < 1 || maxRevisions > 1e4) {
     throw new RangeError("maxRevisionsPerBatch must be between 1 and 10000");
   }
+  if (options.labels && Object.keys(options.labels).length > 0 && !warnedLabelsIgnored) {
+    warnedLabelsIgnored = true;
+    process.emitWarning(
+      "BigQuery warehouse sink option `labels` has no effect: BigQuery ignores labels inside a load job's configuration.load and the official client cannot set configuration.labels for local-file loads. Attribute cost through INFORMATION_SCHEMA.JOBS by destination table or the adcp_rr_ job ID prefix.",
+      { code: "ADCP_BIGQUERY_SINK_LABELS_IGNORED", type: "DeprecationWarning" }
+    );
+  }
   const tables = {
     projectId: options.projectId,
     datasetId: options.datasetId,
@@ -48,29 +61,55 @@ function createBigQueryReportingWarehouseSinkV1(options) {
     ...options.projectId ? { projectId: options.projectId } : {},
     ...options.location ? { location: options.location } : {}
   });
-  async function loadOnce(tableId, jobId, lines, signal) {
+  const matchesPlan = `WHERE sink_name = $1
+    AND committed_cursor IS NOT DISTINCT FROM $2
+    AND planned_from_cursor IS NOT DISTINCT FROM $2
+    AND planned_to_cursor = $3 AND planned_revisions = $4::jsonb
+    AND planned_rows_attempt = $5 AND planned_revisions_attempt = $6
+    AND reset_generation = $7`;
+  const stalePlan = () => new Error("Warehouse sink plan changed during an overlapping run; retry runOnce()");
+  const jobOptions = options.projectId || options.location ? {
+    ...options.projectId ? { projectId: options.projectId } : {},
+    ...options.location ? { location: options.location } : {}
+  } : void 0;
+  async function cancelLoad(jobId, signal) {
+    try {
+      const job = options.bigquery.job(jobId, jobOptions);
+      if (typeof job.cancel !== "function") return;
+      const cancel = job.cancel.bind(job);
+      await withinDeadline(cancel, Math.min(loadTimeout, 3e4), signal);
+    } catch (error) {
+      const code = error?.code;
+      if (code === 404 || signal?.aborted) return;
+      process.emitWarning(
+        `Cancelling BigQuery load job ${jobId} failed (${typeof code === "number" || typeof code === "string" ? code : "no status code"}); the job may still be running`,
+        { code: "ADCP_BIGQUERY_SINK_CANCEL_FAILED" }
+      );
+    }
+  }
+  async function loadOnce(tableId, jobId, lines, attempt, signal) {
+    const loadDeadline = Math.min(loadTimeout * 2 ** Math.min(attempt, 16), MAX_LOAD_TIMEOUT);
     signal?.throwIfAborted();
     const directory = await fs.mkdtemp(path.join(tmpdir(), "adcp-warehouse-"));
     const file = path.join(directory, `${jobId}.ndjson`);
     try {
-      await fs.writeFile(file, lines.length ? lines.join("\n") + "\n" : "");
+      await fs.writeFile(file, lines.length ? lines.join("\n") + "\n" : "", { mode: 384 });
       try {
         await withinDeadline(
           () => dataset.table(tableId).load(file, {
             jobId,
             sourceFormat: "NEWLINE_DELIMITED_JSON",
             writeDisposition: "WRITE_APPEND",
-            jobTimeoutMs: String(loadTimeout),
-            ...options.location ? { location: options.location } : {},
-            ...options.labels ? { labels: { ...options.labels } } : {}
+            ...options.location ? { location: options.location } : {}
           }),
-          loadTimeout,
+          loadDeadline,
           signal
         );
       } catch (error) {
+        if (isDeadlineExceeded(error)) await cancelLoad(jobId, signal);
         if (!isAlreadyExists(error)) throw error;
         const metadata = await withinDeadline(
-          () => options.bigquery.job(jobId, options.location ? { location: options.location } : void 0).getMetadata(),
+          () => options.bigquery.job(jobId, jobOptions).getMetadata(),
           loadTimeout,
           signal
         );
@@ -83,6 +122,40 @@ function createBigQueryReportingWarehouseSinkV1(options) {
   return {
     defaultTablesSql: reportingWarehouseDefaultTablesSqlV1(tables),
     currentRowsViewSql: reportingWarehouseCurrentRowsViewSqlV1(tables),
+    async reset(resetOptions = {}) {
+      const removeConsumer = options.store.removeFeedConsumer?.bind(options.store);
+      if (!removeConsumer) {
+        throw new TypeError("reset() needs a store with removeFeedConsumer (PostgresReportingLedgerStore has it)");
+      }
+      const cleared = await options.db.query(
+        `UPDATE adcp_reporting_warehouse_sinks
+            SET committed_cursor = NULL, planned_from_cursor = NULL, planned_to_cursor = NULL,
+                planned_revisions = NULL, planned_rows_attempt = 0, planned_revisions_attempt = 0,
+                reset_generation = reset_generation + 1, updated_at = clock_timestamp()
+          WHERE sink_name = $1 AND ($2::boolean OR planned_to_cursor IS NULL)
+          RETURNING sink_name`,
+        [options.name, resetOptions.discardRetainedPlan === true]
+      ).catch(missingMigration);
+      if (cleared.rows.length === 0) {
+        const exists = await options.db.query(`SELECT 1 FROM adcp_reporting_warehouse_sinks WHERE sink_name = $1`, [
+          options.name
+        ]);
+        if (exists.rows.length > 0) {
+          throw new Error(
+            "Warehouse sink has a retained batch plan whose load jobs may have succeeded; reconcile it against BigQuery, then call reset({ discardRetainedPlan: true })"
+          );
+        }
+      }
+      try {
+        await removeConsumer(options.name);
+      } catch (cause) {
+        throw new Error(
+          "Warehouse sink state was cleared but its feed consumer could not be unregistered; call reset() again before restarting workers",
+          { cause }
+        );
+      }
+      return { cleared: cleared.rows.length > 0 };
+    },
     async runOnce(runOptions = {}) {
       const signal = runOptions.signal;
       await options.db.query(
@@ -91,10 +164,20 @@ function createBigQueryReportingWarehouseSinkV1(options) {
       );
       const state = (await options.db.query(
         `SELECT committed_cursor, planned_from_cursor, planned_to_cursor, planned_revisions,
-                  planned_rows_attempt, planned_revisions_attempt
+                  planned_rows_attempt, planned_revisions_attempt, reset_generation
              FROM adcp_reporting_warehouse_sinks WHERE sink_name = $1`,
         [options.name]
-      )).rows[0];
+      ).catch(missingMigration)).rows[0];
+      if (state.planned_to_cursor !== null && state.planned_from_cursor !== state.committed_cursor) {
+        throw new Error(
+          "Warehouse sink has an inconsistent retained plan; reconcile the plan and BigQuery jobs before resuming"
+        );
+      }
+      if (options.account_id && state.planned_revisions?.some((planned) => planned.account_id !== options.account_id)) {
+        throw new Error(
+          "Warehouse sink has a retained plan for another account; this sink name is shared across feed scopes"
+        );
+      }
       let plan = state.planned_to_cursor && state.planned_revisions ? {
         from: state.planned_from_cursor,
         to: state.planned_to_cursor,
@@ -103,31 +186,74 @@ function createBigQueryReportingWarehouseSinkV1(options) {
         revisionsAttempt: state.planned_revisions_attempt
       } : void 0;
       if (!plan) {
-        const page = await options.store.changesAfter({
+        const position = {
           ...state.committed_cursor ? { cursor: state.committed_cursor } : {},
           ...options.account_id ? { account_id: options.account_id } : {},
-          kinds: ["revision"],
           limit: maxRevisions
-        });
-        if (page.records.length === 0) {
-          if (page.cursor !== state.committed_cursor) await commit(page.cursor);
+        };
+        let page;
+        let readCursor = position.cursor;
+        try {
+          page = await options.store.changesAfter({ ...position, kinds: ["revision"] });
+          if (page.records.length === 0) {
+            readCursor = page.cursor;
+            page = await options.store.changesAfter({ ...position, cursor: readCursor });
+          }
+        } catch (error) {
+          if (error?.code === "CURSOR_EXPIRED" && state.committed_cursor === null) {
+            const cursor = readCursor ?? error.cursor;
+            if (cursor !== void 0 && typeof cursor !== "string") throw error;
+            if (cursor !== void 0) {
+              try {
+                decodeReportingChangeCursorV1(cursor, position.account_id ?? null);
+              } catch {
+                throw error;
+              }
+              await options.db.query(
+                `UPDATE adcp_reporting_warehouse_sinks SET committed_cursor = $2, updated_at = clock_timestamp()
+                  WHERE sink_name = $1 AND committed_cursor IS NULL AND reset_generation = $3
+                    AND planned_from_cursor IS NULL AND planned_to_cursor IS NULL AND planned_revisions IS NULL`,
+                [options.name, cursor, state.reset_generation]
+              );
+            }
+          }
+          throw error;
+        }
+        if (page.records.length === 0 && page.cursor === state.committed_cursor) {
+          if (state.committed_cursor) {
+            await options.store.saveFeedConsumerCursor(options.name, state.committed_cursor, {
+              refreshUnchanged: false
+            });
+          }
           return { idle: true, revisions: 0, rows: 0, missing: [] };
         }
         plan = {
           from: state.committed_cursor,
           to: page.cursor,
-          revisions: page.records.map((record) => ({ id: record.record_id, account_id: record.account_id })),
+          revisions: page.records.filter((record) => record.kind === "revision").map((record) => ({ id: record.record_id, account_id: record.account_id })),
           rowsAttempt: 0,
           revisionsAttempt: 0
         };
-        await options.db.query(
+        const claimed = await options.db.query(
           `UPDATE adcp_reporting_warehouse_sinks
               SET planned_from_cursor = $2, planned_to_cursor = $3, planned_revisions = $4::jsonb,
                   planned_rows_attempt = 0, planned_revisions_attempt = 0, updated_at = clock_timestamp()
-            WHERE sink_name = $1`,
-          [options.name, plan.from, plan.to, JSON.stringify(plan.revisions)]
+            WHERE sink_name = $1 AND committed_cursor IS NOT DISTINCT FROM $2
+              AND planned_to_cursor IS NULL AND planned_revisions IS NULL AND reset_generation = $5
+            RETURNING sink_name`,
+          [options.name, plan.from, plan.to, JSON.stringify(plan.revisions), state.reset_generation]
         );
+        if (claimed.rows.length === 0) throw stalePlan();
       }
+      const planValues = [
+        options.name,
+        plan.from,
+        plan.to,
+        JSON.stringify(plan.revisions),
+        plan.rowsAttempt,
+        plan.revisionsAttempt,
+        state.reset_generation
+      ];
       const rowLines = [];
       const revisionLines = [];
       const missing = [];
@@ -181,7 +307,7 @@ function createBigQueryReportingWarehouseSinkV1(options) {
           })
         );
       }
-      const baseJobId = reportingWarehouseJobIdV1(options.name, plan.from, plan.to);
+      const baseJobId = reportingWarehouseJobIdV1(options.name, plan.from, plan.to, state.reset_generation);
       const suffix = (attempt) => attempt ? `_a${attempt}` : "";
       const steps = [
         { table: options.rowsTableId, kind: "rows", lines: rowLines, attempt: plan.rowsAttempt },
@@ -190,37 +316,50 @@ function createBigQueryReportingWarehouseSinkV1(options) {
       for (const step of steps) {
         if (!step.lines.length) continue;
         try {
-          await loadOnce(step.table, `${baseJobId}_${step.kind}${suffix(step.attempt)}`, [...step.lines], signal);
+          await loadOnce(
+            step.table,
+            `${baseJobId}_${step.kind}${suffix(step.attempt)}`,
+            [...step.lines],
+            step.attempt,
+            signal
+          );
         } catch (error) {
           if (isFinishedWithError(error)) {
             const column = step.kind === "rows" ? "planned_rows_attempt" : "planned_revisions_attempt";
             await options.db.query(
               `UPDATE adcp_reporting_warehouse_sinks SET ${column} = ${column} + 1,
-                      updated_at = clock_timestamp() WHERE sink_name = $1`,
-              [options.name]
+                      updated_at = clock_timestamp() ${matchesPlan}`,
+              planValues
             );
           }
           throw error;
         }
       }
-      await commit(plan.to);
-      return { idle: false, revisions: revisionLines.length, rows: rowLines.length, missing };
+      const committed = await options.db.query(
+        `UPDATE adcp_reporting_warehouse_sinks
+            SET committed_cursor = $3, planned_from_cursor = NULL, planned_to_cursor = NULL,
+                planned_revisions = NULL, planned_rows_attempt = 0, planned_revisions_attempt = 0,
+                updated_at = clock_timestamp()
+          ${matchesPlan} RETURNING sink_name`,
+        planValues
+      );
+      if (committed.rows.length === 0) throw stalePlan();
+      await options.store.saveFeedConsumerCursor(options.name, plan.to);
+      return { idle: plan.revisions.length === 0, revisions: revisionLines.length, rows: rowLines.length, missing };
     }
   };
-  async function commit(cursor) {
-    await options.db.query(
-      `UPDATE adcp_reporting_warehouse_sinks
-          SET committed_cursor = $2, planned_from_cursor = NULL, planned_to_cursor = NULL,
-              planned_revisions = NULL, planned_rows_attempt = 0, planned_revisions_attempt = 0,
-              updated_at = clock_timestamp()
-        WHERE sink_name = $1`,
-      [options.name, cursor]
+}
+function missingMigration(error) {
+  if (error?.code === "42703") {
+    throw new Error(
+      "The adcp_reporting_warehouse_sinks table is missing columns; apply REPORTING_WAREHOUSE_SINK_MIGRATION again (it is idempotent)",
+      { cause: error }
     );
-    await options.store.saveFeedConsumerCursor(options.name, cursor);
   }
+  throw error;
 }
-function reportingWarehouseJobIdV1(name, from, to) {
-  return `adcp_rr_${createHash("sha256").update(JSON.stringify([name, from, to])).digest("hex").slice(0, 40)}`;
+function reportingWarehouseJobIdV1(name, from, to, generation = 0) {
+  return `adcp_rr_${createHash("sha256").update(JSON.stringify(generation > 0 ? [name, from, to, generation] : [name, from, to])).digest("hex").slice(0, 40)}`;
 }
 function qualified(tables, table) {
   return `\`${tables.projectId ? `${tables.projectId}.` : ""}${tables.datasetId}.${table}\``;
@@ -299,10 +438,11 @@ async function withinDeadline(operation, milliseconds, signal) {
     return await Promise.race([
       operation(),
       new Promise((_, reject) => {
-        timer = setTimeout(
-          () => reject(new Error("BigQuery call exceeded its deadline; the batch will be retried")),
-          milliseconds
-        );
+        timer = setTimeout(() => {
+          const error = new Error("BigQuery call exceeded its deadline; the batch will be retried");
+          Object.defineProperty(error, "adcpDeadlineExceeded", { value: true });
+          reject(error);
+        }, milliseconds);
         if (signal) {
           onAbort = () => reject(signal.reason ?? new Error("aborted"));
           signal.addEventListener("abort", onAbort, { once: true });
@@ -314,6 +454,9 @@ async function withinDeadline(operation, milliseconds, signal) {
     if (signal && onAbort) signal.removeEventListener("abort", onAbort);
   }
 }
+function isDeadlineExceeded(error) {
+  return error?.adcpDeadlineExceeded === true;
+}
 function isAlreadyExists(error) {
   const record = error;
   return record?.code === 409 || !!record?.errors?.some((entry) => entry.reason === "duplicate");

package/dist/lib/reporting/ledger/change-feed.d.mts

@@ -7,7 +7,9 @@
  * adjustment and retirement in the same transaction as the record, taking the
  * sequence value only after the account lock, so per-account sequence order is
  * commit order. Deployment-wide readers order by `(xid, seq)` and stop below
- * the reading snapshot's `xmin`, so a slow commit is never skipped.
+ * the reading snapshot's `xmin`, so a slow commit is never skipped. Account
+ * readers order by `seq` and end the page before the first change at or above
+ * that `xmin`. Use exactly one writer SDK per ledger database.
  */
 export declare const REPORTING_LEDGER_CHANGES_MIGRATION: string;
 export type ReportingChangeKindV1 = 'obligation' | 'revision' | 'adjustment' | 'retirement';
@@ -35,7 +37,12 @@ export declare function encodeReportingChangeCursorV1(cursor: ChangeCursorV1): s
 export declare function decodeReportingChangeCursorV1(value: string, account: string | null): ChangeCursorV1;
 /** Thrown when a change cursor is older than the retained change history. */
 export declare class ReportingChangeCursorExpiredError extends Error {
+    readonly cursor?: string | undefined;
     readonly code: "CURSOR_EXPIRED";
-    constructor();
+    /**
+     * Original feed position, when available, so a cold-start consumer can retain its recovery
+     * boundary. It encodes the feed's account scope: do not serialize it to other tenants.
+     */
+    constructor(cursor?: string | undefined);
 }
 export {};

package/dist/lib/reporting/ledger/change-feed.d.ts

@@ -7,7 +7,9 @@
  * adjustment and retirement in the same transaction as the record, taking the
  * sequence value only after the account lock, so per-account sequence order is
  * commit order. Deployment-wide readers order by `(xid, seq)` and stop below
- * the reading snapshot's `xmin`, so a slow commit is never skipped.
+ * the reading snapshot's `xmin`, so a slow commit is never skipped. Account
+ * readers order by `seq` and end the page before the first change at or above
+ * that `xmin`. Use exactly one writer SDK per ledger database.
  */
 export declare const REPORTING_LEDGER_CHANGES_MIGRATION: string;
 export type ReportingChangeKindV1 = 'obligation' | 'revision' | 'adjustment' | 'retirement';
@@ -35,7 +37,12 @@ export declare function encodeReportingChangeCursorV1(cursor: ChangeCursorV1): s
 export declare function decodeReportingChangeCursorV1(value: string, account: string | null): ChangeCursorV1;
 /** Thrown when a change cursor is older than the retained change history. */
 export declare class ReportingChangeCursorExpiredError extends Error {
+    readonly cursor?: string | undefined;
     readonly code: "CURSOR_EXPIRED";
-    constructor();
+    /**
+     * Original feed position, when available, so a cold-start consumer can retain its recovery
+     * boundary. It encodes the feed's account scope: do not serialize it to other tenants.
+     */
+    constructor(cursor?: string | undefined);
 }
 export {};

package/dist/lib/reporting/ledger/change-feed.js

@@ -86,11 +86,17 @@ function decodeReportingChangeCursorV1(value, account) {
   return cursor;
 }
 class ReportingChangeCursorExpiredError extends Error {
-  code = "CURSOR_EXPIRED";
-  constructor() {
+  /**
+   * Original feed position, when available, so a cold-start consumer can retain its recovery
+   * boundary. It encodes the feed's account scope: do not serialize it to other tenants.
+   */
+  constructor(cursor) {
     super("Reporting change cursor is older than the retained change history; resynchronize from current revisions");
+    this.cursor = cursor;
     this.name = "ReportingChangeCursorExpiredError";
   }
+  cursor;
+  code = "CURSOR_EXPIRED";
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/lib/reporting/ledger/change-feed.mjs

@@ -60,11 +60,17 @@ function decodeReportingChangeCursorV1(value, account) {
   return cursor;
 }
 class ReportingChangeCursorExpiredError extends Error {
-  code = "CURSOR_EXPIRED";
-  constructor() {
+  /**
+   * Original feed position, when available, so a cold-start consumer can retain its recovery
+   * boundary. It encodes the feed's account scope: do not serialize it to other tenants.
+   */
+  constructor(cursor) {
     super("Reporting change cursor is older than the retained change history; resynchronize from current revisions");
+    this.cursor = cursor;
     this.name = "ReportingChangeCursorExpiredError";
   }
+  cursor;
+  code = "CURSOR_EXPIRED";
 }
 export {
   REPORTING_LEDGER_CHANGES_MIGRATION,

package/dist/lib/reporting/ledger/handler.js

@@ -157,7 +157,7 @@ function createReportingStatusHandler(store, options) {
           page.snapshot.ledgerAsOf,
           (0, import_coverage.reportingLedgerScopeClosed)(query, page.snapshot.ledgerAsOf, ledgerCoverage.complete)
         );
-        const persistedIssues = projection.health === "delayed" || projection.health === "action_required" ? page.snapshot.issues.filter(
+        const persistedIssues = page.snapshot.issues.filter(
           (issue) => issue.reporting_obligation_id === obligation.reporting_obligation_id && !issue.resolvedAt && // A CONSUMER_STATUS_MISMATCH is caller-scoped, but the issue
           // store is keyed by obligation alone and carries no consumer
           // dimension. Republishing a persisted one would hand every
@@ -168,11 +168,17 @@ function createReportingStatusHandler(store, options) {
           // contract forbids. This projection recomputes the mismatch
           // from the caller's current leaf on every read, so the
           // persisted copy is redundant as well as unsafe.
-          issue.code !== "CONSUMER_STATUS_MISMATCH" && // Retiring an issue removes it from the projection rather
+          issue.code !== "CONSUMER_STATUS_MISMATCH" && (projection.health === "delayed" || projection.health === "action_required" || issue.code === "REVISION_UNREADABLE") && // Retiring an issue removes it from the projection rather
           // than publishing it at a terminal state, which is what lets
           // a reader treat a nonempty `issues[]` as degradation.
           issue.issueState !== "resolved" && issue.issueState !== "waived"
-        ) : [];
+        );
+        const persistedHealth = (0, import_health.projectReportingUnreadableRevisionHealthV1)(
+          obligation,
+          revisions,
+          page.snapshot.issues,
+          projection.health
+        );
         const consumerStatusHistory = (page.snapshot.consumerStatuses ?? []).filter(
           (value) => consumerStatusMatchesObligation(value, obligation)
         );
@@ -182,7 +188,7 @@ function createReportingStatusHandler(store, options) {
           obligation,
           currentConsumerStatus,
           revisions,
-          projection.health,
+          persistedHealth,
           page.snapshot.ledgerAsOf,
           consumerMismatchEscalation
         );
@@ -191,6 +197,7 @@ function createReportingStatusHandler(store, options) {
         (0, import_instant.compareReportingInstants)(page.snapshot.ledgerAsOf, obligation.recoveryDeadlineAt) > 0;
         const baseProjection = {
           ...projection,
+          health: persistedHealth,
           issues: uniqueIssues([...persistedIssues, ...projection.issues, ...mismatch ? [mismatch.issue] : []])
         };
         const managed = projectManagedDelivery({
@@ -404,6 +411,9 @@ function createReportingStatusHandler(store, options) {
         ),
         issues: issues.map(wireIssue)
       };
+    } catch (error) {
+      if (error instanceof import_health.ReportingLedgerIssueIntegrityError) return operationalUnavailable(view);
+      throw error;
     } finally {
       releaseReadSlot();
     }
@@ -813,6 +823,7 @@ function wireIssue(issue) {
     ...issue.issueState === "open" || issue.issueState === "acknowledged" ? { issue_state: issue.issueState } : {},
     ...issue.externalRef ? { external_ref: issue.externalRef } : {},
     ...issue.reporting_status_id ? { reporting_status_id: issue.reporting_status_id } : {},
+    ...issue.reporting_revision_id ? { reporting_revision_id: issue.reporting_revision_id } : {},
     ...issue.reporting_obligation_id === "scope" ? {} : { reporting_obligation_id: issue.reporting_obligation_id }
   };
 }

package/dist/lib/reporting/ledger/handler.mjs

@@ -15,7 +15,9 @@ import {
   assertReportingConsumerMismatchEscalation,
   reportingEffectiveConsumerMismatchEscalationV1,
   projectReportingConsumerStatusMismatchV1,
-  projectReportingObligationHealthV1
+  projectReportingObligationHealthV1,
+  projectReportingUnreadableRevisionHealthV1,
+  ReportingLedgerIssueIntegrityError
 } from "./health.mjs";
 import { compareReportingInstants } from "./instant.mjs";
 import { getRevisionMetadataFromStore, readRevisionRowsFromStore } from "./revision-metadata.mjs";
@@ -140,7 +142,7 @@ function createReportingStatusHandler(store, options) {
           page.snapshot.ledgerAsOf,
           reportingLedgerScopeClosed(query, page.snapshot.ledgerAsOf, ledgerCoverage.complete)
         );
-        const persistedIssues = projection.health === "delayed" || projection.health === "action_required" ? page.snapshot.issues.filter(
+        const persistedIssues = page.snapshot.issues.filter(
           (issue) => issue.reporting_obligation_id === obligation.reporting_obligation_id && !issue.resolvedAt && // A CONSUMER_STATUS_MISMATCH is caller-scoped, but the issue
           // store is keyed by obligation alone and carries no consumer
           // dimension. Republishing a persisted one would hand every
@@ -151,11 +153,17 @@ function createReportingStatusHandler(store, options) {
           // contract forbids. This projection recomputes the mismatch
           // from the caller's current leaf on every read, so the
           // persisted copy is redundant as well as unsafe.
-          issue.code !== "CONSUMER_STATUS_MISMATCH" && // Retiring an issue removes it from the projection rather
+          issue.code !== "CONSUMER_STATUS_MISMATCH" && (projection.health === "delayed" || projection.health === "action_required" || issue.code === "REVISION_UNREADABLE") && // Retiring an issue removes it from the projection rather
           // than publishing it at a terminal state, which is what lets
           // a reader treat a nonempty `issues[]` as degradation.
           issue.issueState !== "resolved" && issue.issueState !== "waived"
-        ) : [];
+        );
+        const persistedHealth = projectReportingUnreadableRevisionHealthV1(
+          obligation,
+          revisions,
+          page.snapshot.issues,
+          projection.health
+        );
         const consumerStatusHistory = (page.snapshot.consumerStatuses ?? []).filter(
           (value) => consumerStatusMatchesObligation(value, obligation)
         );
@@ -165,7 +173,7 @@ function createReportingStatusHandler(store, options) {
           obligation,
           currentConsumerStatus,
           revisions,
-          projection.health,
+          persistedHealth,
           page.snapshot.ledgerAsOf,
           consumerMismatchEscalation
         );
@@ -174,6 +182,7 @@ function createReportingStatusHandler(store, options) {
         compareReportingInstants(page.snapshot.ledgerAsOf, obligation.recoveryDeadlineAt) > 0;
         const baseProjection = {
           ...projection,
+          health: persistedHealth,
           issues: uniqueIssues([...persistedIssues, ...projection.issues, ...mismatch ? [mismatch.issue] : []])
         };
         const managed = projectManagedDelivery({
@@ -387,6 +396,9 @@ function createReportingStatusHandler(store, options) {
         ),
         issues: issues.map(wireIssue)
       };
+    } catch (error) {
+      if (error instanceof ReportingLedgerIssueIntegrityError) return operationalUnavailable(view);
+      throw error;
     } finally {
       releaseReadSlot();
     }
@@ -796,6 +808,7 @@ function wireIssue(issue) {
     ...issue.issueState === "open" || issue.issueState === "acknowledged" ? { issue_state: issue.issueState } : {},
     ...issue.externalRef ? { external_ref: issue.externalRef } : {},
     ...issue.reporting_status_id ? { reporting_status_id: issue.reporting_status_id } : {},
+    ...issue.reporting_revision_id ? { reporting_revision_id: issue.reporting_revision_id } : {},
     ...issue.reporting_obligation_id === "scope" ? {} : { reporting_obligation_id: issue.reporting_obligation_id }
   };
 }

package/dist/lib/reporting/ledger/health.d.mts

@@ -5,6 +5,12 @@ export interface ReportingObligationHealthProjectionV1 {
     issues: ReportingLedgerIssueV1[];
     satisfied: boolean;
 }
+/** Invalid caller-scoped issue data cannot be treated as a completed report. */
+export declare class ReportingLedgerIssueIntegrityError extends Error {
+    constructor();
+}
+/** Shared by status projection and snapshot paging, before health filters run. */
+export declare function projectReportingUnreadableRevisionHealthV1(obligation: Pick<ReportingLedgerObligationV1, 'reporting_obligation_id'>, revisions: readonly Pick<ReportingLedgerRevisionSnapshotV1, 'reporting_revision_id' | 'reporting_obligation_id'>[], issues: readonly ReportingLedgerIssueV1[], health: ReportingHealthV1): ReportingHealthV1;
 /**
  * The complete set of facts needed to project Core reporting health.
  *

package/dist/lib/reporting/ledger/health.d.ts

@@ -5,6 +5,12 @@ export interface ReportingObligationHealthProjectionV1 {
     issues: ReportingLedgerIssueV1[];
     satisfied: boolean;
 }
+/** Invalid caller-scoped issue data cannot be treated as a completed report. */
+export declare class ReportingLedgerIssueIntegrityError extends Error {
+    constructor();
+}
+/** Shared by status projection and snapshot paging, before health filters run. */
+export declare function projectReportingUnreadableRevisionHealthV1(obligation: Pick<ReportingLedgerObligationV1, 'reporting_obligation_id'>, revisions: readonly Pick<ReportingLedgerRevisionSnapshotV1, 'reporting_revision_id' | 'reporting_obligation_id'>[], issues: readonly ReportingLedgerIssueV1[], health: ReportingHealthV1): ReportingHealthV1;
 /**
  * The complete set of facts needed to project Core reporting health.
  *