@adcp/sdk 15.9.0 → 16.0.0-beta.1

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

@@ -12,12 +12,22 @@ interface ReportingPgClient {
     query<Row extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<ReportingPgResult<Row>>;
     release(error?: Error): void;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface ReportingPgPool {
     query<Row extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<ReportingPgResult<Row>>;
     connect(): Promise<ReportingPgClient>;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare const REPORTING_LEDGER_MIGRATION: string;
-/** Constraint installed by {@link REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION}. */
+/**
+ * Constraint installed by {@link REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION}.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare const REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT = "adcp_reporting_transitions_finality_recorded";
 /**
  * Cutover migration that fences pre-SDK-14 writers out of the transition log.
@@ -39,8 +49,13 @@ export declare const REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT = "adcp_reportin
  * multiply finality-only events, which is the intended trade: loud rejection
  * beats a quietly broken invariant. Idempotent and re-runnable; it takes no lock
  * once installed.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
  */
 export declare const REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION: string;
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface PostgresReportingLedgerStoreOptions {
     /** Assert that the supplied PostgreSQL database/schema is isolated to this deployment. */
     acknowledgeIsolatedDatabase?: boolean;
@@ -103,21 +118,38 @@ export interface PostgresReportingLedgerStoreOptions {
      */
     changeFeed?: boolean;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare class ReportingLedgerLeaseLostError extends Error {
     constructor(message?: string);
 }
-/** A planner or writer named a period whose ledger records were retired by retention. */
+/**
+ * A planner or writer named a period whose ledger records were retired by retention.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare class ReportingLedgerPeriodRetiredError extends Error {
     constructor(message?: string);
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare class ReportingLedgerContinuityError extends Error {
     constructor(message?: string);
 }
-/** Bounded global cleanup for expired cursor snapshots and changes checkpoints. */
+/**
+ * Bounded global cleanup for expired cursor snapshots and changes checkpoints.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function sweepExpiredReportingLedgerState(pool: Pick<ReportingPgPool, 'query'>, limit?: number): Promise<{
     snapshotsDeleted: number;
     checkpointsDeleted: number;
 }>;
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare class PostgresReportingLedgerStore implements ReportingLedgerStore {
     private readonly pool;
     /**
@@ -151,9 +183,11 @@ 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.
+     * Defense in depth for snapshot compaction (see `compactSupersededSnapshots`): throws `INVALID_INPUT`
+     * if a writable object row binding's key template omits `{revision_key}`. Every such binding is
+     * already refused when the store is configured, so this only guards a configuration changed after
+     * construction; `readOnly` bindings are skipped. Called by `compactSupersededSnapshots` and by
+     * service construction when compaction is enabled.
      */
     assertCompactionSafeRowBindings(): void;
     /** Probe and register row storage when enabled. Safe to call repeatedly. */
@@ -475,9 +509,9 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     /**
      * 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
+     * Object keys are unique per row set (every writable template includes `{revision_key}`), but header-only
+     * revisions share chunks within an obligation and rows written under an older template can name one
+     * object from several row sets. 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

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

@@ -12,12 +12,22 @@ interface ReportingPgClient {
     query<Row extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<ReportingPgResult<Row>>;
     release(error?: Error): void;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface ReportingPgPool {
     query<Row extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<ReportingPgResult<Row>>;
     connect(): Promise<ReportingPgClient>;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare const REPORTING_LEDGER_MIGRATION: string;
-/** Constraint installed by {@link REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION}. */
+/**
+ * Constraint installed by {@link REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION}.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare const REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT = "adcp_reporting_transitions_finality_recorded";
 /**
  * Cutover migration that fences pre-SDK-14 writers out of the transition log.
@@ -39,8 +49,13 @@ export declare const REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT = "adcp_reportin
  * multiply finality-only events, which is the intended trade: loud rejection
  * beats a quietly broken invariant. Idempotent and re-runnable; it takes no lock
  * once installed.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
  */
 export declare const REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION: string;
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface PostgresReportingLedgerStoreOptions {
     /** Assert that the supplied PostgreSQL database/schema is isolated to this deployment. */
     acknowledgeIsolatedDatabase?: boolean;
@@ -103,21 +118,38 @@ export interface PostgresReportingLedgerStoreOptions {
      */
     changeFeed?: boolean;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare class ReportingLedgerLeaseLostError extends Error {
     constructor(message?: string);
 }
-/** A planner or writer named a period whose ledger records were retired by retention. */
+/**
+ * A planner or writer named a period whose ledger records were retired by retention.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare class ReportingLedgerPeriodRetiredError extends Error {
     constructor(message?: string);
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare class ReportingLedgerContinuityError extends Error {
     constructor(message?: string);
 }
-/** Bounded global cleanup for expired cursor snapshots and changes checkpoints. */
+/**
+ * Bounded global cleanup for expired cursor snapshots and changes checkpoints.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function sweepExpiredReportingLedgerState(pool: Pick<ReportingPgPool, 'query'>, limit?: number): Promise<{
     snapshotsDeleted: number;
     checkpointsDeleted: number;
 }>;
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare class PostgresReportingLedgerStore implements ReportingLedgerStore {
     private readonly pool;
     /**
@@ -151,9 +183,11 @@ 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.
+     * Defense in depth for snapshot compaction (see `compactSupersededSnapshots`): throws `INVALID_INPUT`
+     * if a writable object row binding's key template omits `{revision_key}`. Every such binding is
+     * already refused when the store is configured, so this only guards a configuration changed after
+     * construction; `readOnly` bindings are skipped. Called by `compactSupersededSnapshots` and by
+     * service construction when compaction is enabled.
      */
     assertCompactionSafeRowBindings(): void;
     /** Probe and register row storage when enabled. Safe to call repeatedly. */
@@ -475,9 +509,9 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     /**
      * 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
+     * Object keys are unique per row set (every writable template includes `{revision_key}`), but header-only
+     * revisions share chunks within an obligation and rows written under an older template can name one
+     * object from several row sets. 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

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

@@ -468,9 +468,11 @@ class PostgresReportingLedgerStore {
     );
   }
   /**
-   * 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.
+   * Defense in depth for snapshot compaction (see `compactSupersededSnapshots`): throws `INVALID_INPUT`
+   * if a writable object row binding's key template omits `{revision_key}`. Every such binding is
+   * already refused when the store is configured, so this only guards a configuration changed after
+   * construction; `readOnly` bindings are skipped. Called by `compactSupersededSnapshots` and by
+   * service construction when compaction is enabled.
    */
   assertCompactionSafeRowBindings() {
     this.rowStorage.assertCompactionSafeKeyTemplates();
@@ -857,6 +859,7 @@ ${managedDueArm}       )
       rows: revision.rows,
       finality: revision.finality,
       periodStart: lease.obligation.period.start,
+      sourceTimezone: lease.obligation.period.sourceTimezone,
       binding: revision.binding,
       controlTotals: revision.wireRevision.control_totals
     }) : void 0;
@@ -1015,6 +1018,7 @@ ${managedDueArm}       )
       obligationId: adjustment.reporting_obligation_id,
       rows: adjustment.rows,
       periodStart: lease.obligation.period.start,
+      sourceTimezone: lease.obligation.period.sourceTimezone,
       binding: adjustment.binding
     }) : void 0;
     const upload = prepared?.binding.kind === "object" ? await this.uploadRowSetUnlessCommitted(prepared, lease, "adcp_reporting_adjustments", "adjustment_id") : void 0;
@@ -1569,16 +1573,16 @@ ${managedDueArm}       )
     );
     if (rowStorage) {
       const objects = await this.query(
-        `SELECT DISTINCT row_set.row_binding_id, chunk.object_key, chunk.native_version
+        `SELECT DISTINCT row_set.row_binding_id, chunk.object_ref, chunk.native_version_ref
            FROM adcp_reporting_row_chunks chunk
            JOIN adcp_reporting_row_sets row_set ON row_set.row_set_id = chunk.row_set_id
-          WHERE chunk.obligation_id = $1 AND chunk.object_key IS NOT NULL`,
+          WHERE chunk.obligation_id = $1 AND chunk.object_ref IS NOT NULL`,
         [obligationId]
       );
       const byBinding = /* @__PURE__ */ new Map();
       for (const row of objects.rows) {
         const list = byBinding.get(row.row_binding_id) ?? [];
-        list.push({ objectKey: row.object_key, nativeVersion: row.native_version });
+        list.push({ objectRef: row.object_ref, nativeVersionRef: row.native_version_ref });
         byBinding.set(row.row_binding_id, list);
       }
       for (const [bindingId, list] of byBinding) {
@@ -1799,15 +1803,15 @@ ${managedDueArm}       )
     );
     if (binding.rows.length === 0) return false;
     const objects = await this.query(
-      `SELECT DISTINCT chunk.object_key, chunk.native_version
+      `SELECT DISTINCT chunk.object_ref, chunk.native_version_ref
          FROM adcp_reporting_row_chunks chunk
-        WHERE chunk.row_set_id = $1 AND chunk.object_key IS NOT NULL`,
+        WHERE chunk.row_set_id = $1 AND chunk.object_ref IS NOT NULL`,
       [revisionId]
     );
     if (objects.rows.length > 0) {
       await this.deleteUnreferencedObjects(
         binding.rows[0].row_binding_id,
-        objects.rows.map((row) => ({ objectKey: row.object_key, nativeVersion: row.native_version })),
+        objects.rows.map((row) => ({ objectRef: row.object_ref, nativeVersionRef: row.native_version_ref })),
         { rowSetId: revisionId },
         signal
       );
@@ -1815,10 +1819,10 @@ ${managedDueArm}       )
     await this.transaction(
       async (client) => {
         const dropped = await client.query(
-          `DELETE FROM adcp_reporting_row_chunks WHERE row_set_id = $1 RETURNING sha256, object_key`,
+          `DELETE FROM adcp_reporting_row_chunks WHERE row_set_id = $1 RETURNING sha256, object_ref`,
           [revisionId]
         );
-        const bodies = [...new Set(dropped.rows.filter((row) => row.object_key === null).map((row) => row.sha256))];
+        const bodies = [...new Set(dropped.rows.filter((row) => row.object_ref === null).map((row) => row.sha256))];
         if (bodies.length > 0) {
           await client.query(
             `DELETE FROM adcp_reporting_chunk_bodies body
@@ -1826,7 +1830,7 @@ ${managedDueArm}       )
                 AND NOT EXISTS (
                   SELECT 1 FROM adcp_reporting_row_chunks other
                    WHERE other.account_id = body.account_id AND other.obligation_id = body.obligation_id
-                     AND other.sha256 = body.sha256 AND other.object_key IS NULL
+                     AND other.sha256 = body.sha256 AND other.object_ref IS NULL
                 )`,
             [accountId, obligationId, bodies]
           );
@@ -1884,7 +1888,12 @@ ${managedDueArm}       )
                 RETURNING created_objects`,
               key
             );
-            return updated.rows[0]?.created_objects;
+            return updated.rows[0]?.created_objects.map((object) => ({
+              objectRef: object.object_ref ?? object.objectKey,
+              nativeVersionRef: object.native_version_ref ?? object.nativeVersion
+            })).filter(
+              (object) => typeof object.objectRef === "string" && typeof object.nativeVersionRef === "string"
+            );
           },
           { preBeginAdvisoryLock: accountLock(intent.account_id) }
         );
@@ -1931,9 +1940,9 @@ ${managedDueArm}       )
   /**
    * 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
+   * Object keys are unique per row set (every writable template includes `{revision_key}`), but header-only
+   * revisions share chunks within an obligation and rows written under an older template can name one
+   * object from several row sets. 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
@@ -1955,27 +1964,30 @@ ${managedDueArm}       )
       signal?.throwIfAborted();
       const removed = await this.transaction(async (client) => {
         await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
-          objectLock(bindingId, object.objectKey)
+          objectLock(bindingId, object.objectRef)
         ]);
         const referenced = await client.query(
           `(SELECT 1 FROM adcp_reporting_row_chunks chunk
               JOIN adcp_reporting_row_sets row_set ON row_set.row_set_id = chunk.row_set_id
-             WHERE row_set.row_binding_id = $1 AND chunk.object_key = $2 AND chunk.native_version = $3
+             WHERE row_set.row_binding_id = $1 AND chunk.object_ref = $2 AND chunk.native_version_ref = $3
                AND row_set.rows_state IN ('live', 'unavailable')
                AND ($4::text IS NULL OR chunk.obligation_id <> $4)
                AND ($5::text IS NULL OR chunk.row_set_id <> $5)
              LIMIT 1)
            UNION ALL
            (SELECT 1 FROM adcp_reporting_row_write_intents intent
-             WHERE intent.row_binding_id = $1 AND intent.state = 'open' AND intent.created_objects @> $6::jsonb
+             WHERE intent.row_binding_id = $1 AND intent.state = 'open'
+               AND (intent.created_objects @> $6::jsonb OR intent.created_objects @> $7::jsonb)
              LIMIT 1)`,
           [
             bindingId,
-            object.objectKey,
-            object.nativeVersion,
+            object.objectRef,
+            object.nativeVersionRef,
             scope.obligationId ?? null,
             scope.rowSetId ?? null,
-            JSON.stringify([{ objectKey: object.objectKey, nativeVersion: object.nativeVersion }])
+            JSON.stringify([{ object_ref: object.objectRef, native_version_ref: object.nativeVersionRef }]),
+            // An older writer still running during a rolling upgrade records the pre-alignment keys.
+            JSON.stringify([{ objectKey: object.objectRef, nativeVersion: object.nativeVersionRef }])
           ]
         );
         if (referenced.rows.length > 0) return false;
@@ -2061,7 +2073,11 @@ ${managedDueArm}       )
             SET created_objects = created_objects || $5::jsonb
           WHERE row_binding_id = $1 AND row_set_id = $2 AND content_sha256 = $3
             AND owner_token = $4 AND state = 'open'`,
-        [...intentKey, ownerToken, JSON.stringify([object])]
+        [
+          ...intentKey,
+          ownerToken,
+          JSON.stringify([{ object_ref: object.objectRef, native_version_ref: object.nativeVersionRef }])
+        ]
       );
       if (recorded.rowCount !== 1) {
         throw new import_row_storage.ReportingRowStoreError("STATE_UNAVAILABLE", "the row upload intent was taken over or swept");
@@ -2097,10 +2113,10 @@ ${managedDueArm}       )
       }
     }
     if (!upload.sharedFrom) {
-      const adopted = upload.locators.filter((locator) => !locator.created).sort((left, right) => left.objectKey < right.objectKey ? -1 : left.objectKey > right.objectKey ? 1 : 0);
+      const adopted = upload.locators.filter((locator) => !locator.created).sort((left, right) => left.objectRef < right.objectRef ? -1 : left.objectRef > right.objectRef ? 1 : 0);
       for (const locator of adopted) {
         await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
-          objectLock(prepared.bindingId, locator.objectKey)
+          objectLock(prepared.bindingId, locator.objectRef)
         ]);
       }
       if (adopted.length > 0) await this.rowStorage.assertObjectsPresent(prepared.bindingId, adopted);
@@ -4294,8 +4310,8 @@ function rfc3339Microseconds(expression) {
 function accountLock(accountId) {
   return `adcp-reporting-account:${accountId}`;
 }
-function objectLock(bindingId, objectKey) {
-  return `adcp-reporting-object:${bindingId}:${objectKey}`;
+function objectLock(bindingId, objectRef) {
+  return `adcp-reporting-object:${bindingId}:${objectRef}`;
 }
 async function resolveStoredFinalityBaseline(transaction, obligationId) {
   const latest = await transaction.query(

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

@@ -469,9 +469,11 @@ class PostgresReportingLedgerStore {
     );
   }
   /**
-   * 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.
+   * Defense in depth for snapshot compaction (see `compactSupersededSnapshots`): throws `INVALID_INPUT`
+   * if a writable object row binding's key template omits `{revision_key}`. Every such binding is
+   * already refused when the store is configured, so this only guards a configuration changed after
+   * construction; `readOnly` bindings are skipped. Called by `compactSupersededSnapshots` and by
+   * service construction when compaction is enabled.
    */
   assertCompactionSafeRowBindings() {
     this.rowStorage.assertCompactionSafeKeyTemplates();
@@ -858,6 +860,7 @@ ${managedDueArm}       )
       rows: revision.rows,
       finality: revision.finality,
       periodStart: lease.obligation.period.start,
+      sourceTimezone: lease.obligation.period.sourceTimezone,
       binding: revision.binding,
       controlTotals: revision.wireRevision.control_totals
     }) : void 0;
@@ -1016,6 +1019,7 @@ ${managedDueArm}       )
       obligationId: adjustment.reporting_obligation_id,
       rows: adjustment.rows,
       periodStart: lease.obligation.period.start,
+      sourceTimezone: lease.obligation.period.sourceTimezone,
       binding: adjustment.binding
     }) : void 0;
     const upload = prepared?.binding.kind === "object" ? await this.uploadRowSetUnlessCommitted(prepared, lease, "adcp_reporting_adjustments", "adjustment_id") : void 0;
@@ -1570,16 +1574,16 @@ ${managedDueArm}       )
     );
     if (rowStorage) {
       const objects = await this.query(
-        `SELECT DISTINCT row_set.row_binding_id, chunk.object_key, chunk.native_version
+        `SELECT DISTINCT row_set.row_binding_id, chunk.object_ref, chunk.native_version_ref
            FROM adcp_reporting_row_chunks chunk
            JOIN adcp_reporting_row_sets row_set ON row_set.row_set_id = chunk.row_set_id
-          WHERE chunk.obligation_id = $1 AND chunk.object_key IS NOT NULL`,
+          WHERE chunk.obligation_id = $1 AND chunk.object_ref IS NOT NULL`,
         [obligationId]
       );
       const byBinding = /* @__PURE__ */ new Map();
       for (const row of objects.rows) {
         const list = byBinding.get(row.row_binding_id) ?? [];
-        list.push({ objectKey: row.object_key, nativeVersion: row.native_version });
+        list.push({ objectRef: row.object_ref, nativeVersionRef: row.native_version_ref });
         byBinding.set(row.row_binding_id, list);
       }
       for (const [bindingId, list] of byBinding) {
@@ -1800,15 +1804,15 @@ ${managedDueArm}       )
     );
     if (binding.rows.length === 0) return false;
     const objects = await this.query(
-      `SELECT DISTINCT chunk.object_key, chunk.native_version
+      `SELECT DISTINCT chunk.object_ref, chunk.native_version_ref
          FROM adcp_reporting_row_chunks chunk
-        WHERE chunk.row_set_id = $1 AND chunk.object_key IS NOT NULL`,
+        WHERE chunk.row_set_id = $1 AND chunk.object_ref IS NOT NULL`,
       [revisionId]
     );
     if (objects.rows.length > 0) {
       await this.deleteUnreferencedObjects(
         binding.rows[0].row_binding_id,
-        objects.rows.map((row) => ({ objectKey: row.object_key, nativeVersion: row.native_version })),
+        objects.rows.map((row) => ({ objectRef: row.object_ref, nativeVersionRef: row.native_version_ref })),
         { rowSetId: revisionId },
         signal
       );
@@ -1816,10 +1820,10 @@ ${managedDueArm}       )
     await this.transaction(
       async (client) => {
         const dropped = await client.query(
-          `DELETE FROM adcp_reporting_row_chunks WHERE row_set_id = $1 RETURNING sha256, object_key`,
+          `DELETE FROM adcp_reporting_row_chunks WHERE row_set_id = $1 RETURNING sha256, object_ref`,
           [revisionId]
         );
-        const bodies = [...new Set(dropped.rows.filter((row) => row.object_key === null).map((row) => row.sha256))];
+        const bodies = [...new Set(dropped.rows.filter((row) => row.object_ref === null).map((row) => row.sha256))];
         if (bodies.length > 0) {
           await client.query(
             `DELETE FROM adcp_reporting_chunk_bodies body
@@ -1827,7 +1831,7 @@ ${managedDueArm}       )
                 AND NOT EXISTS (
                   SELECT 1 FROM adcp_reporting_row_chunks other
                    WHERE other.account_id = body.account_id AND other.obligation_id = body.obligation_id
-                     AND other.sha256 = body.sha256 AND other.object_key IS NULL
+                     AND other.sha256 = body.sha256 AND other.object_ref IS NULL
                 )`,
             [accountId, obligationId, bodies]
           );
@@ -1885,7 +1889,12 @@ ${managedDueArm}       )
                 RETURNING created_objects`,
               key
             );
-            return updated.rows[0]?.created_objects;
+            return updated.rows[0]?.created_objects.map((object) => ({
+              objectRef: object.object_ref ?? object.objectKey,
+              nativeVersionRef: object.native_version_ref ?? object.nativeVersion
+            })).filter(
+              (object) => typeof object.objectRef === "string" && typeof object.nativeVersionRef === "string"
+            );
           },
           { preBeginAdvisoryLock: accountLock(intent.account_id) }
         );
@@ -1932,9 +1941,9 @@ ${managedDueArm}       )
   /**
    * 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
+   * Object keys are unique per row set (every writable template includes `{revision_key}`), but header-only
+   * revisions share chunks within an obligation and rows written under an older template can name one
+   * object from several row sets. 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
@@ -1956,27 +1965,30 @@ ${managedDueArm}       )
       signal?.throwIfAborted();
       const removed = await this.transaction(async (client) => {
         await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
-          objectLock(bindingId, object.objectKey)
+          objectLock(bindingId, object.objectRef)
         ]);
         const referenced = await client.query(
           `(SELECT 1 FROM adcp_reporting_row_chunks chunk
               JOIN adcp_reporting_row_sets row_set ON row_set.row_set_id = chunk.row_set_id
-             WHERE row_set.row_binding_id = $1 AND chunk.object_key = $2 AND chunk.native_version = $3
+             WHERE row_set.row_binding_id = $1 AND chunk.object_ref = $2 AND chunk.native_version_ref = $3
                AND row_set.rows_state IN ('live', 'unavailable')
                AND ($4::text IS NULL OR chunk.obligation_id <> $4)
                AND ($5::text IS NULL OR chunk.row_set_id <> $5)
              LIMIT 1)
            UNION ALL
            (SELECT 1 FROM adcp_reporting_row_write_intents intent
-             WHERE intent.row_binding_id = $1 AND intent.state = 'open' AND intent.created_objects @> $6::jsonb
+             WHERE intent.row_binding_id = $1 AND intent.state = 'open'
+               AND (intent.created_objects @> $6::jsonb OR intent.created_objects @> $7::jsonb)
              LIMIT 1)`,
           [
             bindingId,
-            object.objectKey,
-            object.nativeVersion,
+            object.objectRef,
+            object.nativeVersionRef,
             scope.obligationId ?? null,
             scope.rowSetId ?? null,
-            JSON.stringify([{ objectKey: object.objectKey, nativeVersion: object.nativeVersion }])
+            JSON.stringify([{ object_ref: object.objectRef, native_version_ref: object.nativeVersionRef }]),
+            // An older writer still running during a rolling upgrade records the pre-alignment keys.
+            JSON.stringify([{ objectKey: object.objectRef, nativeVersion: object.nativeVersionRef }])
           ]
         );
         if (referenced.rows.length > 0) return false;
@@ -2062,7 +2074,11 @@ ${managedDueArm}       )
             SET created_objects = created_objects || $5::jsonb
           WHERE row_binding_id = $1 AND row_set_id = $2 AND content_sha256 = $3
             AND owner_token = $4 AND state = 'open'`,
-        [...intentKey, ownerToken, JSON.stringify([object])]
+        [
+          ...intentKey,
+          ownerToken,
+          JSON.stringify([{ object_ref: object.objectRef, native_version_ref: object.nativeVersionRef }])
+        ]
       );
       if (recorded.rowCount !== 1) {
         throw new ReportingRowStoreError("STATE_UNAVAILABLE", "the row upload intent was taken over or swept");
@@ -2098,10 +2114,10 @@ ${managedDueArm}       )
       }
     }
     if (!upload.sharedFrom) {
-      const adopted = upload.locators.filter((locator) => !locator.created).sort((left, right) => left.objectKey < right.objectKey ? -1 : left.objectKey > right.objectKey ? 1 : 0);
+      const adopted = upload.locators.filter((locator) => !locator.created).sort((left, right) => left.objectRef < right.objectRef ? -1 : left.objectRef > right.objectRef ? 1 : 0);
       for (const locator of adopted) {
         await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
-          objectLock(prepared.bindingId, locator.objectKey)
+          objectLock(prepared.bindingId, locator.objectRef)
         ]);
       }
       if (adopted.length > 0) await this.rowStorage.assertObjectsPresent(prepared.bindingId, adopted);
@@ -4295,8 +4311,8 @@ function rfc3339Microseconds(expression) {
 function accountLock(accountId) {
   return `adcp-reporting-account:${accountId}`;
 }
-function objectLock(bindingId, objectKey) {
-  return `adcp-reporting-object:${bindingId}:${objectKey}`;
+function objectLock(bindingId, objectRef) {
+  return `adcp-reporting-object:${bindingId}:${objectRef}`;
 }
 async function resolveStoredFinalityBaseline(transaction, obligationId) {
   const latest = await transaction.query(