@adcp/sdk 15.8.1 → 16.0.0-beta.1

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
@@ -111,7 +116,8 @@ service runs for you. See
    view are the operator's responsibility.
 4. **Change feed.** Apply `REPORTING_LEDGER_CHANGES_MIGRATION` (PostgreSQL 13+)
    or pass `changeFeed`. Register each durable consumer with
-   `saveFeedConsumerCursor`, and size `maxFeedHoldDays` so one stalled consumer
+   `saveFeedConsumerCursor` (checkpoints are forward-only; pass `{ rewind: true }`
+   to move a consumer back), and size `maxFeedHoldDays` so one stalled consumer
    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
@@ -135,15 +141,25 @@ Alert on these row-storage signals:
 - `ROWS_INTEGRITY_FAILED` or `ROWS_UNAVAILABLE` from reads. These are never
   normal, and buyers see `SERVICE_UNAVAILABLE` for the affected revision.
 - A growing count of `adcp_reporting_row_write_intents` in `sweeping` state,
-  or `sweepRowWriteIntents` reporting failures. Provider deletes are failing.
+  or `sweepRowWriteIntents` reporting failures. Provider deletes are failing;
+  failed intents back off (one minute, doubling, capped at six hours) rather than
+  blocking others. `skippedUnconfigured` counts expired uploads whose binding this
+  host does not configure, and `overdue` (expired more than 24 hours ago, still
+  unswept) means no host is handling them and their objects are leaking. The
+  maintenance helper reports both through `onError`.
 - The `snapshot compaction` task reporting `failed` revisions. Provider deletes
   are failing; the revisions stay `pruning` (reads already answer not-found) and
   the next pass resumes them.
-- `retireExpiredPeriods` returning `failed` IDs. Usually a binding was removed
-  from configuration while revisions still reference it; keep retired bindings
-  configured.
-- `ReportingChangeCursorExpiredError` in a consumer. That consumer fell behind
-  retention and must resynchronize from `listCurrentRevisions`.
+- `retireExpiredPeriods` returning `failed` IDs or a non-empty `stuck` list.
+  Usually a binding was removed from configuration while revisions still
+  reference it; keep retired bindings configured. A failing period retries with
+  backoff (up to six hours) and does not block other periods; `stuck` lists
+  those that have failed five or more times, with their cause.
+- `ReportingChangeCursorExpiredError` (`code === 'CURSOR_EXPIRED'`) in a
+  consumer. Usually it fell behind retention and must resynchronize from
+  `listCurrentRevisions`. A first read with no cursor can also throw it when a
+  prune commits mid-read; retry it. A new warehouse sink stuck on it after such
+  a race recovers with `sink.reset()`.
 - A non-empty `missing` from the warehouse sink's `runOnce()`. The sink was down
   longer than `maxFeedHoldDays`, retention stopped waiting for it, and the
   warehouse lacks those revisions. Backfill them or accept the gap, and keep
@@ -270,6 +286,19 @@ version with the chunk manifest, restore the exact recorded version from bucket
 versioning or backups, and verify by reading the revision through `getRevision`.
 Never edit a chunk manifest or digest to match the stored bytes.
 
+Multi-transport managed delivery: when one runtime delivers through several
+transports behind the managed-delivery router, key alerts on the per-route
+worker counts (`deliveryFailuresByRoute`, `revocationFailuresByRoute`,
+`overdueByRoute`) instead of the totals, so one failing transport is not
+averaged away. A non-zero `~unrouted` count is a configuration problem, not a
+provider outage: a binding or destination authorization has no route (often a
+legacy authorization with no recorded transport and no `legacyDefault`). List
+those authorizations with `listDestinationAuthorizationsWithoutContract()`,
+then add the route or a `legacyDefault`. A startup probe failure names the
+failing route; fix that route's provider access before restarting, because
+offerings are not withdrawn at runtime. See "Multi-transport delivery with the
+router" in `REPORTING-LEDGER.md`.
+
 Clock skew: remove the host from service. Lease and event times use PostgreSQL
 where correctness needs a shared clock, while provider deadlines and process
 timeouts still depend on healthy host clocks.
@@ -289,3 +318,196 @@ timeouts still depend on healthy host clocks.
 For the optional GCS provider write-fence primitive and its bucket policy, inventory retention and cancellation requirements, see [Durable GCS reporting write fence](REPORTING-GCS-FENCE.md). Complete managed delivery integration remains a separate step.
 
 For complete GCS file-transfer delivery, private contracts and scoped buyer readers, see [Managed reporting delivery on GCS](REPORTING-GCS-MANAGED.md).
+
+## Live GCP validation
+
+`scripts/validate-reporting-gcp.mjs` runs the built SDK against a real BigQuery
+project and a real GCS bucket. The in-memory doubles in the test suite cannot
+prove how BigQuery names jobs, where it stores load options, or what a real
+bucket policy looks like; this script does. It is not published with the
+package, so run it from a repository checkout.
+
+What it checks:
+
+- **BigQuery warehouse sink** (`@adcp/sdk/reporting/bigquery`). It applies the
+  ledger migrations into fresh PostgreSQL schemas, commits revisions, creates a
+  uniquely named dataset in the destination project from `defaultTablesSql` and
+  `currentRowsViewSql`, and runs the sink. It verifies row and revision counts
+  and the JSON `row` column by query, that the load jobs exist in the
+  destination project and location under the deterministic job IDs, that a
+  crash after the rows load (an injected failing revisions load) replays with no
+  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. 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
+  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
+  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
+  the crash replay fails if the "job already exists" status check looks in the
+  client's default project instead.
+- **GCS row provider** (`@adcp/sdk/reporting/gcs`). It prints the bucket policy,
+  runs the provider probe (uniform bucket-level access, public access
+  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). 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
+PostgreSQL schemas `adcp_validation_<run id>_*`. All of it is deleted in
+`finally` (and on Ctrl-C) unless `KEEP=1`. Deletion is limited to those names:
+the script refuses to delete a dataset without the prefix, an object outside
+the run prefix, or a schema without the run id.
+
+### Setup
+
+```bash
+npm ci && npm run build
+# Optional peers; --no-save leaves package.json alone.
+npm install --no-save @google-cloud/bigquery @google-cloud/storage
+```
+
+Use Application Default Credentials (workload identity,
+`gcloud auth application-default login`, or `GOOGLE_APPLICATION_CREDENTIALS`).
+The script never reads, writes or prints credentials, and it redacts the
+PostgreSQL URL and bearer tokens from anything it prints. If a peer package is
+missing it prints the install command and exits with status 2.
+
+| Variable                                                             | Required                 | Meaning                                                                                                                                                              |
+| -------------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `REPORTING_LEDGER_PG_URL`                                            | yes                      | PostgreSQL the ledger runs on. The role must be able to create and drop schemas.                                                                                     |
+| `GCP_BQ_PROJECT`                                                     | unless `--skip-bigquery` | Destination project for the temporary dataset.                                                                                                                       |
+| `GCP_BQ_LOCATION`                                                    | no (`US`)                | Dataset and job location.                                                                                                                                            |
+| `GCP_CLIENT_PROJECT`                                                 | no                       | The BigQuery client's default project (billing project for queries and DDL). Set it different from `GCP_BQ_PROJECT` to exercise the cross-project path.             |
+| `GCP_DATASET_PREFIX`                                                 | no (`adcp_sink_validation_`) | Dataset name prefix.                                                                                                                                     |
+| `GCS_BUCKET`                                                         | unless `--skip-gcs`      | Bucket under test. Its policy must satisfy the row-provider probe.                                                                                                   |
+| `GCS_PREFIX`                                                         | no (`adcp-reporting-validation`) | A prefix you own for the test; a unique run folder is created beneath it.                                                                                    |
+| `KEEP=1`                                                             | no                       | Keep the dataset, objects and schemas, and print how to remove them.                                                                                                 |
+| `ADCP_SDK_ROOT`                                                      | no                       | Another built checkout whose `dist/` is tested (see below).                                                                                                          |
+| `--yes` or `CONFIRM=1`                                               | yes                      | Acknowledge the preflight; without it nothing is created and the exit status is 2.                                                                                   |
+| `--skip-bigquery`, `--skip-gcs` (or `SKIP_BIGQUERY=1`, `SKIP_GCS=1`) | no                       | Skip a section.                                                                                                                                                      |
+
+The preflight prints the identity ADC resolves to, the projects, location,
+bucket, prefix and dataset name before anything is created.
+
+### Required IAM
+
+- **Destination project** (or the dataset, once it exists): BigQuery Data
+  Editor (`roles/bigquery.dataEditor`; it includes `bigquery.datasets.create`
+  and table create and read) and BigQuery Job User (`roles/bigquery.jobUser`;
+  load jobs are created here). The creator of a dataset owns it, which covers
+  the forced delete in cleanup; if your organization strips that, grant
+  `roles/bigquery.dataOwner` instead. If reading job metadata is denied, add
+  `roles/bigquery.resourceViewer` (`bigquery.jobs.get`).
+- **Client project**, when it differs: BigQuery Job User, because the DDL and
+  verification queries run as jobs there.
+- **GCS**: Storage Object Admin (`roles/storage.objectAdmin`) on the test
+  prefix, with an IAM condition such as
+  `resource.name.startsWith("projects/_/buckets/BUCKET/objects/PREFIX/")`, plus
+  `storage.buckets.get` for the probe (for example
+  `roles/storage.legacyBucketReader`, or a custom role holding only
+  `storage.buckets.get`). Object Admin alone does not include
+  `storage.buckets.get`.
+
+### Running it
+
+Against current `main`:
+
+```bash
+git checkout main && git pull && npm ci && npm run build
+npm install --no-save @google-cloud/bigquery @google-cloud/storage
+export REPORTING_LEDGER_PG_URL=postgres://...   # a scratch database
+export GCP_BQ_PROJECT=dest-project GCP_CLIENT_PROJECT=billing-project GCP_BQ_LOCATION=US
+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
+`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
+```
+
+The same environment applies. The run ends with a `PASS`, `FAIL` and `INFO`
+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.
+
+`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,
+reporting and cleanup safety stay covered without credentials. It proves nothing
+about real BigQuery or GCS behavior.
+
+### The Python SDK's equivalent
+
+The Python SDK (`adcp-client-python`, package `adcp`) has the same GCS row
+provider and the same conformance runner: `create_gcs_reporting_row_object_provider_v1`
+in `adcp.reporting.ledger.row_storage_gcs` and
+`run_reporting_row_object_provider_conformance_v1` in
+`adcp.reporting.ledger.row_storage_object`, with the same bucket policy rules.
+Install `pip install 'adcp[reporting-gcs]'`, then run the conformance against the
+same bucket and prefix as above (it writes and deletes only
+`$GCS_PREFIX/conformance/<uuid>.jsonl`):
+
+```bash
+python - <<'PY'
+import asyncio, os
+from google.cloud import storage
+from adcp.reporting.ledger.row_storage_gcs import create_gcs_reporting_row_object_provider_v1
+from adcp.reporting.ledger.row_storage_object import run_reporting_row_object_provider_conformance_v1
+
+async def main():
+    provider = create_gcs_reporting_row_object_provider_v1(storage=storage.Client())
+    passed = await run_reporting_row_object_provider_conformance_v1(
+        provider,
+        location={"bucket": os.environ["GCS_BUCKET"]},
+        prefix=os.environ.get("GCS_PREFIX", "adcp-reporting-validation"),
+    )
+    print("PASS", passed)
+
+asyncio.run(main())
+PY
+```
+
+Python has no BigQuery warehouse sink. A live JavaScript to Python interop run
+against GCS is not possible with the existing interop test: the Python test
+(`tests/conformance/reporting/test_reporting_row_storage_interop_pg.py`) and its
+JavaScript driver (`tests/interop/reporting_row_storage_js_driver.cjs`) both
+hard-code the filesystem provider and a directory bucket root, and the
+cross-SDK row-storage fixtures replay on a filesystem too. Running it on GCS
+would need both drivers changed to build an object binding with
+`provider: 'gcs'` and `location: { bucket }` (same prefix, deployment namespace
+and binding definition on both sides). The optional live GCS controls in
+`scripts/reporting-interop/GCS.md` exercise the Managed Delivery evidence
+readers, not row storage.

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-11
-> Library: @adcp/sdk v15.8.1
+> Generated at: 2026-10-14
+> Library: @adcp/sdk v16.0.0-beta.1
 > 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.
@@ -1575,7 +1575,7 @@ Flow: `get_products → create_media_buy → update_media_buy → get_media_buys
 Flow: `sync_accounts → create_media_buy → update_media_buy → get_media_buys → update_media_buy`
 
 **Seller handles typed proposal negotiation with constraints, product changes, and alternatives** — Verifies the AdCP 3.2 typed negotiation lifecycle: capability-gated constraint satisfaction, product changes, digest-verified alternatives, partial invariant, immutable lineage, finalize atomicity, and idempotent replay through refine_proposals.
-Flow: `get_adcp_capabilities → sync_accounts → get_products → refine_proposals → accept_proposal → refine_proposals`
+Flow: `get_adcp_capabilities → sync_accounts → request_proposals → refine_proposals → accept_proposal → refine_proposals`
 
 **Vendor-metric external catalog precondition** — Exercises the 3.1 SHOULD-window behavior for vendor_metric goals whose metric_id is absent from a seeded measurement.metrics[] catalog.
 Flow: `sync_accounts → comply_test_controller → create_media_buy`
@@ -1864,7 +1864,7 @@ Flow: `comply_test_controller`
 **OAuth discovery and metadata consistency** — Capability-gated evaluation of an agent's RFC 9728 protected-resource metadata and the complete RFC 8414 authorization-server graph it advertises.
 Flow: `get_adcp_capabilities`
 
-**Signed requests — RFC 9421 transport-layer verification** — Agent verifies RFC 9421 HTTP Signatures on incoming AdCP requests per the 3.1-compatible transport-layer profile. Universal capability-gated storyboard — runs for any agent advertising `request_signing.supported: true` regardless of `supported_protocols`. Graded against the legacy wire suite covering every 3.1 checklist step and canonicalization-edge rule.
+**Signed requests — RFC 9421 transport-layer verification** — Agent verifies RFC 9421 HTTP Signatures on incoming AdCP requests per the 3.1-compatible transport-layer profile. Universal capability-gated storyboard — runs for any agent advertising `request_signing.supported: true` regardless of `supported_protocols`. Graded against the legacy wire suite covering every 3.1 checklist step and canonicalization-edge rule; a verifier advertising `covers_content_digest: \
 Flow: `get_adcp_capabilities`
 
 **Trusted Match publisher authentication rejection** — Verifies that a TMP router deployment rejects schema-valid Context Match and Identity Match requests with absent or invalid publisher authentication using HTTP 401 and a WWW-Authenticate challenge.
@@ -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

@@ -391,6 +391,22 @@ Each `CanonicalFormatLegacyRoute` contains `product_id`, the stable
 resolver to `AgentClient` or `createAdcpServerFromPlatform()` without changing
 the existing resolver callback contract.
 
+Routes built with `legacyRoutesForProduct()` from products returned by
+`getProducts()` also record `seller_declared`. It is `false` when the SDK derived
+the option from a seller's legacy `format_ids`; such a route also carries
+`canonical_selector`, the `format_kind` + `params` that a canonical-wire write
+sends in place of the SDK-minted `format_option_id`, which the seller cannot
+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.
+
 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,18 +11,18 @@ below as the publication/deployment gate.
 
 | Fact | Value |
 | --- | --- |
-| Exact npm package | `@adcp/sdk@15.8.1` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.8.1 dist.integrity` |
+| Exact npm package | `@adcp/sdk@16.0.0-beta.1` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.0.0-beta.1 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
-| Default AdCP wire release | `3.2.3` |
-| 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` |
+| 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` |
 | Canonical migration notes | [SDK 15 OAuth](./migration-oauth-issuer-bindings.md), [issuer-binding and storage](./guides/OAUTH-ISSUER-BINDING.md); historical [13.x → 14](./migration-13-to-14.md) |
 
 Install exact production inputs rather than a moving range or dist-tag:
 
 ```bash
-npm install --save-exact '@adcp/sdk@15.8.1'
-npm view '@adcp/sdk@15.8.1' dist.integrity
+npm install --save-exact '@adcp/sdk@16.0.0-beta.1'
+npm view '@adcp/sdk@16.0.0-beta.1' dist.integrity
 ```
 
 ### Required and optional peers
@@ -63,7 +63,7 @@ ESM example:
 import { getCanonicalToolValidator } from '@adcp/sdk/schemas';
 
 const validate = getCanonicalToolValidator('get_reporting_status', 'sync', {
-  adcpVersion: '3.2.3',
+  adcpVersion: '3.2.4',
 });
 if (!validate) throw new Error('Requested protocol schema is unavailable');
 
@@ -86,7 +86,7 @@ CommonJS uses the same packed-artifact export:
 ```js
 const { getCanonicalToolValidator } = require('@adcp/sdk/schemas');
 const validate = getCanonicalToolValidator('get_reporting_status', 'sync', {
-  adcpVersion: '3.2.3',
+  adcpVersion: '3.2.4',
 });
 if (!validate) throw new Error('Requested protocol schema is unavailable');
 if (validate({ status: 'completed', view: 'summary' })) {