@adcp/sdk 16.0.0-beta.3 → 16.0.0-beta.4

package/dist/lib/reporting/ledger/notification-activity.mjs

@@ -1,1337 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { notificationSuppressionDisposition } from "../../server/notification-subscriptions/index.mjs";
-import { canonicalJsonSha256 } from "../../utils/jcs.mjs";
-const DEFAULT_TABLE = "adcp_reporting_notification_activity";
-const REPORTING_STATUS_EVENT_TYPE = "reporting.status_changed";
-const REPORTING_LEDGER_EVENT_TYPE = "reporting.ledger_changed";
-const REPORTING_DELIVERY_EVENT_TYPE = "reporting.delivery_ready";
-const REPORTING_EVENT_STORAGE_PREFIX = "reporting-event:";
-const DEFAULT_NAMESPACE = "adcp-reporting";
-const DEFAULT_RETENTION_MS = 90 * 24 * 60 * 60 * 1e3;
-const DEFAULT_MAX_PENDING_PER_TENANT = 1e5;
-const DEFAULT_MAX_ATTEMPTS = 100;
-const MAX_ACTIVITY_BYTES = 64 * 1024;
-const MAX_CURSOR_BYTES = 16 * 1024;
-class ReportingNotificationRetryableSuppressionError extends Error {
-  constructor(reason) {
-    super(`Reporting notification delivery authority failed closed (${reason}); no external attempt was made`);
-    this.reason = reason;
-  }
-  reason;
-  name = "ReportingNotificationRetryableSuppressionError";
-}
-const MAX_SUPPORTED_RECIPIENTS = 1e4;
-const MAX_SUPPORTED_RETAINED_RECIPIENTS = 1e5;
-const MAX_BTREE_ENTRY_BYTES = 2704;
-const RECIPIENT_FINGERPRINT_BYTES = 64;
-const RECIPIENT_ROUND_BYTES = 4;
-const MAX_TRANSITION_ID_BYTES = 512;
-const MAX_RECIPIENT_TABLE_BYTES = 53;
-function getReportingNotificationActivityMigration(options = {}) {
-  const raw = options.tableName ?? DEFAULT_TABLE;
-  const table = quoteIdentifier(raw);
-  const rawRecipients = recipientTableName(raw);
-  const recipientTable = quoteIdentifier(rawRecipients, MAX_RECIPIENT_TABLE_BYTES);
-  const cursorTable = quoteIdentifier(`${raw}_cursor`, MAX_RECIPIENT_TABLE_BYTES);
-  return `
-CREATE TABLE IF NOT EXISTS ${table} (
-  namespace              TEXT NOT NULL,
-  transition_id          TEXT NOT NULL,
-  activity_sequence      BIGSERIAL NOT NULL UNIQUE,
-  tenant_scope           TEXT NOT NULL,
-  account_id             TEXT NOT NULL,
-  obligation_id          TEXT NOT NULL,
-  activity               JSONB NOT NULL,
-  intent_fingerprint     TEXT NOT NULL,
-  state                  TEXT NOT NULL DEFAULT 'pending',
-  notification_required  BOOLEAN NOT NULL,
-  attempt_count          INTEGER NOT NULL DEFAULT 0,
-  next_attempt_at        TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
-  lease_owner            TEXT,
-  lease_version          BIGINT NOT NULL DEFAULT 0,
-  lease_expires_at       TIMESTAMPTZ,
-  created_at             TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
-  projected_at           TIMESTAMPTZ,
-  retain_until           TIMESTAMPTZ,
-  delivery_intent_at     TIMESTAMPTZ,
-  abandoned_at           TIMESTAMPTZ,
-  PRIMARY KEY (namespace, transition_id),
-  CONSTRAINT ${raw}_valid_state CHECK (state IN ('pending', 'projected', 'abandoned')),
-  CONSTRAINT ${raw}_valid_fingerprint CHECK (intent_fingerprint ~ '^[a-f0-9]{64}$'),
-  CONSTRAINT ${raw}_valid_activity CHECK (jsonb_typeof(activity) = 'object'),
-  CONSTRAINT ${raw}_valid_projection CHECK (
-    (state = 'pending' AND notification_required AND projected_at IS NULL AND retain_until IS NULL) OR
-    (state = 'projected' AND projected_at IS NOT NULL AND retain_until IS NOT NULL) OR
-    -- Abandoned: bounded out of the pending set without ever being recorded as
-    -- delivered, so it stops consuming tenant capacity but stays auditable.
-    (state = 'abandoned' AND projected_at IS NULL AND retain_until IS NOT NULL AND abandoned_at IS NOT NULL)
-  )
-);
-
-CREATE TABLE IF NOT EXISTS ${cursorTable} (
-  namespace     TEXT PRIMARY KEY,
-  tenant_scope TEXT,
-  changed_at   TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
-);
-
--- Upgrade in place, once, and touch nothing on a rerun.
---
--- Every statement here is guarded on the catalog, including the column adds:
--- \`ADD COLUMN IF NOT EXISTS\` still takes ACCESS EXCLUSIVE to discover the
--- column already exists, so a rerun during normal traffic blocks behind ordinary
--- readers and fails outright under a lock_timeout. An already-upgraded rerun now
--- issues no table-locking statement at all.
---
--- Every guard is scoped to this schema's table by resolving it once to a
--- regclass. A database-wide lookup by index name would see an upgraded index in
--- another schema and skip the upgrade here, leaving that deployment with a
--- projected-only retention index that cannot serve abandonment pruning.
-DO $$
-DECLARE
-  activity_table regclass := to_regclass('${raw}');
-  stale_index oid;
-BEGIN
-  IF activity_table IS NULL THEN
-    RETURN;
-  END IF;
-  IF NOT EXISTS (
-    SELECT 1 FROM pg_attribute
-     WHERE attrelid = activity_table AND attname = 'delivery_intent_at' AND NOT attisdropped
-  ) THEN
-    ALTER TABLE ${table} ADD COLUMN delivery_intent_at TIMESTAMPTZ;
-  END IF;
-  IF NOT EXISTS (
-    SELECT 1 FROM pg_attribute
-     WHERE attrelid = activity_table AND attname = 'abandoned_at' AND NOT attisdropped
-  ) THEN
-    ALTER TABLE ${table} ADD COLUMN abandoned_at TIMESTAMPTZ;
-  END IF;
-  IF NOT EXISTS (
-    SELECT 1 FROM pg_constraint
-     WHERE conrelid = activity_table AND conname = '${raw}_valid_state'
-       AND pg_get_constraintdef(oid) LIKE '%abandoned%'
-  ) THEN
-    ALTER TABLE ${table} DROP CONSTRAINT IF EXISTS ${raw}_valid_state;
-    ALTER TABLE ${table} ADD CONSTRAINT ${raw}_valid_state
-      CHECK (state IN ('pending', 'projected', 'abandoned')) NOT VALID;
-    ALTER TABLE ${table} VALIDATE CONSTRAINT ${raw}_valid_state;
-  END IF;
-  IF NOT EXISTS (
-    SELECT 1 FROM pg_constraint
-     WHERE conrelid = activity_table AND conname = '${raw}_valid_projection'
-       AND pg_get_constraintdef(oid) LIKE '%abandoned_at%'
-  ) THEN
-    ALTER TABLE ${table} DROP CONSTRAINT IF EXISTS ${raw}_valid_projection;
-    ALTER TABLE ${table} ADD CONSTRAINT ${raw}_valid_projection CHECK (
-      (state = 'pending' AND notification_required AND projected_at IS NULL AND retain_until IS NULL) OR
-      (state = 'projected' AND projected_at IS NOT NULL AND retain_until IS NOT NULL) OR
-      (state = 'abandoned' AND projected_at IS NULL AND retain_until IS NOT NULL AND abandoned_at IS NOT NULL)
-    ) NOT VALID;
-    ALTER TABLE ${table} VALIDATE CONSTRAINT ${raw}_valid_projection;
-  END IF;
-  SELECT index_class.oid INTO stale_index
-    FROM pg_index
-    JOIN pg_class index_class ON index_class.oid = pg_index.indexrelid
-   WHERE pg_index.indrelid = activity_table
-     AND index_class.relname = 'idx_${raw}_retention'
-     AND pg_get_indexdef(pg_index.indexrelid) NOT LIKE '%abandoned%';
-  IF stale_index IS NOT NULL THEN
-    EXECUTE format('DROP INDEX %s', stale_index::regclass);
-  END IF;
-  IF NOT EXISTS (
-    SELECT 1 FROM pg_index
-     JOIN pg_class index_class ON index_class.oid = pg_index.indexrelid
-    WHERE pg_index.indrelid = activity_table AND index_class.relname = 'idx_${raw}_retention'
-  ) THEN
-    CREATE INDEX idx_${raw}_retention
-      ON ${table}(namespace, retain_until, activity_sequence)
-      WHERE state IN ('projected', 'abandoned');
-  END IF;
-END $$;
-
--- One row per frozen recipient, carrying that recipient's own delivery state.
---
--- Relational rather than one serialized document: a document needs a size cap,
--- and a fanout that legitimately exceeded it could never be committed and would
--- retry until it aged out. Only the bounded 64-hex fingerprint enters the index,
--- so an individual recipient reference has no length limit of its own.
---
--- Per-recipient rather than per-emission: attempt_at is the durable pre-POST
--- checkpoint for exactly one recipient, so one recipient's attempt cannot pin a
--- sibling that was suppressed before its own first POST. Rows with no
--- attempt_at are revisable and replaced in place, so a pre-attempt retry can
--- never accumulate superseded state.
---
--- subscriber_key identifies the subscriber independently of its destination
--- generation. Pinning is per subscriber: once a subscriber has been addressed,
--- a later generation of the same subscriber is never addressed for this
--- notification, because that would be the same logical delivery under a new
--- idempotency key. A different subscriber is unaffected.
-CREATE TABLE IF NOT EXISTS ${recipientTable} (
-  namespace              TEXT NOT NULL,
-  transition_id          TEXT NOT NULL,
-  recipient_fingerprint  TEXT NOT NULL,
-  subscriber_key         TEXT NOT NULL,
-  recipient              JSONB NOT NULL,
-  frozen_at              TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
-  attempt_at             TIMESTAMPTZ,
-  settled_at             TIMESTAMPTZ,
-  disposition            TEXT,
-  PRIMARY KEY (namespace, transition_id, recipient_fingerprint),
-  CONSTRAINT ${rawRecipients}_fk FOREIGN KEY (namespace, transition_id)
-    REFERENCES ${table}(namespace, transition_id) ON DELETE CASCADE,
-  CONSTRAINT ${rawRecipients}_fp CHECK (recipient_fingerprint ~ '^[a-f0-9]{64}$'),
-  CONSTRAINT ${rawRecipients}_sk CHECK (subscriber_key ~ '^[a-f0-9]{64}$'),
-  CONSTRAINT ${rawRecipients}_obj CHECK (jsonb_typeof(recipient) = 'object'),
-  CONSTRAINT ${rawRecipients}_set CHECK (
-    (settled_at IS NULL AND disposition IS NULL) OR
-    (settled_at IS NOT NULL AND disposition IN ('delivered', 'terminal'))
-  )
-);
--- Indexes are catalog-guarded too. CREATE INDEX IF NOT EXISTS still takes a
--- ShareLock to discover the index already exists, which conflicts with the
--- RowExclusiveLock every ordinary writer holds \u2014 so an already-current rerun
--- would stall live traffic, or fail under a lock_timeout, despite creating
--- nothing. Scoped to this schema's tables by regclass, like every other guard.
-DO $$
-DECLARE
-  activity_table regclass := to_regclass('${raw}');
-  recipient_table regclass := to_regclass('${rawRecipients}');
-BEGIN
-  IF activity_table IS NULL OR recipient_table IS NULL THEN
-    RETURN;
-  END IF;
-  IF NOT EXISTS (
-    SELECT 1 FROM pg_index
-     JOIN pg_class index_class ON index_class.oid = pg_index.indexrelid
-    WHERE pg_index.indrelid = recipient_table AND index_class.relname = 'idx_${rawRecipients}_unsettled'
-  ) THEN
-    CREATE INDEX idx_${rawRecipients}_unsettled
-      ON ${recipientTable}(namespace, transition_id)
-      WHERE settled_at IS NULL;
-  END IF;
-  -- At most one addressed generation per subscriber, enforced by the database.
-  --
-  -- The checkpoint and a concurrent recipient replacement run as separate
-  -- statements against a connection pool, so neither sees the other's
-  -- uncommitted work: a freeze can propose a replacement generation while the
-  -- original is being checkpointed, and PostgreSQL will keep both rows. This
-  -- index is the serialization point. The second generation's checkpoint fails,
-  -- so it is never POSTed, and the next freeze drops it because its subscriber
-  -- is already claimed. One logical delivery, one idempotency key.
-  IF NOT EXISTS (
-    SELECT 1 FROM pg_index
-     JOIN pg_class index_class ON index_class.oid = pg_index.indexrelid
-    WHERE pg_index.indrelid = recipient_table
-      AND index_class.relname = 'idx_${rawRecipients}_attempted_subscriber'
-  ) THEN
-    CREATE UNIQUE INDEX idx_${rawRecipients}_attempted_subscriber
-      ON ${recipientTable}(namespace, transition_id, subscriber_key)
-      WHERE attempt_at IS NOT NULL;
-  END IF;
-  IF NOT EXISTS (
-    SELECT 1 FROM pg_index
-     JOIN pg_class index_class ON index_class.oid = pg_index.indexrelid
-    WHERE pg_index.indrelid = activity_table AND index_class.relname = 'idx_${raw}_pending'
-  ) THEN
-    CREATE INDEX idx_${raw}_pending
-      ON ${table}(namespace, next_attempt_at, lease_expires_at, activity_sequence)
-      WHERE state = 'pending';
-  END IF;
-  IF NOT EXISTS (
-    SELECT 1 FROM pg_index
-     JOIN pg_class index_class ON index_class.oid = pg_index.indexrelid
-    WHERE pg_index.indrelid = activity_table AND index_class.relname = 'idx_${raw}_pending_tenant'
-  ) THEN
-    CREATE INDEX idx_${raw}_pending_tenant
-      ON ${table}(namespace, tenant_scope)
-      WHERE state = 'pending';
-  END IF;
-  IF NOT EXISTS (
-    SELECT 1 FROM pg_index
-     JOIN pg_class index_class ON index_class.oid = pg_index.indexrelid
-    WHERE pg_index.indrelid = activity_table AND index_class.relname = 'idx_${raw}_pending_tenant_due'
-  ) THEN
-    CREATE INDEX idx_${raw}_pending_tenant_due
-      ON ${table}(namespace, tenant_scope, next_attempt_at, lease_expires_at)
-      WHERE state = 'pending';
-  END IF;
-  IF NOT EXISTS (
-    SELECT 1 FROM pg_index
-     JOIN pg_class index_class ON index_class.oid = pg_index.indexrelid
-    WHERE pg_index.indrelid = activity_table AND index_class.relname = 'idx_${raw}_account_activity'
-  ) THEN
-    CREATE INDEX idx_${raw}_account_activity
-      ON ${table}(namespace, tenant_scope, account_id, activity_sequence DESC);
-  END IF;
-END $$;
-`.trim();
-}
-function recipientTableName(tableName = DEFAULT_TABLE) {
-  return `${tableName}_recipients`;
-}
-const REPORTING_NOTIFICATION_ACTIVITY_MIGRATION = getReportingNotificationActivityMigration();
-function createPostgresReportingNotificationAttemptCheckpoint(options) {
-  if (!options?.db || typeof options.db.query !== "function") {
-    throw new TypeError("createPostgresReportingNotificationAttemptCheckpoint requires a PostgreSQL queryable");
-  }
-  const namespace = options.namespace ?? DEFAULT_NAMESPACE;
-  assertIdentifier(namespace, "namespace", 255);
-  const rawTable = options.tableName ?? DEFAULT_TABLE;
-  const recipientTable = quoteIdentifier(recipientTableName(rawTable), MAX_RECIPIENT_TABLE_BYTES);
-  const owned = /* @__PURE__ */ new Set([
-    REPORTING_STATUS_EVENT_TYPE,
-    REPORTING_LEDGER_EVENT_TYPE,
-    REPORTING_DELIVERY_EVENT_TYPE,
-    ...options.eventTypes ?? []
-  ]);
-  const checkpoint = async (input) => {
-    if (!owned.has(input.eventType)) return;
-    const fingerprint = recipientFingerprint({
-      scope: input.scope,
-      subscriberId: input.subscriberId,
-      destinationGeneration: input.destinationGeneration
-    });
-    const marked = await reportingActivityDatabaseOperation(
-      "Reporting notification delivery attempt could not be checkpointed",
-      () => options.db.query(
-        `UPDATE ${recipientTable} SET attempt_at = COALESCE(attempt_at, clock_timestamp())
-            WHERE namespace = $1 AND transition_id = $2 AND recipient_fingerprint = $3`,
-        [namespace, input.notificationId, fingerprint]
-      )
-    );
-    if (marked.rowCount !== 1) {
-      throw new Error(
-        "Reporting notification delivery attempt has no frozen recipient to checkpoint; the emission owner must freeze its recipient set before any external attempt"
-      );
-    }
-  };
-  return Object.assign(checkpoint, {
-    activityStore: Object.freeze({ db: options.db, namespace, tableName: rawTable })
-  });
-}
-function createPostgresReportingNotificationActivityRuntime(options) {
-  if (!options?.db || typeof options.db.query !== "function") {
-    throw new TypeError("createPostgresReportingNotificationActivityRuntime requires a PostgreSQL queryable");
-  }
-  if (!options.notifications || typeof options.notifications.emit !== "function") {
-    throw new TypeError(
-      "createPostgresReportingNotificationActivityRuntime requires the persistent notification runtime"
-    );
-  }
-  if (typeof options.tenantScopeForAccount !== "function") {
-    throw new TypeError("tenantScopeForAccount must be a function");
-  }
-  if (options.notifications.hasDeliveryAttemptCheckpoint !== true && !options.acknowledgeMissingAttemptCheckpoint) {
-    throw new TypeError(
-      "createPostgresReportingNotificationActivityRuntime requires a notification port that runs the durable pre-POST attempt checkpoint. Build createPostgresReportingNotificationAttemptCheckpoint() and pass it as checkpointDeliveryAttempt; a custom port must set hasDeliveryAttemptCheckpoint: true to prove it forwards the event it is given."
-    );
-  }
-  const namespace = options.namespace ?? DEFAULT_NAMESPACE;
-  if (!options.attemptCheckpoint && !options.acknowledgeMissingAttemptCheckpoint) {
-    throw new TypeError(
-      "createPostgresReportingNotificationActivityRuntime requires attemptCheckpoint: pass the very checkpoint wired into the notification runtime so its durable store can be verified against this one."
-    );
-  }
-  const wired = options.notifications.deliveryAttemptCheckpoint;
-  if (wired !== void 0 && options.attemptCheckpoint && wired !== options.attemptCheckpoint) {
-    throw new TypeError(
-      "createPostgresReportingNotificationActivityRuntime: the notification runtime invokes a different checkpoint than the one passed as attemptCheckpoint. Each can be correctly built and still target a different store, in which case every delivery checkpoints nothing and is abandoned undelivered. Pass the very object wired into checkpointDeliveryAttempt."
-    );
-  }
-  if (options.attemptCheckpoint && wired === void 0 && !options.attemptCheckpoint.activityStore) {
-    throw new TypeError(
-      "createPostgresReportingNotificationActivityRuntime: attemptCheckpoint declares no durable store and the notification port does not expose the checkpoint it invokes, so neither its identity nor its target can be verified. Build it with createPostgresReportingNotificationAttemptCheckpoint()."
-    );
-  }
-  if (options.attemptCheckpoint?.activityStore) {
-    const bound = options.attemptCheckpoint.activityStore;
-    const mismatch = bound.db !== options.db || bound.namespace !== namespace || bound.tableName !== (options.tableName ?? DEFAULT_TABLE);
-    if (mismatch) {
-      throw new TypeError(
-        `createPostgresReportingNotificationActivityRuntime: attemptCheckpoint is bound to a different durable store (namespace ${JSON.stringify(bound.namespace)}, table ${JSON.stringify(bound.tableName)}${bound.db === options.db ? "" : ", different queryable"}) than this runtime (namespace ${JSON.stringify(namespace)}, table ${JSON.stringify(options.tableName ?? DEFAULT_TABLE)}). A mismatched pair checkpoints nothing, so every delivery is suppressed until its binding retires and the notification is lost silently.`
-      );
-    }
-  }
-  const development = process.env.NODE_ENV === "test" || process.env.NODE_ENV === "development";
-  if (!development && options.namespace === void 0 && !options.acknowledgeIsolatedDatabase) {
-    throw new TypeError(
-      "Production reporting notification activity requires an explicit deployment namespace or acknowledgeIsolatedDatabase: true"
-    );
-  }
-  assertIdentifier(namespace, "namespace", 255);
-  const rawTable = options.tableName ?? DEFAULT_TABLE;
-  const table = quoteIdentifier(rawTable);
-  const retentionMs = options.retentionMs ?? DEFAULT_RETENTION_MS;
-  positiveInteger(retentionMs, "retentionMs");
-  const maxPendingPerTenant = options.maxPendingPerTenant ?? DEFAULT_MAX_PENDING_PER_TENANT;
-  boundedInteger(maxPendingPerTenant, "maxPendingPerTenant", 1, 1e6);
-  const maxRecipients = options.maxRecipients ?? MAX_SUPPORTED_RECIPIENTS;
-  boundedInteger(maxRecipients, "maxRecipients", 1, MAX_SUPPORTED_RECIPIENTS);
-  const maxRetainedRecipients = options.maxRetainedRecipients ?? maxRecipients * 2;
-  boundedInteger(maxRetainedRecipients, "maxRetainedRecipients", 1, MAX_SUPPORTED_RETAINED_RECIPIENTS);
-  if (maxRetainedRecipients < maxRecipients) {
-    throw new TypeError(
-      `maxRetainedRecipients ${maxRetainedRecipients} is below maxRecipients ${maxRecipients}; a full fanout could then never be retained and every claim at that size would abandon undelivered`
-    );
-  }
-  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
-  boundedInteger(maxAttempts, "maxAttempts", 1, 1e5);
-  const recipientRawTable = recipientTableName(rawTable);
-  const recipientTable = quoteIdentifier(recipientRawTable, MAX_RECIPIENT_TABLE_BYTES);
-  const cursorTable = quoteIdentifier(`${rawTable}_cursor`, MAX_RECIPIENT_TABLE_BYTES);
-  const worstCaseIndexBytes = Buffer.byteLength(namespace, "utf8") + MAX_TRANSITION_ID_BYTES + RECIPIENT_ROUND_BYTES + RECIPIENT_FINGERPRINT_BYTES;
-  if (worstCaseIndexBytes > MAX_BTREE_ENTRY_BYTES) {
-    throw new TypeError(
-      `Reporting notification activity namespace is too long to index recipient intent (${worstCaseIndexBytes} of ${MAX_BTREE_ENTRY_BYTES} bytes); shorten namespace`
-    );
-  }
-  const persistActivity = async (transaction, input) => {
-    const { activity, eventId, notificationRequired, obligation } = input;
-    const persistenceEventId = activity.activityType === "reporting.lifecycle_changed" ? eventId.startsWith(REPORTING_EVENT_STORAGE_PREFIX) || Buffer.byteLength(eventId, "utf8") > 255 || !/^[A-Za-z0-9_.:-]+$/.test(eventId) ? `${REPORTING_EVENT_STORAGE_PREFIX}${canonicalJsonSha256({ kind: "lifecycle", eventId })}` : eventId : `${REPORTING_EVENT_STORAGE_PREFIX}${canonicalJsonSha256({
-      kind: activity.activityType,
-      changeKind: activity.activityType === "reporting.ledger_changed" ? activity.changeKind : "ready",
-      eventId
-    })}`;
-    const accountId = obligation.account.account_id;
-    const tenantId = activity.tenantId;
-    if (Buffer.byteLength(JSON.stringify(activity), "utf8") > MAX_ACTIVITY_BYTES) {
-      throw new RangeError("Reporting notification/activity intent exceeds 64 KiB");
-    }
-    const fingerprint = canonicalJsonSha256(activity);
-    if (notificationRequired) {
-      await reportingActivityDatabaseOperation("Reporting notification/activity capacity check failed", async () => {
-        await transaction.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
-          `adcp-reporting-activity-cap:${namespace}:${tenantId}`
-        ]);
-        const existing = await transaction.query(
-          `SELECT intent_fingerprint, tenant_scope, account_id, obligation_id
-             FROM ${table}
-            WHERE namespace = $1 AND transition_id = $2`,
-          [namespace, persistenceEventId]
-        );
-        const existingIntent = existing.rows[0];
-        if (existingIntent) {
-          if (existingIntent.intent_fingerprint !== fingerprint || existingIntent.tenant_scope !== tenantId || existingIntent.account_id !== accountId || existingIntent.obligation_id !== obligation.reporting_obligation_id) {
-            throw new Error("Reporting event identity conflicts with existing notification/activity intent");
-          }
-          return;
-        }
-        const pending = await transaction.query(
-          `SELECT COUNT(*)::integer AS count
-             FROM (
-               SELECT 1 FROM ${table}
-                WHERE namespace = $1 AND tenant_scope = $2 AND state = 'pending'
-                LIMIT $3
-             ) bounded_pending`,
-          [namespace, tenantId, maxPendingPerTenant]
-        );
-        if ((pending.rows[0]?.count ?? 0) >= maxPendingPerTenant) {
-          throw new Error("Reporting notification activity pending capacity reached; recovery must catch up");
-        }
-      });
-    }
-    let write;
-    try {
-      write = await transaction.query(
-        `INSERT INTO ${table} (
-         namespace, transition_id, tenant_scope, account_id, obligation_id,
-         activity, intent_fingerprint, notification_required, state,
-         projected_at, retain_until
-       ) VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8,
-                 CASE WHEN $8 THEN 'pending' ELSE 'projected' END,
-                 CASE WHEN $8 THEN NULL ELSE clock_timestamp() END,
-                 CASE WHEN $8 THEN NULL ELSE clock_timestamp() + ($9::bigint * INTERVAL '1 millisecond') END)
-       ON CONFLICT (namespace, transition_id) DO UPDATE SET
-         transition_id = EXCLUDED.transition_id
-       WHERE ${table}.intent_fingerprint = EXCLUDED.intent_fingerprint
-         AND ${table}.tenant_scope = EXCLUDED.tenant_scope
-         AND ${table}.account_id = EXCLUDED.account_id
-         AND ${table}.obligation_id = EXCLUDED.obligation_id
-       RETURNING transition_id`,
-        [
-          namespace,
-          persistenceEventId,
-          tenantId,
-          accountId,
-          obligation.reporting_obligation_id,
-          JSON.stringify(activity),
-          fingerprint,
-          notificationRequired,
-          retentionMs
-        ]
-      );
-    } catch (cause) {
-      if (isPostgresUndefinedTable(cause)) {
-        throw new Error(
-          "Reporting notification/activity persistence failed: run getReportingNotificationActivityMigration() before serving",
-          { cause }
-        );
-      }
-      throw new Error("Reporting notification/activity persistence failed", { cause });
-    }
-    if (write.rowCount !== 1) {
-      throw new Error("Reporting event identity conflicts with existing notification/activity intent");
-    }
-  };
-  const activityScope = (transaction, obligation, eventId) => {
-    if (!transaction || typeof transaction.query !== "function") {
-      throw new TypeError("Reporting notification/activity persistence requires the active ledger transaction");
-    }
-    const accountId = obligation.account.account_id;
-    assertIdentifier(accountId, "accountId", 512);
-    assertIdentifier(eventId, "eventId", MAX_TRANSITION_ID_BYTES);
-    const tenantId = options.tenantScopeForAccount(accountId);
-    if (isPromiseLike(tenantId)) {
-      throw new TypeError("tenantScopeForAccount must be synchronous and side-effect free");
-    }
-    assertIdentifier(tenantId, "tenantId", 512);
-    return { accountId, tenantId };
-  };
-  const databaseNow = async (transaction) => {
-    const result = await transaction.query("SELECT clock_timestamp() AS now");
-    if (!result.rows[0]) throw new Error("Reporting notification/activity database clock is unavailable");
-    return asIso(result.rows[0].now);
-  };
-  const port = {
-    async recordTransition(input, transaction) {
-      const { tenantId } = activityScope(transaction, input.obligation, input.transition.transitionId);
-      if (input.transition.reporting_obligation_id !== input.obligation.reporting_obligation_id) {
-        throw new Error("Reporting transition and authoritative obligation identities disagree");
-      }
-      const activity = buildActivity(namespace, tenantId, input.transition, input.obligation);
-      const notificationRequired = input.transition.previousHealth !== input.transition.health;
-      await persistActivity(transaction, {
-        eventId: input.transition.transitionId,
-        obligation: input.obligation,
-        activity,
-        notificationRequired
-      });
-    },
-    async recordLedgerChanged(input, transaction) {
-      const record = "revision" in input ? input.revision : input.adjustment;
-      const eventId = "revision" in input ? input.revision.reporting_revision_id : input.adjustment.reporting_adjustment_id;
-      const { tenantId } = activityScope(transaction, input.obligation, eventId);
-      if (record.reporting_obligation_id !== input.obligation.reporting_obligation_id) {
-        throw new Error("Reporting ledger record and authoritative obligation identities disagree");
-      }
-      const occurredAt = await databaseNow(transaction);
-      const activity = buildLedgerChangedActivity(namespace, tenantId, occurredAt, input);
-      await persistActivity(transaction, {
-        eventId,
-        obligation: input.obligation,
-        activity,
-        notificationRequired: true
-      });
-    },
-    async recordDeliveryReady(input, transaction) {
-      const eventId = input.materialization.reporting_materialization_id;
-      const { tenantId } = activityScope(transaction, input.obligation, eventId);
-      if (input.revision.reporting_obligation_id !== input.obligation.reporting_obligation_id || input.materialization.reporting_revision_id !== input.revision.reporting_revision_id) {
-        throw new Error("Reporting delivery-ready records do not share one authoritative ledger identity");
-      }
-      if (input.materialization.status !== "available" && input.materialization.status !== "delivered") {
-        throw new Error("Reporting delivery-ready activity requires a successful materialization");
-      }
-      const occurredAt = await databaseNow(transaction);
-      const activity = buildDeliveryReadyActivity(namespace, tenantId, occurredAt, input);
-      await persistActivity(transaction, {
-        eventId,
-        obligation: input.obligation,
-        activity,
-        notificationRequired: true
-      });
-    }
-  };
-  const readActivity = async (input, lifecycleOnly) => {
-    assertIdentifier(input.tenantId, "tenantId", 512);
-    assertIdentifier(input.accountId, "accountId", 512);
-    const expectedTenantId = options.tenantScopeForAccount(input.accountId);
-    if (isPromiseLike(expectedTenantId)) {
-      throw new TypeError("tenantScopeForAccount must be synchronous and side-effect free");
-    }
-    assertIdentifier(expectedTenantId, "tenantId", 512);
-    if (expectedTenantId !== input.tenantId) {
-      throw new TypeError("Reporting account activity scope does not match the trusted account directory");
-    }
-    const limit = input.limit ?? 100;
-    boundedInteger(limit, "limit", 1, 200);
-    const before = decodeCursor(input.cursor, namespace, input.tenantId, input.accountId);
-    const result = await reportingActivityDatabaseOperation(
-      "Reporting account activity read failed",
-      () => options.db.query(
-        `SELECT activity, state, created_at, projected_at, abandoned_at, activity_sequence
-           FROM ${table}
-          WHERE namespace = $1 AND tenant_scope = $2 AND account_id = $3
-            AND ($4::bigint IS NULL OR activity_sequence < $4)
-            AND ($6::boolean = false OR activity->>'activityType' = 'reporting.lifecycle_changed')
-          ORDER BY activity_sequence DESC
-          LIMIT $5`,
-        [namespace, input.tenantId, input.accountId, before ?? null, limit + 1, lifecycleOnly]
-      )
-    );
-    const selected = result.rows.slice(0, limit);
-    const activities = selected.map((row) => ({
-      ...structuredClone(row.activity),
-      recordedAt: asIso(row.created_at),
-      ...row.projected_at ? { notificationProjectedAt: asIso(row.projected_at) } : {},
-      ...row.abandoned_at ? { notificationAbandonedAt: asIso(row.abandoned_at) } : {}
-    }));
-    const hasMore = result.rows.length > limit;
-    return {
-      activities,
-      hasMore,
-      ...hasMore && selected.length > 0 ? {
-        nextCursor: encodeCursor(
-          namespace,
-          input.tenantId,
-          input.accountId,
-          String(selected[selected.length - 1].activity_sequence)
-        )
-      } : {}
-    };
-  };
-  return {
-    port,
-    migrations: {
-      activity: getReportingNotificationActivityMigration({ tableName: rawTable }),
-      all: [getReportingNotificationActivityMigration({ tableName: rawTable })]
-    },
-    async probe() {
-      if (options.notifications.hasDeliveryAttemptCheckpoint !== true) {
-        throw new Error(
-          "Reporting notification/activity probe failed: the notification port does not prove it runs the durable pre-POST attempt checkpoint. Wire createPostgresReportingNotificationAttemptCheckpoint() into checkpointDeliveryAttempt, or set hasDeliveryAttemptCheckpoint: true on a custom port that forwards the event it is given."
-        );
-      }
-      try {
-        await options.db.query(
-          `SELECT namespace, transition_id, tenant_scope, account_id, obligation_id,
-                  activity, intent_fingerprint, state, notification_required, lease_owner, lease_version,
-                  lease_expires_at, projected_at, retain_until, delivery_intent_at, abandoned_at
-             FROM ${table} LIMIT 0`
-        );
-        await options.db.query(
-          `SELECT namespace, transition_id, recipient_fingerprint, recipient, frozen_at,
-                  attempt_at, settled_at, disposition
-             FROM ${recipientTable} LIMIT 0`
-        );
-        await options.db.query(`SELECT namespace, tenant_scope, changed_at FROM ${cursorTable} LIMIT 0`);
-      } catch (cause) {
-        throw new Error(
-          "Reporting notification/activity probe failed: run getReportingNotificationActivityMigration() before serving",
-          { cause }
-        );
-      }
-    },
-    async recoverOnce(recoveryOptions = {}) {
-      const ownerToken = recoveryOptions.ownerToken ?? randomUUID();
-      assertIdentifier(ownerToken, "ownerToken", 255);
-      if (ownerToken.length < 8) throw new TypeError("ownerToken must contain at least 8 characters");
-      const leaseMs = recoveryOptions.leaseMs ?? 6e4;
-      const limit = recoveryOptions.limit ?? 50;
-      const retryAfterMs = recoveryOptions.retryAfterMs ?? 3e4;
-      boundedInteger(leaseMs, "leaseMs", 1e3, 3e5);
-      boundedInteger(limit, "limit", 1, 1e3);
-      boundedInteger(retryAfterMs, "retryAfterMs", 1, 6048e5);
-      const metrics = {
-        claimed: 0,
-        matched: 0,
-        projected: 0,
-        retried: 0,
-        leaseLost: 0,
-        abandoned: 0
-      };
-      let emptyTenantClaims = 0;
-      while (metrics.claimed < limit && emptyTenantClaims < 8) {
-        recoveryOptions.signal?.throwIfAborted();
-        const [claim] = await claimPending(options.db, table, cursorTable, namespace, ownerToken, leaseMs, 1);
-        if (!claim) {
-          emptyTenantClaims += 1;
-          continue;
-        }
-        emptyTenantClaims = 0;
-        metrics.claimed += 1;
-        let leaseLost = false;
-        let renewing = false;
-        const heartbeat = setInterval(
-          () => {
-            if (renewing || leaseLost) return;
-            renewing = true;
-            void renewClaim(options.db, table, namespace, claim, leaseMs).then((renewed) => {
-              if (!renewed) leaseLost = true;
-            }).catch(() => {
-              leaseLost = true;
-            }).finally(() => {
-              renewing = false;
-            });
-          },
-          Math.max(250, Math.floor(leaseMs / 3))
-        );
-        heartbeat.unref?.();
-        try {
-          const notificationType = claim.activity.notificationType;
-          if (!notificationType) throw new Error("Pending reporting activity has no notification type");
-          let frozen = [];
-          let froze = false;
-          const result = await options.notifications.emit({
-            emissionId: claim.activity.activityId,
-            notificationId: claim.transitionId,
-            notificationType,
-            anchor: "account",
-            tenantId: claim.tenantId,
-            accountId: claim.accountId,
-            payload: notificationPayload(claim.activity),
-            // Commit the recipient set under this lease before anything leaves
-            // the process. Each recipient is revisable until its own durable
-            // pre-POST checkpoint and pinned afterwards.
-            freezeRecipients: async (candidates) => {
-              froze = true;
-              frozen = await freezeClaimRecipients(
-                options.db,
-                table,
-                recipientTable,
-                namespace,
-                claim,
-                maxRecipients,
-                maxRetainedRecipients,
-                candidates
-              );
-              return frozen;
-            }
-          });
-          if (!froze) {
-            throw new Error(
-              "Reporting notification port did not freeze its recipient set; it must forward the emitted event, including freezeRecipients, to a runtime that honours it. Nothing was projected."
-            );
-          }
-          metrics.matched += result.matched;
-          const outcomes = result.deliveries.map((delivery) => classifyDelivery(delivery));
-          const settlement = await settleClaimRecipients(
-            options.db,
-            table,
-            recipientTable,
-            namespace,
-            claim,
-            frozen,
-            outcomes
-          );
-          if (!settlement.settled) {
-            const retryable = outcomes.find((outcome) => outcome.disposition === "retryable");
-            throw retryable?.suppression ? new ReportingNotificationRetryableSuppressionError(retryable.suppression) : new Error(
-              `Reporting notification delivery is not settled for ${settlement.unsettled} recipient(s); retrying`
-            );
-          }
-          const projected = !leaseLost && await projectClaim(options.db, table, namespace, claim, retentionMs);
-          if (projected) metrics.projected += 1;
-          else metrics.leaseLost += 1;
-        } catch (error) {
-          reportProjectionError(recoveryOptions.onError, error, claim);
-          if (!leaseLost && claim.attemptCount >= maxAttempts) {
-            const abandoned = await abandonClaim(options.db, table, namespace, claim, retentionMs);
-            if (abandoned) metrics.abandoned += 1;
-            else metrics.leaseLost += 1;
-          } else {
-            const released = !leaseLost && await releaseClaim(options.db, table, namespace, claim, retryAfterMs);
-            if (released) metrics.retried += 1;
-            else metrics.leaseLost += 1;
-          }
-        } finally {
-          clearInterval(heartbeat);
-        }
-      }
-      return metrics;
-    },
-    async listActivity(input) {
-      return await readActivity(input, true);
-    },
-    async listNotificationActivity(input) {
-      return readActivity(input, false);
-    },
-    async pruneProjected(pruneOptions = {}) {
-      const limit = pruneOptions.limit ?? 1e3;
-      boundedInteger(limit, "limit", 1, 1e4);
-      const result = await reportingActivityDatabaseOperation(
-        "Reporting account activity pruning failed",
-        () => options.db.query(
-          `WITH expired AS (
-           SELECT namespace, transition_id FROM ${table}
-            WHERE namespace = $1 AND state IN ('projected', 'abandoned')
-              AND retain_until <= clock_timestamp()
-            ORDER BY retain_until, activity_sequence
-            FOR UPDATE SKIP LOCKED LIMIT $2
-         )
-         DELETE FROM ${table} target USING expired
-          WHERE target.namespace = expired.namespace AND target.transition_id = expired.transition_id`,
-          [namespace, limit]
-        )
-      );
-      return result.rowCount ?? 0;
-    }
-  };
-}
-function buildActivity(namespace, tenantId, transition, obligation) {
-  const identity = canonicalJsonSha256({
-    namespace,
-    tenantId,
-    accountId: obligation.account.account_id,
-    transitionId: transition.transitionId
-  });
-  return {
-    activityId: `ract_${identity.slice(0, 32)}`,
-    transitionId: transition.transitionId,
-    activityType: "reporting.lifecycle_changed",
-    ...transition.previousHealth === transition.health ? {} : { notificationType: "reporting.status_changed" },
-    tenantId,
-    accountId: obligation.account.account_id,
-    reporting_obligation_id: obligation.reporting_obligation_id,
-    previousHealth: transition.previousHealth,
-    health: transition.health,
-    previousFinality: transition.previousFinality ?? "none",
-    finality: transition.finality ?? "none",
-    issueIds: [...transition.issueIds],
-    occurredAt: transition.occurredAt,
-    correlation: {
-      delivery_config_id: obligation.delivery_config_id,
-      delivery_config_version: obligation.delivery_config_version,
-      report_definition_id: obligation.report_definition_id,
-      feed_purpose: obligation.feedPurpose,
-      period: { start: obligation.period.start, end: obligation.period.end }
-    }
-  };
-}
-function activityIdentity(namespace, tenantId, accountId, eventId, eventType) {
-  return `ract_${canonicalJsonSha256({ namespace, tenantId, accountId, eventId, eventType }).slice(0, 32)}`;
-}
-function buildLedgerChangedActivity(namespace, tenantId, occurredAt, input) {
-  const accountId = input.obligation.account.account_id;
-  if ("revision" in input) {
-    const eventId2 = input.revision.reporting_revision_id;
-    return {
-      activityId: activityIdentity(
-        namespace,
-        tenantId,
-        accountId,
-        eventId2,
-        `${REPORTING_LEDGER_EVENT_TYPE}:revision_published`
-      ),
-      transitionId: eventId2,
-      activityType: REPORTING_LEDGER_EVENT_TYPE,
-      notificationType: REPORTING_LEDGER_EVENT_TYPE,
-      tenantId,
-      accountId,
-      reporting_obligation_id: input.obligation.reporting_obligation_id,
-      occurredAt,
-      changeKind: "revision_published",
-      reporting_revision_id: eventId2,
-      ...input.revision.supersedes_reporting_revision_id ? { supersedes_reporting_revision_id: input.revision.supersedes_reporting_revision_id } : {},
-      finality: input.revision.finality
-    };
-  }
-  const eventId = input.adjustment.reporting_adjustment_id;
-  return {
-    activityId: activityIdentity(
-      namespace,
-      tenantId,
-      accountId,
-      eventId,
-      `${REPORTING_LEDGER_EVENT_TYPE}:adjustment_published`
-    ),
-    transitionId: eventId,
-    activityType: REPORTING_LEDGER_EVENT_TYPE,
-    notificationType: REPORTING_LEDGER_EVENT_TYPE,
-    tenantId,
-    accountId,
-    reporting_obligation_id: input.obligation.reporting_obligation_id,
-    occurredAt,
-    changeKind: "adjustment_published",
-    reporting_adjustment_id: eventId,
-    adjusts_reporting_revision_id: input.adjustment.adjusts_reporting_revision_id
-  };
-}
-function buildDeliveryReadyActivity(namespace, tenantId, occurredAt, input) {
-  const accountId = input.obligation.account.account_id;
-  const eventId = input.materialization.reporting_materialization_id;
-  const readiness = input.materialization.status;
-  if (readiness !== "available" && readiness !== "delivered") {
-    throw new Error("Reporting delivery-ready activity requires a successful materialization");
-  }
-  return {
-    activityId: activityIdentity(namespace, tenantId, accountId, eventId, REPORTING_DELIVERY_EVENT_TYPE),
-    transitionId: eventId,
-    activityType: REPORTING_DELIVERY_EVENT_TYPE,
-    notificationType: REPORTING_DELIVERY_EVENT_TYPE,
-    tenantId,
-    accountId,
-    reporting_obligation_id: input.obligation.reporting_obligation_id,
-    occurredAt,
-    delivery_config_id: input.obligation.delivery_config_id,
-    delivery_config_version: input.obligation.delivery_config_version,
-    feed_purpose: input.obligation.feedPurpose,
-    reporting_revision_id: input.revision.reporting_revision_id,
-    reporting_materialization_id: eventId,
-    readiness,
-    finality: input.revision.finality,
-    data_through: input.revision.dataThrough
-  };
-}
-function notificationPayload(activity) {
-  if (activity.activityType === "reporting.lifecycle_changed") {
-    return {
-      reporting_obligation_id: activity.reporting_obligation_id,
-      previous_health: activity.previousHealth,
-      health: activity.health,
-      issue_ids: [...activity.issueIds],
-      fired_at: activity.occurredAt,
-      delivery_config_id: activity.correlation.delivery_config_id,
-      delivery_config_version: activity.correlation.delivery_config_version,
-      feed_purpose: activity.correlation.feed_purpose
-    };
-  }
-  if (activity.activityType === REPORTING_LEDGER_EVENT_TYPE) {
-    return {
-      fired_at: activity.occurredAt,
-      change_kind: activity.changeKind,
-      ...activity.reporting_revision_id ? { reporting_revision_id: activity.reporting_revision_id } : {},
-      ...activity.supersedes_reporting_revision_id ? { supersedes_reporting_revision_id: activity.supersedes_reporting_revision_id } : {},
-      ...activity.finality ? { finality: activity.finality } : {},
-      ...activity.reporting_adjustment_id ? { reporting_adjustment_id: activity.reporting_adjustment_id } : {},
-      ...activity.adjusts_reporting_revision_id ? { adjusts_reporting_revision_id: activity.adjusts_reporting_revision_id } : {}
-    };
-  }
-  return {
-    fired_at: activity.occurredAt,
-    delivery_config_id: activity.delivery_config_id,
-    delivery_config_version: activity.delivery_config_version,
-    feed_purpose: activity.feed_purpose,
-    reporting_revision_id: activity.reporting_revision_id,
-    reporting_materialization_id: activity.reporting_materialization_id,
-    readiness: activity.readiness,
-    finality: activity.finality,
-    data_through: activity.data_through
-  };
-}
-async function claimPending(db, table, cursorTable, namespace, ownerToken, leaseMs, limit) {
-  const result = await reportingActivityDatabaseOperation(
-    "Reporting notification recovery claim failed",
-    () => db.query(
-      `WITH selected_tenant AS (
-       INSERT INTO ${cursorTable} (namespace, tenant_scope)
-       VALUES (
-         $1,
-         (SELECT MIN(tenant_scope) FROM ${table}
-           WHERE namespace = $1 AND state = 'pending' AND next_attempt_at <= clock_timestamp()
-             AND (lease_expires_at IS NULL OR lease_expires_at < clock_timestamp()))
-       )
-       ON CONFLICT (namespace) DO UPDATE SET
-         tenant_scope = COALESCE(
-           (SELECT MIN(candidate.tenant_scope) FROM ${table} candidate
-             WHERE candidate.namespace = $1 AND candidate.state = 'pending'
-               AND candidate.next_attempt_at <= clock_timestamp()
-               AND (candidate.lease_expires_at IS NULL OR candidate.lease_expires_at < clock_timestamp())
-               AND candidate.tenant_scope > ${cursorTable}.tenant_scope),
-           (SELECT MIN(candidate.tenant_scope) FROM ${table} candidate
-             WHERE candidate.namespace = $1 AND candidate.state = 'pending'
-               AND candidate.next_attempt_at <= clock_timestamp()
-               AND (candidate.lease_expires_at IS NULL OR candidate.lease_expires_at < clock_timestamp()))
-         ),
-         changed_at = clock_timestamp()
-       RETURNING tenant_scope
-     ), candidates AS (
-       SELECT activity.namespace, activity.transition_id FROM ${table} activity
-       CROSS JOIN selected_tenant selected
-        WHERE activity.namespace = $1 AND activity.state = 'pending'
-          AND activity.tenant_scope = selected.tenant_scope
-          AND activity.next_attempt_at <= clock_timestamp()
-          AND (activity.lease_expires_at IS NULL OR activity.lease_expires_at < clock_timestamp())
-        ORDER BY activity.next_attempt_at, activity.activity_sequence
-        FOR UPDATE OF activity SKIP LOCKED LIMIT $4
-     )
-     UPDATE ${table} target SET
-       lease_owner = $2,
-       lease_version = target.lease_version + 1,
-       lease_expires_at = clock_timestamp() + ($3::bigint * INTERVAL '1 millisecond'),
-       attempt_count = target.attempt_count + 1
-     FROM candidates
-     WHERE target.namespace = candidates.namespace AND target.transition_id = candidates.transition_id
-     RETURNING target.transition_id, target.tenant_scope, target.account_id,
-               target.activity, target.lease_version::text, target.attempt_count`,
-      [namespace, ownerToken, leaseMs, limit]
-    )
-  );
-  return result.rows.map((row) => ({
-    transitionId: row.transition_id,
-    tenantId: row.tenant_scope,
-    accountId: row.account_id,
-    activity: structuredClone(row.activity),
-    leaseOwner: ownerToken,
-    leaseVersion: row.lease_version,
-    attemptCount: row.attempt_count
-  }));
-}
-async function freezeClaimRecipients(db, table, recipientTable, namespace, claim, maxRecipients, maxRetainedRecipients, candidates) {
-  if (candidates.length > maxRecipients) {
-    throw new Error(
-      `Reporting notification fanout of ${candidates.length} recipients exceeds maxRecipients ${maxRecipients}; raise maxRecipients to at least the notification runtime maxFanoutCandidates`
-    );
-  }
-  const fenced = await reportingActivityDatabaseOperation(
-    "Reporting notification recipient intent could not be committed",
-    () => db.query(
-      `UPDATE ${table} SET delivery_intent_at = COALESCE(delivery_intent_at, clock_timestamp())
-          WHERE namespace = $1 AND transition_id = $2 AND state = 'pending'
-            AND lease_owner = $3 AND lease_version = $4::bigint
-            AND lease_expires_at >= clock_timestamp()`,
-      [namespace, claim.transitionId, claim.leaseOwner, claim.leaseVersion]
-    )
-  );
-  if (fenced.rowCount !== 1) {
-    throw new Error("Reporting notification recipient intent was not committed; the recovery lease was lost");
-  }
-  const rows = canonicalRecipients(candidates);
-  await compactSettledRecipients(db, table, recipientTable, namespace, claim);
-  const committed = await reportingActivityDatabaseOperation(
-    "Reporting notification recipient intent could not be committed",
-    () => db.query(
-      `WITH leased AS MATERIALIZED (
-           -- The parent row is the serialization point, and MATERIALIZED makes
-           -- its lock the statement's first act. Reading the lease without
-           -- locking it only proved the lease was live when the snapshot was
-           -- taken: a statement that then blocked on a recipient lock could
-           -- resume long after a successor had claimed, still see its own lease
-           -- in the cached snapshot, and mutate the successor's rows. Holding
-           -- this lock means a takeover cannot complete while this statement
-           -- runs, and a statement that starts after one sees the new lease and
-           -- matches nothing.
-           SELECT transition_id FROM ${table}
-            WHERE namespace = $1 AND transition_id = $2 AND state = 'pending'
-              AND lease_owner = $3 AND lease_version = $4::bigint
-              AND lease_expires_at >= clock_timestamp()
-              FOR UPDATE
-         ), existing AS (
-           -- FOR UPDATE is what serializes this statement against a concurrent
-           -- checkpoint. Without it the budget is computed from a snapshot in
-           -- which a row is still revisable, the DELETE then re-checks the
-           -- locked row, finds it attempted and skips it, and the retained set
-           -- lands one row above the budget that approved the write.
-           SELECT current.recipient_fingerprint, current.subscriber_key, current.recipient,
-                  current.attempt_at, current.settled_at
-             FROM ${recipientTable} current, leased
-            WHERE current.namespace = $1 AND current.transition_id = $2
-            FOR UPDATE OF current
-         ), claimed AS (
-           SELECT subscriber_key FROM existing
-            WHERE attempt_at IS NOT NULL OR settled_at IS NOT NULL
-         ), proposed AS (
-           SELECT entry.fingerprint, entry.subscriber_key, entry.recipient::jsonb AS recipient
-             FROM leased, unnest($5::text[], $6::text[], $7::text[])
-                    AS entry(fingerprint, subscriber_key, recipient)
-            WHERE NOT EXISTS (SELECT 1 FROM claimed WHERE claimed.subscriber_key = entry.subscriber_key)
-         ), budget AS (
-           SELECT
-             (SELECT count(*) FROM existing
-               WHERE attempt_at IS NOT NULL OR settled_at IS NOT NULL
-                  OR recipient_fingerprint IN (SELECT fingerprint FROM proposed))
-             + (SELECT count(*) FROM proposed
-                 WHERE fingerprint NOT IN (SELECT recipient_fingerprint FROM existing)) AS retained
-         ), gate AS (
-           -- The lease is part of the gate, not just of the row sources. A
-           -- stale worker sees an empty \`leased\`, which makes every source
-           -- empty and the budget zero; without this predicate the budget would
-           -- be satisfied and the delete below would reap the rows the
-           -- successor had already frozen under its own lease.
-           SELECT retained, retained <= $8::integer AND EXISTS (SELECT 1 FROM leased) AS ok FROM budget
-         ), dropped AS (
-           DELETE FROM ${recipientTable} stale USING gate, leased
-            WHERE gate.ok AND stale.namespace = $1 AND stale.transition_id = $2
-              AND stale.attempt_at IS NULL AND stale.settled_at IS NULL
-              AND NOT (stale.recipient_fingerprint IN (SELECT fingerprint FROM proposed))
-         ), added AS (
-           INSERT INTO ${recipientTable}
-             (namespace, transition_id, recipient_fingerprint, subscriber_key, recipient)
-           SELECT $1, $2, proposed.fingerprint, proposed.subscriber_key, proposed.recipient
-             FROM proposed, gate, leased WHERE gate.ok
-           ON CONFLICT (namespace, transition_id, recipient_fingerprint) DO NOTHING
-         ), pinned AS (
-           SELECT recipient FROM existing WHERE attempt_at IS NOT NULL AND settled_at IS NULL
-         )
-         SELECT (SELECT count(*) FROM leased) = 1 AS leased, gate.ok, gate.retained, entry.recipient
-           FROM gate
-           LEFT JOIN (SELECT recipient FROM proposed UNION ALL SELECT recipient FROM pinned) entry ON TRUE`,
-      [
-        namespace,
-        claim.transitionId,
-        claim.leaseOwner,
-        claim.leaseVersion,
-        rows.map((entry) => entry.fingerprint),
-        rows.map((entry) => entry.subscriberKey),
-        rows.map((entry) => JSON.stringify(entry.recipient)),
-        maxRetainedRecipients
-      ]
-    )
-  );
-  const verdict = committed.rows[0];
-  if (!verdict?.leased) {
-    throw new Error("Reporting notification recipient intent was not committed; the recovery lease was lost");
-  }
-  if (!verdict.ok) {
-    throw new Error(
-      `Reporting notification recipient intent would hold ${verdict.retained} recipients, above maxRetainedRecipients ${maxRetainedRecipients}; nothing was changed. Raise maxRetainedRecipients to at least the fanout plus the distinct subscribers this notification can replace, or reduce its destination churn`
-    );
-  }
-  return committed.rows.flatMap((row) => row.recipient === null ? [] : [row.recipient]);
-}
-async function settleClaimRecipients(db, table, recipientTable, namespace, claim, frozen, deliveries) {
-  const outcomes = new Map(deliveries.map((delivery) => [recipientFingerprint(delivery.recipient), delivery]));
-  const terminal = [];
-  const delivered = [];
-  for (const recipient of frozen) {
-    const fingerprint = recipientFingerprint(recipient);
-    const outcome = outcomes.get(fingerprint);
-    if (outcome === void 0) {
-      terminal.push(fingerprint);
-      continue;
-    }
-    if (outcome.disposition === "delivered") delivered.push(fingerprint);
-    else if (outcome.disposition === "terminal") terminal.push(fingerprint);
-  }
-  if (delivered.length > 0 || terminal.length > 0) {
-    await reportingActivityDatabaseOperation(
-      "Reporting notification recipient settlement failed",
-      () => db.query(
-        `WITH leased AS MATERIALIZED (
-           SELECT transition_id FROM ${table}
-            WHERE namespace = $1 AND transition_id = $2 AND state = 'pending'
-              AND lease_owner = $5 AND lease_version = $6::bigint
-              AND lease_expires_at >= clock_timestamp()
-              FOR UPDATE
-         )
-         UPDATE ${recipientTable} AS target SET settled_at = clock_timestamp(),
-           disposition = CASE WHEN target.recipient_fingerprint = ANY($3::text[]) THEN 'delivered' ELSE 'terminal' END
-          FROM leased
-          WHERE target.namespace = $1 AND target.transition_id = $2 AND target.settled_at IS NULL
-            AND (target.recipient_fingerprint = ANY($3::text[]) OR target.recipient_fingerprint = ANY($4::text[]))`,
-        [namespace, claim.transitionId, delivered, terminal, claim.leaseOwner, claim.leaseVersion]
-      )
-    );
-    await compactSettledRecipients(db, table, recipientTable, namespace, claim);
-  }
-  const remaining = await reportingActivityDatabaseOperation(
-    "Reporting notification recipient settlement failed",
-    () => db.query(
-      `SELECT count(*)::integer AS unsettled FROM ${recipientTable}
-          WHERE namespace = $1 AND transition_id = $2 AND settled_at IS NULL`,
-      [namespace, claim.transitionId]
-    )
-  );
-  const unsettled = remaining.rows[0]?.unsettled ?? 0;
-  return { settled: unsettled === 0, unsettled };
-}
-async function compactSettledRecipients(db, table, recipientTable, namespace, claim) {
-  await reportingActivityDatabaseOperation(
-    "Reporting notification recipient compaction failed",
-    () => db.query(
-      `WITH leased AS MATERIALIZED (
-         SELECT transition_id FROM ${table}
-          WHERE namespace = $1 AND transition_id = $2 AND state = 'pending'
-            AND lease_owner = $3 AND lease_version = $4::bigint
-            AND lease_expires_at >= clock_timestamp()
-            FOR UPDATE
-       )
-       DELETE FROM ${recipientTable} superseded USING leased
-        WHERE superseded.namespace = $1 AND superseded.transition_id = $2
-          AND superseded.settled_at IS NOT NULL
-          AND EXISTS (
-            SELECT 1 FROM ${recipientTable} survivor
-             WHERE survivor.namespace = superseded.namespace
-               AND survivor.transition_id = superseded.transition_id
-               AND survivor.subscriber_key = superseded.subscriber_key
-               AND survivor.settled_at IS NOT NULL
-               AND (survivor.disposition, survivor.recipient_fingerprint)
-                   > (superseded.disposition, superseded.recipient_fingerprint)
-          )`,
-      [namespace, claim.transitionId, claim.leaseOwner, claim.leaseVersion]
-    )
-  );
-}
-function classifyDelivery(delivery) {
-  const recipient = {
-    scope: delivery.scope,
-    subscriberId: delivery.subscriberId,
-    destinationGeneration: delivery.destinationGeneration
-  };
-  if (delivery.failure !== void 0 || !delivery.result) {
-    return { recipient, disposition: delivery.failure?.terminal === true ? "terminal" : "retryable" };
-  }
-  const suppression = delivery.result.suppression;
-  if (suppression) {
-    return {
-      recipient,
-      disposition: notificationSuppressionDisposition(suppression.reason) === "retryable" ? "retryable" : "terminal",
-      suppression: suppression.reason
-    };
-  }
-  if (delivery.result.delivered) return { recipient, disposition: "delivered" };
-  return { recipient, disposition: delivery.result.terminal === true ? "terminal" : "retryable" };
-}
-function recipientFingerprint(recipient) {
-  return canonicalJsonSha256({
-    scope: recipient.scope,
-    subscriberId: recipient.subscriberId,
-    destinationGeneration: recipient.destinationGeneration
-  });
-}
-function canonicalRecipients(candidates) {
-  return candidates.map((candidate) => {
-    const recipient = {
-      scope: candidate.scope,
-      subscriberId: candidate.subscriberId,
-      destinationGeneration: candidate.destinationGeneration
-    };
-    return {
-      fingerprint: recipientFingerprint(recipient),
-      subscriberKey: subscriberKey(recipient),
-      recipient
-    };
-  }).sort((left, right) => left.fingerprint < right.fingerprint ? -1 : 1);
-}
-function subscriberKey(recipient) {
-  return canonicalJsonSha256({ scope: recipient.scope, subscriberId: recipient.subscriberId });
-}
-async function renewClaim(db, table, namespace, claim, leaseMs) {
-  const result = await reportingActivityDatabaseOperation(
-    "Reporting notification lease renewal failed",
-    () => db.query(
-      `UPDATE ${table} SET lease_expires_at = clock_timestamp() + ($5::bigint * INTERVAL '1 millisecond')
-      WHERE namespace = $1 AND transition_id = $2 AND state = 'pending'
-        AND lease_owner = $3 AND lease_version = $4::bigint
-        AND lease_expires_at >= clock_timestamp()`,
-      [namespace, claim.transitionId, claim.leaseOwner, claim.leaseVersion, leaseMs]
-    )
-  );
-  return result.rowCount === 1;
-}
-async function projectClaim(db, table, namespace, claim, retentionMs) {
-  const result = await reportingActivityDatabaseOperation(
-    "Reporting notification projection settlement failed",
-    () => db.query(
-      `UPDATE ${table} SET state = 'projected', projected_at = clock_timestamp(),
-       retain_until = clock_timestamp() + ($5::bigint * INTERVAL '1 millisecond'),
-       lease_owner = NULL, lease_expires_at = NULL
-      WHERE namespace = $1 AND transition_id = $2 AND state = 'pending'
-        AND lease_owner = $3 AND lease_version = $4::bigint
-        AND lease_expires_at >= clock_timestamp()`,
-      [namespace, claim.transitionId, claim.leaseOwner, claim.leaseVersion, retentionMs]
-    )
-  );
-  return result.rowCount === 1;
-}
-async function releaseClaim(db, table, namespace, claim, retryAfterMs) {
-  const result = await reportingActivityDatabaseOperation(
-    "Reporting notification lease release failed",
-    () => db.query(
-      `UPDATE ${table} SET lease_owner = NULL, lease_expires_at = NULL,
-       next_attempt_at = clock_timestamp() + ($5::bigint * INTERVAL '1 millisecond')
-      WHERE namespace = $1 AND transition_id = $2 AND state = 'pending'
-        AND lease_owner = $3 AND lease_version = $4::bigint
-        AND lease_expires_at >= clock_timestamp()`,
-      [namespace, claim.transitionId, claim.leaseOwner, claim.leaseVersion, retryAfterMs]
-    )
-  );
-  return result.rowCount === 1;
-}
-async function abandonClaim(db, table, namespace, claim, retentionMs) {
-  const result = await reportingActivityDatabaseOperation(
-    "Reporting notification abandonment failed",
-    () => db.query(
-      `UPDATE ${table} SET state = 'abandoned',
-         abandoned_at = clock_timestamp(),
-         retain_until = clock_timestamp() + ($5::bigint * INTERVAL '1 millisecond'),
-         lease_owner = NULL, lease_expires_at = NULL
-      WHERE namespace = $1 AND transition_id = $2 AND state = 'pending'
-        AND lease_owner = $3 AND lease_version = $4::bigint
-        AND lease_expires_at >= clock_timestamp()`,
-      [namespace, claim.transitionId, claim.leaseOwner, claim.leaseVersion, retentionMs]
-    )
-  );
-  return result.rowCount === 1;
-}
-function encodeCursor(namespace, tenantId, accountId, before) {
-  const cursor = `ract1.${Buffer.from(JSON.stringify({ namespace, tenantId, accountId, before })).toString("base64url")}`;
-  if (Buffer.byteLength(cursor, "utf8") > MAX_CURSOR_BYTES) {
-    throw new Error("Reporting account activity cursor exceeds its internal bound");
-  }
-  return cursor;
-}
-function decodeCursor(cursor, namespace, tenantId, accountId) {
-  if (cursor === void 0) return void 0;
-  try {
-    if (Buffer.byteLength(cursor, "utf8") > MAX_CURSOR_BYTES) throw new Error();
-    if (!cursor.startsWith("ract1.")) throw new Error();
-    const value = JSON.parse(Buffer.from(cursor.slice(6), "base64url").toString("utf8"));
-    if (value.namespace !== namespace || value.tenantId !== tenantId || value.accountId !== accountId || typeof value.before !== "string" || !/^[1-9][0-9]*$/.test(value.before)) {
-      throw new Error();
-    }
-    if (BigInt(value.before) > 9223372036854775807n) throw new Error();
-    return value.before;
-  } catch {
-    throw new TypeError("Reporting account activity cursor is invalid for the authenticated scope");
-  }
-}
-function quoteIdentifier(value, maxBytes = 42) {
-  if (!/^[a-z_][a-z0-9_]*$/.test(value) || Buffer.byteLength(value, "utf8") > maxBytes) {
-    throw new TypeError(
-      `Invalid reporting activity table name ${JSON.stringify(value)}: use at most ${maxBytes} lowercase characters`
-    );
-  }
-  return `"${value}"`;
-}
-function assertIdentifier(value, name, maxBytes) {
-  if (typeof value !== "string" || value.length === 0 || value.includes("\0") || Buffer.byteLength(value) > maxBytes) {
-    throw new TypeError(`${name} must be a non-empty UTF-8 string of at most ${maxBytes} bytes without NUL`);
-  }
-}
-function positiveInteger(value, name) {
-  if (!Number.isSafeInteger(value) || value < 1) throw new TypeError(`${name} must be a positive safe integer`);
-}
-function boundedInteger(value, name, minimum, maximum) {
-  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
-    throw new TypeError(`${name} must be an integer from ${minimum} through ${maximum}`);
-  }
-}
-function isPromiseLike(value) {
-  return value != null && typeof value === "object" && typeof value.then === "function";
-}
-function isPostgresUndefinedTable(value) {
-  return typeof value === "object" && value !== null && value.code === "42P01";
-}
-function reportProjectionError(observer, error, claim) {
-  try {
-    const result = observer?.(error, {
-      transitionId: claim.transitionId,
-      tenantId: claim.tenantId,
-      accountId: claim.accountId,
-      attemptCount: claim.attemptCount
-    });
-    if (isPromiseLike(result)) void Promise.resolve(result).catch(() => {
-    });
-  } catch {
-  }
-}
-async function reportingActivityDatabaseOperation(message, operation) {
-  try {
-    return await operation();
-  } catch (cause) {
-    throw new Error(message, { cause });
-  }
-}
-function asIso(value) {
-  return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
-}
-export {
-  REPORTING_NOTIFICATION_ACTIVITY_MIGRATION,
-  ReportingNotificationRetryableSuppressionError,
-  createPostgresReportingNotificationActivityRuntime,
-  createPostgresReportingNotificationAttemptCheckpoint,
-  getReportingNotificationActivityMigration,
-  recipientTableName
-};