@adcp/sdk 15.9.0 → 16.0.0-beta.1

package/dist/lib/version.d.mts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "15.9.0";
+export declare const LIBRARY_VERSION = "16.0.0-beta.1";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "15.9.0";
+    readonly library: "16.0.0-beta.1";
     readonly adcp: "3.2.4";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4"];
-    readonly generatedAt: "2026-10-13T01:26:11.275Z";
+    readonly generatedAt: "2026-10-14T03:59:15.421Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.d.ts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "15.9.0";
+export declare const LIBRARY_VERSION = "16.0.0-beta.1";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "15.9.0";
+    readonly library: "16.0.0-beta.1";
     readonly adcp: "3.2.4";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4"];
-    readonly generatedAt: "2026-10-13T01:26:11.275Z";
+    readonly generatedAt: "2026-10-14T03:59:15.421Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.js

@@ -31,7 +31,7 @@ __export(version_exports, {
   toReleasePrecisionVersion: () => toReleasePrecisionVersion
 });
 module.exports = __toCommonJS(version_exports);
-const LIBRARY_VERSION = "15.9.0";
+const LIBRARY_VERSION = "16.0.0-beta.1";
 const ADCP_VERSION = "3.2.4";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -98,10 +98,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.4"
 ];
 const VERSION_INFO = {
-  library: "15.9.0",
+  library: "16.0.0-beta.1",
   adcp: "3.2.4",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-13T01:26:11.275Z"
+  generatedAt: "2026-10-14T03:59:15.421Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "15.9.0";
+const LIBRARY_VERSION = "16.0.0-beta.1";
 const ADCP_VERSION = "3.2.4";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -65,10 +65,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.4"
 ];
 const VERSION_INFO = {
-  library: "15.9.0",
+  library: "16.0.0-beta.1",
   adcp: "3.2.4",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-13T01:26:11.275Z"
+  generatedAt: "2026-10-14T03:59:15.421Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-13
-> @adcp/sdk v15.9.0
+> Generated at: 2026-10-14
+> @adcp/sdk v16.0.0-beta.1
 
 Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
 

package/docs/guides/DISCOVERY-CACHE-AND-SESSION-REUSE.md

@@ -9,6 +9,10 @@ Two independent mechanisms remove that cost:
 
 ## Shared discovery cache
 
+`comply()` automatically owns discovery and connections for one run. Storyboards reuse clients, tool schemas and capability observations for the same URL, credentials, headers, AdCP version and transport settings, including a configured `trustedFetchFn`. Routed agents and changed credentials or versions get separate discovery. Explicit invalidation refreshes discovery, and failed discovery remains retryable by later storyboards. Every new `comply()` invocation starts with fresh discovery; ordinary SDK calls with a scoped fetch still follow the isolation rules below.
+
+Failed discovery is attempted once per storyboard, so the runner's applicability and execution checks do not repeat a failing probe. Auth-diagnostic storyboards retain an empty profile after an authentication rejection, including when they load test-kit credentials; this placeholder contains no tool or capability evidence. MCP sessions remain open across storyboards until the run completes.
+
 ```ts
 import { AgentClient, createInMemoryAgentDiscoveryCache } from '@adcp/sdk';
 

package/docs/guides/REPORTING-LEDGER-CUTOVER.md

@@ -139,7 +139,7 @@ const sink = createBigQueryReportingWarehouseSinkV1({
 
 Give the sink its **own new tables** rather than your legacy ones. It adds its
 own fixed columns (`reporting_revision_id`, `reporting_obligation_id`,
-`account_id`, `revision_number`, `finality`, `period_date`, `ordinal`), and
+`account_id`, `revision_number`, `finality`, `period_date` (the period start's date in its source timezone), `ordinal`), and
 loading into a table another writer owns invites double counting. Give analysts
 one view that `UNION ALL`s the legacy table, bounded to periods before the
 cutover boundary, with the sink's `current_rows` view, bounded to periods from

package/docs/guides/REPORTING-LEDGER.md

@@ -2,6 +2,8 @@
 
 `@adcp/sdk/reporting/ledger` turns a conforming reporting source into durable seller-side Reliable Reporting Core. It is separate from the buyer-side `reconcileReporting` API.
 
+> **Stability:** the storage, row, change-feed, managed-delivery and warehouse-sink exports (`@adcp/sdk/reporting/gcs`, `s3`, `azure`, `bigquery`, and the `@experimental` exports of `ledger`) are experimental and may change in minor releases. Pin with `~`. See the [Reliable Reporting stability policy](REPORTING-STABILITY.md).
+
 ## Recommended: install the lifecycle service
 
 `createReliableReportingService` is the adapter-first Core path. A
@@ -338,6 +340,19 @@ do {
 Removing rows from ledger documents frees space only after `VACUUM FULL` or an
 online repack of `adcp_reporting_revisions` and `adcp_reporting_adjustments`.
 
+### Stored field names
+
+Stored values use AdCP's names and bounds: a chunk's `object_ref` and
+`native_version_ref` (1 to 1024 characters each, enforced by `CHECK`
+constraints), `size_bytes` (the stored object's size after compression, as in
+the AdCP file manifest), and `canonical_size_bytes` (the uncompressed canonical
+bytes that the chunk digests cover; a row set's `content_size_bytes` is the
+byte count of the content its `content_sha256` covers). A row set records `format` (`jsonl`) and
+`algorithm` (`adcp_jcs_rows_v1`). Neither token feeds a digest. Installed
+databases upgrade in place when you re-apply `REPORTING_ROW_STORAGE_MIGRATION`;
+see [Breaking: reporting row storage field alignment](../migration-reporting-row-storage-alignment.md)
+for the old names, the API renames and the re-sync option.
+
 ### Object storage bindings
 
 Rows can live in object storage instead of PostgreSQL. A binding is defined in
@@ -368,7 +383,7 @@ const store = new PostgresReportingLedgerStore(pool, {
     providers: {
       filesystem: createFilesystemReportingRowObjectProviderV1({ roots: { reports: '/var/lib/adcp/rows' } }),
     },
-    selectRowBinding: ({ canonical_byte_count }) => (canonical_byte_count < 256 * 1024 ? 'inline' : 'reports'),
+    selectRowBinding: ({ content_size_bytes }) => (content_size_bytes < 256 * 1024 ? 'inline' : 'reports'),
   },
 });
 await store.readyRowStorage();
@@ -380,19 +395,41 @@ await store.readyRowStorage();
 - Keys always start with `{prefix}/{namespace_key}/` and use a hashed account
   segment, never a raw account ID. Override `keyTemplate` with the placeholders
   in `REPORTING_ROW_KEY_PLACEHOLDERS`; templates must include
-  `{content_sha256}` and `{chunk_index}`.
-  Enabling snapshot compaction additionally requires `{revision_key}` (see
-  [Compacting superseded snapshots](#compacting-superseded-snapshots-opt-in)).
-- A custom `keyTemplate` without `{account_key}` and `{revision_key}` can map
-  row sets from different obligations or accounts with identical chunk content
-  (an adjustment's digest covers its rows alone) to one object, which the
-  second writer adopts. Every delete path (period retirement, compaction and
-  the intent sweep) therefore skips an object while a live row set outside the
+  `{content_sha256}`, `{chunk_index}` and `{revision_key}`. `{revision_key}` is
+  required on every writable binding, so each row set writes its own object
+  keys (it hashes the row-set ID, so two uploads never name the same key). The store refuses a
+  template without it when it is configured and again in `readyRowStorage`,
+  with `INVALID_INPUT`.
+  `{period_date}` renders AdCP's `YYYY-MM-DD`: the calendar date of the period
+  start in the period's `source_timezone`, never UTC (a period starting
+  `2026-10-02T07:00:00Z` in `America/Los_Angeles` is `2026-10-02`; one starting
+  `2026-10-01T15:00:00Z` in `Asia/Tokyo` is also `2026-10-02`). It is one path
+  segment, so the default layout is
+  `{prefix}/{namespace_key}/{account_key}/2026-10-02/{finality}/...`, not
+  `2026/10/02/`. A missing, unknown or non-IANA timezone fails the write with
+  `INVALID_INPUT` rather than guessing a date. The rendered key must stay within
+  AdCP's 1024-character `object_ref` bound.
+- Rows written under an older template without `{revision_key}` stay readable:
+  every read uses the chunk's recorded `object_ref`, never a re-rendered key.
+  Changing a template needs a new binding ID, and the old definition must stay
+  configured while revisions reference it. Mark that old definition
+  `readOnly: true` to keep it configured without `{revision_key}`: it is
+  exempt from the requirement, never selected for new writes, and still used
+  for reads and retirement. A read-only binding is still registered and
+  probed by `readyRowStorage`, so keep its location reachable (and keep
+  enforcing `readOnly` in every process that shares the database: it is not
+  stored).
+- Header-only revisions share their predecessor's chunks within an obligation,
+  and chunk rows written under an older template can name one object from
+  several row sets. Every delete path (period retirement, compaction and the
+  intent sweep) therefore skips an object while a live row set outside the
   operation still references the same binding, key and native version, or an
-  open write intent created it. The reference check and the delete run in one
+  open write intent created it. (With unique keys, a create-only write only
+  finds an existing object when a writer retries the same row set.) The check
+  and delete run under the per-object lock described below. The reference check and the delete run in one
   transaction under a per-object advisory lock, and a commit that adopts an
-  existing object takes the same lock, re-reads the object and holds the lock
-  until its chunk rows commit. A delete that wins the lock makes the adopting
+  existing object takes the same lock, proves the object is still there and
+  holds the lock until its chunk rows commit. A delete that wins the lock makes the adopting
   commit fail with `STATE_UNAVAILABLE` (the writer re-uploads once its intent
   lapses); a commit that wins is seen by the delete, which skips. A skipped
   object is deleted by the retirement, compaction or sweep of the last row set
@@ -415,7 +452,16 @@ await store.readyRowStorage();
   filesystem is wrong, not the code.
 - Custom providers implement `ReportingRowObjectProviderV1`. Run
   `runReportingRowObjectProviderConformanceV1(provider, { location, prefix })`
-  against a dedicated test prefix before using one.
+  against a dedicated test prefix before using one. Provider calls take and
+  return AdCP's names: `objectRef` (the decoded, destination-relative object
+  key) and `nativeVersionRef` (the decoded provider-native version), each 1 to
+  1024 characters. Implement the optional `stat({ objectRef, nativeVersionRef })`,
+  which returns `{ sizeBytes }` for that exact version or `null` when it is
+  absent, without reading the body. The commit transaction uses it to prove an
+  adopted object is unchanged (native versions are write-unique, so the same
+  version at the recorded size is the same bytes) instead of downloading it
+  while holding the account and object locks. A provider without `stat` falls
+  back to reading the whole object there. All bundled providers implement it.
 
 #### Cloud providers
 
@@ -690,15 +736,16 @@ revision referencing them is compacted.
 Compaction records no change-feed row: the revision's metadata did not change,
 and a sink still catching up holds the revision back (above).
 
-Compaction requires every object row binding's `keyTemplate` to include
-`{revision_key}` (the default template does). Deletes now skip objects another
-row set still references (see [Object storage](#object-storage-bindings)),
-so this is defense in depth rather than the only guard: with `{revision_key}`
-no two revisions ever name the same object, so compaction never depends on the
-reference check. The SDK fails closed: `createReliableReportingService` and
-`createPostgresReliableReportingProductionService` throw at construction when
-compaction is enabled and a binding's template omits `{revision_key}`, and
-`compactSupersededSnapshots` throws the same error before deleting anything.
+Every writable object row binding's `keyTemplate` must include
+`{revision_key}` (the default template does), so two uploads never name the
+same object. Deletes skip objects another row set still references (see
+[Object storage](#object-storage-bindings)), which still matters for header-only
+revisions that share chunks within an obligation and for rows written under an
+older template, so compaction does not depend on key uniqueness alone. A
+`readOnly` binding for older rows is exempt: it never takes commits, so nothing
+can adopt through it. The SDK fails closed when the store is configured, and
+`createReliableReportingService`, `createPostgresReliableReportingProductionService`
+and `compactSupersededSnapshots` re-check before compacting.
 
 ### Core-only setup with row storage, change feed and retention
 
@@ -908,32 +955,69 @@ setInterval(() => {
   store's verified reader. It loads rows first and revision metadata second,
   in one load job per table per tick. The sink always adds
   `reporting_revision_id`, `reporting_obligation_id`, `account_id`,
-  `revision_number`, `finality`, `period_date` (the period's date in its source
-  timezone) and `ordinal` to your mapped columns.
+  `revision_number`, `finality`, `period_date` and `ordinal` to your mapped
+  columns. `period_date` is a `DATE`: the calendar date of the period start in
+  the period's `source_timezone`, as `YYYY-MM-DD` (an SDK column derived from
+  AdCP's `period`), not the UTC date unless that is the source timezone. A
+  period starting `2026-10-02T07:00:00Z` in `America/Los_Angeles` is
+  `2026-10-02`; one starting `2026-10-01T15:00:00Z` in `Asia/Tokyo` is also
+  `2026-10-02`. It is the start's date only, not a coverage range: a period
+  that crosses local midnight or spans several days is one `period_date`, so
+  `PARTITION BY period_date` holds source-local days and a UTC "yesterday"
+  filter can straddle partitions. The sink computes it with the same helper
+  that renders `{period_date}` in object keys. It fails the batch rather than
+  load a guessed date when a revision's period or timezone is missing or
+  invalid. The batch stays retained, so the sink stops until that revision's
+  period is repaired (or the runtime's timezone data is upgraded); reset with
+  `discardRetainedPlan` restarts from the beginning, so empty the tables first.
 - Batches are planned durably before loading, and job IDs derive from the
-  change-feed range. A crash between a load and the cursor commit replays the
-  same batch under the same job ID, which BigQuery refuses to run twice. A job
-  that finished with an error is retried under a new attempt for that table
-  only.
+  change-feed range. Before every submission the sink looks that job ID up in
+  the destination project and location: a job that finished cleanly counts as
+  loaded, a job that is pending or running is waited for (never uploaded
+  again), and only a missing job (404) is uploaded. A crash or timeout between a
+  load and the cursor commit therefore replays the same batch under the same
+  job ID without a second upload. An upload an earlier run abandoned at its
+  deadline is still running in the same process (the official client cannot
+  abort it), so the next run waits for it, within its own deadline, rather than
+  starting another, however long ago it started (that age includes the gap
+  between runs). If that wait outlasts the run's deadline it counts as a timeout
+  and the deadline grows. Only an upload still pending after 6 hours, the
+  largest deadline, is abandoned and replaced; BigQuery refuses a duplicate job
+  ID, so a replacement can never load the batch twice. A job that finished with
+  an error is retried under a new attempt for that table only. Deadline and
+  timeout errors name the table (`rows` or `revisions`, and its ID), the
+  deadline in force and that table's timeout count, never a file path or
+  credential.
 - `projectId` scopes both load submission and replay status checks. When it is
   omitted, both use the BigQuery client's default project. Each replica must
-  be able to read the BigQuery jobs submitted by the other replicas.
-- `loadTimeoutMilliseconds` (default 10 minutes) is a client-side deadline for
-  one load. When a load passes it, the sink asks BigQuery to cancel that job by
-  its deterministic ID, in `projectId` and `location`, and rejects with the
-  plan retained. The next run finds the cancelled job finished with an error,
-  advances that table's attempt and rejects; the run after that loads under the
-  new attempt. If the cancel has not taken effect yet it waits for the job.
-  Each attempt doubles the load deadline (up to 6 hours), so a slow but healthy
-  load converges; set the deadline above your slowest expected load to avoid
-  the cancelled attempts. Cancellation is best effort (BigQuery may finish the
-  job anyway, which the next run then accepts), a failed cancel other than "not
-  found" raises a `ADCP_BIGQUERY_SINK_CANCEL_FAILED` process warning, and a
-  status check that times out is not cancelled. BigQuery's server-side
-  `jobTimeoutMs` is not used: for a local-file load the official client builds
-  `configuration.load` from the load options and cannot set job-level fields,
-  and BigQuery silently drops `labels` and `jobTimeoutMs` found inside
-  `configuration.load`. (Staging the file in GCS and submitting the load with
+  be able to read the BigQuery jobs submitted by the other replicas. Set
+  `location` for any dataset outside the US and EU multi-regions: BigQuery
+  answers a job lookup without the right location with 404, and the sink then
+  cannot find the jobs it created.
+- `loadTimeoutMilliseconds` (default 10 minutes) is the base deadline for one
+  run's work on one load: uploading the file, or waiting for a job that is still
+  running. It bounds a run, not the job. BigQuery does not stop a load when the
+  client gives up (a cancel is accepted and the job finishes anyway), and it
+  refuses a resubmitted job ID only after the whole file is uploaded again, so
+  the sink never cancels and never relies on that refusal. When the deadline
+  passes, the run rejects with the plan retained and nothing advanced: the job
+  ID, the attempt and the cursor stay as they were, and the next run looks the
+  job up by its ID again. A job whose upload outlasted a deadline is created in
+  the background and is picked up by the next run with no second upload. Each
+  such timeout doubles that table's deadline for later runs (up to 6 hours).
+  The growth is kept with the plan in `planned_rows_timeouts` and
+  `planned_revisions_timeouts` (so it survives restarts and applies to every
+  replica, and clears when the batch commits), so an upload slower than the
+  deadline eventually gets enough time. Set the deadline above your slowest
+  expected load to avoid the extra runs. Only a job BigQuery reports as
+  finished with an error advances the attempt. A status check that times out
+  is bounded by the base deadline and does not grow it. Re-run
+  `REPORTING_WAREHOUSE_SINK_MIGRATION` after upgrading: it adds the two timeout
+  columns (a sink table without them rejects with a message saying so).
+  BigQuery's server-side `jobTimeoutMs` is not used: for a local-file load the
+  official client builds `configuration.load` from the load options and cannot
+  set job-level fields, and BigQuery silently drops `labels` and `jobTimeoutMs`
+  found inside `configuration.load`. (Staging the file in GCS and submitting the load with
   `bigquery.createJob` can set both; the sink does not stage files.) For the
   same reason the `labels` option has no effect (it warns once per process and
   is deprecated). To attribute load cost, query
@@ -974,7 +1058,9 @@ setInterval(() => {
   jobs may have succeeded; reconcile the plan against BigQuery, then call
   `reset({ discardRetainedPlan: true })`. It does not touch the warehouse: a sink
   that already loaded history reloads the retained revisions, so empty the
-  destination tables first or use a new sink name against new tables. Every
+  destination tables first (after stopping every worker and letting in-flight
+  uploads and jobs finish, since the sink never cancels a load) or use a new
+  sink name against new tables. Every
   reset starts a new job ID generation, so reloaded batches submit fresh BigQuery
   jobs instead of matching the finished jobs of the earlier history. Nothing holds
   change retention between `reset()` and the first committed batch. If `reset()`

package/docs/guides/REPORTING-OPERATIONS.md

@@ -5,6 +5,8 @@ consumer runtime. Reliable Reporting controls evidence used for billing and
 large media-spend decisions. Treat its PostgreSQL state, destination objects,
 signing keys, and authentication registry as financial infrastructure.
 
+> **Stability:** the storage subpaths this runbook operates are experimental. Pin `@adcp/sdk` with `~` and read each minor's changeset before upgrading. See the [Reliable Reporting stability policy](REPORTING-STABILITY.md).
+
 ## Production topology
 
 Use one PostgreSQL primary with synchronous durability appropriate to the
@@ -90,6 +92,9 @@ service runs for you. See
    verified chunks. Existing revisions keep their inline rows, and every
    binary built with row storage reads both forms. Do not run a writer older
    than this release once chunked revisions exist: it cannot read them.
+   Upgrading from 15.8.x? Row storage renamed its stored fields to AdCP's
+   names; re-apply the migration before starting new binaries (see
+   [Breaking: reporting row storage field alignment](../migration-reporting-row-storage-alignment.md)).
 2. **Existing inline rows (optional).** Run `migrateInlineRows` in bounded
    batches from a maintenance job until it returns no cursor. Alert on any
    `quarantined` IDs: those revisions no longer reproduce their committed
@@ -334,9 +339,22 @@ What it checks:
   duplicate rows, and that `current_rows` returns one revision per obligation.
   It also asserts (`PASS`/`FAIL`) that the sink sends no `labels` or
   `jobTimeoutMs` inside `configuration.load`, where BigQuery silently drops
-  them, and that a job cancel addressed with the destination project and
-  location (what the sink sends when a load passes its client-side deadline) is
-  accepted by BigQuery.
+  them. A deadline scenario runs a sink with the minimum 1-second load deadline
+  and holds the first load's result past it: the run must reject with the plan
+  and job ID unchanged and that table's persisted deadline grown, the job must
+  end `DONE` without an error (the sink never cancels it), and later runs under
+  the same sink name must converge with no duplicate rows, the same job ID and
+  no second upload. A #3234 scenario runs a sink whose upload of a 50,000-row
+  batch outlasts its 1-second deadline and asserts that it converges within 8
+  runs, loads every row exactly once, never changes the job ID, and never
+  starts an upload after the job exists (a link fast enough to beat the
+  deadline passes and says so). A
+  `period_date` scenario checks that non-UTC periods land on their
+  source-timezone date.
+- **Cancel probe of the service** (`INFO`, never a failure). It cancels a
+  5000-row load the moment it is created and reports whether BigQuery stopped
+  it; in practice it accepts the cancel and lets the load finish, which is why
+  the sink never cancels a load and finds it by job ID instead.
 - **Overlapping runs** (`INFO`, never a failure). Two concurrent `runOnce()`
   calls over one pending batch, and a deterministic reproduction of #3196: one
   run reads its sink state, another completes the batch and a new revision
@@ -353,7 +371,10 @@ What it checks:
   prevention, lifecycle rules) and `runReportingRowObjectProviderConformanceV1`,
   then commits a revision through an object binding on the bucket and reads it
   back verified (full read, ranged page, a second store instance, and a replayed
-  commit that uploads nothing).
+  commit that uploads nothing). It also commits revisions for non-UTC periods and
+  checks that each object key has one `{period_date}` segment holding the
+  source-timezone date, and that each chunk's `native_version_ref` and
+  `size_bytes` match the stored object's generation and size.
 
 Everything it creates carries a per-run id: a dataset named
 `<GCP_DATASET_PREFIX><run id>`, objects under `<GCS_PREFIX>/<run id>/`, and

package/docs/guides/REPORTING-STABILITY.md

@@ -0,0 +1,76 @@
+# Reliable Reporting stability policy
+
+The Reliable Reporting storage surface is **experimental**. It is new, it has not yet run in production at an adopter, and its shape is still being settled by real use. Marking it experimental lets breaking changes there ship in minor releases, with notice, instead of forcing a major release of the whole SDK.
+
+This follows how the AdCP protocol treats experimental surfaces (`x-status: experimental` in the schemas, with advance notice of breaking changes).
+
+## What is experimental
+
+An export is experimental when its TSDoc carries an `@experimental` tag that links to this page. Editors show the tag on hover, and some mark the symbol as unstable.
+
+| Subpath                        | Status                                                                      |
+| ------------------------------ | --------------------------------------------------------------------------- |
+| `@adcp/sdk/reporting/gcs`      | Experimental (every export)                                                 |
+| `@adcp/sdk/reporting/s3`       | Experimental (every export)                                                 |
+| `@adcp/sdk/reporting/azure`    | Experimental (every export)                                                 |
+| `@adcp/sdk/reporting/bigquery` | Experimental (every export)                                                 |
+| `@adcp/sdk/reporting/ledger`   | Partly experimental (see below)                                             |
+| `@adcp/sdk/reporting/service`  | Partly experimental: retention, compaction and change-feed maintenance only |
+
+Within `@adcp/sdk/reporting/ledger`, the experimental exports are:
+
+- the PostgreSQL ledger store (`PostgresReportingLedgerStore`), its migrations and errors, and `sweepExpiredReportingLedgerState`;
+- row storage (`ReportingRowStorageV1`, row bindings, row encoding, the row-storage migration and probe, and row-store errors) and object writes;
+- the host change feed (`REPORTING_LEDGER_CHANGES_MIGRATION`, change records and cursors);
+- managed delivery (the runtime, the store, the adapter contract, the adapter router and the PostgreSQL store);
+- notification activity stores and checkpoints;
+- the store, transaction, lease and row-read interfaces in `ledger/types`.
+
+Within `@adcp/sdk/reporting/service`, the experimental exports are `ReportingRetentionOptionsV1`, `ReportingCompactionOptionsV1`, `ReportingChangeFeedMaintenanceOptionsV1`, `runReportingLedgerMaintenance` and the related maintenance types and error.
+
+### Not experimental
+
+These follow normal semver. A breaking change to them ships in a major release.
+
+- The protocol-facing handlers: `createReportingDeliveryHandler`, `createReportingStatusHandler`, `createSyncReportingStatusHandler`, `createSyncReportingReceiptsHandler`, and the status-ingest request and response schemas.
+- `createReportingProducer`, `assertSupportedReportingAuthoritativeParty` and `UnsupportedReportingFeatureError`.
+- The health, coverage, lifecycle, schedule and consumer-status-identity helpers in `@adcp/sdk/reporting/ledger`.
+- `createReliableReportingService`, `createPostgresReliableReportingProductionService` and the service conformance runner in `@adcp/sdk/reporting/service`.
+- `@adcp/sdk/reporting/consumer` (buyer reconciliation and worker) and `@adcp/sdk/reporting/source` (source contract and executor). They are separate subpaths with their own `V1` contract suffixes and are not covered by this policy.
+
+If you are unsure about a symbol, read its TSDoc. An `@experimental` tag means it is covered. No tag means it is not.
+
+## What "experimental" means
+
+- **Breaking changes may ship in minor releases.** That covers signatures, option names, stored field and column names, migrations, and defaults in the experimental exports.
+- **Every such change is announced.** The changeset describes the break and includes a migration note, and the release notes carry it. Larger changes also get a `docs/migration-*.md` walkthrough.
+- **The wire protocol is not affected.** Buyer-visible behavior these exports implement (reporting delivery, `revision_content_sha256`, status, receipts and so on) follows AdCP's own versioning, not this policy. A change to the SDK's storage layout does not change what a buyer sees.
+- **Security and correctness fixes are not held back.** If a fix needs a breaking change, it ships in a minor.
+
+## How to pin
+
+Adopters of the experimental subpaths should not use a caret range, which accepts every future minor.
+
+```json
+{
+  "dependencies": {
+    "@adcp/sdk": "~16.0.0"
+  }
+}
+```
+
+- `~16.0.0` takes patches only (recommended).
+- An exact version (`"16.0.0"`) is stricter still.
+- Read the changelog before widening to a new minor, and apply any migration it names.
+
+If you use only the stable surfaces, a caret range is fine as usual.
+
+## Migrations
+
+Database migrations exported from experimental subpaths (`REPORTING_LEDGER_MIGRATION`, `REPORTING_ROW_STORAGE_MIGRATION` and the others) stay idempotent where practical, and a changeset says when you must re-apply one. See [Reliable Reporting production operations](REPORTING-OPERATIONS.md) and the [ledger guide](REPORTING-LEDGER.md).
+
+## When this will change
+
+The surface is expected to stabilize after the first production adopter runs on SDK 16 stable. At that point the `@experimental` tags are removed in a minor release with a changelog note, and breaking changes need a major release from then on.
+
+Related: [Seller reporting ledger](REPORTING-LEDGER.md), [Reliable Reporting production operations](REPORTING-OPERATIONS.md).

package/docs/guides/account-resolution.md

@@ -29,6 +29,101 @@ For buyer setup and opt-in lifecycle management, see
 For upgrading an existing integration, use the
 [14.0-to-14.1 checklist](../migration-14.0-to-14.1.md).
 
+### Account sync contracts
+
+For platform `accounts.upsert`, the framework looks up accepted natural-key
+entries with `provisioning: false` before calling the batch method. The optional
+`ctx.existing` array is aligned with the entries passed to `upsert`; each element
+is the pre-write account snapshot or `null`. All natural-key dimensions are
+preserved, including brand countries, operator unit, currency, timezone and sandbox.
+Natural-key snapshots require the resolved account's own brand and operator;
+identity-free singleton resolvers supply no snapshot rather than matching every key.
+Use these snapshots to update the existing ID instead of creating another account.
+Snapshots are advisory: enforce uniqueness atomically in your own storage too.
+
+The framework emits typed, server-side `accounts.onDiagnostic` events for
+`ACCOUNT_SYNC_IDEMPOTENCY_VIOLATION`, `ACCOUNT_SYNC_PAYMENT_TERMS_MISMATCH`, and
+`ACCOUNT_BILLING_FIELDS_MISSING`, plus `ACCOUNT_SYNC_BILLING_MISMATCH` when an
+active result silently replaces requested agent billing with another party
+(strict mode rejects it with `BILLING_NOT_SUPPORTED`). ID-only resolvers that reject natural-key
+lookups remain usable and emit `ACCOUNT_SYNC_LOOKUP_UNSUPPORTED`; their
+identity checks require store-level enforcement. Events contain only the code, tool and original
+row index. Development logs also receive warnings. Callback exceptions do not
+change the result of a committed write. The default behavior preserves existing
+responses. Set `accounts.strictIdempotency: true` to return per-row failures for
+changed IDs, `created` on an existing key, or an active account that omits or
+changes requested terms (`PAYMENT_TERMS_NOT_SUPPORTED`). Identity violations
+return `SERVICE_UNAVAILABLE`. These post-write checks cannot roll back adopter writes.
+
+Missing sync billing/terms are filled only from a stored account whose ID matches
+the result, never from the buyer's requested terms. Agent-billed list rows without
+terms also emit a diagnostic. Low-level handler-bag overrides do not use this
+platform-store guard.
+
+### Persistent keyed accounts
+
+`createKeyedAccountStore` from `@adcp/sdk/server` supplies deterministic IDs and
+additive, non-expiring account syncs. Choose `memoryKeyedAccountBackend()` for one
+process, `pgKeyedAccountBackend(pool)` for PostgreSQL, or
+`redisKeyedAccountBackend(client)` for a persistent Redis deployment with eviction
+disabled. Custom KV backends can implement `KeyedAccountBackend` using native
+atomic compare-and-swap; ordinary read followed by write is insufficient.
+
+```ts
+import {
+  createKeyedAccountStore,
+  getKeyedAccountMigration,
+  pgKeyedAccountBackend,
+} from '@adcp/sdk/server';
+
+await pool.query(getKeyedAccountMigration());
+const accounts = createKeyedAccountStore({
+  namespace: 'seller-production', // trusted deployment namespace
+  backend: pgKeyedAccountBackend(pool),
+  resolution: 'implicit',
+  buildAccount: async (entry, { accountId, existing, dryRun, ctx }) => {
+    // Your onboarding code accepts the requested terms or throws AdcpError.
+    // It must use accountId for idempotent upstream writes too.
+    return onboardAdvertiser(entry, { accountId, existing, dryRun, authInfo: ctx?.authInfo });
+  },
+});
+```
+
+`buildAccount` is required and returns the actual account, using the supplied
+`accountId`. The store validates active payment terms before committing; a
+rejected update leaves the stored account intact. It strips `authInfo` before
+persistence; credentials must also stay out of `ctx_metadata`. By default the
+store partitions accounts by stable OAuth client, API key ID or verified agent
+URL. Override `principalKey` only with a trusted authorization partition, never
+buyer-supplied request fields. Use distinct namespaces for different sellers.
+
+Concurrent writes retry atomic CAS up to ten times, re-running `buildAccount`
+against fresh state. Its external side effects must therefore be idempotent on
+the supplied account ID. A crash between an upstream write and the local CAS
+still requires that upstream idempotency. The backend stores one roster per
+principal with a default `maxAccounts` limit of 1000 and suits modest rosters; large sellers should use indexed account
+tables with unique natural-key constraints. Share the memory backend across
+server factories; use persistent storage across restarts.
+
+Dry runs do not persist; `buildAccount` receives `dryRun: true` and must preview
+without upstream writes or other side effects. Only the seller-returned account
+determines sandbox authority; the buyer's sandbox flag participates in identity
+and never grants test-tool access. Settings updates cannot provision a missing natural-key
+account. `delete_missing` and operator identity reconciliation are explicitly
+unsupported; close accounts through your lifecycle code. List cursors are bound
+to the principal, filters and roster revision and become stale after a write.
+An unknown ID-keyed entry rejects the batch before any `buildAccount` callback:
+this interface requires brand/operator on failed rows, and unauthorized account
+identities must not be invented or exposed. Failed known-account updates retain
+the account's actual status and leave persisted state intact.
+
+Run [the account sync storyboard](../../examples/storyboards/account-sync-contract.yaml)
+with one authenticated sandbox caller. Its `account.sync_contract` invariant
+checks repeat syncs with fresh request keys, exact accepted terms and billing
+fields on list rows. The fixture is SDK-authored; canonical protocol storyboards
+remain unchanged. A seller rejecting the fixture's terms needs an accepted-terms
+fixture to exercise successful repeat provisioning.
+
 Account resolvers receive `ctx.provisioning`. It is false on discovery and
 negotiation (`get_products`, `list_products`, `get_signals`, and proposal
 request/refine/decline); these tasks MUST use lookup only. It is true on spend
@@ -623,3 +718,9 @@ const accounts = {
 **Hand-rolled stores.** For stores that don't use `createRosterAccountStore`,
 handle `resolve(undefined, ctx)` in your own `resolve` implementation by
 checking `ref === undefined` before the id-arm branch.
+
+### Callback boundaries
+
+A custom `principalKey` may be synchronous or asynchronous, and must return a nonempty primitive string derived from trusted authentication state. Missing, object, numeric, boolean, or blank values fail closed before backend access. Use a stable tenant identity, keep it deterministic across repeated calls in one request, and bound callback I/O durations.
+
+`createKeyedAccountStore` captures dry-run intent before callbacks and gives each CAS retry fresh copies of sync entries and request input. Mutating callback request arguments cannot change the original request or turn a preview into a committed write. Framework commercial checks also retain an independent request snapshot. Async diagnostic hooks are fire-and-forget; their failures are isolated from dispatch.