@adcp/sdk 15.9.1 → 16.0.0-beta.2

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
@@ -116,7 +121,14 @@ service runs for you. See
    cannot hold the table indefinitely.
 5. **Warehouse sink.** Apply `REPORTING_WAREHOUSE_SINK_MIGRATION`, create the
    tables, and the `current_rows` view, then schedule `runOnce`. Point analysts
-   at `current_rows`.
+   at `current_rows`. Set the sink's `location` to the dataset's location: replay
+   lookups of load jobs need it outside the US and EU multi-regions, and the sink
+   warns once per process when it is unset. When upgrading from 15.9.0, stop
+   every 15.9.0 sink worker before starting newer ones, then re-apply
+   `REPORTING_WAREHOUSE_SINK_MIGRATION`. A 15.9.0 worker cancels a load at its
+   deadline, so one running beside a newer worker on the same sink can cancel a
+   job the newer worker is waiting on; the job ends `DONE` with an error and the
+   attempt advances. Rows do not duplicate, but convergence slows.
 6. **Retention.** Enable `retention` last, after confirming the advertised
    `status_retention_days` is the window you intend to keep. Retirement deletes
    rows and ledger records for whole periods and cannot be undone. Keep backups
@@ -339,21 +351,22 @@ What it checks:
   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
+  no second upload. A slow-upload 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).
+  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
+  calls over one pending batch, and a deterministic reproduction of the stale-plan race: one
   run reads its sink state, another completes the batch and a new revision
   commits, then the first resumes. Without the fence the first run reloads
-  revisions the second already loaded (duplicate rows); with the fence from
-  PR #3197 it rejects as stale and nothing duplicates. Read the verdict in the
+  revisions the second already loaded (duplicate rows); with the plan fence it rejects as stale and nothing duplicates. Read the verdict in the
   report; the exit status does not depend on it.
 - **Cross-project.** Set `GCP_CLIENT_PROJECT` to a project other than
   `GCP_BQ_PROJECT`. Load jobs are then created in the destination project, and
@@ -364,7 +377,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
@@ -436,15 +452,15 @@ export GCS_BUCKET=my-test-bucket GCS_PREFIX=adcp-reporting-validation
 npm run validate:reporting-gcp -- --yes
 ```
 
-Against a pull request branch (for example #3197), keep running the script from
+Against a pull request branch (replace `<n>` with its number), keep running the script from
 `main` and point it at a second built checkout, so a branch cut before this
 script existed still works:
 
 ```bash
-git fetch origin pull/3197/head:pr-3197
-git worktree add ../adcp-client-pr-3197 pr-3197
-(cd ../adcp-client-pr-3197 && npm ci && npm run build)
-ADCP_SDK_ROOT=../adcp-client-pr-3197 npm run validate:reporting-gcp -- --yes
+git fetch origin pull/<n>/head:pr-<n>
+git worktree add ../adcp-client-pr-<n> pr-<n>
+(cd ../adcp-client-pr-<n> && npm ci && npm run build)
+ADCP_SDK_ROOT=../adcp-client-pr-<n> npm run validate:reporting-gcp -- --yes
 ```
 
 The same environment applies. The run ends with a `PASS`, `FAIL` and `INFO`
@@ -452,7 +468,7 @@ report and a markdown block (project and bucket names masked) to paste into
 the PR. The exit status is 0 with no `FAIL`, 1 with any `FAIL`, and 2 for a
 configuration problem or a missing `--yes`. Results of the overlap probes are
 `INFO` on purpose: on `main` expect the stale-run probe to report duplicates,
-and on PR #3197 expect it to report none.
+and on a branch with the plan fence expect it to report none.
 
 `test/lib/reporting-gcp-validation-pg.test.js` drives the script's core against
 in-memory BigQuery and Storage doubles and a real PostgreSQL, so the logic,

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.

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-14
-> Library: @adcp/sdk v15.9.1
+> Generated at: 2026-10-15
+> Library: @adcp/sdk v16.0.0-beta.2
 > AdCP major version: 3
 > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
 > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.
@@ -2143,6 +2143,7 @@ These docs are available locally in the repo and hosted at https://adcontextprot
 | Reporting ledger cutover from custom tables | docs/guides/REPORTING-LEDGER-CUTOVER.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-LEDGER-CUTOVER.md) |
 | Buyer reporting reconciliation | docs/guides/REPORTING-RECONCILIATION.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-RECONCILIATION.md) |
 | Reliable Reporting production operations | docs/guides/REPORTING-OPERATIONS.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-OPERATIONS.md) |
+| Reliable Reporting stability policy (experimental storage subpaths) | docs/guides/REPORTING-STABILITY.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-STABILITY.md) |
 | Validate your agent (5-command checklist) | docs/guides/VALIDATE-YOUR-AGENT.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/VALIDATE-YOUR-AGENT.md) |
 | Async patterns (polling, webhooks, deferred) | docs/guides/ASYNC-DEVELOPER-GUIDE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/ASYNC-DEVELOPER-GUIDE.md) |
 | Async API reference | docs/guides/ASYNC-API-REFERENCE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/ASYNC-API-REFERENCE.md) |

package/docs/migration-12-to-13.md

@@ -400,6 +400,21 @@ resolve. An `AgentClient` given a resolver rebuilt from these routes applies
 that rewrite in another process, as it does after its own discovery. Routes
 without `seller_declared` leave canonical writes unchanged.
 
+A buyer that stored the seller's raw `get_products` product, and projects it
+again in a process that never ran discovery, can record the same origin by
+passing that stored product: `legacyRoutesForProduct(productId,
+projected.format_options, { sellerProduct: storedProduct })`. An option is then
+seller-declared exactly when the stored product's own `format_options[]` names
+it, which is the rule the SDK applies after its own discovery.
+
+The client reads that origin from the resolver function that
+`canonicalFormatLegacyResolverFromRoutes()` returns. A resolver you build around
+it, for example one that tries the stored routes and then another source, is a
+different function and carries no origin unless you pass it through
+`carryFormatOptionOrigins(composedResolver, routesResolver)`.
+`canonicalFormatLegacyResolverFromCatalogSnapshots(snapshots, fallback)` already
+carries its fallback's origin.
+
 Compatibility consumers that must retain top-level `format_ids[]` while
 publishing URL-free canonical declarations can use the additive projection:
 

package/docs/migration-14.x-rc-worksheet.md

@@ -11,8 +11,8 @@ below as the publication/deployment gate.
 
 | Fact | Value |
 | --- | --- |
-| Exact npm package | `@adcp/sdk@15.9.1` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.9.1 dist.integrity` |
+| Exact npm package | `@adcp/sdk@16.0.0-beta.2` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.0.0-beta.2 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.2.4` |
 | Maintained wire releases | `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` |
@@ -21,8 +21,8 @@ below as the publication/deployment gate.
 Install exact production inputs rather than a moving range or dist-tag:
 
 ```bash
-npm install --save-exact '@adcp/sdk@15.9.1'
-npm view '@adcp/sdk@15.9.1' dist.integrity
+npm install --save-exact '@adcp/sdk@16.0.0-beta.2'
+npm view '@adcp/sdk@16.0.0-beta.2' dist.integrity
 ```
 
 ### Required and optional peers