@adcp/sdk 14.0.0-beta.12 → 14.0.0-beta.13

package/docs/migration-5.x-to-6.x.md

@@ -269,11 +269,12 @@ In-memory task registry refuses to construct outside `NODE_ENV=test/development`
 ```ts
 import { createPostgresTaskRegistry, getDecisioningTaskRegistryMigration } from '@adcp/sdk/server';
 
-await pool.query(getDecisioningTaskRegistryMigration());
+const taskRegistryNamespace = 'tenant:my-agent';
+await pool.query(getDecisioningTaskRegistryMigration({ namespace: taskRegistryNamespace }));
 
 createAdcpServerFromPlatform(platform, {
   name: '...', version: '...',
-  taskRegistry: createPostgresTaskRegistry({ pool }),
+  taskRegistry: createPostgresTaskRegistry({ pool, namespace: taskRegistryNamespace }),
 });
 ```
 

package/docs/migration-task-registry-scoping.md

@@ -0,0 +1,61 @@
+# Task registry scope migration
+
+Task registry reads, writes, and background waits now require the account and
+authenticated owner scope that created the task. This prevents a known task ID
+from crossing account or principal boundaries.
+
+```ts
+const scope = { accountId: account.id, ownerScope: `api_key:${keyId}` };
+
+await registry.getTask(taskId, scope);
+await registry.updateProgress(taskId, scope, progress);
+await registry.complete(taskId, scope, result);
+await registry.fail(taskId, scope, error, failureArtifact);
+await registry.awaitTask(taskId, scope);
+```
+
+Custom `TaskRegistry` implementations must apply every scope component in the
+storage query. Do not derive `ownerScope` from request parameters; use the
+authenticated server context. Set `scopeVersion: 1` only after migrating those
+method signatures; the platform factory rejects unmarked legacy registries so
+an old `(taskId, result)` write cannot mistake the new scope argument for a
+result.
+
+`DecisioningAdcpServer.getTaskState()` and `.awaitTask()` accept the same scope.
+Administrative and test code that intentionally has no buyer context can use
+the explicitly named `getTaskStateUnsafe()` and `awaitTaskUnsafe()` helpers.
+Unsafe reads return `null` when the same public task ID exists in more than one
+scope.
+
+PostgreSQL registries additionally require a trusted deployment or tenant
+namespace:
+
+```ts
+const taskRegistryNamespace = 'tenant:my-agent';
+createPostgresTaskRegistry({
+  pool,
+  namespace: taskRegistryNamespace,
+});
+```
+
+Run the migration with that same namespace before deploying the new registry:
+
+```ts
+await pool.query(
+  getDecisioningTaskRegistryMigration({ namespace: taskRegistryNamespace })
+);
+```
+
+It backfills legacy rows to the supplied registry namespace and account fallback
+owner scope, then migrates the primary key to
+`(registry_namespace, account_id, owner_scope, task_id)`. The namespace must be
+stable across deploys and unique for every hosted tenant. A single in-memory
+registry instance must likewise not be shared across tenants unless the host
+includes tenant identity in both `accountId` and `ownerScope`.
+
+The legacy table did not store a tenant identifier. If multiple hosted tenants
+previously shared one legacy table, the SDK cannot infer which tenant owns each
+row: the first migration would otherwise assign every legacy row to its supplied
+namespace. Before migrating, drain in-flight tasks or explicitly map legacy rows
+to tenant namespaces in an operator-managed migration. Do not run separate
+tenant migrations over an ambiguous shared legacy table.

package/examples/hello_seller_adapter_guaranteed.ts

@@ -1355,7 +1355,7 @@ const mediaBuyStore = createMediaBuyStore({ store: stateStore });
 // instance persists across requests — a fresh registry per request would
 // lose every submitted task between create_media_buy and the buyer's
 // first tasks_get poll. SWAP `createInMemoryTaskRegistry()` for
-// `createPostgresTaskRegistry({ pool })` in production; in-memory
+// `createPostgresTaskRegistry({ pool, namespace: tenantId })` in production; in-memory
 // in-flight tasks are lost on process restart.
 const taskRegistry = createInMemoryTaskRegistry();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "14.0.0-beta.12",
+  "version": "14.0.0-beta.13",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -485,9 +485,9 @@
     "pretest": "npm run schemas:ensure",
     "test": "npm run test:node && npm test --workspace=packages/eslint-plugin --if-present && npm test --workspace=@adcp/reference-renderers",
     "test:node": "npm run test:node:fast && npm run test:node:slow",
-    "test:node:fast": "NODE_ENV=test node --test-timeout=60000 --test-force-exit --test $(find test -maxdepth 1 -name '*.test.js' ! -name 'canonical-creatives-a2a-e2e.test.js' ! -name 'generate-zod-object-intersections.test.js' -print) $(find test/lib -maxdepth 1 -name '*.test.js' ! -name 'cli-auth-scheme.test.js' ! -name 'cli-soft-fail.test.js' ! -name 'cli-webhook-receiver-flag.test.js' ! -name 'conformance-cli.test.js' ! -name 'conformance-seeder.test.js' ! -name 'media-buy-lifecycle-release-gate.test.js' ! -name 'storyboard-notices.test.js' ! -name 'storyboard-requires-gate.test.js' -print)",
-    "test:node:fast:shard": "test -n \"$TEST_SHARD\" && NODE_ENV=test node --test-timeout=60000 --test-force-exit --test-shard=$TEST_SHARD --test $(find test -maxdepth 1 -name '*.test.js' ! -name 'canonical-creatives-a2a-e2e.test.js' ! -name 'generate-zod-object-intersections.test.js' -print) $(find test/lib -maxdepth 1 -name '*.test.js' ! -name 'cli-auth-scheme.test.js' ! -name 'cli-soft-fail.test.js' ! -name 'cli-webhook-receiver-flag.test.js' ! -name 'conformance-cli.test.js' ! -name 'conformance-seeder.test.js' ! -name 'media-buy-lifecycle-release-gate.test.js' ! -name 'storyboard-notices.test.js' ! -name 'storyboard-requires-gate.test.js' -print)",
-    "test:node:slow": "NODE_ENV=test node --test-timeout=180000 --test-force-exit --test test/canonical-creatives-a2a-e2e.test.js test/generate-zod-object-intersections.test.js test/lib/cli-auth-scheme.test.js test/lib/cli-soft-fail.test.js test/lib/cli-webhook-receiver-flag.test.js test/lib/conformance-cli.test.js test/lib/conformance-seeder.test.js test/lib/media-buy-lifecycle-release-gate.test.js test/lib/storyboard-notices.test.js test/lib/storyboard-requires-gate.test.js",
+    "test:node:fast": "NODE_ENV=test node --test-timeout=60000 --test-force-exit --test $(find test -maxdepth 1 -name '*.test.js' ! -name 'canonical-creatives-a2a-e2e.test.js' ! -name 'generate-zod-object-intersections.test.js' ! -name 'server-decisioning-from-platform.test.js' -print) $(find test/lib -maxdepth 1 -name '*.test.js' ! -name 'cli-auth-scheme.test.js' ! -name 'cli-soft-fail.test.js' ! -name 'cli-webhook-receiver-flag.test.js' ! -name 'conformance-cli.test.js' ! -name 'conformance-seeder.test.js' ! -name 'media-buy-lifecycle-release-gate.test.js' ! -name 'storyboard-notices.test.js' ! -name 'storyboard-requires-gate.test.js' -print)",
+    "test:node:fast:shard": "test -n \"$TEST_SHARD\" && NODE_ENV=test node --test-timeout=60000 --test-force-exit --test-shard=$TEST_SHARD --test $(find test -maxdepth 1 -name '*.test.js' ! -name 'canonical-creatives-a2a-e2e.test.js' ! -name 'generate-zod-object-intersections.test.js' ! -name 'server-decisioning-from-platform.test.js' -print) $(find test/lib -maxdepth 1 -name '*.test.js' ! -name 'cli-auth-scheme.test.js' ! -name 'cli-soft-fail.test.js' ! -name 'cli-webhook-receiver-flag.test.js' ! -name 'conformance-cli.test.js' ! -name 'conformance-seeder.test.js' ! -name 'media-buy-lifecycle-release-gate.test.js' ! -name 'storyboard-notices.test.js' ! -name 'storyboard-requires-gate.test.js' -print)",
+    "test:node:slow": "NODE_ENV=test node --test-timeout=180000 --test-force-exit --test test/canonical-creatives-a2a-e2e.test.js test/generate-zod-object-intersections.test.js test/server-decisioning-from-platform.test.js test/lib/cli-auth-scheme.test.js test/lib/cli-soft-fail.test.js test/lib/cli-webhook-receiver-flag.test.js test/lib/conformance-cli.test.js test/lib/conformance-seeder.test.js test/lib/media-buy-lifecycle-release-gate.test.js test/lib/storyboard-notices.test.js test/lib/storyboard-requires-gate.test.js",
     "pretest:lib": "npm run schemas:ensure",
     "test:lib": "npm run test:lib:fast && npm run test:lib:slow",
     "test:lib:fast": "NODE_ENV=test node --test-timeout=60000 --test-force-exit --test $(find test/lib -maxdepth 1 -name '*.test.js' ! -name 'cli-auth-scheme.test.js' ! -name 'cli-soft-fail.test.js' ! -name 'cli-webhook-receiver-flag.test.js' ! -name 'conformance-cli.test.js' ! -name 'conformance-seeder.test.js' ! -name 'media-buy-lifecycle-release-gate.test.js' ! -name 'storyboard-notices.test.js' ! -name 'storyboard-requires-gate.test.js' -print)",

package/skills/build-decisioning-creative-template/SKILL.md

@@ -405,7 +405,7 @@ serve(() => server, {
 
 - Calls `validatePlatform()` — throws if you advertise a specialism but don't implement it, or define both halves of a method-pair
 - Wraps each method with `AdcpError`-catch + `submitted`-envelope projection for HITL
-- Returns a `DecisioningAdcpServer` (extends `AdcpServer`) with `getTaskState(taskId)` + `awaitTask(taskId)` for HITL inspection
+- Returns a `DecisioningAdcpServer` (extends `AdcpServer`) with scoped `getTaskState(taskId, scope)` + `awaitTask(taskId, scope)` for HITL inspection. Trusted admin/tests may use the explicitly unsafe `getTaskStateUnsafe(taskId)` + `awaitTaskUnsafe(taskId)` helpers.
 
 `serve()` accepts the server and binds HTTP transport for both MCP and A2A.
 
@@ -483,7 +483,7 @@ console.log(result.structuredContent);
 
 `dispatchTestRequest` is the canonical loop for unit-testing platform behavior without HTTP. It's available on `DecisioningAdcpServer` (the type returned by `createAdcpServerFromPlatform`). Set `validation: { requests: 'off' }` while iterating; turn it back to `strict` for end-to-end tests.
 
-For HITL platforms, `server.awaitTask(taskId)` settles the background promise; `server.getTaskState(taskId)` reads terminal status.
+For HITL platforms, `server.awaitTask(taskId, scope)` settles the background promise; `server.getTaskState(taskId, scope)` reads terminal status. Use the `*Unsafe(taskId)` variants only in trusted admin or test code.
 
 ## What NOT to do
 

package/skills/build-decisioning-platform/SKILL.md

@@ -289,13 +289,15 @@ import { Pool } from 'pg';
 import { createAdcpServerFromPlatform, getAllAdcpMigrations, serve } from '@adcp/sdk/server';
 
 const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-await pool.query(getAllAdcpMigrations()); // one DDL call, all 3 tables
+const taskRegistryNamespace = 'tenant:my-agent';
+await pool.query(getAllAdcpMigrations({ taskRegistryNamespace })); // one DDL call, all 3 tables
 
 const platform = new MyPlatform(myAdServer);
 const server = createAdcpServerFromPlatform(platform, {
   name: 'My Sales Agent',
   version: '1.0.0',
   pool, // wires idempotency + ctxMetadata + taskRegistry
+  taskRegistryNamespace,
 });
 
 serve(() => server, { port: process.env.PORT });
@@ -310,7 +312,7 @@ For dev / single-process: omit `pool` entirely. Framework defaults to in-memory
 Things you set up once at deploy time:
 
 - [ ] `DATABASE_URL` env var pointing at your Postgres instance
-- [ ] Run `getAllAdcpMigrations()` once per database (idempotent — safe to re-run)
+- [ ] Run `getAllAdcpMigrations({ taskRegistryNamespace })` once per database with a stable, trusted namespace (idempotent — safe to re-run)
 - [ ] OAuth provider config — see `advanced/OAUTH.md` if buyers authenticate via OIDC
 - [ ] `ADCP_VERSION` env (default `3.0.0`) if pinning a specific spec version
 

package/skills/build-decisioning-platform/advanced/REFERENCE.md

@@ -267,7 +267,7 @@ sales: SalesPlatform<MyMeta> = {
 **The buyer gets terminal state two ways:**
 
 1. **Webhook push** — buyer included `push_notification_config: { url, token }` in the original request. Framework signs (RFC 9421) + delivers to that URL with the spec's `mcp-webhook-payload.json` envelope on terminal state. URL is validated server-side: rejects RFC 1918, loopback, link-local, CGNAT, IPv6 unique-local, alternate IPv4 forms, and IPv4-mapped IPv6 before delivery (SSRF guard). Bad URLs FAIL FAST with `INVALID_REQUEST` at the request boundary — buyers see their config error immediately, not as silent webhook drops.
-2. **Polling** — framework auto-registers a `tasks_get` custom tool. Buyers call it with `{ task_id, account }` and receive the spec-flat lifecycle shape (`task_id`, `task_type`, `status`, `created_at`, `updated_at`, `completed_at` on terminal, `result` on completed, top-level `error: { code, message, details? }` on failed). Tenant-scoped — passes `account` through `accounts.resolve(ref, ctx)` and refuses cross-tenant probes with `REFERENCE_NOT_FOUND`. You don't write this tool; it's wired in by the framework. Programmatic access for ops / cron code is via `server.getTaskState(taskId, accountId)`.
+2. **Polling** — framework auto-registers a `tasks_get` custom tool. Buyers call it with `{ task_id, account }` and receive the spec-flat lifecycle shape (`task_id`, `task_type`, `status`, `created_at`, `updated_at`, `completed_at` on terminal, `result` on completed, top-level `error: { code, message, details? }` on failed). Tenant-scoped — passes `account` through `accounts.resolve(ref, ctx)` and refuses cross-tenant probes with `REFERENCE_NOT_FOUND`. You don't write this tool; it's wired in by the framework. Scoped application code uses `server.getTaskState(taskId, { accountId, ownerScope })`; explicitly trusted ops and test code can use `server.getTaskStateUnsafe(taskId)`.
 
 **Sync-only tools that need long-running completion** use `publishStatusChange(...)` for lifecycle updates instead of HITL. The per-tool wire response schemas don't include `Submitted` arms for `update_media_buy`, `build_creative`, `sync_catalogs`, or `get_products` (a spec inconsistency tracked as [adcp#3392](https://github.com/adcontextprotocol/adcp/issues/3392) — the Submitted schemas exist but aren't rolled into each tool's response `oneOf`). Until the spec consolidates, long-running work on those tools publishes status changes (`media_buy` → `active` → `completed`) on the event bus and buyers subscribe. When adcp#3392 lands, the SDK will widen the unified shape to `update_media_buy`, `build_creative`, and `sync_catalogs` — but NOT to `get_products` (see "Proposal generation" below).
 
@@ -528,7 +528,7 @@ Same pattern for stdio + http transports — `authenticate` runs at the transpor
 
 The framework's default in-memory `TaskRegistry` is gated by `NODE_ENV` — refuses to construct outside `{test, development}` unless `ADCP_DECISIONING_ALLOW_INMEMORY_TASKS=1` is explicitly set. Every HITL-eligible production deployment needs a durable task registry so task state survives process restarts and load-balancer failover.
 
-Ship `createPostgresTaskRegistry({ pool, tableName? })`:
+Ship `createPostgresTaskRegistry({ pool, namespace, tableName? })`:
 
 ```ts
 import { Pool } from 'pg';
@@ -540,19 +540,20 @@ import {
 
 const pool = new Pool({ connectionString: process.env.DATABASE_URL });
 
-// Once at boot — idempotent CREATE TABLE IF NOT EXISTS, safe to re-run
-await pool.query(getDecisioningTaskRegistryMigration());
+const taskRegistryNamespace = 'tenant:my-agent';
+// Once at boot — idempotent and safe to re-run with the same namespace
+await pool.query(getDecisioningTaskRegistryMigration({ namespace: taskRegistryNamespace }));
 
 const server = createAdcpServerFromPlatform(platform, {
   name: 'My Ad Network',
   version: '1.0.0',
-  taskRegistry: createPostgresTaskRegistry({ pool }),
+  taskRegistry: createPostgresTaskRegistry({ pool, namespace: taskRegistryNamespace }),
 });
 ```
 
 Cross-instance reads work — process A allocates the task, process B reads the lifecycle for `tasks_get`. Terminal-state idempotency is enforced via SQL `WHERE status = 'submitted'` so concurrent webhook deliveries can't race to overwrite each other. Background-completion tracking (`_registerBackground`) is process-local — promises don't serialize, so production HITL flows that span process boundaries drive completion via webhook → an explicit `complete()` / `fail()` from the receiving process.
 
-Custom backend? Implement the `TaskRegistry` interface (8 methods) for Redis / DynamoDB / Spanner / etc. — the framework awaits each call so all 4 mutators (`create`, `complete`, `fail`, `getTask`) can be storage-backed.
+Custom backend? Implement the scoped `TaskRegistry` interface for Redis / DynamoDB / Spanner / etc. The framework awaits every storage method; apply both `accountId` and `ownerScope` on every read and write, then set `scopeVersion: 1`. Keep the explicitly named unsafe methods limited to trusted administrative and test paths.
 
 **Adopter `*Task` return size cap.** Postgres-backed registries cap `result` / `error` JSONB rows at 4MB. Returns over the cap surface via `onTaskTransition` with `errorCode: 'REGISTRY_WRITE_FAILED'` and skip webhook delivery (registry state is inconsistent, so the framework refuses to push). Offload large payloads to blob storage and return references in the result body instead. The cap protects the DB write path only — adopter code that serializes `result` for logs/metrics MUST impose its own bound.