@adcp/sdk 14.0.0-rc.38 → 14.0.0-rc.39

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

@@ -0,0 +1,1110 @@
+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 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);
+  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)
+  )
+);
+
+-- 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'));
+  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)
+    );
+  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}_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, ...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 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 port = {
+    async recordTransition(input, transaction) {
+      if (!transaction || typeof transaction.query !== "function") {
+        throw new TypeError("Reporting notification/activity persistence requires the active ledger transaction");
+      }
+      const accountId = input.obligation.account.account_id;
+      assertIdentifier(accountId, "accountId", 512);
+      assertIdentifier(input.transition.transitionId, "transitionId", 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);
+      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;
+      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, input.transition.transitionId]
+          );
+          const existingIntent = existing.rows[0];
+          if (existingIntent) {
+            if (existingIntent.intent_fingerprint !== fingerprint || existingIntent.tenant_scope !== tenantId || existingIntent.account_id !== accountId || existingIntent.obligation_id !== input.obligation.reporting_obligation_id) {
+              throw new Error("Reporting transition identity conflicts with existing notification/activity intent");
+            }
+            return;
+          }
+          const pending = await transaction.query(
+            `SELECT COUNT(*)::integer AS count FROM ${table}
+              WHERE namespace = $1 AND tenant_scope = $2 AND state = 'pending'`,
+            [namespace, tenantId]
+          );
+          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,
+            input.transition.transitionId,
+            tenantId,
+            accountId,
+            input.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 transition identity conflicts with existing notification/activity intent");
+      }
+    }
+  };
+  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`
+        );
+      } 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
+      };
+      for (let index = 0; index < limit; index += 1) {
+        const [claim] = await claimPending(options.db, table, namespace, ownerToken, leaseMs, 1);
+        if (!claim) break;
+        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 {
+          if (claim.activity.notificationType !== "reporting.status_changed") {
+            throw new Error("Pending reporting activity is not a health-transition notification");
+          }
+          let frozen = [];
+          let froze = false;
+          const result = await options.notifications.emit({
+            emissionId: claim.activity.activityId,
+            notificationId: claim.activity.transitionId,
+            notificationType: "reporting.status_changed",
+            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) {
+      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)
+          ORDER BY activity_sequence DESC
+          LIMIT $5`,
+          [namespace, input.tenantId, input.accountId, before ?? null, limit + 1]
+        )
+      );
+      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)
+          )
+        } : {}
+      };
+    },
+    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 notificationPayload(activity) {
+  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
+  };
+}
+async function claimPending(db, table, namespace, ownerToken, leaseMs, limit) {
+  const result = await reportingActivityDatabaseOperation(
+    "Reporting notification recovery claim failed",
+    () => db.query(
+      `WITH candidates AS (
+       SELECT namespace, transition_id 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())
+        ORDER BY next_attempt_at, activity_sequence
+        FOR UPDATE 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
+};