@adcp/sdk 15.7.1 → 15.8.0

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

@@ -1,6 +1,6 @@
 import type { ReportingAdjustmentReceipt, ReportingMaterialization, ReportingReceipt } from '../../types/index.mjs';
 import { projectReportingObligationHealthV1 } from './health.mjs';
-import type { ReportingConsumerMismatchEscalationV1, ReportingHealthV1, ReportingLedgerAdjustmentSnapshotV1, ReportingLedgerCoverageV1, ReportingLedgerObligationV1, ReportingLedgerRevisionSnapshotV1, ReportingLedgerStore, ReportingManagedDeliveryBindingV1, ReportingDeliveryHandlerV1, ReportingStatusHandlerV1 } from './types.mjs';
+import type { ReportingConsumerMismatchEscalationV1, ReportingHealthV1, ReportingLedgerAdjustmentSnapshotV1, ReportingLedgerCoverageV1, ReportingLedgerObligationV1, ReportingLedgerRevisionSnapshotV1, ReportingLedgerStore, ReportingManagedDeliveryBindingV1, CreateReportingDeliveryHandlerOptionsV1, ReportingDeliveryHandlerV1, ReportingStatusHandlerV1 } from './types.mjs';
 export interface ReportingStatusConsumerScopeOptionsV1<TContext = unknown> {
     resolveConsumerId(context: TContext): string | Promise<string>;
     /**
@@ -21,8 +21,15 @@ export declare function createReportingStatusHandler<TContext = unknown>(store:
  * them through the exact `get_media_buy_delivery` read.
  */
 export declare const REPORTING_STATUS_REVISION_VIEW_MAX_ROWS = 10000;
-/** Exact revision reader for createAdcpServer's getMediaBuyDelivery slot. */
-export declare function createReportingDeliveryHandler(store: ReportingLedgerStore): ReportingDeliveryHandlerV1;
+/**
+ * Exact revision reader for createAdcpServer's getMediaBuyDelivery slot.
+ *
+ * With `legacyRevisionReader`, a revision the SDK ledger does not hold for the
+ * resolved account is offered to that reader (see
+ * {@link ReportingLegacyRevisionReaderV1}). The SDK always answers first, and
+ * only that one not-found case falls through.
+ */
+export declare function createReportingDeliveryHandler(store: ReportingLedgerStore, options?: CreateReportingDeliveryHandlerOptionsV1): ReportingDeliveryHandlerV1;
 export interface ProjectManagedDeliveryInputV1 {
     obligation: ReportingLedgerObligationV1;
     binding?: ReportingManagedDeliveryBindingV1;

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

@@ -1,6 +1,6 @@
 import type { ReportingAdjustmentReceipt, ReportingMaterialization, ReportingReceipt } from '../../types';
 import { projectReportingObligationHealthV1 } from './health';
-import type { ReportingConsumerMismatchEscalationV1, ReportingHealthV1, ReportingLedgerAdjustmentSnapshotV1, ReportingLedgerCoverageV1, ReportingLedgerObligationV1, ReportingLedgerRevisionSnapshotV1, ReportingLedgerStore, ReportingManagedDeliveryBindingV1, ReportingDeliveryHandlerV1, ReportingStatusHandlerV1 } from './types';
+import type { ReportingConsumerMismatchEscalationV1, ReportingHealthV1, ReportingLedgerAdjustmentSnapshotV1, ReportingLedgerCoverageV1, ReportingLedgerObligationV1, ReportingLedgerRevisionSnapshotV1, ReportingLedgerStore, ReportingManagedDeliveryBindingV1, CreateReportingDeliveryHandlerOptionsV1, ReportingDeliveryHandlerV1, ReportingStatusHandlerV1 } from './types';
 export interface ReportingStatusConsumerScopeOptionsV1<TContext = unknown> {
     resolveConsumerId(context: TContext): string | Promise<string>;
     /**
@@ -21,8 +21,15 @@ export declare function createReportingStatusHandler<TContext = unknown>(store:
  * them through the exact `get_media_buy_delivery` read.
  */
 export declare const REPORTING_STATUS_REVISION_VIEW_MAX_ROWS = 10000;
-/** Exact revision reader for createAdcpServer's getMediaBuyDelivery slot. */
-export declare function createReportingDeliveryHandler(store: ReportingLedgerStore): ReportingDeliveryHandlerV1;
+/**
+ * Exact revision reader for createAdcpServer's getMediaBuyDelivery slot.
+ *
+ * With `legacyRevisionReader`, a revision the SDK ledger does not hold for the
+ * resolved account is offered to that reader (see
+ * {@link ReportingLegacyRevisionReaderV1}). The SDK always answers first, and
+ * only that one not-found case falls through.
+ */
+export declare function createReportingDeliveryHandler(store: ReportingLedgerStore, options?: CreateReportingDeliveryHandlerOptionsV1): ReportingDeliveryHandlerV1;
 export interface ProjectManagedDeliveryInputV1 {
     obligation: ReportingLedgerObligationV1;
     binding?: ReportingManagedDeliveryBindingV1;

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

@@ -416,9 +416,14 @@ function reportingRevisionNotFound() {
     field: "reporting_revision_id"
   });
 }
-function createReportingDeliveryHandler(store) {
+const SDK_REVISION_NOT_OWNED = /* @__PURE__ */ Symbol("sdk-revision-not-owned");
+function createReportingDeliveryHandler(store, options = {}) {
+  const legacyRevisionReader = options.legacyRevisionReader;
+  if (legacyRevisionReader !== void 0 && typeof legacyRevisionReader !== "function") {
+    throw new TypeError("legacyRevisionReader must be a function");
+  }
   const activeReadsByAccount = /* @__PURE__ */ new Map();
-  return async (request, context) => {
+  const readFromSdkLedger = async (request, context) => {
     const accountId = resolvedAccountId(context.account);
     let releaseReadSlot;
     try {
@@ -440,9 +445,9 @@ function createReportingDeliveryHandler(store) {
         });
       }
       const revision = await (0, import_revision_metadata.getRevisionMetadataFromStore)(store, raw.reporting_revision_id, accountId);
-      if (!revision) throw reportingRevisionNotFound();
+      if (!revision) return SDK_REVISION_NOT_OWNED;
       const obligation = await store.getObligation(revision.reporting_obligation_id);
-      if (!obligation || obligation.account.account_id !== accountId) throw reportingRevisionNotFound();
+      if (!obligation || obligation.account.account_id !== accountId) return SDK_REVISION_NOT_OWNED;
       const pagination = isRecord(raw.pagination) ? raw.pagination : {};
       const maxResults = typeof pagination.max_results === "number" && Number.isFinite(pagination.max_results) ? Math.max(1, Math.min(500, Math.trunc(pagination.max_results))) : 100;
       const totalCount = revision.binding.rowCount;
@@ -520,6 +525,14 @@ function createReportingDeliveryHandler(store) {
       releaseReadSlot();
     }
   };
+  return async (request, context) => {
+    const result = await readFromSdkLedger(request, context);
+    if (result !== SDK_REVISION_NOT_OWNED) return result;
+    if (!legacyRevisionReader) throw reportingRevisionNotFound();
+    const legacy = await legacyRevisionReader(request, context);
+    if (legacy === null || legacy === void 0) throw reportingRevisionNotFound();
+    return legacy;
+  };
 }
 function resolvedAccountId(account) {
   const resolved = isRecord(account) ? account : {};

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

@@ -399,9 +399,14 @@ function reportingRevisionNotFound() {
     field: "reporting_revision_id"
   });
 }
-function createReportingDeliveryHandler(store) {
+const SDK_REVISION_NOT_OWNED = /* @__PURE__ */ Symbol("sdk-revision-not-owned");
+function createReportingDeliveryHandler(store, options = {}) {
+  const legacyRevisionReader = options.legacyRevisionReader;
+  if (legacyRevisionReader !== void 0 && typeof legacyRevisionReader !== "function") {
+    throw new TypeError("legacyRevisionReader must be a function");
+  }
   const activeReadsByAccount = /* @__PURE__ */ new Map();
-  return async (request, context) => {
+  const readFromSdkLedger = async (request, context) => {
     const accountId = resolvedAccountId(context.account);
     let releaseReadSlot;
     try {
@@ -423,9 +428,9 @@ function createReportingDeliveryHandler(store) {
         });
       }
       const revision = await getRevisionMetadataFromStore(store, raw.reporting_revision_id, accountId);
-      if (!revision) throw reportingRevisionNotFound();
+      if (!revision) return SDK_REVISION_NOT_OWNED;
       const obligation = await store.getObligation(revision.reporting_obligation_id);
-      if (!obligation || obligation.account.account_id !== accountId) throw reportingRevisionNotFound();
+      if (!obligation || obligation.account.account_id !== accountId) return SDK_REVISION_NOT_OWNED;
       const pagination = isRecord(raw.pagination) ? raw.pagination : {};
       const maxResults = typeof pagination.max_results === "number" && Number.isFinite(pagination.max_results) ? Math.max(1, Math.min(500, Math.trunc(pagination.max_results))) : 100;
       const totalCount = revision.binding.rowCount;
@@ -503,6 +508,14 @@ function createReportingDeliveryHandler(store) {
       releaseReadSlot();
     }
   };
+  return async (request, context) => {
+    const result = await readFromSdkLedger(request, context);
+    if (result !== SDK_REVISION_NOT_OWNED) return result;
+    if (!legacyRevisionReader) throw reportingRevisionNotFound();
+    const legacy = await legacyRevisionReader(request, context);
+    if (legacy === null || legacy === void 0) throw reportingRevisionNotFound();
+    return legacy;
+  };
 }
 function resolvedAccountId(account) {
   const resolved = isRecord(account) ? account : {};

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

@@ -2,7 +2,7 @@ import type { ReportingAdjustmentReceipt, ReportingDeliveryCapabilities, Reporti
 import type { AdcpToolMap } from '../../server/create-adcp-server.mjs';
 import { createReportingDeliveryHandler, createReportingStatusHandler } from './handler.mjs';
 import type { ReportingStatusConsumerScopeOptionsV1 } from './handler.mjs';
-import type { ReportingLedgerAdjustmentV1, ReportingLedgerObligationV1, ReportingLedgerRevisionV1, ReportingLedgerStore, ReportingManagedDeliveryBindingV1 } from './types.mjs';
+import type { ReportingLedgerAdjustmentV1, ReportingLegacyRevisionReaderV1, ReportingLedgerObligationV1, ReportingLedgerRevisionV1, ReportingLedgerStore, ReportingManagedDeliveryBindingV1 } from './types.mjs';
 export interface ReportingDestinationAuthorizationV1 {
     account_id: string;
     destination_ref: string;
@@ -274,6 +274,8 @@ export interface CreateReportingManagedDeliveryRuntimeOptionsV1<TContext extends
     account?: unknown;
 }> {
     coreStore: ReportingLedgerStore;
+    /** Exact-revision fallback for revisions the SDK ledger does not hold. */
+    legacyRevisionReader?: ReportingLegacyRevisionReaderV1;
     store: ReportingManagedDeliveryStore & Required<Pick<ReportingManagedDeliveryStore, 'adoptAdvertisedPolicies'>>;
     adapter: ReportingManagedDeliveryAdapterV1;
     offerings: ReportingDeliveryCapabilities['offerings'];

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

@@ -2,7 +2,7 @@ import type { ReportingAdjustmentReceipt, ReportingDeliveryCapabilities, Reporti
 import type { AdcpToolMap } from '../../server/create-adcp-server';
 import { createReportingDeliveryHandler, createReportingStatusHandler } from './handler';
 import type { ReportingStatusConsumerScopeOptionsV1 } from './handler';
-import type { ReportingLedgerAdjustmentV1, ReportingLedgerObligationV1, ReportingLedgerRevisionV1, ReportingLedgerStore, ReportingManagedDeliveryBindingV1 } from './types';
+import type { ReportingLedgerAdjustmentV1, ReportingLegacyRevisionReaderV1, ReportingLedgerObligationV1, ReportingLedgerRevisionV1, ReportingLedgerStore, ReportingManagedDeliveryBindingV1 } from './types';
 export interface ReportingDestinationAuthorizationV1 {
     account_id: string;
     destination_ref: string;
@@ -274,6 +274,8 @@ export interface CreateReportingManagedDeliveryRuntimeOptionsV1<TContext extends
     account?: unknown;
 }> {
     coreStore: ReportingLedgerStore;
+    /** Exact-revision fallback for revisions the SDK ledger does not hold. */
+    legacyRevisionReader?: ReportingLegacyRevisionReaderV1;
     store: ReportingManagedDeliveryStore & Required<Pick<ReportingManagedDeliveryStore, 'adoptAdvertisedPolicies'>>;
     adapter: ReportingManagedDeliveryAdapterV1;
     offerings: ReportingDeliveryCapabilities['offerings'];

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

@@ -89,7 +89,10 @@ async function createReportingManagedDeliveryRuntime(options) {
     ...options.consumerMismatchEscalation ? { consumerMismatchEscalation: options.consumerMismatchEscalation } : {}
   } : void 0;
   const getReportingStatus = (0, import_handler.createReportingStatusHandler)(options.coreStore, statusOptions);
-  const getMediaBuyDelivery = (0, import_handler.createReportingDeliveryHandler)(options.coreStore);
+  const getMediaBuyDelivery = (0, import_handler.createReportingDeliveryHandler)(
+    options.coreStore,
+    options.legacyRevisionReader ? { legacyRevisionReader: options.legacyRevisionReader } : {}
+  );
   const syncReportingReceipts = reconciledBilling ? createSyncReportingReceiptsHandler(options.store, options.resolveConsumerId) : void 0;
   const reportingDeliveryCapabilities = {
     supported: true,

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

@@ -62,7 +62,10 @@ async function createReportingManagedDeliveryRuntime(options) {
     ...options.consumerMismatchEscalation ? { consumerMismatchEscalation: options.consumerMismatchEscalation } : {}
   } : void 0;
   const getReportingStatus = createReportingStatusHandler(options.coreStore, statusOptions);
-  const getMediaBuyDelivery = createReportingDeliveryHandler(options.coreStore);
+  const getMediaBuyDelivery = createReportingDeliveryHandler(
+    options.coreStore,
+    options.legacyRevisionReader ? { legacyRevisionReader: options.legacyRevisionReader } : {}
+  );
   const syncReportingReceipts = reconciledBilling ? createSyncReportingReceiptsHandler(options.store, options.resolveConsumerId) : void 0;
   const reportingDeliveryCapabilities = {
     supported: true,

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

@@ -150,6 +150,12 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     }>;
     /** Append one host change-feed row inside the caller's account-locked transaction. */
     private appendChange;
+    /**
+     * Throws `INVALID_INPUT` when any configured object row binding's key template omits
+     * `{revision_key}`, which makes snapshot compaction unsafe (see `compactSupersededSnapshots`).
+     * Called by `compactSupersededSnapshots` and by service construction when compaction is enabled.
+     */
+    assertCompactionSafeRowBindings(): void;
     /** Probe and register row storage when enabled. Safe to call repeatedly. */
     readyRowStorage(): Promise<void>;
     /**
@@ -318,6 +324,65 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
         }[];
     }>;
     private retirePeriod;
+    /**
+     * Compact superseded snapshot revisions to metadata only, as adcontextprotocol/adcp#8100
+     * permits (`reporting-revision.json` `content_retention`). Opt-in: nothing calls this
+     * unless the host enables `compaction` in maintenance, and it must not be enabled in
+     * production before the AdCP release that takes compaction into effect (the next
+     * eligible minor after November 20, 2026).
+     *
+     * A snapshot revision is compacted only when every one of these holds:
+     *
+     * - it is superseded: a later revision names it in `supersedes_reporting_revision_id`
+     *   (so a current revision, and every official revision, is never compacted);
+     * - it is not the revision the current, unsuperseded revision names;
+     * - its recovery grace has passed: `max(automatedRecoveryWindowSeconds, 3600)` seconds
+     *   since its successor's `created_at`;
+     * - while its window is open (`statusRetentionDays` since its successor's `created_at`),
+     *   no caller's reporting receipt (any status) names it and no caller's current consumer
+     *   status statement of `received`, `unreadable` or `content_mismatch` names it. The
+     *   check spans every caller, so content any caller is entitled to is kept;
+     * - it has rows (nothing to reclaim otherwise, and an empty exact read is still correct);
+     * - no live obligation lease, no pending materialization of it, and no live change-feed
+     *   consumer that has not yet passed its change row (the holds retirement applies,
+     *   narrowed to this revision).
+     *
+     * Only row content is dropped: the revision header, its manifest and every metadata
+     * listing stay. The row set is marked `pruned`, so an exact read answers
+     * `ROWS_EXPIRED`, which the handlers surface as the same nondisclosing
+     * `REFERENCE_NOT_FOUND` as an unknown ID. No change-feed row is recorded: the revision's
+     * metadata is unchanged, and a sink still catching up holds compaction back.
+     *
+     * Compaction is resumable and runs in the same three phases as retirement, under the
+     * account lock where eligibility is decided:
+     *
+     * 1. re-check eligibility and mark the row set `pruning`, so reads answer as expired and
+     *    no new revision can share its chunks;
+     * 2. delete external objects at their recorded versions, skipping any object another
+     *    row set that is not being pruned still references (chunk sharing);
+     * 3. delete the chunk manifest rows and any PostgreSQL chunk body nothing else
+     *    references, and mark the row set `pruned`.
+     *
+     * A crash after phase 1 leaves a `pruning` row set that the next pass resumes.
+     */
+    compactSupersededSnapshots(input: {
+        statusRetentionDays: number;
+        automatedRecoveryWindowSeconds: number;
+        maxFeedHoldDays?: number;
+        limit?: number;
+        account_id?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        compacted: number;
+        failed: string[];
+        /** Secret-free cause per failed revision: a row-store code or the error class name. */
+        failures: {
+            reporting_obligation_id: string;
+            reporting_revision_id: string;
+            cause: string;
+        }[];
+    }>;
+    private compactSnapshot;
     /**
      * Resolve abandoned object uploads (spec §4.3). An expired `open` write
      * intent whose ledger commit never happened is moved to `sweeping` under
@@ -335,6 +400,28 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
         objectsDeleted: number;
         failed: number;
     }>;
+    /**
+     * Delete external row objects, skipping any object another row set still references.
+     *
+     * A custom `keyTemplate` need only include `{content_sha256}` and `{chunk_index}`, so row sets
+     * from different obligations or accounts with identical chunk content can share one object (a
+     * create-only write adopts an existing object). An object is therefore deleted only when no
+     * chunk of a live (or unavailable) row set outside this operation references the same binding,
+     * key and native version, and no other open write intent created it. Row sets already `pruning`
+     * or `pruned` do not count: their own operation deletes the object, and counting them would let
+     * two concurrent retirements each skip the object and leak it. `scope` names what this
+     * operation is deleting: an obligation (retirement) or a row set (compaction).
+     *
+     * The check and the provider delete run in one transaction under a per-object advisory lock.
+     * A commit that adopts an existing object takes the same lock before it inserts its chunk rows
+     * and re-verifies the object under it (`writePreparedRowSet`), and holds it until commit. So
+     * either the delete wins the lock and the adopting commit then fails cleanly, or the commit wins
+     * and the delete sees its chunk rows and skips. A skipped object stays for the row set that owns
+     * it: that row set's own retirement, compaction or sweep deletes it, because by then nothing
+     * else references it. Locks are taken one object at a time, never while waiting on the account
+     * lock, so commits (account lock, then object locks) cannot deadlock with these deletes.
+     */
+    private deleteUnreferencedObjects;
     private optionalTables;
     /**
      * Upload an object-kind row set before its ledger commit (spec §3.5):

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

@@ -150,6 +150,12 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     }>;
     /** Append one host change-feed row inside the caller's account-locked transaction. */
     private appendChange;
+    /**
+     * Throws `INVALID_INPUT` when any configured object row binding's key template omits
+     * `{revision_key}`, which makes snapshot compaction unsafe (see `compactSupersededSnapshots`).
+     * Called by `compactSupersededSnapshots` and by service construction when compaction is enabled.
+     */
+    assertCompactionSafeRowBindings(): void;
     /** Probe and register row storage when enabled. Safe to call repeatedly. */
     readyRowStorage(): Promise<void>;
     /**
@@ -318,6 +324,65 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
         }[];
     }>;
     private retirePeriod;
+    /**
+     * Compact superseded snapshot revisions to metadata only, as adcontextprotocol/adcp#8100
+     * permits (`reporting-revision.json` `content_retention`). Opt-in: nothing calls this
+     * unless the host enables `compaction` in maintenance, and it must not be enabled in
+     * production before the AdCP release that takes compaction into effect (the next
+     * eligible minor after November 20, 2026).
+     *
+     * A snapshot revision is compacted only when every one of these holds:
+     *
+     * - it is superseded: a later revision names it in `supersedes_reporting_revision_id`
+     *   (so a current revision, and every official revision, is never compacted);
+     * - it is not the revision the current, unsuperseded revision names;
+     * - its recovery grace has passed: `max(automatedRecoveryWindowSeconds, 3600)` seconds
+     *   since its successor's `created_at`;
+     * - while its window is open (`statusRetentionDays` since its successor's `created_at`),
+     *   no caller's reporting receipt (any status) names it and no caller's current consumer
+     *   status statement of `received`, `unreadable` or `content_mismatch` names it. The
+     *   check spans every caller, so content any caller is entitled to is kept;
+     * - it has rows (nothing to reclaim otherwise, and an empty exact read is still correct);
+     * - no live obligation lease, no pending materialization of it, and no live change-feed
+     *   consumer that has not yet passed its change row (the holds retirement applies,
+     *   narrowed to this revision).
+     *
+     * Only row content is dropped: the revision header, its manifest and every metadata
+     * listing stay. The row set is marked `pruned`, so an exact read answers
+     * `ROWS_EXPIRED`, which the handlers surface as the same nondisclosing
+     * `REFERENCE_NOT_FOUND` as an unknown ID. No change-feed row is recorded: the revision's
+     * metadata is unchanged, and a sink still catching up holds compaction back.
+     *
+     * Compaction is resumable and runs in the same three phases as retirement, under the
+     * account lock where eligibility is decided:
+     *
+     * 1. re-check eligibility and mark the row set `pruning`, so reads answer as expired and
+     *    no new revision can share its chunks;
+     * 2. delete external objects at their recorded versions, skipping any object another
+     *    row set that is not being pruned still references (chunk sharing);
+     * 3. delete the chunk manifest rows and any PostgreSQL chunk body nothing else
+     *    references, and mark the row set `pruned`.
+     *
+     * A crash after phase 1 leaves a `pruning` row set that the next pass resumes.
+     */
+    compactSupersededSnapshots(input: {
+        statusRetentionDays: number;
+        automatedRecoveryWindowSeconds: number;
+        maxFeedHoldDays?: number;
+        limit?: number;
+        account_id?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        compacted: number;
+        failed: string[];
+        /** Secret-free cause per failed revision: a row-store code or the error class name. */
+        failures: {
+            reporting_obligation_id: string;
+            reporting_revision_id: string;
+            cause: string;
+        }[];
+    }>;
+    private compactSnapshot;
     /**
      * Resolve abandoned object uploads (spec §4.3). An expired `open` write
      * intent whose ledger commit never happened is moved to `sweeping` under
@@ -335,6 +400,28 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
         objectsDeleted: number;
         failed: number;
     }>;
+    /**
+     * Delete external row objects, skipping any object another row set still references.
+     *
+     * A custom `keyTemplate` need only include `{content_sha256}` and `{chunk_index}`, so row sets
+     * from different obligations or accounts with identical chunk content can share one object (a
+     * create-only write adopts an existing object). An object is therefore deleted only when no
+     * chunk of a live (or unavailable) row set outside this operation references the same binding,
+     * key and native version, and no other open write intent created it. Row sets already `pruning`
+     * or `pruned` do not count: their own operation deletes the object, and counting them would let
+     * two concurrent retirements each skip the object and leak it. `scope` names what this
+     * operation is deleting: an obligation (retirement) or a row set (compaction).
+     *
+     * The check and the provider delete run in one transaction under a per-object advisory lock.
+     * A commit that adopts an existing object takes the same lock before it inserts its chunk rows
+     * and re-verifies the object under it (`writePreparedRowSet`), and holds it until commit. So
+     * either the delete wins the lock and the adopting commit then fails cleanly, or the commit wins
+     * and the delete sees its chunk rows and skips. A skipped object stays for the row set that owns
+     * it: that row set's own retirement, compaction or sweep deletes it, because by then nothing
+     * else references it. Locks are taken one object at a time, never while waiting on the account
+     * lock, so commits (account lock, then object locks) cannot deadlock with these deletes.
+     */
+    private deleteUnreferencedObjects;
     private optionalTables;
     /**
      * Upload an object-kind row set before its ledger commit (spec §3.5):