@adcp/sdk 15.5.0 → 15.6.0

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

@@ -0,0 +1,341 @@
+import { createHash } from "crypto";
+import { promises as fs } from "fs";
+import { tmpdir } from "os";
+import * as path from "path";
+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}$'),
+  committed_cursor TEXT,
+  planned_from_cursor TEXT,
+  planned_to_cursor TEXT,
+  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),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  CHECK ((planned_to_cursor IS NULL) = (planned_revisions IS NULL))
+);
+`.trim();
+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}$/;
+function createBigQueryReportingWarehouseSinkV1(options) {
+  if (!NAME.test(options.name)) throw new TypeError("Warehouse sink name must be a bounded non-secret identifier");
+  if (options.projectId !== void 0 && !PROJECT.test(options.projectId)) {
+    throw new TypeError("BigQuery projectId is invalid");
+  }
+  for (const [label, value] of [
+    ["datasetId", options.datasetId],
+    ["rowsTableId", options.rowsTableId],
+    ["revisionsTableId", options.revisionsTableId]
+  ]) {
+    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) {
+    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");
+  }
+  const tables = {
+    projectId: options.projectId,
+    datasetId: options.datasetId,
+    rowsTableId: options.rowsTableId,
+    revisionsTableId: options.revisionsTableId
+  };
+  const dataset = options.bigquery.dataset(options.datasetId, {
+    ...options.projectId ? { projectId: options.projectId } : {},
+    ...options.location ? { location: options.location } : {}
+  });
+  async function loadOnce(tableId, jobId, lines, signal) {
+    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" : "");
+      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 } } : {}
+          }),
+          loadTimeout,
+          signal
+        );
+      } catch (error) {
+        if (!isAlreadyExists(error)) throw error;
+        const metadata = await withinDeadline(
+          () => options.bigquery.job(jobId, options.location ? { location: options.location } : void 0).getMetadata(),
+          loadTimeout,
+          signal
+        );
+        assertJobSucceeded(metadata);
+      }
+    } finally {
+      await fs.rm(directory, { recursive: true, force: true });
+    }
+  }
+  return {
+    defaultTablesSql: reportingWarehouseDefaultTablesSqlV1(tables),
+    currentRowsViewSql: reportingWarehouseCurrentRowsViewSqlV1(tables),
+    async runOnce(runOptions = {}) {
+      const signal = runOptions.signal;
+      await options.db.query(
+        `INSERT INTO adcp_reporting_warehouse_sinks (sink_name) VALUES ($1) ON CONFLICT DO NOTHING`,
+        [options.name]
+      );
+      const state = (await options.db.query(
+        `SELECT committed_cursor, planned_from_cursor, planned_to_cursor, planned_revisions,
+                  planned_rows_attempt, planned_revisions_attempt
+             FROM adcp_reporting_warehouse_sinks WHERE sink_name = $1`,
+        [options.name]
+      )).rows[0];
+      let plan = state.planned_to_cursor && state.planned_revisions ? {
+        from: state.planned_from_cursor,
+        to: state.planned_to_cursor,
+        revisions: state.planned_revisions,
+        rowsAttempt: state.planned_rows_attempt,
+        revisionsAttempt: state.planned_revisions_attempt
+      } : void 0;
+      if (!plan) {
+        const page = await options.store.changesAfter({
+          ...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);
+          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 })),
+          rowsAttempt: 0,
+          revisionsAttempt: 0
+        };
+        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)]
+        );
+      }
+      const rowLines = [];
+      const revisionLines = [];
+      const missing = [];
+      for (const planned of plan.revisions) {
+        signal?.throwIfAborted();
+        const revision = await options.store.getRevisionMetadata(planned.id, planned.account_id);
+        if (!revision) {
+          missing.push(planned.id);
+          continue;
+        }
+        const periodDate = sourceLocalDate(
+          revision.wireRevision.period?.start,
+          revision.wireRevision.period?.source_timezone
+        );
+        const base = {
+          reporting_revision_id: revision.reporting_revision_id,
+          reporting_obligation_id: revision.reporting_obligation_id,
+          account_id: planned.account_id,
+          revision_number: revision.revisionNumber,
+          finality: revision.finality,
+          period_date: periodDate
+        };
+        for (let offset = 0; offset < revision.binding.rowCount; ) {
+          const page = await options.store.readRevisionRows({
+            reporting_revision_id: revision.reporting_revision_id,
+            account_id: planned.account_id,
+            offset,
+            limit: 5e3,
+            ...signal ? { signal } : {}
+          });
+          if (!page || page.rows.length === 0) throw new Error("Reporting revision rows ended early");
+          page.rows.forEach((row, index) => {
+            const ordinal = offset + index;
+            const mapped = options.mapRow ? options.mapRow(row, { revision, ordinal }) : { row };
+            rowLines.push(JSON.stringify({ ...mapped, ...base, ordinal }));
+          });
+          offset += page.rows.length;
+        }
+        revisionLines.push(
+          JSON.stringify({
+            ...base,
+            supersedes_reporting_revision_id: revision.supersedes_reporting_revision_id ?? null,
+            period_start: revision.wireRevision.period?.start ?? null,
+            period_end: revision.wireRevision.period?.end ?? null,
+            source_timezone: revision.wireRevision.period?.source_timezone ?? null,
+            observed_at: revision.observedAt,
+            data_through: revision.dataThrough,
+            revision_content_sha256: revision.binding.sha256,
+            row_count: revision.binding.rowCount,
+            control_totals: revision.wireRevision.control_totals ?? []
+          })
+        );
+      }
+      const baseJobId = reportingWarehouseJobIdV1(options.name, plan.from, plan.to);
+      const suffix = (attempt) => attempt ? `_a${attempt}` : "";
+      const steps = [
+        { table: options.rowsTableId, kind: "rows", lines: rowLines, attempt: plan.rowsAttempt },
+        { table: options.revisionsTableId, kind: "revs", lines: revisionLines, attempt: plan.revisionsAttempt }
+      ];
+      for (const step of steps) {
+        if (!step.lines.length) continue;
+        try {
+          await loadOnce(step.table, `${baseJobId}_${step.kind}${suffix(step.attempt)}`, [...step.lines], 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]
+            );
+          }
+          throw error;
+        }
+      }
+      await commit(plan.to);
+      return { idle: false, 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]
+    );
+    await options.store.saveFeedConsumerCursor(options.name, cursor);
+  }
+}
+function reportingWarehouseJobIdV1(name, from, to) {
+  return `adcp_rr_${createHash("sha256").update(JSON.stringify([name, from, to])).digest("hex").slice(0, 40)}`;
+}
+function qualified(tables, table) {
+  return `\`${tables.projectId ? `${tables.projectId}.` : ""}${tables.datasetId}.${table}\``;
+}
+function reportingWarehouseDefaultTablesSqlV1(tables) {
+  return `
+CREATE TABLE IF NOT EXISTS ${qualified(tables, tables.rowsTableId)} (
+  reporting_revision_id STRING NOT NULL,
+  reporting_obligation_id STRING NOT NULL,
+  account_id STRING NOT NULL,
+  revision_number INT64 NOT NULL,
+  finality STRING NOT NULL,
+  period_date DATE,
+  ordinal INT64 NOT NULL,
+  row JSON
+)
+PARTITION BY period_date
+CLUSTER BY account_id, reporting_revision_id;
+
+CREATE TABLE IF NOT EXISTS ${qualified(tables, tables.revisionsTableId)} (
+  reporting_revision_id STRING NOT NULL,
+  reporting_obligation_id STRING NOT NULL,
+  account_id STRING NOT NULL,
+  revision_number INT64 NOT NULL,
+  finality STRING NOT NULL,
+  period_date DATE,
+  supersedes_reporting_revision_id STRING,
+  period_start TIMESTAMP,
+  period_end TIMESTAMP,
+  source_timezone STRING,
+  observed_at TIMESTAMP,
+  data_through TIMESTAMP,
+  revision_content_sha256 STRING NOT NULL,
+  row_count INT64 NOT NULL,
+  control_totals JSON
+)
+PARTITION BY period_date
+CLUSTER BY account_id, reporting_obligation_id;`.trim();
+}
+function reportingWarehouseCurrentRowsViewSqlV1(tables) {
+  const view = tables.viewId ?? "current_rows";
+  if (!DATASET_OR_TABLE.test(view)) throw new TypeError("BigQuery viewId is invalid");
+  return `
+CREATE OR REPLACE VIEW ${qualified(tables, view)} AS
+SELECT row_data.*
+  FROM ${qualified(tables, tables.rowsTableId)} AS row_data
+  JOIN (
+    SELECT reporting_obligation_id,
+           ARRAY_AGG(reporting_revision_id ORDER BY revision_number DESC LIMIT 1)[OFFSET(0)] AS reporting_revision_id
+      FROM ${qualified(tables, tables.revisionsTableId)}
+     GROUP BY reporting_obligation_id
+  ) AS current_revision
+ USING (reporting_obligation_id, reporting_revision_id);`.trim();
+}
+function sourceLocalDate(start, timeZone) {
+  if (!start) return null;
+  const instant = new Date(start);
+  if (Number.isNaN(instant.getTime())) return null;
+  try {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+      timeZone: timeZone ?? "UTC",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit"
+    }).format(instant);
+    return parts;
+  } catch {
+    return instant.toISOString().slice(0, 10);
+  }
+}
+async function withinDeadline(operation, milliseconds, signal) {
+  signal?.throwIfAborted();
+  let timer;
+  let onAbort;
+  try {
+    return await Promise.race([
+      operation(),
+      new Promise((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error("BigQuery call exceeded its deadline; the batch will be retried")),
+          milliseconds
+        );
+        if (signal) {
+          onAbort = () => reject(signal.reason ?? new Error("aborted"));
+          signal.addEventListener("abort", onAbort, { once: true });
+        }
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}
+function isAlreadyExists(error) {
+  const record = error;
+  return record?.code === 409 || !!record?.errors?.some((entry) => entry.reason === "duplicate");
+}
+function isFinishedWithError(error) {
+  return error?.adcpJobFailed === true;
+}
+function assertJobSucceeded(metadata) {
+  const record = Array.isArray(metadata) ? metadata[0] : metadata;
+  if (record?.status?.state !== "DONE") {
+    throw new Error("A BigQuery load job for this batch is still running; retry later");
+  }
+  if (record.status.errorResult) {
+    const failure = new Error("A BigQuery load job for this batch failed; it will be retried as a new attempt");
+    Object.defineProperty(failure, "adcpJobFailed", { value: true });
+    throw failure;
+  }
+}
+export {
+  REPORTING_WAREHOUSE_SINK_MIGRATION,
+  createBigQueryReportingWarehouseSinkV1,
+  reportingWarehouseCurrentRowsViewSqlV1,
+  reportingWarehouseDefaultTablesSqlV1,
+  reportingWarehouseJobIdV1
+};

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

@@ -280,10 +280,20 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
      *
      * Planners skip retired periods, and `ledger_retained_from` advances past
      * them because their obligations no longer exist.
+     *
+     * When the change-feed tables exist, a period that is not yet retiring is
+     * also held while any live registered feed consumer (updated within
+     * `maxFeedHoldDays`, default 7) has not passed that period's change rows in
+     * the consumer's own feed order, the same rule `pruneChanges` applies. A
+     * held period is simply not a candidate this pass. A consumer that stays
+     * silent past `maxFeedHoldDays` stops holding, so retention is never
+     * blocked forever; it then falls behind retention and a sink sees the
+     * retired revisions as missing.
      */
     retireExpiredPeriods(input: {
         statusRetentionDays: number;
         recordRetentionDays?: number;
+        maxFeedHoldDays?: number;
         limit?: number;
         account_id?: string;
         signal?: AbortSignal;

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

@@ -280,10 +280,20 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
      *
      * Planners skip retired periods, and `ledger_retained_from` advances past
      * them because their obligations no longer exist.
+     *
+     * When the change-feed tables exist, a period that is not yet retiring is
+     * also held while any live registered feed consumer (updated within
+     * `maxFeedHoldDays`, default 7) has not passed that period's change rows in
+     * the consumer's own feed order, the same rule `pruneChanges` applies. A
+     * held period is simply not a candidate this pass. A consumer that stays
+     * silent past `maxFeedHoldDays` stops holding, so retention is never
+     * blocked forever; it then falls behind retention and a sink sees the
+     * retired revisions as missing.
      */
     retireExpiredPeriods(input: {
         statusRetentionDays: number;
         recordRetentionDays?: number;
+        maxFeedHoldDays?: number;
         limit?: number;
         account_id?: string;
         signal?: AbortSignal;

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

@@ -1289,6 +1289,15 @@ ${managedDueArm}       )
    *
    * Planners skip retired periods, and `ledger_retained_from` advances past
    * them because their obligations no longer exist.
+   *
+   * When the change-feed tables exist, a period that is not yet retiring is
+   * also held while any live registered feed consumer (updated within
+   * `maxFeedHoldDays`, default 7) has not passed that period's change rows in
+   * the consumer's own feed order, the same rule `pruneChanges` applies. A
+   * held period is simply not a candidate this pass. A consumer that stays
+   * silent past `maxFeedHoldDays` stops holding, so retention is never
+   * blocked forever; it then falls behind retention and a sink sees the
+   * retired revisions as missing.
    */
   async retireExpiredPeriods(input) {
     if (!Number.isSafeInteger(input.statusRetentionDays) || input.statusRetentionDays < 1) {
@@ -1300,8 +1309,18 @@ ${managedDueArm}       )
     }
     const limit = input.limit ?? 100;
     positiveInteger(limit, "limit");
+    const holdDays = input.maxFeedHoldDays ?? 7;
+    positiveInteger(holdDays, "maxFeedHoldDays");
     const tables = await this.optionalTables();
     const materializationHold = tables.has("adcp_reporting_materializations") ? `AND NOT EXISTS (SELECT 1 FROM adcp_reporting_materializations hold WHERE hold.obligation_id = obligation.obligation_id)` : "";
+    const feedHold = tables.has("adcp_reporting_changes") && tables.has("adcp_reporting_feed_consumers") ? `AND NOT EXISTS (
+                  SELECT 1 FROM adcp_reporting_changes change
+                    JOIN adcp_reporting_feed_consumers consumer
+                      ON consumer.updated_at > clock_timestamp() - ($4::integer * INTERVAL '1 day')
+                   WHERE change.obligation_id = obligation.obligation_id
+                     AND ((consumer.account_id IS NULL
+                           AND (change.xid, change.seq) > (consumer.cursor_xid, consumer.cursor_seq))
+                       OR (consumer.account_id = change.account_id AND change.seq > consumer.cursor_seq)))` : "";
     const candidates = await this.query(
       `SELECT obligation_id, account_id FROM (
          SELECT tombstone.obligation_id, tombstone.account_id, 0 AS resume, tombstone.period_end
@@ -1322,10 +1341,11 @@ ${managedDueArm}       )
             AND NOT EXISTS (SELECT 1 FROM adcp_reporting_obligation_tombstones tombstone
                              WHERE tombstone.obligation_id = obligation.obligation_id)
             ${materializationHold}
+            ${feedHold}
        ) candidate
        ORDER BY resume, period_end, obligation_id
        LIMIT $1`,
-      [limit, input.account_id ?? null, recordDays]
+      feedHold ? [limit, input.account_id ?? null, recordDays, holdDays] : [limit, input.account_id ?? null, recordDays]
     );
     let retired = 0;
     const failed = [];
@@ -1497,7 +1517,8 @@ ${managedDueArm}       )
       `SELECT table_name AS name FROM information_schema.tables
         WHERE table_schema = current_schema()
           AND table_name IN ('adcp_reporting_row_sets', 'adcp_reporting_row_write_intents',
-                             'adcp_reporting_materializations')`
+                             'adcp_reporting_materializations', 'adcp_reporting_changes',
+                             'adcp_reporting_feed_consumers')`
     );
     return new Set(result.rows.map((row) => row.name));
   }

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

@@ -1288,6 +1288,15 @@ ${managedDueArm}       )
    *
    * Planners skip retired periods, and `ledger_retained_from` advances past
    * them because their obligations no longer exist.
+   *
+   * When the change-feed tables exist, a period that is not yet retiring is
+   * also held while any live registered feed consumer (updated within
+   * `maxFeedHoldDays`, default 7) has not passed that period's change rows in
+   * the consumer's own feed order, the same rule `pruneChanges` applies. A
+   * held period is simply not a candidate this pass. A consumer that stays
+   * silent past `maxFeedHoldDays` stops holding, so retention is never
+   * blocked forever; it then falls behind retention and a sink sees the
+   * retired revisions as missing.
    */
   async retireExpiredPeriods(input) {
     if (!Number.isSafeInteger(input.statusRetentionDays) || input.statusRetentionDays < 1) {
@@ -1299,8 +1308,18 @@ ${managedDueArm}       )
     }
     const limit = input.limit ?? 100;
     positiveInteger(limit, "limit");
+    const holdDays = input.maxFeedHoldDays ?? 7;
+    positiveInteger(holdDays, "maxFeedHoldDays");
     const tables = await this.optionalTables();
     const materializationHold = tables.has("adcp_reporting_materializations") ? `AND NOT EXISTS (SELECT 1 FROM adcp_reporting_materializations hold WHERE hold.obligation_id = obligation.obligation_id)` : "";
+    const feedHold = tables.has("adcp_reporting_changes") && tables.has("adcp_reporting_feed_consumers") ? `AND NOT EXISTS (
+                  SELECT 1 FROM adcp_reporting_changes change
+                    JOIN adcp_reporting_feed_consumers consumer
+                      ON consumer.updated_at > clock_timestamp() - ($4::integer * INTERVAL '1 day')
+                   WHERE change.obligation_id = obligation.obligation_id
+                     AND ((consumer.account_id IS NULL
+                           AND (change.xid, change.seq) > (consumer.cursor_xid, consumer.cursor_seq))
+                       OR (consumer.account_id = change.account_id AND change.seq > consumer.cursor_seq)))` : "";
     const candidates = await this.query(
       `SELECT obligation_id, account_id FROM (
          SELECT tombstone.obligation_id, tombstone.account_id, 0 AS resume, tombstone.period_end
@@ -1321,10 +1340,11 @@ ${managedDueArm}       )
             AND NOT EXISTS (SELECT 1 FROM adcp_reporting_obligation_tombstones tombstone
                              WHERE tombstone.obligation_id = obligation.obligation_id)
             ${materializationHold}
+            ${feedHold}
        ) candidate
        ORDER BY resume, period_end, obligation_id
        LIMIT $1`,
-      [limit, input.account_id ?? null, recordDays]
+      feedHold ? [limit, input.account_id ?? null, recordDays, holdDays] : [limit, input.account_id ?? null, recordDays]
     );
     let retired = 0;
     const failed = [];
@@ -1496,7 +1516,8 @@ ${managedDueArm}       )
       `SELECT table_name AS name FROM information_schema.tables
         WHERE table_schema = current_schema()
           AND table_name IN ('adcp_reporting_row_sets', 'adcp_reporting_row_write_intents',
-                             'adcp_reporting_materializations')`
+                             'adcp_reporting_materializations', 'adcp_reporting_changes',
+                             'adcp_reporting_feed_consumers')`
     );
     return new Set(result.rows.map((row) => row.name));
   }

package/dist/lib/reporting/ledger/row-storage-object.js

@@ -127,10 +127,8 @@ function createFilesystemReportingRowObjectProviderV1(options) {
     }
     return target;
   };
-  const version = async (target) => {
-    const stat = await import_fs.promises.stat(target);
-    return `${stat.ino}:${stat.mtimeMs}:${stat.size}`;
-  };
+  const versionOf = (stat) => `${stat.ino}:${stat.birthtimeNs}:${stat.mtimeNs}:${stat.size}`;
+  const version = async (target) => versionOf(await import_fs.promises.stat(target, { bigint: true }));
   return {
     name: "filesystem",
     rangedReads: true,
@@ -153,6 +151,8 @@ function createFilesystemReportingRowObjectProviderV1(options) {
       const handle = await import_fs.promises.open(temporary, "wx");
       try {
         await handle.writeFile(input.bytes);
+        const mtime = Date.now() / 1e3 + (0, import_crypto.randomInt)(0, 1e3) / 1e6;
+        await handle.utimes(mtime, mtime);
         await handle.sync();
       } finally {
         await handle.close();
@@ -180,11 +180,12 @@ function createFilesystemReportingRowObjectProviderV1(options) {
         throw new import_row_storage_errors.ReportingRowStoreError("PROVIDER_UNAVAILABLE", "filesystem read failed");
       }
       try {
-        const stat = await handle.stat();
-        if (`${stat.ino}:${stat.mtimeMs}:${stat.size}` !== input.nativeVersion) return null;
+        const stat = await handle.stat({ bigint: true });
+        if (versionOf(stat) !== input.nativeVersion) return null;
+        const size = Number(stat.size);
         const offset = input.range?.offset ?? 0;
-        const length = input.range?.length ?? stat.size - offset;
-        if (offset < 0 || length < 0 || offset + length > stat.size) {
+        const length = input.range?.length ?? size - offset;
+        if (offset < 0 || length < 0 || offset + length > size) {
           throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
         }
         if (length > input.maxBytes) {
@@ -262,6 +263,28 @@ async function runReportingRowObjectProviderConformanceV1(provider, input) {
     throw new Error("repeated delete was not idempotent");
   }
   passed.push("exact-version-delete");
+  const recreated = await provider.putIfAbsent(
+    { ...base, key, bytes: first, contentType: "application/x-ndjson", metadata },
+    context
+  );
+  if (!recreated.created || !recreated.nativeVersion) throw new Error("putIfAbsent did not re-create a deleted object");
+  if (recreated.nativeVersion === created.nativeVersion) {
+    throw new Error("re-creating identical bytes produced the same native version; versions must be write-unique");
+  }
+  if (await provider.delete({ ...base, key, nativeVersion: created.nativeVersion }, context) !== "absent") {
+    throw new Error("delete of a stale version removed or reported a later write");
+  }
+  const survivor = await provider.get(
+    { ...base, key, nativeVersion: recreated.nativeVersion, maxBytes: 1024 },
+    context
+  );
+  if (!survivor || !Buffer.from(survivor).equals(first)) {
+    throw new Error("delete of a stale version removed a later write with identical bytes");
+  }
+  if (await provider.delete({ ...base, key, nativeVersion: recreated.nativeVersion }, context) !== "deleted") {
+    throw new Error("delete did not remove the re-created version");
+  }
+  passed.push("write-unique-version");
   return passed;
 }
 function sha256Hex(value) {

package/dist/lib/reporting/ledger/row-storage-object.mjs

@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from "crypto";
+import { createHash, randomInt, randomUUID } from "crypto";
 import { promises as fs } from "fs";
 import * as path from "path";
 import { canonicalize } from "../../utils/jcs.mjs";
@@ -86,10 +86,8 @@ function createFilesystemReportingRowObjectProviderV1(options) {
     }
     return target;
   };
-  const version = async (target) => {
-    const stat = await fs.stat(target);
-    return `${stat.ino}:${stat.mtimeMs}:${stat.size}`;
-  };
+  const versionOf = (stat) => `${stat.ino}:${stat.birthtimeNs}:${stat.mtimeNs}:${stat.size}`;
+  const version = async (target) => versionOf(await fs.stat(target, { bigint: true }));
   return {
     name: "filesystem",
     rangedReads: true,
@@ -112,6 +110,8 @@ function createFilesystemReportingRowObjectProviderV1(options) {
       const handle = await fs.open(temporary, "wx");
       try {
         await handle.writeFile(input.bytes);
+        const mtime = Date.now() / 1e3 + randomInt(0, 1e3) / 1e6;
+        await handle.utimes(mtime, mtime);
         await handle.sync();
       } finally {
         await handle.close();
@@ -139,11 +139,12 @@ function createFilesystemReportingRowObjectProviderV1(options) {
         throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "filesystem read failed");
       }
       try {
-        const stat = await handle.stat();
-        if (`${stat.ino}:${stat.mtimeMs}:${stat.size}` !== input.nativeVersion) return null;
+        const stat = await handle.stat({ bigint: true });
+        if (versionOf(stat) !== input.nativeVersion) return null;
+        const size = Number(stat.size);
         const offset = input.range?.offset ?? 0;
-        const length = input.range?.length ?? stat.size - offset;
-        if (offset < 0 || length < 0 || offset + length > stat.size) {
+        const length = input.range?.length ?? size - offset;
+        if (offset < 0 || length < 0 || offset + length > size) {
           throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
         }
         if (length > input.maxBytes) {
@@ -221,6 +222,28 @@ async function runReportingRowObjectProviderConformanceV1(provider, input) {
     throw new Error("repeated delete was not idempotent");
   }
   passed.push("exact-version-delete");
+  const recreated = await provider.putIfAbsent(
+    { ...base, key, bytes: first, contentType: "application/x-ndjson", metadata },
+    context
+  );
+  if (!recreated.created || !recreated.nativeVersion) throw new Error("putIfAbsent did not re-create a deleted object");
+  if (recreated.nativeVersion === created.nativeVersion) {
+    throw new Error("re-creating identical bytes produced the same native version; versions must be write-unique");
+  }
+  if (await provider.delete({ ...base, key, nativeVersion: created.nativeVersion }, context) !== "absent") {
+    throw new Error("delete of a stale version removed or reported a later write");
+  }
+  const survivor = await provider.get(
+    { ...base, key, nativeVersion: recreated.nativeVersion, maxBytes: 1024 },
+    context
+  );
+  if (!survivor || !Buffer.from(survivor).equals(first)) {
+    throw new Error("delete of a stale version removed a later write with identical bytes");
+  }
+  if (await provider.delete({ ...base, key, nativeVersion: recreated.nativeVersion }, context) !== "deleted") {
+    throw new Error("delete did not remove the re-created version");
+  }
+  passed.push("write-unique-version");
   return passed;
 }
 function sha256Hex(value) {

package/dist/lib/reporting/ledger/row-storage-provider-io.d.mts

@@ -42,10 +42,3 @@ export declare function assertReportingRowLocationKeys(location: Readonly<Record
  * owned prefix. An absent or empty filter matches everything.
  */
 export declare function reportingRowPrefixFilterOverlaps(filter: string | undefined, bindingPrefix: string): boolean;
-/**
- * S3 and Azure record a version ID when the store is versioned, else the
- * ETag. ETags are always kept quoted, which version IDs never are, so the two
- * cannot be confused when the version is read back.
- */
-export declare function reportingRowEtagVersion(etag: string): string;
-export declare function isReportingRowEtagVersion(nativeVersion: string): boolean;

package/dist/lib/reporting/ledger/row-storage-provider-io.d.ts

@@ -42,10 +42,3 @@ export declare function assertReportingRowLocationKeys(location: Readonly<Record
  * owned prefix. An absent or empty filter matches everything.
  */
 export declare function reportingRowPrefixFilterOverlaps(filter: string | undefined, bindingPrefix: string): boolean;
-/**
- * S3 and Azure record a version ID when the store is versioned, else the
- * ETag. ETags are always kept quoted, which version IDs never are, so the two
- * cannot be confused when the version is read back.
- */
-export declare function reportingRowEtagVersion(etag: string): string;
-export declare function isReportingRowEtagVersion(nativeVersion: string): boolean;