@adcp/sdk 15.4.0 → 15.5.0

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

@@ -0,0 +1,142 @@
+# Discovery cache and MCP session reuse
+
+A server-side caller that makes one AdCP call per incoming request, building a `SingleAgentClient` (or `AgentClient`) per request because auth, headers or deadlines differ, used to pay for the SDK's whole setup sequence on every call: an endpoint probe, a `tools/list` and a `get_adcp_capabilities`, each on its own MCP session. Against a slow seller that comes straight out of the caller's deadline.
+
+Two independent mechanisms remove that cost:
+
+1. an **opt-in shared discovery cache** so client instances for the same agent and principal reuse one endpoint / `tools/list` / capabilities observation, and
+2. **reusable MCP connections** that per-call correlation headers, `AbortSignal`s and timeouts no longer split, plus a public **connection scope** to run a whole workflow on one session.
+
+## Shared discovery cache
+
+```ts
+import { AgentClient, createInMemoryAgentDiscoveryCache } from '@adcp/sdk';
+
+// One per process (or implement AgentDiscoveryCache over your own store).
+const discoveryCache = createInMemoryAgentDiscoveryCache({ maxEntries: 256 });
+
+function clientFor(request: IncomingRequest) {
+  return new AgentClient(
+    {
+      id: 'seller',
+      name: 'Seller',
+      agent_uri: 'https://seller.example/mcp',
+      protocol: 'mcp',
+      auth_token: request.token,
+    },
+    {
+      discoveryCache: {
+        cache: discoveryCache,
+        authIdentity: request.authorizationScopeId, // principal + tenant + granted permissions
+        ttlMs: 5 * 60_000, // default 5 minutes, max 24 hours
+      },
+    }
+  );
+}
+```
+
+### What is shared, and for how long
+
+An entry holds the endpoint that discovery resolved, the `tools/list` input-schema map and the capabilities from an authoritative `get_adcp_capabilities` response. Every entry carries `observedAt` / `expiresAt`; the SDK enforces the TTL on read, whatever your backend does. A reader also applies its own `ttlMs`, so a short-TTL client cannot inherit a longer writer's freshness window. A long-lived client honors that bound for both endpoints and capabilities in its own in-memory copy.
+
+### Isolation (the part to get right)
+
+The key is a SHA-256 over:
+
+| Input                                                | Why                                                                                                                    |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| agent URL and protocol                               | endpoint identity                                                                                                      |
+| `authIdentity`                                       | **caller-owned** principal. Deliberately _not_ derived from the token: you decide who may share evidence               |
+| credential kind (anonymous, bearer, OAuth or header) | Keeps anonymous and authenticated discovery separate while allowing token rotation                                     |
+| configured `adcpVersion` / `wireAdcpVersion`         | negotiated version                                                                                                     |
+| every non-correlation, non-credential header         | unknown `x-*` tenant / routing / policy headers can select a different upstream view, so they fail closed into the key. This includes `baggage`, **ambient OpenTelemetry baggage included** |
+| request-signing identity and policy                  | `kind`, `kid`, `alg`, agent URL and signing policy; never the private key                                              |
+| effective `allowPrivateIp`, `maxResponseBytes`       | the transport policy the evidence was gathered under (per-call `transport` overrides included)                         |
+
+Not part of the key: correlation headers (`x-request-id`, `x-correlation-id`, `traceparent`, ...), and credential header values (`Authorization`, `x-adcp-auth`) — OAuth and `auth_token` credentials are also owned by `authIdentity`; a token rotation for the same authorization scope keeps the entry. **Choose `authIdentity` at least as narrow as the credential's authorization scope.** Change the identity or invalidate the cache when permissions change or access is revoked; use a distinct identity for anonymous access. Two principals must never share an identity. Keys are hashes and never contain the identity, token or header values.
+
+Never shared:
+
+- **Synthetic capabilities** (a seller with no `get_adcp_capabilities`, or whose capabilities call failed) stay private to the instance that built them.
+- **Scoped `trustedFetchFn` calls** bypass the cache in both directions: their network boundary is per call.
+- Entries are copied in and out, so mutating a returned capabilities object cannot poison the cache.
+
+### Concurrency, cancellation, failures
+
+- Cold concurrent clients for the same key share one in-process discovery: one leader discovers, followers wait for it under **their own** signal and request timeout. A leader that is cancelled or fails never fails its followers; they discover for themselves.
+- A cache backend that throws, returns a malformed entry or hangs costs a rediscovery, never a failed call. Each cache read or mutation wait is bounded by a 2 second deadline and, for reads and automatic writes, by the caller's `AbortSignal`. Mutations of one key are ordered in-process. A timed-out backend mutation retains its place until it settles, so a late writer cannot overwrite or delete a newer seed; later mutation waits also time out while discovery proceeds live. The queue is bounded: a write whose caller already stopped waiting is dropped if it has not started, a full per-key queue refuses further writes (a failed write, never a failed call), and invalidations queued behind a hung delete coalesce into one follow-up delete. Nothing is ever replayed automatically.
+- The shared cache is in-process singleflight. Across processes each cold process still discovers once.
+
+### Invalidation
+
+- `client.invalidateDiscoveryCache()` drops this client's local evidence and the shared entry. `SingleAgentClient.refreshCapabilities()` does the same and re-discovers; on `AgentClient`, call `invalidateDiscoveryCache()` and then `getCapabilities()`.
+- A feature check (`require`, or the pre-flight check before a task) that fails against **shared** evidence invalidates it and re-decides on live capabilities before refusing the call.
+- A seller error of `VERSION_UNSUPPORTED`, `UNSUPPORTED_FEATURE`, `FEATURE_UNSUPPORTED`, `TOOL_NOT_FOUND`, `METHOD_NOT_FOUND` or `UNKNOWN_TOOL` invalidates the shared entry, on every task path including `executeTask()` and the typed methods. Each such live re-check costs one rediscovery; a seller that genuinely lacks a feature pays it on every refused call.
+- A malformed or expired entry is deleted and treated as a miss. An entry older than this reader's shorter TTL is also a miss.
+- Invalidation by any client sharing the cache in this process also drops other instances' local evidence and endpoint for that key (application-owned `primeCapabilities` evidence keeps its own freshness bound). In this process an invalidation leaves a tombstone, so a shared entry observed before it is a miss even when the backend delete failed or is still queued; the tombstone record set is bounded and, once pruned, errs toward a miss. Other processes still rely on the backend delete.
+- In-process invalidation takes precedence over an earlier discovery still in flight. External backends with concurrent writers in other processes must supply their own atomic invalidation/versioning if they need that guarantee across processes.
+
+### Pre-seeding
+
+| Method                | Lifetime                                                       | Result                                              |
+| --------------------- | -------------------------------------------------------------- | --------------------------------------------------- |
+| `primeCapabilities`   | One client, bound to its capability scope                      | Synchronous; `true` if accepted, otherwise `false`  |
+| `primeDiscoveryCache` | Shared cache, bound to explicit authorization identity and TTL | Asynchronous; `true` if accepted, otherwise `false` |
+
+```ts
+const ok = await client.primeDiscoveryCache({
+  capabilities, // authoritative, non-synthetic
+  toolSchemas, // optional when capabilities.discoveredTools is present
+  endpoint: { agentUri: 'https://seller.example/mcp', mcpEra: 'modern' }, // optional
+});
+```
+
+Unlike [`primeCapabilities`](../TYPE-SUMMARY.md) — which stays client-bound and scope-keyed — seeded evidence outlives the instance. It returns `true` only once the backing cache accepted the entry, and `false` (seeding nothing) for synthetic, malformed, uncloneable or foreign-origin evidence. When the cache rejects the write or does not answer within the 2 second deadline, `false` means *not confirmed*, not *empty*: a write already handed to the backend may still land later, while one still queued behind earlier operations is dropped. After such a `false`, seed again or invalidate rather than assuming nothing was stored. Without `endpoint` the first call of a cold client still runs the endpoint probe once.
+
+## Reusable MCP connections
+
+This behavior applies by default, including calls that pass a signal or timeout outside a connection scope. The process-wide legacy/OAuth session cache retains at most 20 connections per cache with LRU eviction and has no idle expiry. For request workflows with many distinct credentials, use a scope to bound session lifetime. At process shutdown, `closeConnections()` from `@adcp/sdk/advanced` closes the process-wide connections.
+
+A reusable session is keyed only by what changes the _connection_: endpoint, credential, tenant / routing headers, signing identity, `allowPrivateIp`, a caller-injected fetch, and the workflow scope. These no longer choose or split a session:
+
+- **Correlation headers**: `traceparent`, `tracestate`, `x-request-id`, `x-correlation-id`, `x-trace-id`, `x-span-id`, `x-debug-id`, `x-client-request-id`, `x-b3-*`, `x-amzn-trace-id`, `x-cloud-trace-context`, `x-datadog-*`, `sentry-trace`, and vendor-prefixed `x-<vendor>-request-id` / `-correlation-id` / `-trace-id` / `-span-id` / `-debug-id`. Names suggesting credentials or tenant/routing identity (including `auth`, `token`, `tenant`, `account`, `workspace`, `seat`, `advertiser`, `publisher`, `buyer` and `seller`) are never treated as correlation. **`baggage` stays in the key**: it can carry tenant or routing members. Any header outside the list above also stays in the key (fail closed).
+- **`AbortSignal`** and **`requestTimeoutMs`**: they bound a call.
+
+Each call still sends _its own_ correlation headers, deadline and cancellation on every request over the shared session (including concurrent calls), through per-call context rather than values frozen at connect time. Explicit caller headers win over ambient OpenTelemetry context.
+
+Isolation properties:
+
+- A cancelled or timed-out call tears down only its own request. It does not evict or terminate a session other calls are using; other failures retire the session and close it once its in-flight calls finish. A session the seller has expired may fail the current call once; the SDK retires that connection and never replays a dispatched call, so a caller must reconcile the outcome of a mutation that failed that way (for example by re-reading it) before retrying with the same `idempotency_key`.
+- A caller that joins another caller's in-flight connect waits under its own signal and timeout. If the creator cancels the connect, the joiner retries for itself, with at most two retries after foreign aborts.
+- A caller-injected `fetchFn` (a per-call network trust boundary) keeps its own one-shot session outside a connection scope; inside a scope its identity is part of the key.
+- Connections are never shared across credentials, tenant headers, signing identities or `allowPrivateIp` settings.
+
+### Public connection scope
+
+```ts
+import { withMCPConnectionScope } from '@adcp/sdk'; // also from '@adcp/sdk/advanced'
+
+await withMCPConnectionScope(async () => {
+  await client.syncAccounts(accounts);
+  await client.getCapabilities();
+  await client.getProducts(brief); // same MCP session
+}); // the session is terminated once, here
+```
+
+Await every operation before the scope callback returns; the callback owns the session lifetime. Open process-wide sessions can keep sockets alive, so close them at shutdown.
+
+Inside a scope the endpoint probe, capability discovery, `tools/list` and tool calls share one negotiated session per identity. `closeScopedConnections()` closes the current MCP scope's sessions early and does nothing when no MCP scope is active (A2A connections are not scoped). Nested `withMCPConnectionScope` calls join the outer scope unless you pass `{ isolate: true }`.
+
+### One exception: the first legacy handoff
+
+For a seller on the pre-2026 MCP protocol era, the SDK negotiates with the v2 client first and then hands the call to the v1 client so 2025 Tasks keep working. That handoff is a cold cost the SDK cannot avoid: the first scope against such a seller opens one classification handshake plus one shared v1 session. Within the scope everything after that (probe aside) shares the v1 session, including `tools/list`, and the classification is remembered across scopes for five minutes, so a later scope opens only its own session. Modern-era sellers need a single negotiation per scope.
+
+### Troubleshooting cache misses
+
+Unknown headers participate in identity. A varying header such as `x-forwarded-for` causes a cache miss even when `authIdentity` matches, and so does varying `baggage`, including ambient OpenTelemetry baggage that differs per request. Ambient OpenTelemetry context is not a way to split or merge keys: set the baggage identically for callers that should share evidence, or keep it out of routing. Calls with a scoped `trustedFetchFn` bypass the cache entirely, so a client that always passes one never hits it. Also check version, transport policy, signing policy and TTL before assuming the cache backend failed.
+
+The cache holds capabilities, schemas and the endpoint URL. Endpoint sharing excludes URLs with userinfo, a query string or a fragment; those endpoints stay local while their capabilities and schemas can still be shared. `primeDiscoveryCache` refuses such an endpoint. Put credentials in authentication headers. Treat a custom `AgentDiscoveryCache` backend as trusted storage.
+
+## Related
+
+- [Session reuse for multi-tool workflows](https://github.com/adcontextprotocol/adcp-client/issues/2118).

package/docs/guides/EXISTING-PLATFORM.md

@@ -77,22 +77,53 @@ The submitted continuation's `waitForCompletion` function is deliberately proces
 Do not catch every outcome into a string. Switch on `result.status`; use `result.adcpError` for failed results, and catch thrown cancellation/configuration errors separately. Internal transport retries reuse an idempotency key. A new application intent must receive a new key; after an ambiguous timeout, reconcile by the persisted natural key before deciding to retry.
 
 Transport diagnostics never delay delivery of the operational `Response`.
-SSE, non-text, and explicitly over-limit bodies are not cloned; their single
-response event is emitted immediately with `responseBodyTruncated: true`. Other
-diagnostic text bodies, including chunked responses without `Content-Length`
-and responses with an invalid length, are cloned synchronously and captured in
-the background up to 64 KiB for at most `BODY_SNIPPET_TIMEOUT_MS` (currently 1
-second). Their single response event is emitted when capture completes,
-truncates, or expires, while the original response stream remains exclusively
-available to the protocol client. The enclosing task then waits within
+Each request emits `request_started`, then `response_received`, then (for
+streamed replies) `response_completed`. `response_received` means **response
+headers arrived**: its `durationMs` is time to headers. For an MCP server that
+answers over `text/event-stream`, that is not the end of the reply, so do not
+record it as a finished call.
+
+Bodies are captured only when they are text-like and declare a finite
+`Content-Length` of at most 64 KiB. Those are cloned synchronously and read in
+the background for at most `BODY_SNIPPET_TIMEOUT_MS` (currently 1 second), and
+their single `response_received` event is emitted when capture completes,
+truncates, or expires. The enclosing task then waits within
 `OBSERVER_FLUSH_TIMEOUT_MS` for that event's asynchronous observer, so
-short-lived processes do not lose the final audit record. Observer
-failures remain isolated. Applications should synchronously enqueue each event into their own
-bounded in-memory or durable queue and return promptly; flushing that queue is
-an application lifecycle concern.
+short-lived processes do not lose the final audit record.
+
+Every other body is never cloned or buffered: SSE, non-text content, chunked
+responses or responses with a missing or invalid `Content-Length`, and bodies
+declared over the limit. Their `response_received` event is emitted
+immediately with `responseBodyTruncated: true` and, when the body can be observed, `streaming: true`; `streaming` is the signal that a `response_completed` event will follow. The body
+is passed through an observing stream with the same bytes, status, headers,
+`url`, `redirected`, and `type`, and with pull-driven backpressure. When the
+caller finishes with it, exactly one `response_completed` event reports
+`outcome`, total `bytes`, and `durationMs` measured from `startedAt`:
+
+| `outcome`   | Meaning                                                                    |
+| ----------- | -------------------------------------------------------------------------- |
+| `ended`     | The caller read the stream to EOF.                                         |
+| `errored`   | The stream failed (`errorName` / sanitized `errorMessage` are set).        |
+| `aborted`   | The request's `AbortSignal` fired (also when the body is cancelled after it fired), or the stream failed with an abort error. |
+| `cancelled` | The consumer cancelled the body, including SDK cleanup after delivering a successful MCP result. |
+
+A streamed call that never answers therefore shows `response_received` with no
+matching `response_completed` until the caller aborts it (for example, when its
+deadline fires an `AbortSignal` on the request), then an `aborted` completion. `response_completed` is fire-and-forget: it can arrive
+after the diagnostics scope exits, the scope never waits for it, and a body
+that is never read or aborted never emits one. It carries the request correlation
+fields, `httpStatus`, and `statusText`, but no request or response bodies and no
+response headers. The SDK does not parse SSE messages, so it cannot say whether
+a stream carried a final result.
+
+Observer failures remain isolated. Applications should synchronously enqueue
+each event into their own bounded in-memory or durable queue and return
+promptly; flushing that queue is an application lifecycle concern.
 
 ## Reuse scoped capability evidence
 
+For evidence shared across separate client instances, use the opt-in [discovery cache](./DISCOVERY-CACHE-AND-SESSION-REUSE.md). That guide also covers MCP connection scopes and per-call session reuse.
+
 An application factory that already performs a bounded seller preflight can
 construct and prime the specific client instance before exposing it for task
 dispatch:

package/docs/guides/REPORTING-LEDGER.md

@@ -272,6 +272,215 @@ Official configurations also pin a `finalityPolicy` (`policyId` plus `source_fin
 
 Every revision stores its rows together with an RFC 8785 JCS SHA-256 binding and exact decimal control totals for requested numeric metrics. A revision number and obligation are immutable. Official revisions are terminal; later source corrections are immutable adjustments bound to the official revision, never superseding revisions. Status snapshots omit row payloads, are capped at 8 MiB, expire after 15 minutes, and keep cursor pages stable over the flat obligation/revision/adjustment union. A periods response returns an opaque `changes_checkpoint`; echo that value verbatim as `changes_after` rather than supplying a timestamp. Account-scoped write/snapshot locks make those checkpoints gap-free for SDK store writes. The default table set is deployment-wide; use a dedicated database/schema and acknowledge that boundary explicitly. `sourceScope` must contain opaque routing identities only—never credentials or bearer tokens—because it is retained with the obligation. Retained resource locations are held to the same rule, and at the seam that persists them rather than only in the worker's pre-flight, because a caller driving `settleMaterialization` directly would otherwise store a presigned location that `get_reporting_status` then publishes. Query and fragment are refused on the raw string rather than on a successful parse, because a relative path carrying a presigning query never parsed as a URL at all; userinfo is refused as a colon-separated pair before the `@`, which is the credential shape, plus any `http(s)` userinfo at all. A blanket `@` rule would refuse `abfss://container@account.dfs.core.windows.net/...` and a Snowflake stage reference, neither of which carries a secret.
 
+## Row storage
+
+By default every revision document carries its rows inline. At pulse cadence
+that keeps bulk report bytes in the transactional database. Opt in to row
+storage to keep only the revision header in the ledger document and store
+rows as verified canonical JSONL chunks (the shared SDK persistence layout,
+adcontextprotocol/adcp#7996):
+
+```ts
+import { REPORTING_ROW_STORAGE_MIGRATION } from '@adcp/sdk/reporting/ledger';
+
+await pool.query(REPORTING_ROW_STORAGE_MIGRATION); // after REPORTING_LEDGER_MIGRATION; PostgreSQL 13+
+const store = new PostgresReportingLedgerStore(pool, {
+  acknowledgeIsolatedDatabase: true,
+  rowStorage: true,
+});
+await store.readyRowStorage();
+```
+
+`createPostgresReliableReportingProductionService` accepts the same
+`rowStorage` option and adds the migration to `setup.migrations`.
+
+- Rows are split into 500-row segments and chunks of at most 10,000 rows or
+  8 MiB. Chunk, segment and manifest digests are committed with the revision,
+  and every read is verified before rows are released. Delivery pages read only
+  the segments they need.
+- A revision whose rows are byte-identical to a live row set in the same
+  obligation is stored as a header-only revision. It gets a new identity,
+  freshness and binding, and references the existing chunks
+  (`rows_shared_from_row_set_id`), so an unchanged pulse uploads nothing.
+- Revisions written before you enable row storage keep their inline rows.
+  Reads handle both forms whether or not the option is set.
+- Missing or corrupt rows inside the retention window make
+  `get_media_buy_delivery` fail with `SERVICE_UNAVAILABLE` rather than reporting
+  the revision as absent; expired rows read like an unknown revision.
+- Managed Delivery claims hydrate PostgreSQL-stored rows automatically.
+
+To move existing inline rows into row storage, run the resumable migration in
+bounded batches. A revision whose rows do not reproduce its committed binding is
+reported in `quarantined` and left untouched:
+
+```ts
+let cursor: string | undefined;
+do {
+  const batch = await store.migrateInlineRows({ limit: 100, cursor });
+  if (batch.quarantined.length) console.warn('unverifiable inline rows', batch.quarantined);
+  cursor = batch.cursor;
+} while (cursor);
+```
+
+Removing rows from ledger documents frees space only after `VACUUM FULL` or an
+online repack of `adcp_reporting_revisions` and `adcp_reporting_adjustments`.
+
+### Object storage bindings
+
+Rows can live in object storage instead of PostgreSQL. A binding is defined in
+host code, which makes the configuration the allowlist: the database records
+which binding each revision used and its identity digest, but it can never
+point reads or writes at a destination the host did not configure.
+
+```ts
+import {
+  PostgresReportingLedgerStore,
+  createFilesystemReportingRowObjectProviderV1,
+} from '@adcp/sdk/reporting/ledger';
+
+const store = new PostgresReportingLedgerStore(pool, {
+  acknowledgeIsolatedDatabase: true,
+  rowStorage: {
+    deploymentNamespace: 'prod-us',
+    bindings: {
+      inline: { kind: 'postgres' },
+      reports: {
+        kind: 'object',
+        provider: 'filesystem', // or a cloud provider registered below
+        location: { root: 'reports' },
+        prefix: 'adcp-rows',
+        compression: 'gzip',
+      },
+    },
+    providers: {
+      filesystem: createFilesystemReportingRowObjectProviderV1({ roots: { reports: '/var/lib/adcp/rows' } }),
+    },
+    selectRowBinding: ({ canonical_byte_count }) => (canonical_byte_count < 256 * 1024 ? 'inline' : 'reports'),
+  },
+});
+await store.readyRowStorage();
+```
+
+- Each chunk is one object, written create-only. If an object already exists at
+  a planned key, it is adopted only when its bytes decode to the exact chunk;
+  otherwise the commit fails with `CONTENT_CONFLICT`.
+- 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}`.
+- An upload runs only while the obligation lease still covers
+  `writeDeadlineMilliseconds` plus five seconds. A fenced write intent records
+  every object the upload created, and the ledger commit closes the intent in
+  the same transaction. Objects of an upload that never committed are left for
+  the intent sweep.
+- Every read verifies the stored bytes against the recorded physical digest
+  before decompressing, then verifies segments, chunks and the revision binding.
+- Keep a retired binding configured while revisions still reference it.
+- Custom providers implement `ReportingRowObjectProviderV1`. Run
+  `runReportingRowObjectProviderConformanceV1(provider, { location, prefix })`
+  against a dedicated test prefix before using one.
+
+#### Cloud providers
+
+Cloud providers wrap official clients that the host constructs with its own
+credentials. A binding's `location` holds only non-secret coordinates, and its
+optional `credentialRef` names one of the clients you injected; an unknown
+reference fails `UNSAFE_BINDING`. Provider errors surface only as stable
+`ReportingRowStoreError` codes. Row buckets are separate from Managed Delivery
+buckets.
+
+**Google Cloud Storage** (`@adcp/sdk/reporting/gcs`, optional peer
+`@google-cloud/storage`):
+
+```ts
+import { Storage } from '@google-cloud/storage';
+import { createGcsReportingRowObjectProviderV1 } from '@adcp/sdk/reporting/gcs';
+
+const gcs = createGcsReportingRowObjectProviderV1({
+  storage: new Storage(), // keyless credentials (workload identity / ADC)
+  clients: { 'tenant-eu': euStorage }, // optional, selected by credentialRef
+});
+// binding: { kind: 'object', provider: 'gcs', location: { bucket: 'acme-adcp-rows' }, prefix: 'adcp-rows' }
+// providers: { gcs }
+```
+
+- Writes are single-request uploads with `ifGenerationMatch: 0` and a declared
+  MD5, without `Content-Encoding`. The recorded native version is the object
+  generation; reads and deletes pin it, and reads never transcode.
+- The probe requires uniform bucket-level access and enforced public access
+  prevention. Versioning, soft delete and retention policies are allowed. A
+  lifecycle `Delete` rule that can match live objects under the binding prefix
+  (no `matchesPrefix`, or a prefix that overlaps it) is refused; rules limited
+  to noncurrent versions (`isLive: false`, `numNewerVersions`,
+  `daysSinceNoncurrentTime`, `noncurrentTimeBefore`) are allowed. Keep
+  retention-driven deletion in the ledger's pruning, not in bucket lifecycle.
+- The client needs `storage.buckets.get` for the probe plus object create, get
+  and delete on the bucket.
+
+### Retention
+
+Retention is period-aligned and opt-in. A period becomes eligible once both its
+end and its latest publication are older than `max(statusRetentionDays,
+recordRetentionDays)`, no worker holds its lease, and no Managed Delivery
+materialization still references it. Superseded snapshots stay readable for the
+whole window, as the protocol requires.
+
+```ts
+await store.retireExpiredPeriods({ statusRetentionDays: 30, recordRetentionDays: 45, limit: 100 });
+await store.sweepRowWriteIntents({ limit: 100 }); // abandoned object uploads
+```
+
+Retirement runs in three resumable phases. First it records a `retiring`
+tombstone and marks the period's rows as expired. Then it deletes external row
+objects at their recorded versions. Finally it deletes the period's rows and
+ledger records together. The tombstone keeps the final revision ID and digest,
+and planners never re-create a retired period. `ledger_retained_from` advances
+because the retired obligations no longer exist.
+
+`createPostgresReliableReportingProductionService` accepts
+`retention: { enabled: true, recordRetentionDays?, limit? }`. Its scheduler
+always sweeps abandoned row uploads and expired cursor snapshots and
+checkpoints, and retires periods when retention is enabled.
+
+### Host reads: current revisions and the change feed
+
+In-process consumers such as pacing, alerts and warehouse loaders read from the
+ledger, never from a warehouse copy.
+
+```ts
+import { REPORTING_LEDGER_CHANGES_MIGRATION } from '@adcp/sdk/reporting/ledger';
+
+await pool.query(REPORTING_LEDGER_CHANGES_MIGRATION); // PostgreSQL 13+
+const store = new PostgresReportingLedgerStore(pool, { acknowledgeIsolatedDatabase: true, changeFeed: true });
+
+const current = await store.getCurrentRevision({ account_id, reporting_obligation_id });
+const { revisions, cursor: next } = await store.listCurrentRevisions({
+  account_id,
+  period_start_from: '2026-10-01T00:00:00Z',
+  period_start_to: '2026-10-08T00:00:00Z',
+});
+
+let cursor = await loadCursor();
+const page = await store.changesAfter({ account_id, cursor, kinds: ['revision'] });
+// ...apply page.records...
+await store.saveFeedConsumerCursor('pacing', page.cursor); // holds back pruning
+```
+
+- The current revision is the official revision if one exists, otherwise the
+  highest-numbered snapshot. An official revision is terminal, so this is always
+  one index lookup.
+- `changesAfter` lists committed obligation, revision, adjustment and retirement
+  changes. Account feeds order by sequence. The deployment-wide feed (omit
+  `account_id`) orders by `(xid, seq)` and returns only changes whose
+  transaction precedes every transaction still in flight, so a slow commit is
+  never skipped.
+- `pruneChanges` deletes changes older than `changeRetentionDays` (default 30)
+  that every consumer updated within `maxFeedHoldDays` (default 7) has passed.
+  An older cursor throws `ReportingChangeCursorExpiredError`; resynchronize from
+  `listCurrentRevisions`.
+- The production service accepts `changeFeed: true | { changeRetentionDays,
+  maxFeedHoldDays }` and prunes the feed on its scheduler.
+
 ## Managed Delivery and Reconciled Billing
 
 Core remains the default and has no destination, external-resource, or receipt dependency. To opt into the higher tiers, apply `REPORTING_MANAGED_DELIVERY_MIGRATION` **after** `REPORTING_LEDGER_MIGRATION`, explicitly construct the Core store with `managedDelivery: true`, create a `PostgresReportingManagedDeliveryStore`, and pass both stores with a destination adapter to `createReportingManagedDeliveryRuntime`. The async factory proves the stores share one authority and validates the RC3 tier wiring before returning it. It advertises `managed_delivery` only when an immutable binding, delivery, bounded resource reading, generation-fenced revocation, and at least one verification profile are installed. The advertised automated recovery window must be at least the widest installed managed Core configuration recovery window. It advertises `reconciled_billing` and `receipt_task` only when an authenticated consumer resolver and canonical-digest verification are also installed.

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-08
-> Library: @adcp/sdk v15.4.0
+> Generated at: 2026-10-09
+> Library: @adcp/sdk v15.5.0
 > 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.
@@ -136,6 +136,8 @@ A submitted mutation must settle before it can be controlled; retain the task ha
 
 **Existing applications.** The [thin existing-platform recipe](./guides/EXISTING-PLATFORM.md) shows one SDK task inside application-owned auth and transactions, durable submitted-task recording, the error/cancellation matrix, non-blocking bounded diagnostics, and same-instance capability evidence reuse with `AgentClient.createWithCapabilityPreflight()` (or the lower-level `getCapabilityEvidenceScope()` + `primeCapabilities()` pair). The SDK 14 release represented by the checkout, its registry integrity check, peer/runtime ranges, wire pin, and a historical rc.33/rc.35 → rc.36 example are generated in [the release worksheet](./migration-14.x-rc-worksheet.md).
 
+**Request-local clients.** Share endpoint and capability discovery with an application-owned `discoveryCache` and explicit authorization identity. The public `withMCPConnectionScope()` groups a workflow's MCP calls onto reusable sessions; correlation headers, cancellation and deadlines remain per call. See [Discovery cache and session reuse](./guides/DISCOVERY-CACHE-AND-SESSION-REUSE.md).
+
 ## Canonical Reference Resolver
 
 `format_schema` and `platform_extensions` references use immutable `{ uri, digest }` pointers. Use `createCanonicalReferenceResolver` from `@adcp/sdk/canonical-references` instead of raw fetches; it applies SSRF-safe DNS-pinned fetches, redirect blocking, timeout/body caps, SHA-256 verification, structured non-throwing statuses, and bounded policy-scoped LRU caching. The zero-argument cache holds at most 64 entries / 32 MiB estimated retained data; use `createCanonicalReferenceCache({ maxEntries, maxBytes })` to tune the per-resolver budget or inject a fully caller-owned cache.

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.4.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.4.0 dist.integrity` |
+| Exact npm package | `@adcp/sdk@15.5.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.5.0 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` |
@@ -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.4.0'
-npm view '@adcp/sdk@15.4.0' dist.integrity
+npm install --save-exact '@adcp/sdk@15.5.0'
+npm view '@adcp/sdk@15.5.0' dist.integrity
 ```
 
 ### Required and optional peers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "15.4.0",
+  "version": "15.5.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",