@adcp/sdk 5.25.0 → 6.0.0

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

@@ -0,0 +1,304 @@
+---
+name: build-decisioning-platform
+description: Build an AdCP sales agent (publisher / SSP / retail-media network). Implement 5 functions, throw 8 typed errors, run it. Framework handles idempotency, HITL, signing, multi-tenant, schema validation.
+---
+
+# Build a sales agent
+
+Implement 6 functions. The framework does the rest.
+
+## What you're building
+
+A `DecisioningPlatform` for the `sales-non-guaranteed` (or `sales-guaranteed`) specialism. Buyers call your AdCP server to discover products, create media buys, push creatives, update buys, and pull delivery reports. You translate those calls to your platform (GAM, FreeWheel, Kevel, your own ad server, whatever).
+
+## Imports cheat sheet
+
+For 95% of sales agents, these are the only `@adcp/sdk/server` imports you need:
+
+```ts
+import {
+  // Server entry + persistence
+  createAdcpServerFromPlatform, getAllAdcpMigrations, serve,
+  // Wire-shape helpers (eliminate 30+ lines of boilerplate per Product)
+  buildProduct, buildPackage, buildPricingOption,
+  // Typed errors — pick from this catalog instead of `throw new AdcpError(...)`
+  PackageNotFoundError, MediaBuyNotFoundError, ProductNotFoundError,
+  BudgetTooLowError, BackwardsTimeRangeError, InvalidStateError,
+  RateLimitedError, UnsupportedFeatureError,
+  // Types
+  type DecisioningPlatform, type SalesPlatform,
+} from '@adcp/sdk/server';
+```
+
+For other agent shapes:
+- **Creative agent (template / generative):** swap `SalesPlatform` for `CreativeBuilderPlatform`
+- **Signals agent:** swap for `SignalsPlatform`
+- **Brand-rights agent:** swap for `BrandRightsPlatform`
+- **Multi-tenant host:** add `createTenantRegistry`
+
+The full export list is in `@adcp/sdk/server`. Many surfaces are marked `@deprecated` (legacy v5 response builders, old MCP task helpers) — your IDE will strikethrough them. Trust the strikethrough.
+
+## When you need...
+
+- HITL flows (operator approval, async creative review) → `advanced/HITL.md`
+- Multi-tenant hosting → `advanced/MULTI-TENANT.md`
+- OAuth / OIDC authentication → `advanced/OAUTH.md`
+- Sandbox / test-mode routing → `advanced/SANDBOX.md`
+- Compliance test scenarios (`comply_test_controller`) → `advanced/COMPLIANCE.md`
+- Campaign governance specialism → `advanced/GOVERNANCE.md`
+- Brand rights specialism → `advanced/BRAND-RIGHTS.md`
+- Replay TTL / idempotency principal tuning → `advanced/IDEMPOTENCY.md`
+- State machine transitions (`pending_creatives` → `active`) → `advanced/STATE-MACHINE.md`
+- Postgres operations / sizing / indices / cleanup → `../../docs/guides/POSTGRES.md`
+- Edge cases / full reference → `advanced/REFERENCE.md`
+
+## The 6 functions
+
+```ts
+import {
+  createAdcpServerFromPlatform,
+  createCtxMetadataStore, memoryCtxMetadataStore,
+  PackageNotFoundError, MediaBuyNotFoundError, ProductNotFoundError,
+  BudgetTooLowError, BackwardsTimeRangeError, InvalidStateError,
+  type DecisioningPlatform, type SalesPlatform,
+} from '@adcp/sdk/server';
+
+class MyPlatform implements DecisioningPlatform {
+  capabilities = {
+    adcp_version: '3.0.0',
+    specialisms: ['sales-non-guaranteed'] as const,
+    pricingModels: ['cpm'] as const,
+    channels: ['display', 'video'] as const,                  // strict literal-union — TS catches typos
+    formats: [{ format_id: 'display_300x250' }],
+    idempotency: { replay_ttl_seconds: 86400 },
+  };
+
+  accounts = {
+    resolution: 'derived' as const,                            // single tenant; framework returns the same Account every call
+    resolve: async () => ({ id: 'pub_main', operator: 'mypub', ctx_metadata: {} }),
+    upsert: async () => ({ ok: true, items: [] }),
+    list: async () => ({ items: [], nextCursor: null }),
+  };
+
+  sales: SalesPlatform = {
+    // 1. Catalog lookup. Brief in, products out.
+    getProducts: async (req, ctx) => {
+      const products = await this.platform.searchInventory(req.brief, req.promoted_offering);
+      return {
+        products: products.map(p => ({
+          product_id: p.id,
+          name: p.name,
+          format_ids: p.formatIds.map(id => ({ id })),
+          delivery_type: 'non_guaranteed',
+          pricing_options: [{ pricing_option_id: `${p.id}-cpm`, model: 'cpm', floor: { amount: p.floor, currency: 'USD' } }],
+          ctx_metadata: { gam: { ad_unit_ids: p.adUnitIds } },  // stashed; framework round-trips
+        })),
+      };
+    },
+
+    // 2. Create a buy. Sync path; HITL is `ctx.handoffToTask` (see advanced/HITL.md).
+    //    SDK auto-hydrates each pkg.product with the resolved Product (incl. ctx_metadata)
+    //    from the prior getProducts call — no separate lookup needed.
+    //
+    //    CONTRACT — `pkg.product` is `undefined` when SDK has no record of that product_id.
+    //    That's NOT authoritative "doesn't exist" — the SDK store is a cache, and your
+    //    publisher's DB might still have it. Decision tree when undefined:
+    //      - Have your own product DB → look up there; throw `ProductNotFoundError(pkg.product_id)`
+    //        only if YOUR DB also returns nothing.
+    //      - Pure-SDK store (no own DB) → throw `ProductNotFoundError(pkg.product_id)` immediately.
+    //      - Either way: never let `undefined` flow downstream silently.
+    createMediaBuy: async (req, ctx) => {
+      if (new Date(req.start_time) >= new Date(req.end_time)) throw new BackwardsTimeRangeError();
+      if (req.total_budget?.amount < 1000) throw new BudgetTooLowError({ floor: 1000, currency: 'USD' });
+
+      const lineItems = [];
+      for (const pkg of req.packages) {
+        if (!pkg.product) throw new ProductNotFoundError(pkg.product_id);
+        // pkg.product is the full Product from getProducts, with adapter-internal config attached:
+        const adUnits = pkg.product.ctx_metadata?.gam?.ad_unit_ids ?? [];
+        const formats = pkg.product.format_ids;
+        lineItems.push(await this.platform.createLineItem(pkg, { adUnits, formats }));
+      }
+      const order = await this.platform.createOrder(req, lineItems);
+
+      // Stash your platform's IDs so subsequent updateMediaBuy can hydrate them too.
+      return {
+        media_buy_id: order.id,
+        status: 'pending_creatives',                           // creative state machine — see advanced/STATE-MACHINE.md
+        ctx_metadata: { gam_order_id: order.gamOrderId },     // SDK persists; subsequent updateMediaBuy gets req.ctx_metadata.gam_order_id
+        packages: order.lineItems.map(li => ({
+          package_id: li.id,
+          status: 'pending_creatives',
+          buyer_ref: li.buyerRef,
+          ctx_metadata: { gam_line_item_id: li.gamLineItemId },
+        })),
+      };
+    },
+
+    // 3. Update a buy. SDK auto-hydrates the resolved MediaBuy (and its packages,
+    //    each with ctx_metadata) at req.mediaBuy when present in the store from a
+    //    prior createMediaBuy / getMediaBuys call. Falls back gracefully if absent
+    //    (publisher uses their own DB).
+    //    (6.2 will pre-read state + decompose into atomic verbs; track adcp-client#1071.)
+    updateMediaBuy: async (mediaBuyId, patch, ctx) => {
+      const orderMeta = await ctx.ctxMetadata?.mediaBuy(mediaBuyId);
+      if (!orderMeta) throw new MediaBuyNotFoundError(mediaBuyId);
+
+      for (const pkg of patch.packages ?? []) {
+        const pkgMeta = await ctx.ctxMetadata?.package(pkg.package_id);
+        if (!pkgMeta) throw new PackageNotFoundError(pkg.package_id);
+        await this.platform.updateLineItem(pkgMeta.gam_line_item_id, pkg);
+      }
+      const order = await this.platform.getOrder(orderMeta.gam_order_id);
+      return this.toMediaBuy(order);
+    },
+
+    // 4. Push creatives. Returns one row per creative with action + status.
+    syncCreatives: async (creatives, ctx) => {
+      const out = [];
+      for (const c of creatives) {
+        const native = await this.platform.upsertCreative(c);
+        await ctx.ctxMetadata?.set('creative', c.creative_id, { gam_creative_id: native.id });
+        out.push({ creative_id: c.creative_id, action: 'created', status: 'approved' });
+      }
+      return out;
+    },
+
+    // 5. List buys this account owns. REQUIRED — non-negotiable. Every seller
+    //    needs to support reading back what they created. SDK auto-stores
+    //    returned buys for hydration on subsequent updateMediaBuy calls.
+    //
+    //    WRITE-ONLY ADOPTERS (proposal-mode push-channel sellers, retail-media
+    //    flows that deliver via webhook): return `{ media_buys: [] }`. Never
+    //    lie — empty array is truthful "no buys to enumerate via this surface."
+    //    Buyers asking for a list get an empty answer. Don't omit the method
+    //    or stub-throw; just return empty.
+    getMediaBuys: async (req, ctx) => {
+      const buys = await this.platform.listOrders({ accountId: ctx.account.id, status: req.status });
+      return {
+        media_buys: buys.map(buy => ({
+          media_buy_id: buy.id,
+          status: this.statusMappers.mediaBuy(buy.nativeStatus),
+          buyer_ref: buy.buyerRef,
+          total_budget: { amount: buy.budgetAmount, currency: buy.currency },  // REQUIRED on the wire shape
+          start_time: buy.startTime,
+          end_time: buy.endTime,
+          packages: buy.lineItems.map(li => ({
+            package_id: li.id,
+            status: this.statusMappers.mediaBuy(li.nativeStatus),
+            buyer_ref: li.buyerRef,
+            ctx_metadata: { gam_line_item_id: li.gamLineItemId },               // round-trip publisher state
+          })),
+          ctx_metadata: { gam_order_id: buy.gamOrderId },
+        })),
+      };
+    },
+
+    // 6. Delivery report.
+    getMediaBuyDelivery: async (filter, ctx) => ({ deliveries: await this.platform.fetchReports(filter) }),
+  };
+
+  constructor(private platform: MyAdServer) {}
+}
+```
+
+That's the agent. Five functions. The framework wires the wire protocol around it (MCP tools, A2A skill manifest, idempotency, schema validation, HITL task envelopes, RFC 9421 webhook signing, multi-tenant routing).
+
+## Errors you throw — pick from the import list
+
+```ts
+import {
+  PackageNotFoundError,        // wrong package_id on update
+  MediaBuyNotFoundError,       // wrong media_buy_id
+  ProductNotFoundError,        // wrong product_id on create
+  ProductUnavailableError,     // product exists but sold out
+  CreativeNotFoundError,       // wrong creative_id
+  CreativeRejectedError,       // brand-safety failed, etc.
+  BudgetTooLowError,           // under floor (correctable — buyer raises)
+  BudgetExhaustedError,        // pacing burst hit cap
+  IdempotencyConflictError,    // same key, different payload
+  InvalidRequestError,         // generic field-level bad input
+  InvalidStateError,           // illegal transition (paused → archived violations)
+  BackwardsTimeRangeError,     // start_time >= end_time
+  AuthRequiredError,           // need auth, then retry
+  PermissionDeniedError,       // auth present, lacks scope
+  RateLimitedError,            // throttled (clamps retry_after to [1, 3600])
+  UnsupportedFeatureError,     // tool unimplemented
+  ComplianceUnsatisfiedError,  // brand-safety attestation missing
+  GovernanceDeniedError,       // spending authority revoked
+  PolicyViolationError,        // categorical content rejection
+} from '@adcp/sdk/server';
+```
+
+Each class encodes the right `code` / `recovery` / `field` shape. **Don't throw generic `Error`** — the framework catches that and maps to `SERVICE_UNAVAILABLE`, which the buyer can't pattern-match.
+
+## Persisting platform state — `ctx.ctxMetadata`
+
+Your platform has IDs (GAM order_id, line_item_id) that AdCP doesn't model. Stash them once, read them on subsequent calls. The framework round-trips per `(account.id, kind, id)` and strips from buyer-facing wire payloads.
+
+```ts
+// Wire a store at server construction:
+import { createCtxMetadataStore, memoryCtxMetadataStore, pgCtxMetadataStore, getCtxMetadataMigration } from '@adcp/sdk/server';
+
+await pool.query(getCtxMetadataMigration());                                  // Postgres only
+const ctxMetadata = createCtxMetadataStore({ backend: pgCtxMetadataStore(pool) });
+
+// Stash in any handler return:
+await ctx.ctxMetadata?.set('product', productId, { gam: { ad_unit_ids: [...] } });
+
+// Read in a later handler:
+const meta = await ctx.ctxMetadata?.product(productId);
+```
+
+**Memory backend:** fine for dev; use Postgres in cluster — silent loss after rolling restart produces "package not found" errors that look like publisher bugs and run for weeks.
+
+**Account scoping is automatic.** `ctx.ctxMetadata` binds to `ctx.account.id` per request. No-account tools (`provide_performance_feedback`, `list_creative_formats`) get `ctx.ctxMetadata = undefined` — branch defensively.
+
+## Run it
+
+```ts
+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 platform = new MyPlatform(myAdServer);
+const server = createAdcpServerFromPlatform(platform, {
+  name: 'My Sales Agent',
+  version: '1.0.0',
+  pool,                                                                    // wires idempotency + ctxMetadata + taskRegistry
+});
+
+serve(() => server, { port: process.env.PORT });
+```
+
+That's the whole bootstrap. **One pool, one migration, three persistence concerns wired by the framework.**
+
+For dev / single-process: omit `pool` entirely. Framework defaults to in-memory backends. Don't ship that to production — silent state loss after rolling restart produces "package not found" errors that look like publisher bugs and run for weeks.
+
+## Operator checklist
+
+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)
+- [ ] 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
+
+## See also
+
+- `advanced/HITL.md` — long-running tools (creative review, manual approval). Use `ctx.handoffToTask(fn)`.
+- `advanced/MULTI-TENANT.md` — `TenantRegistry` for one-process-many-publishers.
+- `advanced/OAUTH.md` — auth providers (OIDC client_credentials, etc.).
+- `advanced/SANDBOX.md` — test-mode routing via `AccountReference.sandbox`.
+- `advanced/COMPLIANCE.md` — `comply_test_controller` for storyboard-driven QA.
+- `advanced/GOVERNANCE.md` — `campaign-governance` specialism.
+- `advanced/BRAND-RIGHTS.md` — `brand-rights` specialism.
+- `advanced/IDEMPOTENCY.md` — replay TTL / principal resolver tuning.
+- `advanced/STATE-MACHINE.md` — `pending_creatives` → `pending_start` → `active` transitions.
+- `advanced/REFERENCE.md` — full reference (everything above + edge cases + design rationale).

package/skills/build-decisioning-platform/advanced/BRAND-RIGHTS.md

@@ -0,0 +1,25 @@
+# Brand rights specialism
+
+If you claim `brand-rights`, implement `BrandRightsPlatform`. Buyers call to discover brand identity, query rights, and acquire rights for creative production.
+
+```ts
+class MyPlatform implements DecisioningPlatform {
+  capabilities = {
+    specialisms: ['brand-rights'] as const,
+    brand: { /* BrandCapabilities — see REFERENCE.md for shape */ },
+    ...
+  };
+
+  brandRights: BrandRightsPlatform = {
+    getBrandIdentity: async (req, ctx) => { ... },
+    getRights: async (req, ctx) => { ... },
+    acquireRights: async (req, ctx) => {
+      // Returns one of three native arms — Acquired / PendingApproval / Rejected
+    },
+  };
+}
+```
+
+Async delivery for the `PendingApproval` arm rides the buyer's `push_notification_config.url`. There's no polling tool for `acquire_rights` — webhook is the only delivery channel.
+
+See `REFERENCE.md` for the full brand-rights section + the 3-arm wire shape.

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

@@ -0,0 +1,23 @@
+# Compliance testing — `comply_test_controller`
+
+Adopters who claim `compliance_testing` capability get a wire tool the AdCP storyboard runner uses to drive deterministic test scenarios (seed products, force creative statuses, simulate delivery, etc.).
+
+```ts
+import { createComplyController } from '@adcp/sdk/testing';
+
+createAdcpServerFromPlatform(platform, {
+  name: '...', version: '...',
+  complyTest: {
+    sandboxGate: (input) => input.account?.sandbox === true,            // ONLY in sandbox accounts
+    seed: { product: async (input) => seedProductFixture(input) },
+    force: { creative_status: async (input) => forceStatus(input) },
+    simulate: { delivery: async (input) => simulateDelivery(input) },
+  },
+});
+```
+
+Framework auto-projects `capabilities.compliance_testing.scenarios` to `get_adcp_capabilities` based on which adapters you wired.
+
+Production agents typically gate registration on `process.env.ADCP_SANDBOX === '1'` so the tool isn't reachable in prod tools/list.
+
+See `REFERENCE.md` for the full compliance-testing section.

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

@@ -0,0 +1,24 @@
+# Campaign governance specialism
+
+If you claim `governance-spend-authority` or `governance-delivery-monitor`, implement `CampaignGovernancePlatform`. Buyers call governance tools to delegate spending authority, monitor delivery against caps, and revoke authority when caps are breached.
+
+```ts
+class MyPlatform implements DecisioningPlatform {
+  capabilities = {
+    specialisms: ['sales-non-guaranteed', 'governance-spend-authority'] as const,
+    ...
+  };
+
+  campaignGovernance: CampaignGovernancePlatform = {
+    grantSpendAuthority: async (req, ctx) => { /* mint a JWS */ },
+    revokeSpendAuthority: async (req, ctx) => { /* revoke + emit status change */ },
+    getDeliveryAttestation: async (req, ctx) => { /* aggregate delivery vs cap */ },
+  };
+}
+```
+
+Framework owns JWS verification on inbound `governance_context` tokens; you receive `ctx.state.governanceContext()` already verified, plan-bound, and seller-bound.
+
+Throw `GovernanceDeniedError` for revoked authority, `ComplianceUnsatisfiedError` for delivery cap breaches.
+
+See `REFERENCE.md` for the full governance section.

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

@@ -0,0 +1,34 @@
+# HITL — long-running tools
+
+When a tool can't return synchronously (operator approval, expensive report, brand-safety review), promote the call to a background task with `ctx.handoffToTask(fn)`. Framework returns the spec-defined `Submitted` envelope to the buyer immediately and runs `fn` in the background.
+
+## Pattern
+
+```ts
+import { AdcpError } from '@adcp/sdk/server';
+
+createMediaBuy: async (req, ctx) => {
+  if (this.requiresOperatorApproval(req)) {
+    return ctx.handoffToTask(async (taskCtx) => {
+      await taskCtx.update({ message: 'Awaiting trafficker' });
+      const order = await this.runApprovalFlow(req);                // can take hours
+      return { media_buy_id: order.id, status: 'pending_creatives', packages: ... };
+    });
+  }
+  return await this.commitSync(req);
+}
+```
+
+## What the framework does
+
+1. Detects the `TaskHandoff` marker on your return.
+2. Allocates a `task_id`, returns `{ task_id, status: 'submitted' }` to the buyer.
+3. Runs your handoff `fn` in the background.
+4. `fn`'s return value becomes the task's terminal `result`. Thrown `AdcpError` becomes terminal `error`.
+5. Buyer polls `tasks_get` OR receives a webhook (if they passed `push_notification_config.url` in the request).
+
+## When a tool is HITL-capable
+
+Only tools whose wire response defines a `Submitted` arm: `create_media_buy`, `sync_creatives`. Other tools (`update_media_buy`, `get_products`) are sync-only — operator re-approval flows surface eventual transitions via `publishStatusChange(...)` rather than HITL on the call itself.
+
+See `REFERENCE.md` for the full HITL section + hybrid-seller patterns + `taskHandoff.notify` semantics.

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

@@ -0,0 +1,52 @@
+# Idempotency — replay TTL and principal resolver
+
+Framework handles replay/dedup automatically. You don't write idempotency logic in your handlers.
+
+## What you don't have to do
+
+- Hash request payloads
+- Cache responses
+- Detect replay-with-same-payload vs replay-with-different-payload conflicts
+- Translate replays into the `replayed: true` envelope marker
+
+The framework owns all of this via `createIdempotencyStore` (memory or Postgres backend). Run `getIdempotencyMigration()` once per database in production.
+
+## When you might need to override
+
+The framework synthesizes a default `resolveIdempotencyPrincipal` from `auth.client_id ?? sessionKey ?? account.id`. That covers the standard case (multi-tenant: each authenticated buyer gets its own idempotency namespace; single-tenant: one shared namespace).
+
+Override only if your auth shape is unusual:
+
+```ts
+createAdcpServerFromPlatform(platform, {
+  name: '...', version: '...',
+  resolveIdempotencyPrincipal: (ctx) => ctx.authInfo?.subjectClaim ?? ctx.account?.id,
+});
+```
+
+## Replay TTL
+
+Default is 86400s (24h). Spec range: 3600 (1h) to 604800 (7d). Out-of-range throws at construction.
+
+```ts
+const idempotency = createIdempotencyStore({
+  backend: pgBackend(pool),
+  ttlSeconds: 86400,                 // 24h
+});
+createAdcpServerFromPlatform(platform, { name: '...', version: '...', idempotency, ... });
+```
+
+Capability projection automatic: framework declares `replay_ttl_seconds` on `get_adcp_capabilities` so buyers can reason about retry safety.
+
+## Conflict semantics
+
+If a buyer reuses an idempotency_key with a different payload, framework throws `IDEMPOTENCY_CONFLICT` automatically — you don't catch this. Buyer corrects with a fresh key.
+
+Production-only flag: in tests / dev, your handler may throw `IdempotencyConflictError` directly to simulate the path:
+
+```ts
+import { IdempotencyConflictError } from '@adcp/sdk/server';
+throw new IdempotencyConflictError({ details: { test_simulation: true } });
+```
+
+See `REFERENCE.md` for the full idempotency section.

package/skills/build-decisioning-platform/advanced/MULTI-TENANT.md

@@ -0,0 +1,47 @@
+# Multi-tenant hosting — TenantRegistry
+
+When one process hosts many publishers (typical SaaS deployment), use `createTenantRegistry` — wraps `createAdcpServerFromPlatform` with per-tenant config, health gates, and JWKS validation.
+
+```ts
+import { createTenantRegistry, serve } from '@adcp/sdk/server';
+
+const registry = createTenantRegistry({
+  resolveTenant: async (req) => {
+    // Map host header / OAuth subject / path prefix to a tenant id
+    return { tenantId: extractTenantFromHost(req.headers.host) };
+  },
+  buildPlatform: async (tenantId) => {
+    // Load tenant config from your DB
+    const tenantConfig = await loadTenant(tenantId);
+    return new MyPlatform(tenantConfig);
+  },
+  // Health gates: 'healthy' / 'unverified' / 'disabled'
+  // Disabled tenants get 503 SERVICE_UNAVAILABLE without invoking the platform.
+});
+
+serve(registry.host, { port: process.env.PORT });
+```
+
+## Per-tenant config
+
+Each tenant can override `capabilities.config` independently:
+
+```ts
+buildPlatform: async (tenantId) => {
+  const cfg = await loadTenant(tenantId);
+  return {
+    capabilities: {
+      ...,
+      config: { networkId: cfg.gamNetworkId, manualApprovalOperations: cfg.approvalOps },
+    },
+    accounts: { ... },
+    sales: { ... },
+  };
+};
+```
+
+## Per-tenant ctxMetadata
+
+Each `createAdcpServerFromPlatform` call gets its own `ctxMetadataStore` instance — multi-tenant hosts pass per-tenant store handles, not a shared one. Account scoping handles the rest (`account.id` in the storage key).
+
+See `REFERENCE.md` for the full multi-tenant section + admin router for ops visibility.

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

@@ -0,0 +1,22 @@
+# OAuth provider wiring
+
+If buyers authenticate via OIDC `client_credentials`, wire an introspection callback so the framework resolves `auth.client_id` from incoming bearer tokens.
+
+```ts
+import { serve, verifyIntrospection } from '@adcp/sdk/server';
+
+serve(() => server, {
+  port,
+  authenticate: verifyIntrospection({
+    introspectionUrl: process.env.OIDC_INTROSPECTION_URL,
+    clientId: process.env.OIDC_CLIENT_ID,
+    clientSecret: process.env.OIDC_CLIENT_SECRET,
+  }),
+});
+```
+
+Framework projects `auth.client_id` → `ctx.authInfo.clientId` in your handlers, and into the default idempotency principal resolver.
+
+For multi-tenant deployments where each tenant has its own OIDC issuer, see `MULTI-TENANT.md` (resolveTenant uses the issuer to route).
+
+See `REFERENCE.md` for full OAuth section.