@adcp/sdk 15.9.1 → 16.0.0-beta.2

package/dist/lib/validation/schema-loader.d.mts

@@ -68,6 +68,8 @@ export declare function resolveBundleKey(version: string): string;
  */
 export declare function validateAdcpVersionWire(value: unknown): asserts value is string;
 export declare function toReleasePrecisionWire(bundleKeyOrVersion: string): string;
+export declare function withIdentity33SchemaScope<T>(fn: () => T, enabled?: boolean): T;
+export declare function bindIdentity33SchemaScope<T extends object>(instance: T): T;
 /**
  * Register a schema bundle supplied outside the installed SDK package.
  *

package/dist/lib/validation/schema-loader.d.ts

@@ -68,6 +68,8 @@ export declare function resolveBundleKey(version: string): string;
  */
 export declare function validateAdcpVersionWire(value: unknown): asserts value is string;
 export declare function toReleasePrecisionWire(bundleKeyOrVersion: string): string;
+export declare function withIdentity33SchemaScope<T>(fn: () => T, enabled?: boolean): T;
+export declare function bindIdentity33SchemaScope<T extends object>(instance: T): T;
 /**
  * Register a schema bundle supplied outside the installed SDK package.
  *

package/dist/lib/validation/schema-loader.js

@@ -30,6 +30,7 @@ var schema_loader_exports = {};
 __export(schema_loader_exports, {
   SCHEMA_FILENAME_SUFFIX: () => SCHEMA_FILENAME_SUFFIX,
   _resetValidationLoader: () => _resetValidationLoader,
+  bindIdentity33SchemaScope: () => bindIdentity33SchemaScope,
   getCanonicalToolValidatorForVersion: () => getCanonicalToolValidatorForVersion,
   getMcpProfileInputSchema: () => getMcpProfileInputSchema,
   getMcpToolSchema: () => getMcpToolSchema,
@@ -43,6 +44,7 @@ __export(schema_loader_exports, {
   getValidator: () => getValidator,
   hasSchemaBundle: () => hasSchemaBundle,
   isExternalSchemaRootActive: () => isExternalSchemaRootActive,
+  isIdentity33SchemaScope: () => isIdentity33SchemaScope,
   listValidatorKeys: () => listValidatorKeys,
   registerExternalSchemaRoot: () => registerExternalSchemaRoot,
   resolveBundleKey: () => resolveBundleKey,
@@ -50,7 +52,8 @@ __export(schema_loader_exports, {
   toReleasePrecisionWire: () => toReleasePrecisionWire,
   unregisterExternalSchemaRoot: () => unregisterExternalSchemaRoot,
   validateAdcpVersionWire: () => validateAdcpVersionWire,
-  withExternalSchemaRoot: () => withExternalSchemaRoot
+  withExternalSchemaRoot: () => withExternalSchemaRoot,
+  withIdentity33SchemaScope: () => withIdentity33SchemaScope
 });
 module.exports = __toCommonJS(schema_loader_exports);
 var import_ajv = __toESM(require("ajv"));
@@ -123,12 +126,30 @@ function toReleasePrecisionWire(bundleKeyOrVersion) {
     "adcpVersion"
   );
 }
+const identity33Scope = new import_async_hooks.AsyncLocalStorage();
+function isIdentity33SchemaScope() {
+  return identity33Scope.getStore() === true;
+}
+function withIdentity33SchemaScope(fn, enabled = true) {
+  return identity33Scope.run(enabled, fn);
+}
+function bindIdentity33SchemaScope(instance) {
+  return new Proxy(instance, {
+    get(target, property, receiver) {
+      const value = withIdentity33SchemaScope(() => Reflect.get(target, property, receiver));
+      const descriptor = Reflect.getOwnPropertyDescriptor(target, property);
+      if (descriptor && !descriptor.configurable && "value" in descriptor && !descriptor.writable) return value;
+      return typeof value === "function" ? (...args) => withIdentity33SchemaScope(() => value.apply(target, args)) : value;
+    }
+  });
+}
 function resolveSchemaRoot(version) {
   const key = resolveBundleKey(version);
   const scopedRoot = scopedExternalSchemaRoots.getStore()?.get(key);
   if (scopedRoot && (0, import_fs.existsSync)(scopedRoot)) return scopedRoot;
   const externalRoot = externalSchemaRoots.get(key);
   if (externalRoot && (0, import_fs.existsSync)(externalRoot)) return externalRoot;
+  if (isIdentity33SchemaScope() && key === "3.3") return resolveSchemaRoot(import_version.ADCP_VERSION);
   const distCandidate = import_path.default.join(__dirname, "..", "schemas-data", key);
   if ((0, import_fs.existsSync)(distCandidate)) return distCandidate;
   const releasePrecisionMatch = /^\d+\.\d+-/.test(key);
@@ -334,6 +355,7 @@ function withExternalSchemaRoot(version, root, fn) {
 }
 function isExternalSchemaRootActive(version) {
   const key = resolveBundleKey(version);
+  if (isIdentity33SchemaScope() && key === "3.3") return true;
   const scopedRoot = scopedExternalSchemaRoots.getStore()?.get(key);
   if (scopedRoot && (0, import_fs.existsSync)(scopedRoot)) return true;
   const registeredRoot = externalSchemaRoots.get(key);
@@ -601,7 +623,7 @@ function getSchemaValidatorByRef(schemaRef, version = import_version.ADCP_VERSIO
   });
   (0, import_ajv_formats.default)(ajv);
   for (const keyword of keywords ?? []) ajv.addKeyword(keyword);
-  const rawSchema = loadJson(file);
+  const rawSchema = identity33ReferenceSchema(loadJson(file), version);
   const dependencySchemas = [];
   const registeredIds = /* @__PURE__ */ new Map();
   for (const schemaFile of walkJsonFiles(root)) {
@@ -610,7 +632,7 @@ function getSchemaValidatorByRef(schemaRef, version = import_version.ADCP_VERSIO
       continue;
     }
     if (schemaFile === file) continue;
-    const schema = loadJson(schemaFile);
+    const schema = identity33ReferenceSchema(loadJson(schemaFile), version);
     if ((keywords || allErrors) && typeof schema.$id === "string") {
       const previous = schema.$id === rawSchema.$id ? rawSchema : registeredIds.get(schema.$id);
       if (previous && !(0, import_node_util.isDeepStrictEqual)(previous, schema)) {
@@ -710,6 +732,20 @@ function getRegisteredSchemaIds(version = import_version.ADCP_VERSION) {
   const bundledRegistry = s.bundledAjv.schemas;
   return [.../* @__PURE__ */ new Set([...Object.keys(registry ?? {}), ...Object.keys(bundledRegistry ?? {})])];
 }
+function identity33ReferenceSchema(schema, version) {
+  if (!isIdentity33SchemaScope() || resolveBundleKey(version) !== "3.3") return schema;
+  const clone = structuredClone(schema);
+  const pending = [clone];
+  while (pending.length) {
+    const node = pending.pop();
+    if (!node || typeof node !== "object") continue;
+    const object = node;
+    if (Array.isArray(object.enum) && object.enum.includes("destination_state_changed"))
+      object.enum = [...object.enum, "relationship_changed", "relationship_expiring"];
+    for (const value of Object.values(object)) if (typeof value === "object") pending.push(value);
+  }
+  return clone;
+}
 function hasSchemaBundle(version) {
   try {
     resolveSchemaRoot(version);
@@ -965,6 +1001,7 @@ function cloneJsonValue(value) {
 0 && (module.exports = {
   SCHEMA_FILENAME_SUFFIX,
   _resetValidationLoader,
+  bindIdentity33SchemaScope,
   getCanonicalToolValidatorForVersion,
   getMcpProfileInputSchema,
   getMcpToolSchema,
@@ -978,6 +1015,7 @@ function cloneJsonValue(value) {
   getValidator,
   hasSchemaBundle,
   isExternalSchemaRootActive,
+  isIdentity33SchemaScope,
   listValidatorKeys,
   registerExternalSchemaRoot,
   resolveBundleKey,
@@ -985,5 +1023,6 @@ function cloneJsonValue(value) {
   toReleasePrecisionWire,
   unregisterExternalSchemaRoot,
   validateAdcpVersionWire,
-  withExternalSchemaRoot
+  withExternalSchemaRoot,
+  withIdentity33SchemaScope
 });

package/dist/lib/validation/schema-loader.mjs

@@ -73,12 +73,30 @@ function toReleasePrecisionWire(bundleKeyOrVersion) {
     "adcpVersion"
   );
 }
+const identity33Scope = new AsyncLocalStorage();
+function isIdentity33SchemaScope() {
+  return identity33Scope.getStore() === true;
+}
+function withIdentity33SchemaScope(fn, enabled = true) {
+  return identity33Scope.run(enabled, fn);
+}
+function bindIdentity33SchemaScope(instance) {
+  return new Proxy(instance, {
+    get(target, property, receiver) {
+      const value = withIdentity33SchemaScope(() => Reflect.get(target, property, receiver));
+      const descriptor = Reflect.getOwnPropertyDescriptor(target, property);
+      if (descriptor && !descriptor.configurable && "value" in descriptor && !descriptor.writable) return value;
+      return typeof value === "function" ? (...args) => withIdentity33SchemaScope(() => value.apply(target, args)) : value;
+    }
+  });
+}
 function resolveSchemaRoot(version) {
   const key = resolveBundleKey(version);
   const scopedRoot = scopedExternalSchemaRoots.getStore()?.get(key);
   if (scopedRoot && existsSync(scopedRoot)) return scopedRoot;
   const externalRoot = externalSchemaRoots.get(key);
   if (externalRoot && existsSync(externalRoot)) return externalRoot;
+  if (isIdentity33SchemaScope() && key === "3.3") return resolveSchemaRoot(ADCP_VERSION);
   const distCandidate = path.join(__dirname, "..", "schemas-data", key);
   if (existsSync(distCandidate)) return distCandidate;
   const releasePrecisionMatch = /^\d+\.\d+-/.test(key);
@@ -284,6 +302,7 @@ function withExternalSchemaRoot(version, root, fn) {
 }
 function isExternalSchemaRootActive(version) {
   const key = resolveBundleKey(version);
+  if (isIdentity33SchemaScope() && key === "3.3") return true;
   const scopedRoot = scopedExternalSchemaRoots.getStore()?.get(key);
   if (scopedRoot && existsSync(scopedRoot)) return true;
   const registeredRoot = externalSchemaRoots.get(key);
@@ -551,7 +570,7 @@ function getSchemaValidatorByRef(schemaRef, version = ADCP_VERSION, keywords, op
   });
   addFormats(ajv);
   for (const keyword of keywords ?? []) ajv.addKeyword(keyword);
-  const rawSchema = loadJson(file);
+  const rawSchema = identity33ReferenceSchema(loadJson(file), version);
   const dependencySchemas = [];
   const registeredIds = /* @__PURE__ */ new Map();
   for (const schemaFile of walkJsonFiles(root)) {
@@ -560,7 +579,7 @@ function getSchemaValidatorByRef(schemaRef, version = ADCP_VERSION, keywords, op
       continue;
     }
     if (schemaFile === file) continue;
-    const schema = loadJson(schemaFile);
+    const schema = identity33ReferenceSchema(loadJson(schemaFile), version);
     if ((keywords || allErrors) && typeof schema.$id === "string") {
       const previous = schema.$id === rawSchema.$id ? rawSchema : registeredIds.get(schema.$id);
       if (previous && !isDeepStrictEqual(previous, schema)) {
@@ -660,6 +679,20 @@ function getRegisteredSchemaIds(version = ADCP_VERSION) {
   const bundledRegistry = s.bundledAjv.schemas;
   return [.../* @__PURE__ */ new Set([...Object.keys(registry ?? {}), ...Object.keys(bundledRegistry ?? {})])];
 }
+function identity33ReferenceSchema(schema, version) {
+  if (!isIdentity33SchemaScope() || resolveBundleKey(version) !== "3.3") return schema;
+  const clone = structuredClone(schema);
+  const pending = [clone];
+  while (pending.length) {
+    const node = pending.pop();
+    if (!node || typeof node !== "object") continue;
+    const object = node;
+    if (Array.isArray(object.enum) && object.enum.includes("destination_state_changed"))
+      object.enum = [...object.enum, "relationship_changed", "relationship_expiring"];
+    for (const value of Object.values(object)) if (typeof value === "object") pending.push(value);
+  }
+  return clone;
+}
 function hasSchemaBundle(version) {
   try {
     resolveSchemaRoot(version);
@@ -914,6 +947,7 @@ function cloneJsonValue(value) {
 export {
   SCHEMA_FILENAME_SUFFIX,
   _resetValidationLoader,
+  bindIdentity33SchemaScope,
   getCanonicalToolValidatorForVersion,
   getMcpProfileInputSchema,
   getMcpToolSchema,
@@ -927,6 +961,7 @@ export {
   getValidator,
   hasSchemaBundle,
   isExternalSchemaRootActive,
+  isIdentity33SchemaScope,
   listValidatorKeys,
   registerExternalSchemaRoot,
   resolveBundleKey,
@@ -934,5 +969,6 @@ export {
   toReleasePrecisionWire,
   unregisterExternalSchemaRoot,
   validateAdcpVersionWire,
-  withExternalSchemaRoot
+  withExternalSchemaRoot,
+  withIdentity33SchemaScope
 };

package/dist/lib/version.d.mts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "15.9.1";
+export declare const LIBRARY_VERSION = "16.0.0-beta.2";
 /**
  * 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.1";
+    readonly library: "16.0.0-beta.2";
     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-14T11:09:46.080Z";
+    readonly generatedAt: "2026-10-15T15:37:12.181Z";
 };
 /**
  * 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.1";
+export declare const LIBRARY_VERSION = "16.0.0-beta.2";
 /**
  * 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.1";
+    readonly library: "16.0.0-beta.2";
     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-14T11:09:46.080Z";
+    readonly generatedAt: "2026-10-15T15:37:12.181Z";
 };
 /**
  * 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.1";
+const LIBRARY_VERSION = "16.0.0-beta.2";
 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.1",
+  library: "16.0.0-beta.2",
   adcp: "3.2.4",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-14T11:09:46.080Z"
+  generatedAt: "2026-10-15T15:37:12.181Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "15.9.1";
+const LIBRARY_VERSION = "16.0.0-beta.2";
 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.1",
+  library: "16.0.0-beta.2",
   adcp: "3.2.4",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-14T11:09:46.080Z"
+  generatedAt: "2026-10-15T15:37:12.181Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-14
-> @adcp/sdk v15.9.1
+> Generated at: 2026-10-15
+> @adcp/sdk v16.0.0-beta.2
 
 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,8 +955,21 @@ 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. Before every submission the sink looks that job ID up in
   the destination project and location: a job that finished cleanly counts as
@@ -957,9 +1017,9 @@ setInterval(() => {
   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
+  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
   `` `region-<location>`.INFORMATION_SCHEMA.JOBS_BY_PROJECT `` (needs
   `bigquery.jobs.listAll`; about 180 days of history), filtering on
@@ -1007,6 +1067,16 @@ setInterval(() => {
   rejects after clearing the sink (it could not unregister the consumer), call
   it again before restarting workers. Re-run `REPORTING_WAREHOUSE_SINK_MIGRATION`
   after upgrading: it adds the `reset_generation` column.
+- 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 then ends
+  `DONE` with an error and the attempt advances. Rows do not duplicate, but
+  convergence slows. Also set `location` to the dataset's location: without it
+  a replay lookup of a load job returns 404 for datasets outside the US and EU
+  multi-regions, and the sink uploads again, gets a 409, and fails with a
+  "check projectId and location" error. The sink warns once per process when
+  `location` is unset.
 - Stop old sink workers before relying on these overlap guarantees. If an
   earlier overlapping run left a plan whose starting cursor differs from the
   committed cursor, the sink rejects it before loading. Reconcile the retained
@@ -1170,7 +1240,7 @@ Managed-only changes are lifecycle candidates in their own right. A settlement,
 
 `MAX_MATERIALIZATIONS_PER_ACCOUNT` and `MAX_RECEIPTS_PER_CONSUMER` are lifetime counts by default. Because managed evidence is immutable, a long-lived account eventually reaches them and then stops planning materializations and refuses every receipt with no way back. Construct the store with `new PostgresReportingManagedDeliveryStore(pool, { evidenceRetentionDays })` to make the caps active-scope: only evidence recorded inside that window counts against them, and `pruneExpiredEvidence({ account_id, limit })` deletes what has fallen outside it — never anything still inside the window, never a `pending` or leased materialization, and never a receipt batch inside its own replay retention. Retention has a floor: at least the 30-day receipt replay retention, and at least the strongest durable status or resource-retention horizon registered for the database. Adoption and binding installation exclusively lock the migration-created policy sentinel before account/binding locks; settlement, revocation claim, and pruning hold shared locks on it through their writes. A stronger promise therefore cannot land between a weaker check and its write, while unrelated hot-path readers remain concurrent. Pruning genuinely does its selection before taking the account lock, and asks which receipts a live replay row still names by expanding those rows once rather than posing a containment question per candidate — a shape no index could serve, which held the lock long enough to fail concurrent Core writes with 55P03. Because that selection is unlocked it is a proposal rather than a verdict: every victim is revalidated under the account lock against current live replay rows, surviving receipts and unexpired resources before it is deleted, so a replay that commits in the gap keeps the receipt it promised to reproduce. The revalidation is narrowed to the candidates' own consumers and keys, so the lock still holds no per-candidate scan. The registry lock is held to commit inside the transaction that acts on it, and a precondition such as the installed-window check runs inside that same transaction so a refusal rolls the write back rather than leaving a durable promise nobody validated, so an install cannot read an empty registry while a narrower promise is being registered, and a prune cannot approve a horizon another replica is about to widen. Pruning deletes and tombstones in one statement against one frozen cutoff, so a moving boundary can never leave a deleted row without its permanent identity. Successive prunes demote the tombstones they supersede, so a subject has exactly one tombstone still claiming to be its leaf and a chain pruned twice resolves the same way every time. Re-presenting a pruned receipt byte-identically answers `unchanged` with the instant the tombstone kept, resolves that receipt's own tombstone before any rule about its subject — so an exact re-presentation is not refused as new content for a settled subject — replays the same answer under the same idempotency key by rehydrating from the tombstone when the body is gone, counts as already-resolved for the batch's duplicate-subject rule, and never recreates the row: recreating it restarted the retention clock, undid the storage the prune reclaimed, and moved the published `received_at` to a moment the consumer never filed anything at. A pruned receipt ID can never bind different content, a subject whose accepted leaf expired can never reopen — the read projection consults tombstones, not just live rows — and materialization attempt history survives as a compact terminal record, so a revision that exhausted its attempts or already succeeded does not restart at attempt 1 once its rows age out. Both conclusions — the acceptance and the fact a delivery succeeded — are folded into the live, filtered and lifecycle projections alike. Counters describe exactly the records the response emits, never more and never less, so a buyer recomputing the association cannot see `ASSOCIATED_HISTORY_INCOMPLETE`; retention therefore refuses to prune an acceptance while the resource it accepts is still readable, which is what keeps a `complete` period from having nothing to show for itself. An acceptance carries the consumer that gave it, so one consumer's pruned acceptance never settles the obligation on another's behalf — including the anonymous fail-safe consumer, which owns no acceptances at all. Pruning also removes the expired replay row before the receipts it names, keeps any receipt a surviving replay row still references — a later batch can name an earlier receipt — and keeps any materialization whose resource is still readable or that a retained receipt names as its evidence. An adjustment receipt names no materialization — it names the revision it corrects — so the readable-resource hold matches on that revision as well, or a period whose revision resource was still readable lost the adjustment acceptance behind its own `complete`. Run it from the same scheduler that runs the worker. Lifecycle receipt reads are driven from the obligation's own subjects into a `(subject_id, receipt_kind, recorded_at)` index rather than asking the global receipt table which of its rows belong to an obligation — a question that supplies neither account nor consumer, so every due obligation re-scanned the whole receipt history. The managed state digest, the obligated-consumer roster read and the permanent delivery tombstones do the same — consumer statuses carry an `obligation_id` index and materialization tombstones an `(obligation_id, reached_success, reached_success_at)` one — because that digest is read inside the apply transaction while it holds the account lock: a scan there is a scan with the lock held, which pushed concurrent Core writes past their lock timeout and failed them with 55P03.
 
-The managed tables are additive and do not alter the Core tables. This is the schema boundary coordinated with #2943: that work owns transactional reporting notification/activity intent and the existing webhook delivery/credential plane. Managed Delivery does not create a second webhook sender, outbox, credential store, or subscriber model. Apply both feature migrations after the Core migration in either order; each owns separate tables and both reuse the Core authority.
+The managed tables are additive and do not alter the Core tables. This is the schema boundary coordinated with the reporting notification work: that work owns transactional reporting notification/activity intent and the existing webhook delivery/credential plane. Managed Delivery does not create a second webhook sender, outbox, credential store, or subscriber model. Apply both feature migrations after the Core migration in either order; each owns separate tables and both reuse the Core authority.
 
 ## Transactional reporting notifications and account activity
 
@@ -1689,7 +1759,7 @@ reconciliation and fails closed if both are supplied, preventing double fire;
 the port's pending rows, rather than `listPendingTransitions()`, own retry.
 
 The activity table is deliberately separate from Core revision and obligation
-rows. Managed Delivery/Reconciled Billing work in #2944 can add immutable
+rows. Managed Delivery/Reconciled Billing work can add immutable
 materialization and receipt tables without changing this transition identity,
 queue schema, or migration ordering.