@adcp/sdk 15.5.0 → 15.7.0

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

@@ -423,6 +423,18 @@ class PostgresReportingLedgerStore {
   rowStorage;
   rowStorageWrites;
   changeFeed;
+  /** Whether this store writes the host change feed (`changeFeed: true`). */
+  get changeFeedEnabled() {
+    return this.changeFeed;
+  }
+  /**
+   * Delete expired cursor snapshots and changes checkpoints, a bounded batch
+   * at a time. The store-bound form of `sweepExpiredReportingLedgerState`, for
+   * hosts that hold the store but not the pool.
+   */
+  async sweepExpiredState(limit = 1e3) {
+    return sweepExpiredReportingLedgerState(this.pool, limit);
+  }
   /** Append one host change-feed row inside the caller's account-locked transaction. */
   async appendChange(client, kind, accountId, recordId, obligationId) {
     if (!this.changeFeed) return;
@@ -1288,6 +1300,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 +1320,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 +1352,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 +1528,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;

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

@@ -20,11 +20,9 @@ var row_storage_provider_io_exports = {};
 __export(row_storage_provider_io_exports, {
   assertReportingRowLocationKeys: () => assertReportingRowLocationKeys,
   assertReportingRowReadBounds: () => assertReportingRowReadBounds,
-  isReportingRowEtagVersion: () => isReportingRowEtagVersion,
   readReportingRowStream: () => readReportingRowStream,
   reportingRowAbortError: () => reportingRowAbortError,
   reportingRowClientMap: () => reportingRowClientMap,
-  reportingRowEtagVersion: () => reportingRowEtagVersion,
   reportingRowPrefixFilterOverlaps: () => reportingRowPrefixFilterOverlaps,
   runReportingRowProviderOperation: () => runReportingRowProviderOperation,
   selectReportingRowClient: () => selectReportingRowClient
@@ -131,21 +129,13 @@ function reportingRowPrefixFilterOverlaps(filter, bindingPrefix) {
   const owned = `${bindingPrefix}/`;
   return owned.startsWith(filter) || filter.startsWith(owned);
 }
-function reportingRowEtagVersion(etag) {
-  return etag.startsWith('"') && etag.endsWith('"') && etag.length >= 2 ? etag : `"${etag}"`;
-}
-function isReportingRowEtagVersion(nativeVersion) {
-  return nativeVersion.length >= 2 && nativeVersion.startsWith('"') && nativeVersion.endsWith('"');
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   assertReportingRowLocationKeys,
   assertReportingRowReadBounds,
-  isReportingRowEtagVersion,
   readReportingRowStream,
   reportingRowAbortError,
   reportingRowClientMap,
-  reportingRowEtagVersion,
   reportingRowPrefixFilterOverlaps,
   runReportingRowProviderOperation,
   selectReportingRowClient

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

@@ -99,20 +99,12 @@ function reportingRowPrefixFilterOverlaps(filter, bindingPrefix) {
   const owned = `${bindingPrefix}/`;
   return owned.startsWith(filter) || filter.startsWith(owned);
 }
-function reportingRowEtagVersion(etag) {
-  return etag.startsWith('"') && etag.endsWith('"') && etag.length >= 2 ? etag : `"${etag}"`;
-}
-function isReportingRowEtagVersion(nativeVersion) {
-  return nativeVersion.length >= 2 && nativeVersion.startsWith('"') && nativeVersion.endsWith('"');
-}
 export {
   assertReportingRowLocationKeys,
   assertReportingRowReadBounds,
-  isReportingRowEtagVersion,
   readReportingRowStream,
   reportingRowAbortError,
   reportingRowClientMap,
-  reportingRowEtagVersion,
   reportingRowPrefixFilterOverlaps,
   runReportingRowProviderOperation,
   selectReportingRowClient

package/dist/lib/reporting/s3/index.d.mts

@@ -0,0 +1,29 @@
+import { type S3Client } from '@aws-sdk/client-s3';
+import type { ReportingRowObjectProviderV1 } from '../ledger/row-storage-object.mjs';
+export interface CreateS3ReportingRowObjectProviderOptionsV1 {
+    /** Official client used by bindings without a `credentialRef`. */
+    client?: S3Client;
+    /**
+     * Official clients keyed by `credentialRef`. This map is the closed set of
+     * references a binding may name; an unknown reference fails `UNSAFE_BINDING`.
+     * Endpoint, region, credentials and path style all come from these clients,
+     * never from binding locations.
+     */
+    clients?: Readonly<Record<string, S3Client>>;
+}
+/**
+ * Amazon S3 (and S3-compatible) row-object provider (`@adcp/sdk/reporting/s3`).
+ *
+ * Inject official `S3Client`s configured by the host (region, endpoint,
+ * credentials). Bindings use `location: { bucket, region? }`; when `region` is
+ * set the probe requires the selected client to be configured for it.
+ *
+ * Writes use `PutObject` with `If-None-Match: *`. Bucket versioning must be
+ * enabled: the recorded native version is the write-unique `VersionId`, and every
+ * read and delete is pinned to it, so a delayed delete can never remove a later
+ * write that re-created identical bytes at the same key (ETags are content-derived
+ * and cannot fence that). The probe refuses unversioned or suspended buckets.
+ * Because S3-compatible stores may silently ignore `If-None-Match`, the probe
+ * also proves create-only behaviour empirically before any binding is used.
+ */
+export declare function createS3ReportingRowObjectProviderV1(options: CreateS3ReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;

package/dist/lib/reporting/s3/index.d.ts

@@ -0,0 +1,29 @@
+import { type S3Client } from '@aws-sdk/client-s3';
+import type { ReportingRowObjectProviderV1 } from '../ledger/row-storage-object';
+export interface CreateS3ReportingRowObjectProviderOptionsV1 {
+    /** Official client used by bindings without a `credentialRef`. */
+    client?: S3Client;
+    /**
+     * Official clients keyed by `credentialRef`. This map is the closed set of
+     * references a binding may name; an unknown reference fails `UNSAFE_BINDING`.
+     * Endpoint, region, credentials and path style all come from these clients,
+     * never from binding locations.
+     */
+    clients?: Readonly<Record<string, S3Client>>;
+}
+/**
+ * Amazon S3 (and S3-compatible) row-object provider (`@adcp/sdk/reporting/s3`).
+ *
+ * Inject official `S3Client`s configured by the host (region, endpoint,
+ * credentials). Bindings use `location: { bucket, region? }`; when `region` is
+ * set the probe requires the selected client to be configured for it.
+ *
+ * Writes use `PutObject` with `If-None-Match: *`. Bucket versioning must be
+ * enabled: the recorded native version is the write-unique `VersionId`, and every
+ * read and delete is pinned to it, so a delayed delete can never remove a later
+ * write that re-created identical bytes at the same key (ETags are content-derived
+ * and cannot fence that). The probe refuses unversioned or suspended buckets.
+ * Because S3-compatible stores may silently ignore `If-None-Match`, the probe
+ * also proves create-only behaviour empirically before any binding is used.
+ */
+export declare function createS3ReportingRowObjectProviderV1(options: CreateS3ReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;