@adcp/sdk 12.0.0 → 12.0.1

package/dist/lib/server/decisioning/buyer-agent.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/server/decisioning/buyer-agent.ts"],"sourcesContent":["/**\n * Buyer-agent identity surface from #1269 / #1292.\n *\n * Models a buyer agent (the buying entity calling a seller) as a durable\n * commercial relationship in the seller's records, distinct from the\n * per-request credential that proves identity. The seller's `BuyerAgent`\n * record carries onboarding state (status, billing capabilities, default\n * account terms, allowed brands) that drives commercial behavior.\n *\n * The credential answers \"who signed?\" / \"who holds this token?\" The\n * `BuyerAgent` answers \"who is this counterparty in our books?\" — analogous\n * to how an SSP has a `buyer_id` row keyed to a DSP regardless of whether\n * the DSP authenticates via OAuth, signed requests, or a pre-shared API\n * key. Token proves identity; row drives commercial behavior.\n *\n * AdCP 3.1 framework paths consume the resolved record for status,\n * sandbox-only, and `sync_accounts.billing` enforcement.\n *\n * @public\n */\n\nimport type { BillingParty, BusinessEntity, PaymentTerms } from '../../types/tools.generated';\n\n/**\n * Wire billing-party enum re-exported here for the registry surface.\n * Aliased to `BillingMode` in design discussion (#1269); `BillingParty` is\n * the canonical wire-schema name.\n *\n * @public\n */\nexport type BuyerAgentBillingMode = BillingParty;\n\n/**\n * Kind-discriminated credential variant on `ResolvedAuthInfo.credential`.\n *\n * `kind: 'http_sig'` is cryptographically verified — `agent_url` derives\n * from the `agents[]` entry whose `jwks_uri` resolved the keyid (per\n * adcontextprotocol/adcp#3831), NOT from JWK / JWS / envelope claims.\n * Security-relevant decisions (mutating-tool authorization, brand-side\n * authorization checks once `BrandAuthorizationResolver` lands) MUST read\n * `agent_url` from this variant, not from any informational field elsewhere\n * on `ResolvedAuthInfo`.\n *\n * `kind: 'api_key'` and `kind: 'oauth'` carry no `agent_url` on the\n * credential — the agent identity comes from the registry's\n * `resolveByCredential` lookup against the seller's onboarding record.\n *\n * @public\n */\nexport type AdcpCredential =\n  | { readonly kind: 'api_key'; readonly key_id: string }\n  | {\n      readonly kind: 'oauth';\n      readonly client_id: string;\n      readonly scopes: readonly string[];\n      readonly expires_at?: number;\n    }\n  | { readonly kind: 'http_sig'; readonly keyid: string; readonly agent_url: string; readonly verified_at: number };\n\n/**\n * Status of a buyer-agent record. Drives framework-level request gating:\n *\n * - `'active'` — normal operation; requests dispatch.\n * - `'suspended'` — temporarily paused; new requests rejected with\n *   `AGENT_SUSPENDED` (recovery: `terminal`). In-flight tasks are NOT\n *   retroactively cancelled — webhooks fire, status updates flow.\n *   Sellers who need hard cutoff implement that in their platform method\n *   via `BuyerAgent.status` check.\n * - `'blocked'` — permanently denied; new requests rejected with\n *   `AGENT_BLOCKED` (recovery: `terminal`). Lifting requires re-onboarding\n *   under a new agent identity.\n *\n * Both `AGENT_SUSPENDED` and `AGENT_BLOCKED` are terminal at the wire level\n * (the buyer cannot recover by retrying the same request). The transient-\n * vs-permanent distinction lives in the seller's `BuyerAgent.status` record\n * — suspension may lift via re-onboarding, blocked does not.\n *\n * Adopted from AdCP 3.1 spec PR adcp#3906, which consolidated the 3.0.5\n * placeholder shape `PERMISSION_DENIED + details.scope:'agent' + details.status`\n * into the dedicated codes.\n *\n * @public\n */\nexport type BuyerAgentStatus = 'active' | 'suspended' | 'blocked';\n\n/**\n * Buyer-agent record — durable commercial relationship in the seller's\n * onboarding ledger. Returned by `BuyerAgentRegistry.resolve` and threaded\n * to handlers via `ctx.agent`.\n *\n * Fields are `readonly` to prevent post-resolution mutation that would\n * silently affect downstream `accounts.resolve` decisions. Mirrors the\n * Python frozen-dataclass shape for cross-language parity.\n *\n * @public\n */\nexport interface BuyerAgent {\n  /**\n   * Canonical agent URL. Treat like a public key: stable enough that\n   * rotation requires explicit re-onboarding. The framework's signed-path\n   * resolution checks both this canonical URL and any `aliases[]` against\n   * the verified `credential.agent_url`. No separate seller-internal id —\n   * adopters who want one mint it in their own DB and key off `agent_url`.\n   */\n  readonly agent_url: string;\n\n  /** Human-readable name for ops / reporting / UI. */\n  readonly display_name: string;\n\n  /** See {@link BuyerAgentStatus}. */\n  readonly status: BuyerAgentStatus;\n\n  /**\n   * Billing models this agent is permitted to request on `sync_accounts`.\n   * Set-valued so real-world models (mixed-billing holdco with both direct\n   * and agency-mediated brands) can be expressed without picking one mode.\n   *\n   * Migration from earlier single-enum sketches:\n   * - `passthrough_only` ↔ `new Set(['operator'])`\n   * - `agent_billable` ↔ `new Set(['agent', 'operator', 'advertiser'])`\n   *\n   * The framework enforces this set on `sync_accounts` in AdCP 3.1\n   * deployments and returns `BILLING_NOT_PERMITTED_FOR_AGENT` with a\n   * clamped details shape when the requested billing value is outside it.\n   */\n  readonly billing_capabilities: ReadonlySet<BuyerAgentBillingMode>;\n\n  /**\n   * Commercial defaults applied when accounts are provisioned under this\n   * agent. Framework merges with per-request overrides on a SPARSE-MERGE\n   * basis: per-request values win for any present field including explicit\n   * `null`. The request is the authoritative current intent; defaults are\n   * seeds for fields the buyer didn't speak to. Adopters who want\n   * non-null-override semantics pre-filter nulls themselves.\n   */\n  readonly default_account_terms?: {\n    readonly rate_card?: string;\n    readonly payment_terms?: PaymentTerms;\n    readonly credit_limit?: { readonly amount: number; readonly currency: string };\n    readonly billing_entity?: BusinessEntity;\n  };\n\n  /**\n   * Static allowlist of brand domains this agent may act for. Pre-RFC\n   * stand-in for the per-request authorization check that\n   * `BrandAuthorizationResolver` will perform once it lands (gated on\n   * Python's RFC + adcp brand-side authz spec finalizing).\n   *\n   * When both this list and `BrandAuthorizationResolver` are configured,\n   * the framework AND-composes them: registry says \"we accept this agent\n   * at all\"; resolver says \"and they're authorized for THIS brand.\" One-\n   * minor deprecation cycle starts the release after\n   * `BrandAuthorizationResolver` ships; sellers who want the static gate\n   * gone stop populating the field.\n   */\n  readonly allowed_brands?: readonly string[];\n\n  /**\n   * Optional grace-period overlap during `agent_url` rotation. Framework's\n   * signed-path resolution checks both canonical `agent_url` AND `aliases`\n   * against the `agents[]` entry that resolved the verified keyid.\n   *\n   * v1 ships with the field present but no special framework behavior\n   * beyond resolution; v1.5 adds the documented sunset window pattern.\n   * Most adopters never populate this.\n   */\n  readonly aliases?: readonly string[];\n\n  /**\n   * When `true`, this buyer agent may ONLY operate against sandbox\n   * accounts. The framework rejects any request whose resolved\n   * `Account.sandbox !== true` with `PERMISSION_DENIED`,\n   * `error.details.scope: 'agent'`, `error.details.reason: 'sandbox-only'`.\n   *\n   * Defense-in-depth for test agents (CI runners, internal QA agents,\n   * partner pre-prod environments): if the test credential leaks, blast\n   * radius is bounded to sandbox accounts. Production agents leave this\n   * unset (or `false`).\n   *\n   * Composes with `Account.sandbox` (the wire-level sandbox marker on\n   * the resolved Account record): the gate fires when `agent.sandbox_only\n   * === true AND ctx.account?.sandbox !== true`. Account-less tools\n   * (`provide_performance_feedback`, `list_creative_formats`, etc.) pass\n   * the gate — they don't operate on a specific account, so the\n   * sandbox/production axis doesn't apply.\n   *\n   * **Load-bearing pair.** For the gate to admit ANY traffic from a\n   * `sandbox_only` agent, the seller's `accounts.resolve` MUST return\n   * `sandbox: true` on the accounts that agent should reach. Adopters\n   * cloning the worked example with `sandbox_only: true` on their seed\n   * agent and a hardcoded `sandbox: true` resolver are demoware-correct;\n   * production adopters either flip the agent to `sandbox_only: false`\n   * OR have their resolver return `sandbox: true` only for actually-\n   * sandbox accounts. Mismatches between these two sides 403 every\n   * request — failure is loud, not silent.\n   *\n   * Default `false` (or undefined) — production-allowed.\n   */\n  readonly sandbox_only?: boolean;\n}\n\nconst BILLING_SUGGESTION_ORDER: readonly BuyerAgentBillingMode[] = ['operator', 'advertiser', 'agent'];\n\n/**\n * Pick the single autonomous-retry billing value exposed on\n * `BILLING_NOT_PERMITTED_FOR_AGENT.details.suggested_billing`.\n *\n * The details schema intentionally allows only one suggestion, not the\n * agent's full permitted set. Preference is the spec-discussed commercial\n * fallback order: operator > advertiser > agent.\n *\n * @public\n */\nexport function suggestBilling(\n  billingCapabilities: ReadonlySet<BuyerAgentBillingMode>,\n  rejected: BuyerAgentBillingMode\n): BuyerAgentBillingMode | undefined {\n  for (const mode of BILLING_SUGGESTION_ORDER) {\n    if (mode !== rejected && billingCapabilities.has(mode)) return mode;\n  }\n  return undefined;\n}\n\n// ---------------------------------------------------------------------------\n// Registry Protocol + factory functions\n// ---------------------------------------------------------------------------\n\n/**\n * Minimal `ResolvedAuthInfo`-shaped argument to `BuyerAgentRegistry.resolve`.\n * Defined here to break a circular dependency with `account.ts` and to keep\n * the registry surface decoupled from the legacy `ResolvedAuthInfo` shape\n * during the two-minor migration cycle.\n *\n * Stage 3 of the implementation will widen `ResolvedAuthInfo` itself with\n * the `credential` field; this interface is the registry-side contract.\n *\n * @public\n */\nexport interface BuyerAgentResolveInput {\n  /**\n   * The kind-discriminated credential proven on the request. Stage 3 of\n   * the Phase 1 implementation will populate this from the verifier\n   * (`http_sig`) or from the legacy `ResolvedAuthInfo` shape (`api_key` /\n   * `oauth`); until then, callers pass it through directly when available.\n   *\n   * When absent, the registry's `resolve` returns `null` — the legacy-\n   * shape synthesis lands in Stage 3 alongside the `ResolvedAuthInfo`\n   * migration shim, not Stage 1.\n   */\n  readonly credential?: AdcpCredential;\n\n  /**\n   * Adopter-provided extension data threaded from `authenticate()`. Populated\n   * from the `extra` field stamped on the `AuthPrincipal` returned by the\n   * `authenticate()` callback (e.g. `verifyApiKey({ verify: token => ({ ...,\n   * extra: { demo_token: token } }) })`). Forwarded to the second argument of\n   * {@link ResolveBuyerAgentByCredential} by `bearerOnly` and `mixed` factories.\n   *\n   * The full MCP `AuthInfo.extra` bag is forwarded here — it includes JWT\n   * claims (if `verifyBearer` was used) and the SDK-internal `credential` key\n   * alongside adopter-stamped fields. Do not use reserved key names (`credential`,\n   * `iss`, `sub`, `aud`, `exp`, `iat`, `nbf`, `jti`) in the `extra` object\n   * to avoid collisions.\n   */\n  readonly extra?: Record<string, unknown>;\n\n  /**\n   * Raw AdCP request parameters for the current tool call, after transport\n   * decoding and before handler dispatch. Registry implementations normally\n   * key only on `credential`, but compliance-controller overlays may need the\n   * request `context.session_id` or `account` to resolve a scoped test\n   * commercial state for this request.\n   */\n  readonly input?: Record<string, unknown>;\n}\n\n/**\n * Buyer-agent registry — durable identity surface called once per request\n * before `accounts.resolve`. Adopters construct via one of the factory\n * functions; the resulting object exposes a single `resolve` method the\n * framework dispatcher invokes.\n *\n * Three implementer postures, encoded at construction:\n *\n * - {@link signingOnly} — production target. Bearer/API-key/OAuth requests\n *   refused at the registry layer; signed requests resolve via\n *   `resolveByAgentUrl` against the verified `credential.agent_url`.\n * - {@link bearerOnly} — pre-trust beta. No signature support; bearer-shaped\n *   credentials resolve via `resolveByCredential` against the seller's\n *   onboarding ledger.\n * - {@link mixed} — transition. Both paths active. Signed traffic resolves\n *   cryptographically; bearer falls through to the legacy key table.\n *\n * The factories produce a `BuyerAgentRegistry` whose `resolve` method\n * routes by `credential.kind` and returns `null` when the credential is\n * not honored by the configured posture (e.g., bearer credential against\n * a `signingOnly` registry → `null`, framework rejects the request).\n *\n * @public\n */\nexport interface BuyerAgentRegistry {\n  /**\n   * Resolve a request's credential to a buyer-agent record.\n   *\n   * Returns `null` when the credential is not recognized OR when the\n   * configured posture rejects the credential's kind (e.g., `bearerOnly`\n   * registry receiving an `http_sig` credential).\n   *\n   * Throws when the underlying lookup fails (DB outage, identity-provider\n   * 5xx). Framework projects the throw to `SERVICE_UNAVAILABLE` so the\n   * buyer can retry; the inner error is logged server-side.\n   */\n  resolve(authInfo: BuyerAgentResolveInput): Promise<BuyerAgent | null>;\n}\n\n/**\n * Resolver function type for the signed path. Receives the\n * cryptographically-verified `agent_url` from the request signature and\n * returns the seller's record (or `null` for unrecognized agents).\n *\n * @public\n */\nexport type ResolveBuyerAgentByAgentUrl = (agent_url: string) => Promise<BuyerAgent | null>;\n\n/**\n * Resolver function type for the bearer/API-key/OAuth path. Receives the\n * raw credential and (optionally) adopter-provided extension data, and\n * returns the seller's record (or `null` for unrecognized credentials).\n *\n * **Implementations MUST switch on `credential.kind`** and reject (return\n * `null`) on any kind they don't explicitly recognize. A naive\n * `WHERE token = $1` lookup against an api-key table would otherwise mis-\n * resolve when handed an `http_sig` credential whose `keyid` happens to\n * collide with an existing api-key value — the credential variants share\n * no key namespace, and the registry MUST NOT bridge them.\n *\n * **Credential exposure.** This callback receives unredacted credential\n * payloads (token, key_id, client_id). Adopters MUST NOT log raw credential\n * values AND MUST NOT include them in thrown `Error` messages — the\n * framework projects `err.message` into `error.details.reason` on the wire\n * when `exposeErrorDetails` is on (default: non-production). Throw with\n * a generic message and log the credential separately if you need it for\n * server-side debugging. The framework redacts credential payloads in any\n * log line emitted from registry-resolution code (Stage 4); adopter\n * implementations are expected to do the same (or to use prepared-statement\n * parameters that don't log).\n *\n * **`extra` — adopter extension data.** When the `authenticate()` callback\n * stamps an `extra` field on the returned `AuthPrincipal` (e.g.\n * `verifyApiKey({ verify: token => ({ principal, extra: { demo_token: token } }) })`),\n * the framework propagates that value through `ResolvedAuthInfo.extra` to\n * this second argument. Use it to carry pre-hash data your authenticator\n * already derived (prefix patterns, tenant IDs, test-kit flags) that you\n * can't recover from the hashed `key_id`. Apply the same care as for\n * `credential`: do not log raw values from `extra` or include them in\n * thrown `Error` messages.\n *\n * Existing single-argument implementations `(credential) => ...` satisfy\n * this type — the second argument is optional.\n *\n * @public\n */\nexport type ResolveBuyerAgentByCredential = (\n  credential: AdcpCredential,\n  extra?: Record<string, unknown>,\n  input?: Record<string, unknown>\n) => Promise<BuyerAgent | null>;\n\n/**\n * Belt-and-suspenders check that an `http_sig` credential carries a non-\n * empty `agent_url`. A misbehaving authenticator could produce `kind:\n * 'http_sig'` without populating the verified URL — without this guard, the\n * registry would pass `undefined` (or `''`) to the adopter's resolver and\n * silently get back `null`. Caller is responsible for the kind dispatch;\n * this function only validates the http_sig payload shape.\n */\nfunction isVerifiedHttpSigPayload(credential: { agent_url?: string }): credential is { agent_url: string } {\n  return typeof credential.agent_url === 'string' && credential.agent_url.length > 0;\n}\n\n/**\n * Module-private symbol used as a provenance brand on verifier-produced\n * `http_sig` credentials. NOT registered via `Symbol.for(...)` — code\n * outside this module cannot synthesize the symbol value, which is what\n * makes it a usable provenance check.\n *\n * The brand is non-enumerable so it's invisible to `JSON.stringify`,\n * `Object.keys`, spread, and structured-clone — meaning a credential\n * that crosses a serialization boundary loses its brand. For the\n * security model that's correct: a hostile relay or replay strips the\n * brand and the registry refuses to treat the credential as verified.\n *\n * Only `markVerifiedHttpSig` (called by the framework's signature\n * verifier in `src/lib/server/auth-signature.ts`) attaches the brand.\n * Custom `authenticate` callbacks that synthesize a literal-shape\n * `{ kind: 'http_sig', ... }` credential will NOT carry the brand —\n * `signingOnly` and `mixed` registry factories reject those.\n */\nconst VERIFIED_HTTP_SIG_BRAND: unique symbol = Symbol('@adcp/sdk.verifiedHttpSig');\n\ntype VerifiedHttpSig = Extract<AdcpCredential, { kind: 'http_sig' }> & {\n  readonly [VERIFIED_HTTP_SIG_BRAND]: true;\n};\n\n/**\n * Brand an `http_sig` credential as verifier-produced. Only the framework's\n * signature verifier (`verifySignatureAsAuthenticator`) calls this; the\n * brand is the registry's proof that the credential's `agent_url` was\n * cryptographically verified per adcontextprotocol/adcp#3831.\n *\n * Returned object is a fresh shallow copy — the input is not mutated.\n *\n * @internal — exported for `auth-signature.ts` only; not part of the\n * adopter surface.\n */\nexport function markVerifiedHttpSig(\n  credential: Extract<AdcpCredential, { kind: 'http_sig' }>\n): Extract<AdcpCredential, { kind: 'http_sig' }> {\n  const branded = { ...credential };\n  Object.defineProperty(branded, VERIFIED_HTTP_SIG_BRAND, {\n    value: true,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  });\n  return branded as VerifiedHttpSig;\n}\n\n/**\n * Predicate the registry factories use to distinguish verifier-produced\n * `http_sig` credentials from literal-shape impostors. Returns true ONLY\n * when the credential was produced by the framework's signature verifier\n * (or another caller that imported the symbol from this module — there\n * are none).\n */\nfunction isVerifiedHttpSig(credential: AdcpCredential): boolean {\n  return credential.kind === 'http_sig' && (credential as Record<symbol, unknown>)[VERIFIED_HTTP_SIG_BRAND] === true;\n}\n\n/**\n * Construct a signing-only `BuyerAgentRegistry`. Bearer/API-key/OAuth\n * requests resolve to `null` (framework rejects); only signed requests\n * are honored.\n *\n * The path-of-least-resistance factory for production sellers — implement\n * one resolver, traffic that doesn't sign is automatically refused.\n *\n * @public\n */\nexport function signingOnly(opts: { resolveByAgentUrl: ResolveBuyerAgentByAgentUrl }): BuyerAgentRegistry {\n  if (typeof opts.resolveByAgentUrl !== 'function') {\n    throw new TypeError('BuyerAgentRegistry.signingOnly: resolveByAgentUrl must be a function');\n  }\n  const resolveByAgentUrl = opts.resolveByAgentUrl;\n  return {\n    async resolve(authInfo) {\n      const credential = authInfo.credential;\n      if (credential === undefined || credential.kind !== 'http_sig') return null;\n      // Reject literal-shape http_sig credentials: only the framework's\n      // signature verifier brands a credential as verified. A custom\n      // `authenticate` callback that synthesizes `{ kind: 'http_sig', ... }`\n      // from arbitrary data would otherwise be routed as if cryptographically\n      // verified — the brand check closes that forgery vector.\n      if (!isVerifiedHttpSig(credential)) return null;\n      if (!isVerifiedHttpSigPayload(credential)) return null;\n      return resolveByAgentUrl(credential.agent_url);\n    },\n  };\n}\n\n/**\n * Construct a bearer-only `BuyerAgentRegistry`. Signed requests still\n * authenticate via the existing signature-verifier surface, but the\n * registry resolves all credential kinds via `resolveByCredential` against\n * the seller's onboarding ledger — useful in pre-trust-beta deployments\n * where the seller maintains a credential→agent table out-of-band.\n *\n * @public\n */\nexport function bearerOnly(opts: { resolveByCredential: ResolveBuyerAgentByCredential }): BuyerAgentRegistry {\n  if (typeof opts.resolveByCredential !== 'function') {\n    throw new TypeError('BuyerAgentRegistry.bearerOnly: resolveByCredential must be a function');\n  }\n  const resolveByCredential = opts.resolveByCredential;\n  return {\n    async resolve(authInfo) {\n      const credential = authInfo.credential;\n      const extra = authInfo.extra;\n      if (credential === undefined) return null;\n      return resolveByCredential(credential, extra, authInfo.input);\n    },\n  };\n}\n\n/**\n * Construct a mixed-mode `BuyerAgentRegistry` that supports both signed and\n * bearer/OAuth/API-key credentials. Signed traffic resolves through\n * `resolveByAgentUrl` against the verified `credential.agent_url`; non-\n * signed credentials fall through to `resolveByCredential`.\n *\n * Framework prefers the signed path: when both an `Authorization: Bearer`\n * and a valid `Signature: ...` are present on the same request, the\n * `http_sig` credential variant is what reaches `resolve`, and only\n * `resolveByAgentUrl` is invoked. The bearer path is never consulted on\n * signed traffic.\n *\n * @public\n */\nexport function mixed(opts: {\n  resolveByAgentUrl: ResolveBuyerAgentByAgentUrl;\n  resolveByCredential: ResolveBuyerAgentByCredential;\n}): BuyerAgentRegistry {\n  if (typeof opts.resolveByAgentUrl !== 'function') {\n    throw new TypeError('BuyerAgentRegistry.mixed: resolveByAgentUrl must be a function');\n  }\n  if (typeof opts.resolveByCredential !== 'function') {\n    throw new TypeError('BuyerAgentRegistry.mixed: resolveByCredential must be a function');\n  }\n  const resolveByAgentUrl = opts.resolveByAgentUrl;\n  const resolveByCredential = opts.resolveByCredential;\n  return {\n    async resolve(authInfo) {\n      const credential = authInfo.credential;\n      const extra = authInfo.extra;\n      if (credential === undefined) return null;\n      if (credential.kind === 'http_sig') {\n        // Same forgery clamp as `signingOnly`: only verifier-branded\n        // http_sig credentials route through the signed path.\n        if (!isVerifiedHttpSig(credential)) return null;\n        // Reject a malformed `http_sig` credential here rather than falling\n        // through to resolveByCredential. Otherwise `mixed` would be strictly\n        // weaker than signingOnly: an authenticator that produces an\n        // http_sig-shaped credential without a verified agent_url could\n        // bypass signed-path enforcement by routing through the bearer table.\n        if (!isVerifiedHttpSigPayload(credential)) return null;\n        return resolveByAgentUrl(credential.agent_url);\n      }\n      return resolveByCredential(credential, extra, authInfo.input);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Caching decorator — Phase 1 Stage 5 of #1269\n// ---------------------------------------------------------------------------\n\n/**\n * Options for {@link cached}.\n *\n * @public\n */\nexport interface BuyerAgentCacheOptions {\n  /**\n   * TTL (seconds) for successful resolutions. Default: 60.\n   *\n   * Adopters whose registry sits in front of a Postgres / external lookup\n   * benefit from caching for the request lifecycle of a single buyer's\n   * traffic burst. Long TTLs (several minutes) are appropriate for\n   * stable agent records; short TTLs (a few seconds) for rapidly-mutating\n   * relationships (suspension flags, billing-capability changes).\n   *\n   * Status changes propagate within `ttlSeconds` of the seller flipping\n   * the agent's row in their store — adopters needing instant\n   * propagation either set a short TTL or invalidate the cache out-of-\n   * band when they mutate.\n   */\n  ttlSeconds?: number;\n\n  /**\n   * TTL (seconds) for `null` returns (negative cache). Default: 0\n   * (don't cache nulls). A freshly onboarded agent is recognized within\n   * one request when nulls aren't cached; sellers willing to delay\n   * recognition by N seconds in exchange for fewer DB hits set this to\n   * a small positive value.\n   *\n   * **Timing-oracle note.** When null caching is enabled, an\n   * unauthenticated prober comparing hit vs. miss latency on null\n   * returns can infer \"this credential was probed recently.\" Pair with\n   * rate-limiting at the edge if your deployment runs in a hostile\n   * environment. The default (0) avoids the oracle entirely.\n   */\n  cacheNullsTtlSeconds?: number;\n\n  /**\n   * Maximum cache entries before LRU eviction. Default: 10000.\n   * The cache is bounded so a malicious or misconfigured caller spamming\n   * unique credentials (e.g., random api keys probing the seller's\n   * onboarding surface) can't exhaust memory.\n   */\n  maxSize?: number;\n\n  /** Override clock for deterministic tests. Returns ms since epoch. */\n  now?: () => number;\n}\n\ninterface CacheEntry {\n  value: BuyerAgent | null;\n  expiresAtMs: number;\n}\n\n/**\n * Cached registry surface. Strict superset of {@link BuyerAgentRegistry}\n * with explicit invalidation hooks adopters call when they mutate the\n * backing record (status flip, billing-capability change). Without\n * `invalidate`, adopters could only purge stale entries by waiting for\n * `ttlSeconds` to expire — for status changes that's exactly the\n * window during which a now-suspended agent retains access.\n *\n * `BuyerAgentRegistry.cached(...)` returns this richer type so adopters\n * can hold a reference and call the invalidation methods directly.\n *\n * @public\n */\nexport interface CachedBuyerAgentRegistry extends BuyerAgentRegistry {\n  /**\n   * Drop the cache entry for a single credential. No-op when the\n   * credential isn't currently cached. Use this when the agent's\n   * record is mutated in your backing store so the next request\n   * re-resolves rather than serving the stale entry.\n   */\n  invalidate(credential: AdcpCredential): void;\n\n  /**\n   * Drop all cached entries. Use on bulk record mutations (onboarding-\n   * record migration, daily reset) or test-environment cleanup.\n   */\n  clear(): void;\n}\n\n/**\n * Compute a cache key from a credential. Returns null when the\n * credential is undefined — uncacheable, falls through to the inner\n * registry on each call. Keys are namespaced by kind so an api_key\n * `key_id` value can never collide with an http_sig `keyid` value or\n * an oauth `client_id`. Note that `key_id` is already a stable hash\n * (Stage 3); using it as a cache key is safe.\n */\nfunction cacheKeyForCredential(credential: AdcpCredential | undefined): string | null {\n  if (credential === undefined) return null;\n  switch (credential.kind) {\n    case 'http_sig':\n      return `http_sig:${credential.agent_url}`;\n    case 'api_key':\n      return `api_key:${credential.key_id}`;\n    case 'oauth':\n      return `oauth:${credential.client_id}`;\n    default: {\n      // Exhaustiveness check — adding a new credential kind without\n      // updating this switch produces a compile error here, not a\n      // runtime cache-miss bug.\n      const _exhaustive: never = credential;\n      void _exhaustive;\n      return null;\n    }\n  }\n}\n\n/**\n * Wrap a {@link BuyerAgentRegistry} with TTL-based result caching and\n * concurrent-resolve coalescing. Adopters whose `resolveByAgentUrl` /\n * `resolveByCredential` hit a database or external service compose\n * the cache via:\n *\n * ```ts\n * const registry = BuyerAgentRegistry.cached(\n *   BuyerAgentRegistry.signingOnly({\n *     resolveByAgentUrl: async url => db.findBuyerAgent(url),\n *   }),\n *   { ttlSeconds: 60 }\n * );\n * ```\n *\n * Cache properties:\n * - **TTL-bounded.** Entries expire after `ttlSeconds` (default 60).\n *   Negative cache (null returns) is opt-in via `cacheNullsTtlSeconds`.\n * - **LRU-evicted.** Bounded to `maxSize` entries (default 10000).\n *   Oldest-accessed entry evicts on overflow.\n * - **Concurrent-resolve coalesced.** N parallel `resolve()` calls on\n *   the same key produce ONE upstream invocation. Subsequent callers\n *   await the in-flight promise — important when the seller front-ends\n *   a slow upstream and a buyer burst arrives.\n * - **Per-kind cache keys.** Keys are namespaced (`http_sig:`,\n *   `api_key:`, `oauth:`) so cross-kind collisions cannot leak an agent\n *   resolved through one credential type to a different type.\n * - **`extra` is not part of the cache key.** The cache keys on credential\n *   identity only. Two requests with the same credential but different\n *   `authInfo.extra` content return the same cached result. This is the\n *   right behaviour when `extra` carries pre-hash data derived from the\n *   same token (the motivating use-case), but can be surprising if you\n *   put per-request session context in `extra`. Set a short `ttlSeconds`\n *   or skip the cache decorator if your resolution is sensitive to `extra`\n *   variance across requests with the same credential.\n * - **Skips uncacheable inputs.** When the credential is undefined,\n *   `resolve()` falls through to the inner registry on each call —\n *   adopters wiring custom auth without `credential` synthesis (Stage 3\n *   migration cycle) see no behavior change.\n * - **Explicit invalidation.** Returns a {@link CachedBuyerAgentRegistry}\n *   with `.invalidate(credential)` and `.clear()` methods. Call\n *   `invalidate` when you mutate an agent's record (status flip,\n *   billing-capability change) so the next request re-resolves rather\n *   than serving the stale entry. Without this, the stale-status window\n *   is bounded by `ttlSeconds` — a now-suspended agent retains access\n *   for up to that long.\n *\n * Mirrors the `AsyncCachingJwksResolver` over `JwksResolver` pattern\n * already in `src/lib/signing/`.\n *\n * @public\n */\nexport function cached(inner: BuyerAgentRegistry, options: BuyerAgentCacheOptions = {}): CachedBuyerAgentRegistry {\n  if (typeof inner !== 'object' || inner === null || typeof inner.resolve !== 'function') {\n    throw new TypeError('BuyerAgentRegistry.cached: `inner` must be a BuyerAgentRegistry');\n  }\n  const ttlMs = (options.ttlSeconds ?? 60) * 1000;\n  const nullsTtlMs = (options.cacheNullsTtlSeconds ?? 0) * 1000;\n  const maxSize = options.maxSize ?? 10000;\n  const now = options.now ?? Date.now;\n\n  if (ttlMs <= 0) throw new RangeError('BuyerAgentRegistry.cached: ttlSeconds must be > 0');\n  if (nullsTtlMs < 0) throw new RangeError('BuyerAgentRegistry.cached: cacheNullsTtlSeconds must be >= 0');\n  if (maxSize < 1) throw new RangeError('BuyerAgentRegistry.cached: maxSize must be >= 1');\n\n  // Map iteration order is insertion order, so re-inserting on hit\n  // gives us LRU-on-access semantics for free.\n  const cache = new Map<string, CacheEntry>();\n  const inFlight = new Map<string, Promise<BuyerAgent | null>>();\n\n  return {\n    async resolve(authInfo) {\n      const key = cacheKeyForCredential(authInfo.credential);\n      if (key === null) {\n        // Uncacheable input — pass through. Adopters wiring custom\n        // auth that hasn't migrated to `credential` synthesis see\n        // every call hit the inner resolver.\n        return inner.resolve(authInfo);\n      }\n\n      const entry = cache.get(key);\n      if (entry !== undefined && now() < entry.expiresAtMs) {\n        // LRU touch: re-insert so this entry becomes the most-recent.\n        cache.delete(key);\n        cache.set(key, entry);\n        return entry.value;\n      }\n      if (entry !== undefined) {\n        // Expired — drop before refetch.\n        cache.delete(key);\n      }\n\n      // Coalesce concurrent resolves: subsequent callers on the same\n      // key await the existing in-flight promise rather than firing\n      // their own upstream lookup. If the upstream rejects, all\n      // coalesced callers see the same rejection; the `finally` below\n      // releases `inFlight` so the next caller retries upstream\n      // (rejected promises do NOT poison the cache — `cache.set`\n      // inside the IIFE is unreachable on rejection).\n      const existing = inFlight.get(key);\n      if (existing !== undefined) return existing;\n\n      const promise = (async () => {\n        const value = await inner.resolve(authInfo);\n        const entryTtlMs = value === null ? nullsTtlMs : ttlMs;\n        if (entryTtlMs > 0) {\n          // Defense-in-depth: freeze the resolved record before\n          // sharing across coalesced callers. The dispatcher seam\n          // also freezes per-request (Stage 2), but freezing here\n          // makes the cached-shared-reference invariant load-\n          // bearing rather than coincidental — a future caller\n          // mutating `BuyerAgent.status` would otherwise corrupt\n          // every other cached-hit consumer's view.\n          if (value !== null && !Object.isFrozen(value)) {\n            if (value.billing_capabilities instanceof Set) {\n              Object.freeze(value.billing_capabilities);\n            }\n            Object.freeze(value);\n          }\n          cache.set(key, { value, expiresAtMs: now() + entryTtlMs });\n          while (cache.size > maxSize) {\n            const oldestKey = cache.keys().next().value;\n            if (oldestKey === undefined) break;\n            cache.delete(oldestKey);\n          }\n        }\n        return value;\n      })();\n      inFlight.set(key, promise);\n      try {\n        return await promise;\n      } finally {\n        inFlight.delete(key);\n      }\n    },\n\n    invalidate(credential) {\n      const key = cacheKeyForCredential(credential);\n      if (key !== null) cache.delete(key);\n    },\n\n    clear() {\n      cache.clear();\n    },\n  };\n}\n\n/**\n * Factory namespace mirroring the documented surface from #1269. Adopters\n * import the namespace and call `BuyerAgentRegistry.signingOnly({...})`,\n * etc. Individual functions are also exported above for direct use.\n *\n * @public\n */\nexport const BuyerAgentRegistry = {\n  signingOnly,\n  bearerOnly,\n  mixed,\n  cached,\n  suggestBilling,\n};\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../../../src/lib/server/decisioning/buyer-agent.ts"],"sourcesContent":["/**\n * Buyer-agent identity surface from #1269 / #1292.\n *\n * Models a buyer agent (the buying entity calling a seller) as a durable\n * commercial relationship in the seller's records, distinct from the\n * per-request credential that proves identity. The seller's `BuyerAgent`\n * record carries onboarding state (status, billing capabilities, default\n * account terms, allowed brands) that drives commercial behavior.\n *\n * The credential answers \"who signed?\" / \"who holds this token?\" The\n * `BuyerAgent` answers \"who is this counterparty in our books?\" — analogous\n * to how an SSP has a `buyer_id` row keyed to a DSP regardless of whether\n * the DSP authenticates via OAuth, signed requests, or a pre-shared API\n * key. Token proves identity; row drives commercial behavior.\n *\n * AdCP 3.1 framework paths consume the resolved record for status,\n * sandbox-only, and `sync_accounts.billing` enforcement.\n *\n * @public\n */\n\nimport type { BillingParty, BusinessEntity, PaymentTerms } from '../../types/tools.generated';\n\n/**\n * Wire billing-party enum re-exported here for the registry surface.\n * Aliased to `BillingMode` in design discussion (#1269); `BillingParty` is\n * the canonical wire-schema name.\n *\n * @public\n */\nexport type BuyerAgentBillingMode = BillingParty;\n\n/**\n * Kind-discriminated credential variant on `ResolvedAuthInfo.credential`.\n *\n * `kind: 'http_sig'` is cryptographically verified — `agent_url` derives\n * from the `agents[]` entry whose `jwks_uri` resolved the keyid (per\n * adcontextprotocol/adcp#3831), NOT from JWK / JWS / envelope claims.\n * Security-relevant decisions (mutating-tool authorization, brand-side\n * authorization checks once `BrandAuthorizationResolver` lands) MUST read\n * `agent_url` from this variant, not from any informational field elsewhere\n * on `ResolvedAuthInfo`.\n *\n * `kind: 'api_key'` and `kind: 'oauth'` carry no `agent_url` on the\n * credential — the agent identity comes from the registry's\n * `resolveByCredential` lookup against the seller's onboarding record.\n *\n * @public\n */\nexport type AdcpCredential =\n  | { readonly kind: 'api_key'; readonly key_id: string }\n  | {\n      readonly kind: 'oauth';\n      readonly client_id: string;\n      readonly scopes: readonly string[];\n      readonly expires_at?: number;\n    }\n  | { readonly kind: 'http_sig'; readonly keyid: string; readonly agent_url: string; readonly verified_at: number };\n\n/**\n * Status of a buyer-agent record. Drives framework-level request gating:\n *\n * - `'active'` — normal operation; requests dispatch.\n * - `'suspended'` — temporarily paused; new requests rejected with\n *   `AGENT_SUSPENDED` (recovery: `terminal`). In-flight tasks are NOT\n *   retroactively cancelled — webhooks fire, status updates flow.\n *   Sellers who need hard cutoff implement that in their platform method\n *   via `BuyerAgent.status` check.\n * - `'blocked'` — permanently denied; new requests rejected with\n *   `AGENT_BLOCKED` (recovery: `terminal`). Lifting requires re-onboarding\n *   under a new agent identity.\n *\n * Both `AGENT_SUSPENDED` and `AGENT_BLOCKED` are terminal at the wire level\n * (the buyer cannot recover by retrying the same request). The transient-\n * vs-permanent distinction lives in the seller's `BuyerAgent.status` record\n * — suspension may lift via re-onboarding, blocked does not.\n *\n * Adopted from AdCP 3.1 spec PR adcp#3906, which consolidated the 3.0.5\n * placeholder shape `PERMISSION_DENIED + details.scope:'agent' + details.status`\n * into the dedicated codes.\n *\n * @public\n */\nexport type BuyerAgentStatus = 'active' | 'suspended' | 'blocked';\n\n/**\n * Buyer-agent record — durable commercial relationship in the seller's\n * onboarding ledger. Returned by `BuyerAgentRegistry.resolve` and threaded\n * to handlers via `ctx.agent`.\n *\n * Fields are `readonly` to prevent post-resolution mutation that would\n * silently affect downstream `accounts.resolve` decisions. Mirrors the\n * Python frozen-dataclass shape for cross-language parity.\n *\n * @public\n */\nexport interface BuyerAgent {\n  /**\n   * Canonical agent URL. Treat like a public key: stable enough that\n   * rotation requires explicit re-onboarding. The framework's signed-path\n   * resolution checks both this canonical URL and any `aliases[]` against\n   * the verified `credential.agent_url`. No separate seller-internal id —\n   * adopters who want one mint it in their own DB and key off `agent_url`.\n   */\n  readonly agent_url: string;\n\n  /** Human-readable name for ops / reporting / UI. */\n  readonly display_name: string;\n\n  /** See {@link BuyerAgentStatus}. */\n  readonly status: BuyerAgentStatus;\n\n  /**\n   * Billing models this agent is permitted to request on `sync_accounts`.\n   * Set-valued so real-world models (mixed-billing holdco with both direct\n   * and agency-mediated brands) can be expressed without picking one mode.\n   *\n   * Migration from earlier single-enum sketches:\n   * - `passthrough_only` ↔ `new Set(['operator'])`\n   * - `agent_billable` ↔ `new Set(['agent', 'operator', 'advertiser'])`\n   *\n   * The framework enforces this set on `sync_accounts` in AdCP 3.1\n   * deployments and returns `BILLING_NOT_PERMITTED_FOR_AGENT` with a\n   * clamped details shape when the requested billing value is outside it.\n   */\n  readonly billing_capabilities: ReadonlySet<BuyerAgentBillingMode>;\n\n  /**\n   * Commercial defaults applied when accounts are provisioned under this\n   * agent. Framework merges with per-request overrides on a SPARSE-MERGE\n   * basis: per-request values win for any present field including explicit\n   * `null`. The request is the authoritative current intent; defaults are\n   * seeds for fields the buyer didn't speak to. Adopters who want\n   * non-null-override semantics pre-filter nulls themselves.\n   */\n  readonly default_account_terms?: {\n    readonly rate_card?: string;\n    readonly payment_terms?: PaymentTerms;\n    readonly credit_limit?: { readonly amount: number; readonly currency: string };\n    readonly billing_entity?: BusinessEntity;\n  };\n\n  /**\n   * Static allowlist of brand domains this agent may act for. Pre-RFC\n   * stand-in for the per-request authorization check that\n   * `BrandAuthorizationResolver` will perform once it lands (gated on\n   * Python's RFC + adcp brand-side authz spec finalizing).\n   *\n   * When both this list and `BrandAuthorizationResolver` are configured,\n   * the framework AND-composes them: registry says \"we accept this agent\n   * at all\"; resolver says \"and they're authorized for THIS brand.\" One-\n   * minor deprecation cycle starts the release after\n   * `BrandAuthorizationResolver` ships; sellers who want the static gate\n   * gone stop populating the field.\n   */\n  readonly allowed_brands?: readonly string[];\n\n  /**\n   * Optional grace-period overlap during `agent_url` rotation. Framework's\n   * signed-path resolution checks both canonical `agent_url` AND `aliases`\n   * against the `agents[]` entry that resolved the verified keyid.\n   *\n   * v1 ships with the field present but no special framework behavior\n   * beyond resolution; v1.5 adds the documented sunset window pattern.\n   * Most adopters never populate this.\n   */\n  readonly aliases?: readonly string[];\n\n  /**\n   * When `true`, this buyer agent may ONLY operate against sandbox\n   * accounts. The framework rejects any request whose resolved\n   * `Account.sandbox !== true` with `PERMISSION_DENIED`,\n   * `error.details.scope: 'agent'`, `error.details.reason: 'sandbox-only'`.\n   *\n   * Defense-in-depth for test agents (CI runners, internal QA agents,\n   * partner pre-prod environments): if the test credential leaks, blast\n   * radius is bounded to sandbox accounts. Production agents leave this\n   * unset (or `false`).\n   *\n   * Composes with `Account.sandbox` (the wire-level sandbox marker on\n   * the resolved Account record): the gate fires when `agent.sandbox_only\n   * === true AND ctx.account?.sandbox !== true`. Account-less tools\n   * (`provide_performance_feedback`, `list_creative_formats`, etc.) pass\n   * the gate — they don't operate on a specific account, so the\n   * sandbox/production axis doesn't apply.\n   *\n   * **Load-bearing pair.** For the gate to admit ANY traffic from a\n   * `sandbox_only` agent, the seller's `accounts.resolve` MUST return\n   * `sandbox: true` on the accounts that agent should reach. Adopters\n   * cloning the worked example with `sandbox_only: true` on their seed\n   * agent and a hardcoded `sandbox: true` resolver are demoware-correct;\n   * production adopters either flip the agent to `sandbox_only: false`\n   * OR have their resolver return `sandbox: true` only for actually-\n   * sandbox accounts. Mismatches between these two sides 403 every\n   * request — failure is loud, not silent.\n   *\n   * Default `false` (or undefined) — production-allowed.\n   */\n  readonly sandbox_only?: boolean;\n}\n\nconst BILLING_SUGGESTION_ORDER: readonly BuyerAgentBillingMode[] = ['operator', 'advertiser', 'agent'];\n\n/**\n * Pick the single autonomous-retry billing value exposed on\n * `BILLING_NOT_PERMITTED_FOR_AGENT.details.suggested_billing`.\n *\n * The details schema intentionally allows only one suggestion, not the\n * agent's full permitted set. Preference is the spec-discussed commercial\n * fallback order: operator > advertiser > agent.\n *\n * @public\n */\nexport function suggestBilling(\n  billingCapabilities: ReadonlySet<BuyerAgentBillingMode>,\n  rejected: BuyerAgentBillingMode\n): BuyerAgentBillingMode | undefined {\n  for (const mode of BILLING_SUGGESTION_ORDER) {\n    if (mode !== rejected && billingCapabilities.has(mode)) return mode;\n  }\n  return undefined;\n}\n\n// ---------------------------------------------------------------------------\n// Registry Protocol + factory functions\n// ---------------------------------------------------------------------------\n\n/**\n * Minimal `ResolvedAuthInfo`-shaped argument to `BuyerAgentRegistry.resolve`.\n * Defined here to break a circular dependency with `account.ts` and to keep\n * the registry surface decoupled from the legacy `ResolvedAuthInfo` shape\n * during the two-minor migration cycle.\n *\n * Stage 3 of the implementation will widen `ResolvedAuthInfo` itself with\n * the `credential` field; this interface is the registry-side contract.\n *\n * @public\n */\nexport interface BuyerAgentResolveInput {\n  /**\n   * The kind-discriminated credential proven on the request. Stage 3 of\n   * the Phase 1 implementation will populate this from the verifier\n   * (`http_sig`) or from the legacy `ResolvedAuthInfo` shape (`api_key` /\n   * `oauth`); until then, callers pass it through directly when available.\n   *\n   * When absent, the registry's `resolve` returns `null` — the legacy-\n   * shape synthesis lands in Stage 3 alongside the `ResolvedAuthInfo`\n   * migration shim, not Stage 1.\n   */\n  readonly credential?: AdcpCredential;\n\n  /**\n   * Adopter-provided extension data threaded from `authenticate()`. Populated\n   * from the `extra` field stamped on the `AuthPrincipal` returned by the\n   * `authenticate()` callback (e.g. `verifyApiKey({ verify: token => ({ ...,\n   * extra: { demo_token: token } }) })`). Forwarded to the second argument of\n   * {@link ResolveBuyerAgentByCredential} by `bearerOnly` and `mixed` factories.\n   *\n   * The full MCP `AuthInfo.extra` bag is forwarded here — it includes JWT\n   * claims (if `verifyBearer` was used) and the SDK-internal `credential` key\n   * alongside adopter-stamped fields. Do not use reserved key names (`credential`,\n   * `iss`, `sub`, `aud`, `exp`, `iat`, `nbf`, `jti`) in the `extra` object\n   * to avoid collisions.\n   */\n  readonly extra?: Record<string, unknown>;\n\n  /**\n   * Raw AdCP request parameters for the current tool call, after transport\n   * decoding and before handler dispatch. Registry implementations normally\n   * key only on `credential`, but compliance-controller overlays may need the\n   * request `context.session_id` or `account` to resolve a scoped test\n   * commercial state for this request.\n   */\n  readonly input?: Record<string, unknown>;\n}\n\n/**\n * Buyer-agent registry — durable identity surface called once per request\n * before `accounts.resolve`. Adopters construct via one of the factory\n * functions; the resulting object exposes a single `resolve` method the\n * framework dispatcher invokes.\n *\n * Three implementer postures, encoded at construction:\n *\n * - {@link signingOnly} — production target. Bearer/API-key/OAuth requests\n *   refused at the registry layer; signed requests resolve via\n *   `resolveByAgentUrl` against the verified `credential.agent_url`.\n * - {@link bearerOnly} — pre-trust beta. No signature support; bearer-shaped\n *   credentials resolve via `resolveByCredential` against the seller's\n *   onboarding ledger.\n * - {@link mixed} — transition. Both paths active. Signed traffic resolves\n *   cryptographically; bearer falls through to the legacy key table.\n *\n * The factories produce a `BuyerAgentRegistry` whose `resolve` method\n * routes by `credential.kind` and returns `null` when the credential is\n * not honored by the configured posture (e.g., bearer credential against\n * a `signingOnly` registry → `null`, framework rejects the request).\n *\n * @public\n */\nexport interface BuyerAgentRegistry {\n  /**\n   * Resolve a request's credential to a buyer-agent record.\n   *\n   * Returns `null` when the credential is not recognized OR when the\n   * configured posture rejects the credential's kind (e.g., `bearerOnly`\n   * registry receiving an `http_sig` credential).\n   *\n   * Throws when the underlying lookup fails (DB outage, identity-provider\n   * 5xx). Framework projects the throw to `SERVICE_UNAVAILABLE` so the\n   * buyer can retry; the inner error is logged server-side.\n   */\n  resolve(authInfo: BuyerAgentResolveInput): Promise<BuyerAgent | null>;\n}\n\n/**\n * Resolver function type for the signed path. Receives the\n * cryptographically-verified `agent_url` from the request signature and\n * returns the seller's record (or `null` for unrecognized agents).\n *\n * @public\n */\nexport type ResolveBuyerAgentByAgentUrl = (agent_url: string) => Promise<BuyerAgent | null>;\n\n/**\n * Resolver function type for the bearer/API-key/OAuth path. Receives the\n * raw credential and (optionally) adopter-provided extension data, and\n * returns the seller's record (or `null` for unrecognized credentials).\n *\n * **Implementations MUST switch on `credential.kind`** and reject (return\n * `null`) on any kind they don't explicitly recognize. A naive\n * `WHERE token = $1` lookup against an api-key table would otherwise mis-\n * resolve when handed an `http_sig` credential whose `keyid` happens to\n * collide with an existing api-key value — the credential variants share\n * no key namespace, and the registry MUST NOT bridge them.\n *\n * **Credential exposure.** This callback receives unredacted credential\n * payloads (token, key_id, client_id). Adopters MUST NOT log raw credential\n * values AND MUST NOT include them in thrown `Error` messages — the\n * framework projects `err.message` into `error.details.reason` on the wire\n * when `exposeErrorDetails` is on (default: non-production). Throw with\n * a generic message and log the credential separately if you need it for\n * server-side debugging. The framework redacts credential payloads in any\n * log line emitted from registry-resolution code (Stage 4); adopter\n * implementations are expected to do the same (or to use prepared-statement\n * parameters that don't log).\n *\n * **`extra` — adopter extension data.** When the `authenticate()` callback\n * stamps an `extra` field on the returned `AuthPrincipal` (e.g.\n * `verifyApiKey({ verify: token => ({ principal, extra: { demo_token: token } }) })`),\n * the framework propagates that value through `ResolvedAuthInfo.extra` to\n * this second argument. Use it to carry pre-hash data your authenticator\n * already derived (prefix patterns, tenant IDs, test-kit flags) that you\n * can't recover from the hashed `key_id`. Apply the same care as for\n * `credential`: do not log raw values from `extra` or include them in\n * thrown `Error` messages.\n *\n * Existing single-argument implementations `(credential) => ...` satisfy\n * this type — the second argument is optional.\n *\n * @public\n */\nexport type ResolveBuyerAgentByCredential = (\n  credential: AdcpCredential,\n  extra?: Record<string, unknown>,\n  input?: Record<string, unknown>\n) => Promise<BuyerAgent | null>;\n\n/**\n * Belt-and-suspenders check that an `http_sig` credential carries a non-\n * empty `agent_url`. A misbehaving authenticator could produce `kind:\n * 'http_sig'` without populating the verified URL — without this guard, the\n * registry would pass `undefined` (or `''`) to the adopter's resolver and\n * silently get back `null`. Caller is responsible for the kind dispatch;\n * this function only validates the http_sig payload shape.\n */\nfunction isVerifiedHttpSigPayload(credential: { agent_url?: string }): credential is { agent_url: string } {\n  return typeof credential.agent_url === 'string' && credential.agent_url.length > 0;\n}\n\n/**\n * Module-private symbol used as a provenance brand on verifier-produced\n * `http_sig` credentials. NOT registered via `Symbol.for(...)` — code\n * outside this module cannot synthesize the symbol value, which is what\n * makes it a usable provenance check.\n *\n * The brand is non-enumerable so it's invisible to `JSON.stringify`,\n * `Object.keys`, spread, and structured-clone — meaning a credential\n * that crosses a serialization boundary loses its brand. For the\n * security model that's correct: a hostile relay or replay strips the\n * brand and the registry refuses to treat the credential as verified.\n *\n * Only `markVerifiedHttpSig` (called by the framework's signature\n * verifier in `src/lib/server/auth-signature.ts`) attaches the brand.\n * Custom `authenticate` callbacks that synthesize a literal-shape\n * `{ kind: 'http_sig', ... }` credential will NOT carry the brand —\n * `signingOnly` and `mixed` registry factories reject those.\n */\nconst VERIFIED_HTTP_SIG_BRAND: unique symbol = Symbol('@adcp/sdk.verifiedHttpSig');\n\ntype VerifiedHttpSig = Extract<AdcpCredential, { kind: 'http_sig' }> & {\n  readonly [VERIFIED_HTTP_SIG_BRAND]: true;\n};\n\n/**\n * Brand an `http_sig` credential as verifier-produced. Only the framework's\n * signature verifier (`verifySignatureAsAuthenticator`) calls this; the\n * brand is the registry's proof that the credential's `agent_url` was\n * cryptographically verified per adcontextprotocol/adcp#3831.\n *\n * Returned object is a fresh shallow copy — the input is not mutated.\n *\n * @internal — exported for `auth-signature.ts` only; not part of the\n * adopter surface.\n */\nexport function markVerifiedHttpSig(\n  credential: Extract<AdcpCredential, { kind: 'http_sig' }>\n): Extract<AdcpCredential, { kind: 'http_sig' }> {\n  const branded = { ...credential };\n  Object.defineProperty(branded, VERIFIED_HTTP_SIG_BRAND, {\n    value: true,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  });\n  return branded as VerifiedHttpSig;\n}\n\n/**\n * Predicate the registry factories use to distinguish verifier-produced\n * `http_sig` credentials from literal-shape impostors. Returns true ONLY\n * when the credential was produced by the framework's signature verifier\n * (or another caller that imported the symbol from this module — there\n * are none).\n */\nfunction isVerifiedHttpSig(credential: AdcpCredential): boolean {\n  return credential.kind === 'http_sig' && (credential as Record<symbol, unknown>)[VERIFIED_HTTP_SIG_BRAND] === true;\n}\n\n/**\n * Construct a signing-only `BuyerAgentRegistry`. Bearer/API-key/OAuth\n * requests resolve to `null` (framework rejects); only signed requests\n * are honored.\n *\n * The path-of-least-resistance factory for production sellers — implement\n * one resolver, traffic that doesn't sign is automatically refused.\n *\n * @public\n */\nexport function signingOnly(opts: { resolveByAgentUrl: ResolveBuyerAgentByAgentUrl }): BuyerAgentRegistry {\n  if (typeof opts.resolveByAgentUrl !== 'function') {\n    throw new TypeError('BuyerAgentRegistry.signingOnly: resolveByAgentUrl must be a function');\n  }\n  const resolveByAgentUrl = opts.resolveByAgentUrl;\n  return {\n    async resolve(authInfo) {\n      const credential = authInfo.credential;\n      if (credential === undefined || credential.kind !== 'http_sig') return null;\n      // Reject literal-shape http_sig credentials: only the framework's\n      // signature verifier brands a credential as verified. A custom\n      // `authenticate` callback that synthesizes `{ kind: 'http_sig', ... }`\n      // from arbitrary data would otherwise be routed as if cryptographically\n      // verified — the brand check closes that forgery vector.\n      if (!isVerifiedHttpSig(credential)) return null;\n      if (!isVerifiedHttpSigPayload(credential)) return null;\n      return resolveByAgentUrl(credential.agent_url);\n    },\n  };\n}\n\n/**\n * Construct a bearer-only `BuyerAgentRegistry`. Signed requests still\n * authenticate via the existing signature-verifier surface, but the\n * registry resolves all credential kinds via `resolveByCredential` against\n * the seller's onboarding ledger — useful in pre-trust-beta deployments\n * where the seller maintains a credential→agent table out-of-band.\n *\n * @public\n */\nexport function bearerOnly(opts: { resolveByCredential: ResolveBuyerAgentByCredential }): BuyerAgentRegistry {\n  if (typeof opts.resolveByCredential !== 'function') {\n    throw new TypeError('BuyerAgentRegistry.bearerOnly: resolveByCredential must be a function');\n  }\n  const resolveByCredential = opts.resolveByCredential;\n  return {\n    async resolve(authInfo) {\n      const credential = authInfo.credential;\n      const extra = authInfo.extra;\n      if (credential === undefined) return null;\n      return resolveByCredential(credential, extra, authInfo.input);\n    },\n  };\n}\n\n/**\n * Construct a mixed-mode `BuyerAgentRegistry` that supports both signed and\n * bearer/OAuth/API-key credentials. Signed traffic resolves through\n * `resolveByAgentUrl` against the verified `credential.agent_url`; non-\n * signed credentials fall through to `resolveByCredential`.\n *\n * Framework prefers the signed path: when both an `Authorization: Bearer`\n * and a valid `Signature: ...` are present on the same request, the\n * `http_sig` credential variant is what reaches `resolve`, and only\n * `resolveByAgentUrl` is invoked. The bearer path is never consulted on\n * signed traffic.\n *\n * @public\n */\nexport function mixed(opts: {\n  resolveByAgentUrl: ResolveBuyerAgentByAgentUrl;\n  resolveByCredential: ResolveBuyerAgentByCredential;\n}): BuyerAgentRegistry {\n  if (typeof opts.resolveByAgentUrl !== 'function') {\n    throw new TypeError('BuyerAgentRegistry.mixed: resolveByAgentUrl must be a function');\n  }\n  if (typeof opts.resolveByCredential !== 'function') {\n    throw new TypeError('BuyerAgentRegistry.mixed: resolveByCredential must be a function');\n  }\n  const resolveByAgentUrl = opts.resolveByAgentUrl;\n  const resolveByCredential = opts.resolveByCredential;\n  return {\n    async resolve(authInfo) {\n      const credential = authInfo.credential;\n      const extra = authInfo.extra;\n      if (credential === undefined) return null;\n      if (credential.kind === 'http_sig') {\n        // Same forgery clamp as `signingOnly`: only verifier-branded\n        // http_sig credentials route through the signed path.\n        if (!isVerifiedHttpSig(credential)) return null;\n        // Reject a malformed `http_sig` credential here rather than falling\n        // through to resolveByCredential. Otherwise `mixed` would be strictly\n        // weaker than signingOnly: an authenticator that produces an\n        // http_sig-shaped credential without a verified agent_url could\n        // bypass signed-path enforcement by routing through the bearer table.\n        if (!isVerifiedHttpSigPayload(credential)) return null;\n        return resolveByAgentUrl(credential.agent_url);\n      }\n      return resolveByCredential(credential, extra, authInfo.input);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Caching decorator — Phase 1 Stage 5 of #1269\n// ---------------------------------------------------------------------------\n\n/**\n * Options for {@link cached}.\n *\n * @public\n */\nexport interface BuyerAgentCacheOptions {\n  /**\n   * TTL (seconds) for successful resolutions. Default: 60.\n   *\n   * Adopters whose registry sits in front of a Postgres / external lookup\n   * benefit from caching for the request lifecycle of a single buyer's\n   * traffic burst. Long TTLs (several minutes) are appropriate for\n   * stable agent records; short TTLs (a few seconds) for rapidly-mutating\n   * relationships (suspension flags, billing-capability changes).\n   *\n   * Status changes propagate within `ttlSeconds` of the seller flipping\n   * the agent's row in their store — adopters needing instant\n   * propagation either set a short TTL or invalidate the cache out-of-\n   * band when they mutate.\n   */\n  ttlSeconds?: number;\n\n  /**\n   * TTL (seconds) for `null` returns (negative cache). Default: 0\n   * (don't cache nulls). A freshly onboarded agent is recognized within\n   * one request when nulls aren't cached; sellers willing to delay\n   * recognition by N seconds in exchange for fewer DB hits set this to\n   * a small positive value.\n   *\n   * **Timing-oracle note.** When null caching is enabled, an\n   * unauthenticated prober comparing hit vs. miss latency on null\n   * returns can infer \"this credential was probed recently.\" Pair with\n   * rate-limiting at the edge if your deployment runs in a hostile\n   * environment. The default (0) avoids the oracle entirely.\n   */\n  cacheNullsTtlSeconds?: number;\n\n  /**\n   * Maximum cache entries before LRU eviction. Default: 10000.\n   * The cache is bounded so a malicious or misconfigured caller spamming\n   * unique credentials (e.g., random api keys probing the seller's\n   * onboarding surface) can't exhaust memory.\n   */\n  maxSize?: number;\n\n  /** Override clock for deterministic tests. Returns ms since epoch. */\n  now?: () => number;\n}\n\ninterface CacheEntry {\n  value: BuyerAgent | null;\n  expiresAtMs: number;\n}\n\n/**\n * Cached registry surface. Strict superset of {@link BuyerAgentRegistry}\n * with explicit invalidation hooks adopters call when they mutate the\n * backing record (status flip, billing-capability change). Without\n * `invalidate`, adopters could only purge stale entries by waiting for\n * `ttlSeconds` to expire — for status changes that's exactly the\n * window during which a now-suspended agent retains access.\n *\n * `BuyerAgentRegistry.cached(...)` returns this richer type so adopters\n * can hold a reference and call the invalidation methods directly.\n *\n * @public\n */\nexport interface CachedBuyerAgentRegistry extends BuyerAgentRegistry {\n  /**\n   * Drop the cache entry for a single credential. No-op when the\n   * credential isn't currently cached. Use this when the agent's\n   * record is mutated in your backing store so the next request\n   * re-resolves rather than serving the stale entry.\n   */\n  invalidate(credential: AdcpCredential): void;\n\n  /**\n   * Drop all cached entries. Use on bulk record mutations (onboarding-\n   * record migration, daily reset) or test-environment cleanup.\n   */\n  clear(): void;\n}\n\n/**\n * Compute a cache key from a credential. Returns null when the\n * credential is undefined — uncacheable, falls through to the inner\n * registry on each call. Keys are namespaced by kind so an api_key\n * `key_id` value can never collide with an http_sig `keyid` value or\n * an oauth `client_id`. Note that `key_id` is already a stable hash\n * (Stage 3); using it as a cache key is safe.\n */\nfunction cacheKeyForCredential(credential: AdcpCredential | undefined): string | null {\n  if (credential === undefined) return null;\n  switch (credential.kind) {\n    case 'http_sig':\n      return `http_sig:${credential.agent_url}`;\n    case 'api_key':\n      return `api_key:${credential.key_id}`;\n    case 'oauth':\n      return `oauth:${credential.client_id}`;\n    default: {\n      // Exhaustiveness check — adding a new credential kind without\n      // updating this switch produces a compile error here, not a\n      // runtime cache-miss bug.\n      const _exhaustive: never = credential;\n      void _exhaustive;\n      return null;\n    }\n  }\n}\n\n/**\n * Wrap a {@link BuyerAgentRegistry} with TTL-based result caching and\n * concurrent-resolve coalescing. Adopters whose `resolveByAgentUrl` /\n * `resolveByCredential` hit a database or external service compose\n * the cache via:\n *\n * ```ts\n * const registry = BuyerAgentRegistry.cached(\n *   BuyerAgentRegistry.signingOnly({\n *     resolveByAgentUrl: async url => db.findBuyerAgent(url),\n *   }),\n *   { ttlSeconds: 60 }\n * );\n * ```\n *\n * Cache properties:\n * - **TTL-bounded.** Entries expire after `ttlSeconds` (default 60).\n *   Negative cache (null returns) is opt-in via `cacheNullsTtlSeconds`.\n * - **LRU-evicted.** Bounded to `maxSize` entries (default 10000).\n *   Oldest-accessed entry evicts on overflow.\n * - **Concurrent-resolve coalesced.** N parallel `resolve()` calls on\n *   the same key produce ONE upstream invocation. Subsequent callers\n *   await the in-flight promise — important when the seller front-ends\n *   a slow upstream and a buyer burst arrives.\n * - **Per-kind cache keys.** Keys are namespaced (`http_sig:`,\n *   `api_key:`, `oauth:`) so cross-kind collisions cannot leak an agent\n *   resolved through one credential type to a different type.\n * - **`extra` is not part of the cache key.** The cache keys on credential\n *   identity only. Two requests with the same credential but different\n *   `authInfo.extra` content return the same cached result. This is the\n *   right behaviour when `extra` carries pre-hash data derived from the\n *   same token (the motivating use-case), but can be surprising if you\n *   put per-request session context in `extra`. Set a short `ttlSeconds`\n *   or skip the cache decorator if your resolution is sensitive to `extra`\n *   variance across requests with the same credential.\n * - **Skips uncacheable inputs.** When the credential is undefined,\n *   `resolve()` falls through to the inner registry on each call —\n *   adopters wiring custom auth without `credential` synthesis (Stage 3\n *   migration cycle) see no behavior change.\n * - **Explicit invalidation.** Returns a {@link CachedBuyerAgentRegistry}\n *   with `.invalidate(credential)` and `.clear()` methods. Call\n *   `invalidate` when you mutate an agent's record (status flip,\n *   billing-capability change) so the next request re-resolves rather\n *   than serving the stale entry. Without this, the stale-status window\n *   is bounded by `ttlSeconds` — a now-suspended agent retains access\n *   for up to that long.\n *\n * Mirrors the `AsyncCachingJwksResolver` over `JwksResolver` pattern\n * already in `src/lib/signing/`.\n *\n * @public\n */\nexport function cached(inner: BuyerAgentRegistry, options: BuyerAgentCacheOptions = {}): CachedBuyerAgentRegistry {\n  if (typeof inner !== 'object' || inner === null || typeof inner.resolve !== 'function') {\n    throw new TypeError('BuyerAgentRegistry.cached: `inner` must be a BuyerAgentRegistry');\n  }\n  const ttlMs = (options.ttlSeconds ?? 60) * 1000;\n  const nullsTtlMs = (options.cacheNullsTtlSeconds ?? 0) * 1000;\n  const maxSize = options.maxSize ?? 10000;\n  const now = options.now ?? Date.now;\n\n  if (ttlMs <= 0) throw new RangeError('BuyerAgentRegistry.cached: ttlSeconds must be > 0');\n  if (nullsTtlMs < 0) throw new RangeError('BuyerAgentRegistry.cached: cacheNullsTtlSeconds must be >= 0');\n  if (maxSize < 1) throw new RangeError('BuyerAgentRegistry.cached: maxSize must be >= 1');\n\n  // Map iteration order is insertion order, so re-inserting on hit\n  // gives us LRU-on-access semantics for free.\n  const cache = new Map<string, CacheEntry>();\n  const inFlight = new Map<string, Promise<BuyerAgent | null>>();\n\n  return {\n    async resolve(authInfo) {\n      const key = cacheKeyForCredential(authInfo.credential);\n      if (key === null) {\n        // Uncacheable input — pass through. Adopters wiring custom\n        // auth that hasn't migrated to `credential` synthesis see\n        // every call hit the inner resolver.\n        return inner.resolve(authInfo);\n      }\n\n      const entry = cache.get(key);\n      if (entry !== undefined && now() < entry.expiresAtMs) {\n        // LRU touch: re-insert so this entry becomes the most-recent.\n        cache.delete(key);\n        cache.set(key, entry);\n        return entry.value;\n      }\n      if (entry !== undefined) {\n        // Expired — drop before refetch.\n        cache.delete(key);\n      }\n\n      // Coalesce concurrent resolves: subsequent callers on the same\n      // key await the existing in-flight promise rather than firing\n      // their own upstream lookup. If the upstream rejects, all\n      // coalesced callers see the same rejection; the `finally` below\n      // releases `inFlight` so the next caller retries upstream\n      // (rejected promises do NOT poison the cache — `cache.set`\n      // inside the IIFE is unreachable on rejection).\n      const existing = inFlight.get(key);\n      if (existing !== undefined) return existing;\n\n      const promise = (async () => {\n        const value = await inner.resolve(authInfo);\n        const entryTtlMs = value === null ? nullsTtlMs : ttlMs;\n        if (entryTtlMs > 0) {\n          // Defense-in-depth: freeze the resolved record before\n          // sharing across coalesced callers. The dispatcher seam\n          // also freezes per-request (Stage 2), but freezing here\n          // makes the cached-shared-reference invariant load-\n          // bearing rather than coincidental — a future caller\n          // mutating `BuyerAgent.status` would otherwise corrupt\n          // every other cached-hit consumer's view.\n          if (value !== null && !Object.isFrozen(value)) {\n            if (value.billing_capabilities instanceof Set) {\n              Object.freeze(value.billing_capabilities);\n            }\n            Object.freeze(value);\n          }\n          cache.set(key, { value, expiresAtMs: now() + entryTtlMs });\n          while (cache.size > maxSize) {\n            const oldestKey = cache.keys().next().value;\n            if (oldestKey === undefined) break;\n            cache.delete(oldestKey);\n          }\n        }\n        return value;\n      })();\n      inFlight.set(key, promise);\n      try {\n        return await promise;\n      } finally {\n        inFlight.delete(key);\n      }\n    },\n\n    invalidate(credential) {\n      const key = cacheKeyForCredential(credential);\n      if (key !== null) cache.delete(key);\n    },\n\n    clear() {\n      cache.clear();\n    },\n  };\n}\n\n/**\n * Factory namespace mirroring the documented surface from #1269. Adopters\n * import the namespace and call `BuyerAgentRegistry.signingOnly({...})`,\n * etc. Individual functions are also exported above for direct use.\n *\n * @public\n */\nexport const BuyerAgentRegistry = {\n  signingOnly,\n  bearerOnly,\n  mixed,\n  cached,\n  suggestBilling,\n};\n"],"mappings":"AAyMA,MAAM,2BAA6D,CAAC,YAAY,cAAc,OAAO;AAY9F,SAAS,eACd,qBACA,UACmC;AACnC,aAAW,QAAQ,0BAA0B;AAC3C,QAAI,SAAS,YAAY,oBAAoB,IAAI,IAAI,EAAG,QAAO;AAAA,EACjE;AACA,SAAO;AACT;AA2JA,SAAS,yBAAyB,YAAyE;AACzG,SAAO,OAAO,WAAW,cAAc,YAAY,WAAW,UAAU,SAAS;AACnF;AAoBA,MAAM,0BAAyC,uBAAO,2BAA2B;AAiB1E,SAAS,oBACd,YAC+C;AAC/C,QAAM,UAAU,EAAE,GAAG,WAAW;AAChC,SAAO,eAAe,SAAS,yBAAyB;AAAA,IACtD,OAAO;AAAA,IACP,YAAY;AAAA,IACZ,cAAc;AAAA,IACd,UAAU;AAAA,EACZ,CAAC;AACD,SAAO;AACT;AASA,SAAS,kBAAkB,YAAqC;AAC9D,SAAO,WAAW,SAAS,cAAe,WAAuC,uBAAuB,MAAM;AAChH;AAYO,SAAS,YAAY,MAA8E;AACxG,MAAI,OAAO,KAAK,sBAAsB,YAAY;AAChD,UAAM,IAAI,UAAU,sEAAsE;AAAA,EAC5F;AACA,QAAM,oBAAoB,KAAK;AAC/B,SAAO;AAAA,IACL,MAAM,QAAQ,UAAU;AACtB,YAAM,aAAa,SAAS;AAC5B,UAAI,eAAe,UAAa,WAAW,SAAS,WAAY,QAAO;AAMvE,UAAI,CAAC,kBAAkB,UAAU,EAAG,QAAO;AAC3C,UAAI,CAAC,yBAAyB,UAAU,EAAG,QAAO;AAClD,aAAO,kBAAkB,WAAW,SAAS;AAAA,IAC/C;AAAA,EACF;AACF;AAWO,SAAS,WAAW,MAAkF;AAC3G,MAAI,OAAO,KAAK,wBAAwB,YAAY;AAClD,UAAM,IAAI,UAAU,uEAAuE;AAAA,EAC7F;AACA,QAAM,sBAAsB,KAAK;AACjC,SAAO;AAAA,IACL,MAAM,QAAQ,UAAU;AACtB,YAAM,aAAa,SAAS;AAC5B,YAAM,QAAQ,SAAS;AACvB,UAAI,eAAe,OAAW,QAAO;AACrC,aAAO,oBAAoB,YAAY,OAAO,SAAS,KAAK;AAAA,IAC9D;AAAA,EACF;AACF;AAgBO,SAAS,MAAM,MAGC;AACrB,MAAI,OAAO,KAAK,sBAAsB,YAAY;AAChD,UAAM,IAAI,UAAU,gEAAgE;AAAA,EACtF;AACA,MAAI,OAAO,KAAK,wBAAwB,YAAY;AAClD,UAAM,IAAI,UAAU,kEAAkE;AAAA,EACxF;AACA,QAAM,oBAAoB,KAAK;AAC/B,QAAM,sBAAsB,KAAK;AACjC,SAAO;AAAA,IACL,MAAM,QAAQ,UAAU;AACtB,YAAM,aAAa,SAAS;AAC5B,YAAM,QAAQ,SAAS;AACvB,UAAI,eAAe,OAAW,QAAO;AACrC,UAAI,WAAW,SAAS,YAAY;AAGlC,YAAI,CAAC,kBAAkB,UAAU,EAAG,QAAO;AAM3C,YAAI,CAAC,yBAAyB,UAAU,EAAG,QAAO;AAClD,eAAO,kBAAkB,WAAW,SAAS;AAAA,MAC/C;AACA,aAAO,oBAAoB,YAAY,OAAO,SAAS,KAAK;AAAA,IAC9D;AAAA,EACF;AACF;AAiGA,SAAS,sBAAsB,YAAuD;AACpF,MAAI,eAAe,OAAW,QAAO;AACrC,UAAQ,WAAW,MAAM;AAAA,IACvB,KAAK;AACH,aAAO,YAAY,WAAW,SAAS;AAAA,IACzC,KAAK;AACH,aAAO,WAAW,WAAW,MAAM;AAAA,IACrC,KAAK;AACH,aAAO,SAAS,WAAW,SAAS;AAAA,IACtC,SAAS;AAIP,YAAM,cAAqB;AAC3B,WAAK;AACL,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAsDO,SAAS,OAAO,OAA2B,UAAkC,CAAC,GAA6B;AAChH,MAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,OAAO,MAAM,YAAY,YAAY;AACtF,UAAM,IAAI,UAAU,iEAAiE;AAAA,EACvF;AACA,QAAM,SAAS,QAAQ,cAAc,MAAM;AAC3C,QAAM,cAAc,QAAQ,wBAAwB,KAAK;AACzD,QAAM,UAAU,QAAQ,WAAW;AACnC,QAAM,MAAM,QAAQ,OAAO,KAAK;AAEhC,MAAI,SAAS,EAAG,OAAM,IAAI,WAAW,mDAAmD;AACxF,MAAI,aAAa,EAAG,OAAM,IAAI,WAAW,8DAA8D;AACvG,MAAI,UAAU,EAAG,OAAM,IAAI,WAAW,iDAAiD;AAIvF,QAAM,QAAQ,oBAAI,IAAwB;AAC1C,QAAM,WAAW,oBAAI,IAAwC;AAE7D,SAAO;AAAA,IACL,MAAM,QAAQ,UAAU;AACtB,YAAM,MAAM,sBAAsB,SAAS,UAAU;AACrD,UAAI,QAAQ,MAAM;AAIhB,eAAO,MAAM,QAAQ,QAAQ;AAAA,MAC/B;AAEA,YAAM,QAAQ,MAAM,IAAI,GAAG;AAC3B,UAAI,UAAU,UAAa,IAAI,IAAI,MAAM,aAAa;AAEpD,cAAM,OAAO,GAAG;AAChB,cAAM,IAAI,KAAK,KAAK;AACpB,eAAO,MAAM;AAAA,MACf;AACA,UAAI,UAAU,QAAW;AAEvB,cAAM,OAAO,GAAG;AAAA,MAClB;AASA,YAAM,WAAW,SAAS,IAAI,GAAG;AACjC,UAAI,aAAa,OAAW,QAAO;AAEnC,YAAM,WAAW,YAAY;AAC3B,cAAM,QAAQ,MAAM,MAAM,QAAQ,QAAQ;AAC1C,cAAM,aAAa,UAAU,OAAO,aAAa;AACjD,YAAI,aAAa,GAAG;AAQlB,cAAI,UAAU,QAAQ,CAAC,OAAO,SAAS,KAAK,GAAG;AAC7C,gBAAI,MAAM,gCAAgC,KAAK;AAC7C,qBAAO,OAAO,MAAM,oBAAoB;AAAA,YAC1C;AACA,mBAAO,OAAO,KAAK;AAAA,UACrB;AACA,gBAAM,IAAI,KAAK,EAAE,OAAO,aAAa,IAAI,IAAI,WAAW,CAAC;AACzD,iBAAO,MAAM,OAAO,SAAS;AAC3B,kBAAM,YAAY,MAAM,KAAK,EAAE,KAAK,EAAE;AACtC,gBAAI,cAAc,OAAW;AAC7B,kBAAM,OAAO,SAAS;AAAA,UACxB;AAAA,QACF;AACA,eAAO;AAAA,MACT,GAAG;AACH,eAAS,IAAI,KAAK,OAAO;AACzB,UAAI;AACF,eAAO,MAAM;AAAA,MACf,UAAE;AACA,iBAAS,OAAO,GAAG;AAAA,MACrB;AAAA,IACF;AAAA,IAEA,WAAW,YAAY;AACrB,YAAM,MAAM,sBAAsB,UAAU;AAC5C,UAAI,QAAQ,KAAM,OAAM,OAAO,GAAG;AAAA,IACpC;AAAA,IAEA,QAAQ;AACN,YAAM,MAAM;AAAA,IACd;AAAA,EACF;AACF;AASO,MAAM,qBAAqB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;","names":[]}

package/dist/lib/server/decisioning/capabilities.mjs

@@ -1,9 +1,3 @@
-import { fileURLToPath as __adcpFileURLToPath } from 'node:url';
-import { dirname as __adcpDirname } from 'node:path';
-import { createRequire as __adcpCreateRequire } from 'node:module';
-const __filename = __adcpFileURLToPath(import.meta.url);
-const __dirname = __adcpDirname(__filename);
-const require = __adcpCreateRequire(import.meta.url);
 const LEGACY_POSTAL_SYSTEMS = {
   us_zip: { country: "US", system: "zip" },
   us_zip_plus_four: { country: "US", system: "zip_plus_four" },

package/dist/lib/server/decisioning/capabilities.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/server/decisioning/capabilities.ts"],"sourcesContent":["/**\n * DecisioningCapabilities — single source of truth for `get_adcp_capabilities`\n * response and any admin UI surface a host wants to render.\n *\n * Adopters declare once. Framework wires the wire-protocol response;\n * adopters' admin tools (or the SDK CLI's `validate_platform_config`) consume\n * the same dataclass so there's no drift between \"what the agent says it\n * supports\" and \"what it actually does.\"\n *\n * Status: Preview / 6.0.\n *\n * @public\n */\n\nimport type { ZodSchema } from 'zod';\nimport type {\n  AdCPSpecialism,\n  MediaChannel,\n  PaymentTerms,\n  PricingModel,\n  GetAdCPCapabilitiesResponse,\n  PostalAreaSupport,\n} from '../../types/tools.generated';\nimport type { ProductMetricOptimizationLike } from '../../utils/capability-rollups';\nimport type { MediaBuyFeatures, AccountCapabilities, CreativeCapabilities } from '../../utils/capabilities';\nimport type { AdcpCapabilitiesOverrides } from '../create-adcp-server';\n\n/**\n * Pre-resolved alias for the wire `media_buy` block. Used as the projection\n * source for the five `media_buy.*` capability fields below so each typed\n * field references a single resolved shape instead of re-walking the\n * `GetAdCPCapabilitiesResponse` type graph independently. Without the\n * alias, `strict + skipLibCheck:false` adopters hit the TS instantiation\n * budget on the published `.d.ts` and tsc OOMs.\n */\ntype _MediaBuyCapabilities = NonNullable<GetAdCPCapabilitiesResponse['media_buy']>;\ntype _MediaBuyTargetingCapabilities = NonNullable<NonNullable<_MediaBuyCapabilities['execution']>['targeting']>;\ntype _ComplianceTestingScenario = NonNullable<\n  NonNullable<GetAdCPCapabilitiesResponse['compliance_testing']>['scenarios']\n>[number];\n\nexport interface DecisioningCapabilities<TConfig = unknown> {\n  /**\n   * Specialisms claimed; framework type-checks these against implemented platform\n   * interfaces. Arrays are `readonly` so adopters can declare with `as const`\n   * (load-bearing for the `RequiredPlatformsFor<S>` compile-time gate).\n   */\n  specialisms: readonly AdCPSpecialism[];\n\n  /**\n   * Creative agents this seller composes with. Framework fetches format catalogs\n   * from each (1h cache) and unions them on `list_creative_formats`. Self-hosting\n   * sellers point at their own `agent_url`; framework calls into their\n   * `CreativePlatform.listFormats()` locally instead of HTTP-fetching.\n   *\n   * `format_ids` filter (optional) subsets a single creative agent's catalog.\n   * Useful when a creative agent hosts 50 formats but this seller only accepts\n   * 10 of them. Filter scope is per-creative-agent: `[{ agent_url: A, format_ids: ['x'] }, { agent_url: B }]`\n   * means \"from A only format x; from B all formats.\"\n   *\n   * Omit for signals-only platforms (`signal-marketplace`, `signal-owned`) — they\n   * sell audience data access, not media inventory, and don't compose with creative agents.\n   */\n  creative_agents?: readonly CreativeAgentRef[];\n\n  /**\n   * Channels this platform sells.\n   *\n   * Omit for non-media-buy platforms — they don't sell ad inventory and have no\n   * channels to declare. Applies to signals (`signal-marketplace`, `signal-owned`),\n   * governance (`governance-spend-authority`, `governance-delivery-monitor`,\n   * `property-lists`, `collection-lists`, `content-standards`), creative-only\n   * (`creative-ad-server`, `creative-template`, `creative-generative`), and\n   * brand (`brand-rights`) platforms.\n   *\n   * **Required at runtime for media-buy platforms.** `validatePlatform` (called\n   * by `createAdcpServerFromPlatform`) throws `PlatformConfigError` when any\n   * `sales-*` specialism is claimed and this field is absent.\n   */\n  channels?: readonly MediaChannel[];\n\n  /**\n   * Pricing models this platform supports.\n   *\n   * Omit for non-media-buy platforms — they don't sell ad inventory and have no\n   * channel-level pricing to declare. For signals platforms specifically, pricing\n   * is declared per-signal in the signal descriptor's `pricing_options[]` instead.\n   * Same non-media-buy specialism set as `channels` above.\n   *\n   * **Required at runtime for media-buy platforms.** `validatePlatform` (called\n   * by `createAdcpServerFromPlatform`) throws `PlatformConfigError` when any\n   * `sales-*` specialism is claimed and this field is absent.\n   */\n  pricingModels?: readonly PricingModel[];\n\n  /** Targeting capabilities. Optional — framework infers reasonable defaults if omitted. */\n  targeting?: TargetingCapabilities;\n\n  /** Reporting capabilities. Optional — framework infers reasonable defaults if omitted. */\n  reporting?: ReportingCapabilities;\n\n  /**\n   * Audience-matching capabilities — projected onto\n   * `get_adcp_capabilities.media_buy.audience_targeting`. Required for\n   * audience-sync adopters (CRM-list adopters that accept hashed\n   * identifiers + UID types) so buyers know which identifier shapes\n   * the platform will match against and what minimum audience size /\n   * matching latency to expect. Omit when the platform doesn't accept\n   * external audience uploads.\n   *\n   * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.audience_targeting`.\n   */\n  audience_targeting?: NonNullable<_MediaBuyCapabilities['audience_targeting']>;\n\n  /**\n   * Conversion-tracking capabilities — projected onto\n   * `get_adcp_capabilities.media_buy.conversion_tracking`. Required for\n   * adopters that accept conversion events via `sync_event_sources` /\n   * `log_event` so buyers know which event types, action sources,\n   * attribution windows, and identifier shapes the platform supports.\n   * Omit when the platform doesn't track conversions.\n   *\n   * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.conversion_tracking`.\n   */\n  conversion_tracking?: NonNullable<_MediaBuyCapabilities['conversion_tracking']>;\n\n  /**\n   * Content-standards capabilities — projected onto\n   * `get_adcp_capabilities.media_buy.content_standards`. Required for\n   * adopters claiming the `content-standards` specialism so buyers know\n   * whether the platform runs local evaluation, which channels it\n   * covers, and whether it supports webhook artifact delivery. Omit\n   * when the platform doesn't ship content-standards artifacts.\n   *\n   * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.content_standards`.\n   */\n  content_standards?: NonNullable<_MediaBuyCapabilities['content_standards']>;\n\n  /**\n   * Seller-level rollup of optimization metrics — projected onto\n   * `get_adcp_capabilities.media_buy.supported_optimization_metrics`.\n   * Added in AdCP 3.1 (adcp#4669). The array union of every product's\n   * `metric_optimization.supported_metrics`. Storyboard runners gate\n   * `metric_optimization`-using scenarios on this field; declaring it\n   * gives buyers an upfront signal of which optimization metrics the\n   * seller can compute against (clicks, views, completed_views, etc.).\n   *\n   * Adopters can compute the rollup from their catalog using the\n   * exported {@link rollupOptimizationMetricsFromProducts} helper —\n   * keeps the declaration in sync with what products actually offer.\n   * Empty arrays are normalized away and the wire field is omitted; use\n   * omission to mean \"no seller-level metric rollup advertised\".\n   *\n   * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.supported_optimization_metrics`.\n   */\n  supported_optimization_metrics?: NonNullable<_MediaBuyCapabilities['supported_optimization_metrics']>;\n\n  /**\n   * Static product-metric summary used for capability rollups.\n   *\n   * When this is present and `supported_optimization_metrics` is omitted,\n   * the framework derives `media_buy.supported_optimization_metrics` as the\n   * sorted union of every product summary's\n   * `metric_optimization.supported_metrics`. Full AdCP `Product` objects work,\n   * but this field is not a general product-discovery surface; a lightweight\n   * startup summary with just the `metric_optimization` block is enough.\n   * Dynamic per-account catalogs should continue to pass an explicit\n   * `supported_optimization_metrics` override. If the derived union is empty,\n   * the framework omits `supported_optimization_metrics` from the wire\n   * capabilities response.\n   */\n  productCatalog?: ReadonlyArray<ProductMetricOptimizationLike>;\n\n  /**\n   * Frequency-cap support declaration — projected onto\n   * `get_adcp_capabilities.media_buy.frequency_capping`. Added in AdCP\n   * 3.1 (adcp#4670). Presence-only object with `supported_per_units` /\n   * `supported_window_units` sub-fields declaring which frequency-cap\n   * shapes the platform honors. Omit when the platform doesn't accept\n   * frequency caps at all; buyers will avoid the field on `pacing.*`.\n   *\n   * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.frequency_capping`.\n   */\n  frequency_capping?: NonNullable<_MediaBuyCapabilities['frequency_capping']>;\n\n  /**\n   * Whether this seller commits to the proposal lifecycle on get_products.\n   * Projected onto `get_adcp_capabilities.media_buy.supports_proposals`.\n   * Direct-buy sellers should declare `false` so proposal-only compliance\n   * storyboards are skipped; sellers with a ProposalManager are auto-derived\n   * as `true` unless they override this explicitly.\n   */\n  supportsProposals?: boolean;\n\n  /**\n   * Brand-protocol capabilities. Projected onto the wire `brand` block of\n   * `get_adcp_capabilities` (`brand: { rights, right_types, available_uses,\n   * generation_providers, description }`). The framework auto-derives\n   * `rights: true` when `BrandRightsPlatform` is supplied; adopters\n   * declare the rest (right_types they license, RightUses they support,\n   * generation providers they issue credentials for).\n   *\n   * REQUIRED when claiming the `'brand-rights'` specialism — enforced at\n   * compile-time via `RequiredCapabilitiesFor<S>`.\n   */\n  brand?: BrandCapabilities;\n\n  /**\n   * Compliance-testing capabilities. The presence of this block declares\n   * the deployment supports deterministic state-machine testing via the\n   * `comply_test_controller` wire tool. Keep this block declared when using\n   * `createAdcpServerFromPlatform(..., { complyTest })`; the framework makes\n   * live principals byte-identical to a production seller that never wired the\n   * controller by hiding this block, filtering `tools/list`, and returning MCP\n   * method-not-found for direct live calls.\n   *\n   * When this block is present, `createAdcpServerFromPlatform` REQUIRES\n   * `opts.complyTest` (the `ComplyControllerConfig` adapter set) to be\n   * supplied — claiming the capability without implementing the\n   * controller is a `PlatformConfigError` at construction.\n   *\n   * Inversely, supplying `opts.complyTest` without declaring this\n   * capability is also caught — the framework derives `scenarios` from\n   * the declared force/simulate/seed adapters and emits the discovery\n   * field on `get_adcp_capabilities` automatically for sandbox/mock\n   * principals. Live principals do not see the block.\n   */\n  compliance_testing?: ComplianceTestingCapabilities;\n\n  /**\n   * Billing parties this platform supports. `'operator'` = retail-media model\n   * (Criteo, Amazon — operator pays the publisher and bills the brand).\n   * `'agent'` = pass-through model (buyer's agent settles directly with the\n   * platform). `'advertiser'` = seller invoices the advertiser directly,\n   * bypassing operator settlement (advertiser-direct sell-side platforms where\n   * the brand is the direct contractual counterparty). Defaults to `['agent']`\n   * when omitted. To express advertiser-direct billing per account, set\n   * `billing.invoicedTo` to a `BrandReference` (the framework maps any\n   * `BrandReference` to `'advertiser'` on the wire).\n   */\n  supportedBillings?: ReadonlyArray<'operator' | 'agent' | 'advertiser'>;\n\n  /**\n   * Payment terms this platform accepts on `sync_accounts.payment_terms`.\n   * Omit to leave terms validation to `accounts.upsert` (or to accept any\n   * schema-valid value). When present, the framework rejects unsupported\n   * requested terms with `PAYMENT_TERMS_NOT_SUPPORTED` before dispatching\n   * the account entry to the adopter.\n   */\n  supportedPaymentTerms?: ReadonlyArray<PaymentTerms>;\n\n  /**\n   * If true, this platform refuses transactions without an authenticated\n   * operator principal (operator-billed retail-media). Framework emits\n   * `AUTH_REQUIRED` envelope before dispatching to the platform.\n   */\n  requireOperatorAuth?: boolean;\n\n  /**\n   * Media-buy feature flags forwarded into `get_adcp_capabilities.media_buy.features`.\n   * Adopter values serve as the base; auto-derived `audience_targeting`,\n   * `conversion_tracking`, and `content_standards` booleans take precedence\n   * for those three keys (overlaid by the framework via the per-domain\n   * `media_buy` override on the inner createAdcpServer call). Use this to\n   * declare `inlineCreativeManagement` and `propertyListFiltering` directly\n   * from `definePlatform`; declare not-supported feature blocks (e.g.\n   * `inlineCreativeManagement: false`) so the conformance runner grades\n   * them `not_applicable` instead of `fail`.\n   *\n   * Resolves the `definePlatform` passthrough gap noted in adcp-client#2199.\n   */\n  features?: Partial<MediaBuyFeatures>;\n\n  /**\n   * Creative-protocol capabilities forwarded into `get_adcp_capabilities.creative`.\n   * Use to declare `supportsCompliance`, `hasCreativeLibrary`,\n   * `supportsGeneration`, and `supportsTransformation` from `definePlatform`.\n   * Adopters that don't run a provenance-verification pipeline should\n   * declare the relevant fields as `false` so creative storyboards gate\n   * cleanly.\n   *\n   * Resolves the `definePlatform` passthrough gap noted in adcp-client#2199.\n   */\n  creative?: Partial<CreativeCapabilities>;\n\n  /**\n   * Account capabilities forwarded into `get_adcp_capabilities.account` as a\n   * base layer. The framework's existing `requireOperatorAuth` and\n   * `supportedBillings` projections overlay on top via the per-domain\n   * `account` override, so explicit projections win on those keys.\n   * `authorizationEndpoint`, `defaultBilling`, `requiredForProducts`, and\n   * `sandbox` are pure adopter-driven additions exposed through this slot.\n   *\n   * Resolves the `definePlatform` passthrough gap noted in adcp-client#2199.\n   */\n  account?: Partial<AccountCapabilities>;\n\n  /**\n   * Deep-merge overrides applied to the wire `get_adcp_capabilities`\n   * response. Use this for fields that the top-level `DecisioningCapabilities`\n   * shape doesn't model — `media_buy.propagation_surfaces`,\n   * `media_buy.measurement_terms`, `signals.discovery_modes`, etc. The\n   * framework's per-domain projections (auto-derived `media_buy`, `brand`,\n   * `account`, `compliance_testing` blocks) are merged AFTER adopter\n   * overrides, so framework-derived values remain authoritative on the keys\n   * the projection engine handles.\n   *\n   * Mirrors `AdcpCapabilitiesConfig.overrides` on the lower-level\n   * `createAdcpServer` API. Resolves the `definePlatform` passthrough gap\n   * noted in adcp-client#2199.\n   */\n  overrides?: AdcpCapabilitiesOverrides;\n\n  /**\n   * Release-precision AdCP versions this platform supports (e.g. `[\"3.0\", \"3.1\"]`).\n   * Forwarded into `get_adcp_capabilities.adcp.supported_versions`. 3.1+\n   * sellers should declare here the same release-precision strings they\n   * emit in `adcp_version` on responses; 3.0-pinned sellers can omit.\n   *\n   * Resolves the same gap previously noted for `supported_versions` —\n   * was unreachable through `definePlatform` because\n   * `CreateAdcpServerFromPlatformOptions` omits `'capabilities'` from\n   * `AdcpServerConfig`. See adcp-client#2199.\n   */\n  supported_versions?: string[];\n\n  /**\n   * Platform-specific config. Strongly typed when the adopter uses the generic.\n   * Example: `class GAM extends DecisioningPlatform<{ networkId: string }>`.\n   */\n  config: TConfig;\n\n  /**\n   * Optional Zod schema for runtime validation of `config`. When provided,\n   * framework validates at platform construction time; missing or wrong-shaped\n   * config rejects the agent at boot rather than at first request.\n   */\n  configSchema?: ZodSchema<TConfig>;\n}\n\nexport interface CreativeAgentRef {\n  agent_url: string;\n  /** Human-readable label for this creative agent. */\n  name?: string;\n  /** Optional allowlist of `format_id.id` values from THIS agent's catalog. Omit to include all. */\n  format_ids?: string[];\n}\n\n/**\n * Targeting capabilities the platform supports in `create_media_buy`. Maps\n * to AdCP `GetAdcpCapabilitiesResponse.media_buy.execution.targeting`.\n *\n * Shape converged across two independently-evolved peer codebases (Scope3\n * `agentic-adapters`, Prebid `salesagent`). Per-geo-system flags rather than\n * coarse enums because the two implementations agreed: real platforms support\n * specific geo identifier formats (Nielsen DMA, Eurostat NUTS2, US ZIP+4), not\n * abstract \"metro\" / \"postal\" categories.\n */\nexport interface TargetingCapabilities {\n  geo_countries?: boolean;\n  geo_regions?: boolean;\n\n  /** Metro / DMA identifier systems. */\n  geo_metros?: {\n    nielsen_dma?: boolean;\n    uk_itl1?: boolean;\n    uk_itl2?: boolean;\n    eurostat_nuts2?: boolean;\n  };\n\n  /**\n   * Postal-code identifier systems.\n   *\n   * AdCP 3.1.0-rc.10 prefers country-keyed arrays, e.g.\n   * `{ US: ['zip'], GB: ['outward'] }`. Deprecated country-fused booleans\n   * such as `{ us_zip: true }` remain accepted for 3.x adopters; the\n   * framework projects both forms with `normalizePostalAreaSupport()` so old\n   * and new buyers can read the capability safely during the migration.\n   */\n  geo_postal_areas?: TargetingPostalAreaSupport;\n\n  /** Geographic-proximity targeting (radius / drive-time / arbitrary geometry). */\n  geo_proximity?: {\n    radius?: boolean;\n    travel_time?: boolean;\n    geometry?: boolean;\n    transport_modes?: ReadonlyArray<'walking' | 'cycling' | 'driving' | 'public_transport'>;\n  };\n\n  /** Age-restriction targeting; `verification_methods` enumerates the assurance levels accepted. */\n  age_restriction?: {\n    supported?: boolean;\n    verification_methods?: ReadonlyArray<\n      'facial_age_estimation' | 'id_document' | 'digital_id' | 'credit_card' | 'world_id'\n    >;\n  };\n\n  device_platform?: boolean;\n  device_type?: boolean;\n  language?: boolean;\n  audience_include?: boolean;\n  audience_exclude?: boolean;\n\n  /** Keyword-targeting match types accepted on positive-match terms. */\n  keyword_targets?: {\n    supported_match_types: ReadonlyArray<'broad' | 'phrase' | 'exact'>;\n  };\n\n  /** Negative-keyword match types accepted. */\n  negative_keywords?: {\n    supported_match_types: ReadonlyArray<'broad' | 'phrase' | 'exact'>;\n  };\n}\n\nexport type TargetingPostalAreaSupport = {\n  US?: readonly ('zip' | 'zip_plus_four')[];\n  GB?: readonly ('outward' | 'full')[];\n  CA?: readonly ('fsa' | 'full')[];\n  DE?: readonly 'plz'[];\n  CH?: readonly 'plz'[];\n  AT?: readonly 'plz'[];\n  FR?: readonly 'code_postal'[];\n  AU?: readonly 'postcode'[];\n  BR?: readonly 'cep'[];\n  IN?: readonly 'pin'[];\n  ZA?: readonly 'postal_code'[];\n  /** @deprecated Use `US: ['zip']`. */\n  us_zip?: boolean;\n  /** @deprecated Use `US: ['zip_plus_four']`. */\n  us_zip_plus_four?: boolean;\n  /** @deprecated Use `GB: ['outward']`. */\n  gb_outward?: boolean;\n  /** @deprecated Use `GB: ['full']`. */\n  gb_full?: boolean;\n  /** @deprecated Use `CA: ['fsa']`. */\n  ca_fsa?: boolean;\n  /** @deprecated Use `CA: ['full']`. */\n  ca_full?: boolean;\n  /** @deprecated Use `DE: ['plz']`. */\n  de_plz?: boolean;\n  /** @deprecated Use `FR: ['code_postal']`. */\n  fr_code_postal?: boolean;\n  /** @deprecated Use `AU: ['postcode']`. */\n  au_postcode?: boolean;\n  /** @deprecated Use `CH: ['plz']`. */\n  ch_plz?: boolean;\n  /** @deprecated Use `AT: ['plz']`. */\n  at_plz?: boolean;\n  [country: `${Uppercase<string>}`]:\n    | readonly (\n        | 'zip'\n        | 'zip_plus_four'\n        | 'outward'\n        | 'full'\n        | 'fsa'\n        | 'plz'\n        | 'code_postal'\n        | 'postcode'\n        | 'cep'\n        | 'pin'\n        | 'postal_code'\n        | 'custom'\n      )[]\n    | undefined;\n};\n\nconst LEGACY_POSTAL_SYSTEMS = {\n  us_zip: { country: 'US', system: 'zip' },\n  us_zip_plus_four: { country: 'US', system: 'zip_plus_four' },\n  gb_outward: { country: 'GB', system: 'outward' },\n  gb_full: { country: 'GB', system: 'full' },\n  ca_fsa: { country: 'CA', system: 'fsa' },\n  ca_full: { country: 'CA', system: 'full' },\n  de_plz: { country: 'DE', system: 'plz' },\n  fr_code_postal: { country: 'FR', system: 'code_postal' },\n  au_postcode: { country: 'AU', system: 'postcode' },\n  ch_plz: { country: 'CH', system: 'plz' },\n  at_plz: { country: 'AT', system: 'plz' },\n} as const;\n\nconst LEGACY_POSTAL_BY_COUNTRY_SYSTEM = new Map(\n  Object.entries(LEGACY_POSTAL_SYSTEMS).map(([legacy, { country, system }]) => [`${country}:${system}`, legacy])\n);\n\nconst POSTAL_SYSTEMS_BY_COUNTRY: Record<string, readonly string[]> = {\n  US: ['zip', 'zip_plus_four'],\n  GB: ['outward', 'full'],\n  CA: ['fsa', 'full'],\n  DE: ['plz'],\n  CH: ['plz'],\n  AT: ['plz'],\n  FR: ['code_postal'],\n  AU: ['postcode'],\n  BR: ['cep'],\n  IN: ['pin'],\n  ZA: ['postal_code'],\n};\n\nconst GENERIC_POSTAL_SYSTEMS = ['postal_code', 'custom'] as const;\nconst POSTAL_COUNTRY_KEY_PATTERN = /^[A-Z]{2}$/;\n\nfunction appendUnique(target: string[], value: string): void {\n  if (!target.includes(value)) target.push(value);\n}\n\nfunction assertSupportedPostalSystems(country: string, systems: readonly string[]): void {\n  const allowed = POSTAL_SYSTEMS_BY_COUNTRY[country] ?? GENERIC_POSTAL_SYSTEMS;\n  const invalid = systems.filter(system => !allowed.includes(system));\n  if (invalid.length > 0) {\n    throw new Error(\n      `Invalid geo_postal_areas support for ${country}: ${invalid.join(', ')}. ` +\n        `Supported systems are: ${allowed.join(', ')}.`\n    );\n  }\n}\n\n/**\n * Normalize postal-area capabilities across the AdCP 3.1.0-rc.10 migration.\n *\n * The wire schema now prefers `{ US: ['zip'] }` style country-local systems,\n * while the old `{ us_zip: true }` booleans stay deprecated but accepted\n * through 3.x. This helper is deliberately bidirectional:\n *\n * - legacy booleans add their country-keyed system;\n * - country-keyed systems backfill the matching legacy boolean when one exists;\n * - explicit unsupported legacy booleans are omitted unless the system is\n *   otherwise advertised.\n */\nexport function normalizePostalAreaSupport(input: TargetingPostalAreaSupport): PostalAreaSupport {\n  const normalized: Record<string, string[] | boolean> = {};\n\n  for (const [key, value] of Object.entries(input)) {\n    if (Array.isArray(value)) {\n      if (!POSTAL_COUNTRY_KEY_PATTERN.test(key)) {\n        throw new Error(\n          `Invalid geo_postal_areas key \"${key}\". Use an ISO 3166-1 alpha-2 country code or a deprecated legacy boolean alias.`\n        );\n      }\n      assertSupportedPostalSystems(key, value);\n      const systems = (normalized[key] = Array.isArray(normalized[key]) ? (normalized[key] as string[]) : []);\n      for (const system of value) appendUnique(systems, system);\n      continue;\n    }\n    if (value === true && key in LEGACY_POSTAL_SYSTEMS) {\n      const { country, system } = LEGACY_POSTAL_SYSTEMS[key as keyof typeof LEGACY_POSTAL_SYSTEMS];\n      const systems = (normalized[country] = Array.isArray(normalized[country])\n        ? (normalized[country] as string[])\n        : []);\n      appendUnique(systems, system);\n      continue;\n    }\n    if (value === true) {\n      throw new Error(\n        `Invalid geo_postal_areas legacy alias \"${key}\". Use an ISO 3166-1 alpha-2 country key with supported postal systems.`\n      );\n    }\n  }\n\n  for (const [country, value] of Object.entries(normalized)) {\n    if (!Array.isArray(value)) continue;\n    for (const system of value) {\n      const legacy = LEGACY_POSTAL_BY_COUNTRY_SYSTEM.get(`${country}:${system}`);\n      if (legacy) normalized[legacy] = true;\n    }\n  }\n\n  return normalized as PostalAreaSupport;\n}\n\nexport function normalizeTargetingCapabilities(input: TargetingCapabilities): _MediaBuyTargetingCapabilities {\n  return {\n    ...input,\n    ...(input.geo_postal_areas && { geo_postal_areas: normalizePostalAreaSupport(input.geo_postal_areas) }),\n  } as _MediaBuyTargetingCapabilities;\n}\n\n/**\n * Reporting capabilities the platform supports in `get_media_buy_delivery`.\n *\n * `availableDimensions` is the breakdown axes the platform can group\n * delivery rows by. Vocabulary converged across Scope3 and Prebid.\n */\nexport interface ReportingCapabilities {\n  frequencies: ReadonlyArray<'hourly' | 'daily' | 'weekly'>;\n  expected_delay_minutes: number;\n  timezone: string;\n  metrics: string[];\n  date_range_support: 'date_range' | 'fixed_only';\n  supports_webhooks: boolean;\n  availableDimensions?: ReadonlyArray<\n    'geo' | 'device_type' | 'device_platform' | 'audience' | 'placement' | 'creative' | 'keyword' | 'catalog_item'\n  >;\n}\n\n/**\n * Brand-protocol capabilities — projected onto the wire `brand` block of\n * `get_adcp_capabilities` via the framework's `overrides.brand` deep-merge\n * seam. Adopters who also implement `BrandRightsPlatform` get\n * `rights: true` auto-derived; the other four fields (`right_types`,\n * `available_uses`, `generation_providers`, `description`) are\n * adopter-declared.\n *\n * Wire spec: `protocol/get-adcp-capabilities-response.json#brand`.\n */\nexport type BrandCapabilities = NonNullable<NonNullable<GetAdCPCapabilitiesResponse['brand']>>;\n\n/**\n * Compliance-testing capabilities — projected onto the wire-side\n * `compliance_testing` block of `get_adcp_capabilities` so buyers and\n * conformance harnesses can discover which `comply_test_controller`\n * scenarios the agent supports.\n *\n * Wire spec: `core/get-adcp-capabilities-response.json#compliance_testing`.\n *\n * The `scenarios` array MUST be non-empty when this block is declared\n * (per the spec). `'list_scenarios'` is implicit — adopters don't need\n * to enumerate it.\n */\nexport interface ComplianceTestingCapabilities {\n  /**\n   * Scenarios this agent advertises support for. Wire enum is the\n   * canonical scenario enum, excluding `list_scenarios` because that\n   * is a discovery operation rather than a test capability. Framework\n   * defaults this from the adopter-supplied `complyTest` adapter set\n   * when omitted.\n   */\n  scenarios?: ReadonlyArray<_ComplianceTestingScenario>;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../../../src/lib/server/decisioning/capabilities.ts"],"sourcesContent":["/**\n * DecisioningCapabilities — single source of truth for `get_adcp_capabilities`\n * response and any admin UI surface a host wants to render.\n *\n * Adopters declare once. Framework wires the wire-protocol response;\n * adopters' admin tools (or the SDK CLI's `validate_platform_config`) consume\n * the same dataclass so there's no drift between \"what the agent says it\n * supports\" and \"what it actually does.\"\n *\n * Status: Preview / 6.0.\n *\n * @public\n */\n\nimport type { ZodSchema } from 'zod';\nimport type {\n  AdCPSpecialism,\n  MediaChannel,\n  PaymentTerms,\n  PricingModel,\n  GetAdCPCapabilitiesResponse,\n  PostalAreaSupport,\n} from '../../types/tools.generated';\nimport type { ProductMetricOptimizationLike } from '../../utils/capability-rollups';\nimport type { MediaBuyFeatures, AccountCapabilities, CreativeCapabilities } from '../../utils/capabilities';\nimport type { AdcpCapabilitiesOverrides } from '../create-adcp-server';\n\n/**\n * Pre-resolved alias for the wire `media_buy` block. Used as the projection\n * source for the five `media_buy.*` capability fields below so each typed\n * field references a single resolved shape instead of re-walking the\n * `GetAdCPCapabilitiesResponse` type graph independently. Without the\n * alias, `strict + skipLibCheck:false` adopters hit the TS instantiation\n * budget on the published `.d.ts` and tsc OOMs.\n */\ntype _MediaBuyCapabilities = NonNullable<GetAdCPCapabilitiesResponse['media_buy']>;\ntype _MediaBuyTargetingCapabilities = NonNullable<NonNullable<_MediaBuyCapabilities['execution']>['targeting']>;\ntype _ComplianceTestingScenario = NonNullable<\n  NonNullable<GetAdCPCapabilitiesResponse['compliance_testing']>['scenarios']\n>[number];\n\nexport interface DecisioningCapabilities<TConfig = unknown> {\n  /**\n   * Specialisms claimed; framework type-checks these against implemented platform\n   * interfaces. Arrays are `readonly` so adopters can declare with `as const`\n   * (load-bearing for the `RequiredPlatformsFor<S>` compile-time gate).\n   */\n  specialisms: readonly AdCPSpecialism[];\n\n  /**\n   * Creative agents this seller composes with. Framework fetches format catalogs\n   * from each (1h cache) and unions them on `list_creative_formats`. Self-hosting\n   * sellers point at their own `agent_url`; framework calls into their\n   * `CreativePlatform.listFormats()` locally instead of HTTP-fetching.\n   *\n   * `format_ids` filter (optional) subsets a single creative agent's catalog.\n   * Useful when a creative agent hosts 50 formats but this seller only accepts\n   * 10 of them. Filter scope is per-creative-agent: `[{ agent_url: A, format_ids: ['x'] }, { agent_url: B }]`\n   * means \"from A only format x; from B all formats.\"\n   *\n   * Omit for signals-only platforms (`signal-marketplace`, `signal-owned`) — they\n   * sell audience data access, not media inventory, and don't compose with creative agents.\n   */\n  creative_agents?: readonly CreativeAgentRef[];\n\n  /**\n   * Channels this platform sells.\n   *\n   * Omit for non-media-buy platforms — they don't sell ad inventory and have no\n   * channels to declare. Applies to signals (`signal-marketplace`, `signal-owned`),\n   * governance (`governance-spend-authority`, `governance-delivery-monitor`,\n   * `property-lists`, `collection-lists`, `content-standards`), creative-only\n   * (`creative-ad-server`, `creative-template`, `creative-generative`), and\n   * brand (`brand-rights`) platforms.\n   *\n   * **Required at runtime for media-buy platforms.** `validatePlatform` (called\n   * by `createAdcpServerFromPlatform`) throws `PlatformConfigError` when any\n   * `sales-*` specialism is claimed and this field is absent.\n   */\n  channels?: readonly MediaChannel[];\n\n  /**\n   * Pricing models this platform supports.\n   *\n   * Omit for non-media-buy platforms — they don't sell ad inventory and have no\n   * channel-level pricing to declare. For signals platforms specifically, pricing\n   * is declared per-signal in the signal descriptor's `pricing_options[]` instead.\n   * Same non-media-buy specialism set as `channels` above.\n   *\n   * **Required at runtime for media-buy platforms.** `validatePlatform` (called\n   * by `createAdcpServerFromPlatform`) throws `PlatformConfigError` when any\n   * `sales-*` specialism is claimed and this field is absent.\n   */\n  pricingModels?: readonly PricingModel[];\n\n  /** Targeting capabilities. Optional — framework infers reasonable defaults if omitted. */\n  targeting?: TargetingCapabilities;\n\n  /** Reporting capabilities. Optional — framework infers reasonable defaults if omitted. */\n  reporting?: ReportingCapabilities;\n\n  /**\n   * Audience-matching capabilities — projected onto\n   * `get_adcp_capabilities.media_buy.audience_targeting`. Required for\n   * audience-sync adopters (CRM-list adopters that accept hashed\n   * identifiers + UID types) so buyers know which identifier shapes\n   * the platform will match against and what minimum audience size /\n   * matching latency to expect. Omit when the platform doesn't accept\n   * external audience uploads.\n   *\n   * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.audience_targeting`.\n   */\n  audience_targeting?: NonNullable<_MediaBuyCapabilities['audience_targeting']>;\n\n  /**\n   * Conversion-tracking capabilities — projected onto\n   * `get_adcp_capabilities.media_buy.conversion_tracking`. Required for\n   * adopters that accept conversion events via `sync_event_sources` /\n   * `log_event` so buyers know which event types, action sources,\n   * attribution windows, and identifier shapes the platform supports.\n   * Omit when the platform doesn't track conversions.\n   *\n   * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.conversion_tracking`.\n   */\n  conversion_tracking?: NonNullable<_MediaBuyCapabilities['conversion_tracking']>;\n\n  /**\n   * Content-standards capabilities — projected onto\n   * `get_adcp_capabilities.media_buy.content_standards`. Required for\n   * adopters claiming the `content-standards` specialism so buyers know\n   * whether the platform runs local evaluation, which channels it\n   * covers, and whether it supports webhook artifact delivery. Omit\n   * when the platform doesn't ship content-standards artifacts.\n   *\n   * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.content_standards`.\n   */\n  content_standards?: NonNullable<_MediaBuyCapabilities['content_standards']>;\n\n  /**\n   * Seller-level rollup of optimization metrics — projected onto\n   * `get_adcp_capabilities.media_buy.supported_optimization_metrics`.\n   * Added in AdCP 3.1 (adcp#4669). The array union of every product's\n   * `metric_optimization.supported_metrics`. Storyboard runners gate\n   * `metric_optimization`-using scenarios on this field; declaring it\n   * gives buyers an upfront signal of which optimization metrics the\n   * seller can compute against (clicks, views, completed_views, etc.).\n   *\n   * Adopters can compute the rollup from their catalog using the\n   * exported {@link rollupOptimizationMetricsFromProducts} helper —\n   * keeps the declaration in sync with what products actually offer.\n   * Empty arrays are normalized away and the wire field is omitted; use\n   * omission to mean \"no seller-level metric rollup advertised\".\n   *\n   * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.supported_optimization_metrics`.\n   */\n  supported_optimization_metrics?: NonNullable<_MediaBuyCapabilities['supported_optimization_metrics']>;\n\n  /**\n   * Static product-metric summary used for capability rollups.\n   *\n   * When this is present and `supported_optimization_metrics` is omitted,\n   * the framework derives `media_buy.supported_optimization_metrics` as the\n   * sorted union of every product summary's\n   * `metric_optimization.supported_metrics`. Full AdCP `Product` objects work,\n   * but this field is not a general product-discovery surface; a lightweight\n   * startup summary with just the `metric_optimization` block is enough.\n   * Dynamic per-account catalogs should continue to pass an explicit\n   * `supported_optimization_metrics` override. If the derived union is empty,\n   * the framework omits `supported_optimization_metrics` from the wire\n   * capabilities response.\n   */\n  productCatalog?: ReadonlyArray<ProductMetricOptimizationLike>;\n\n  /**\n   * Frequency-cap support declaration — projected onto\n   * `get_adcp_capabilities.media_buy.frequency_capping`. Added in AdCP\n   * 3.1 (adcp#4670). Presence-only object with `supported_per_units` /\n   * `supported_window_units` sub-fields declaring which frequency-cap\n   * shapes the platform honors. Omit when the platform doesn't accept\n   * frequency caps at all; buyers will avoid the field on `pacing.*`.\n   *\n   * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.frequency_capping`.\n   */\n  frequency_capping?: NonNullable<_MediaBuyCapabilities['frequency_capping']>;\n\n  /**\n   * Whether this seller commits to the proposal lifecycle on get_products.\n   * Projected onto `get_adcp_capabilities.media_buy.supports_proposals`.\n   * Direct-buy sellers should declare `false` so proposal-only compliance\n   * storyboards are skipped; sellers with a ProposalManager are auto-derived\n   * as `true` unless they override this explicitly.\n   */\n  supportsProposals?: boolean;\n\n  /**\n   * Brand-protocol capabilities. Projected onto the wire `brand` block of\n   * `get_adcp_capabilities` (`brand: { rights, right_types, available_uses,\n   * generation_providers, description }`). The framework auto-derives\n   * `rights: true` when `BrandRightsPlatform` is supplied; adopters\n   * declare the rest (right_types they license, RightUses they support,\n   * generation providers they issue credentials for).\n   *\n   * REQUIRED when claiming the `'brand-rights'` specialism — enforced at\n   * compile-time via `RequiredCapabilitiesFor<S>`.\n   */\n  brand?: BrandCapabilities;\n\n  /**\n   * Compliance-testing capabilities. The presence of this block declares\n   * the deployment supports deterministic state-machine testing via the\n   * `comply_test_controller` wire tool. Keep this block declared when using\n   * `createAdcpServerFromPlatform(..., { complyTest })`; the framework makes\n   * live principals byte-identical to a production seller that never wired the\n   * controller by hiding this block, filtering `tools/list`, and returning MCP\n   * method-not-found for direct live calls.\n   *\n   * When this block is present, `createAdcpServerFromPlatform` REQUIRES\n   * `opts.complyTest` (the `ComplyControllerConfig` adapter set) to be\n   * supplied — claiming the capability without implementing the\n   * controller is a `PlatformConfigError` at construction.\n   *\n   * Inversely, supplying `opts.complyTest` without declaring this\n   * capability is also caught — the framework derives `scenarios` from\n   * the declared force/simulate/seed adapters and emits the discovery\n   * field on `get_adcp_capabilities` automatically for sandbox/mock\n   * principals. Live principals do not see the block.\n   */\n  compliance_testing?: ComplianceTestingCapabilities;\n\n  /**\n   * Billing parties this platform supports. `'operator'` = retail-media model\n   * (Criteo, Amazon — operator pays the publisher and bills the brand).\n   * `'agent'` = pass-through model (buyer's agent settles directly with the\n   * platform). `'advertiser'` = seller invoices the advertiser directly,\n   * bypassing operator settlement (advertiser-direct sell-side platforms where\n   * the brand is the direct contractual counterparty). Defaults to `['agent']`\n   * when omitted. To express advertiser-direct billing per account, set\n   * `billing.invoicedTo` to a `BrandReference` (the framework maps any\n   * `BrandReference` to `'advertiser'` on the wire).\n   */\n  supportedBillings?: ReadonlyArray<'operator' | 'agent' | 'advertiser'>;\n\n  /**\n   * Payment terms this platform accepts on `sync_accounts.payment_terms`.\n   * Omit to leave terms validation to `accounts.upsert` (or to accept any\n   * schema-valid value). When present, the framework rejects unsupported\n   * requested terms with `PAYMENT_TERMS_NOT_SUPPORTED` before dispatching\n   * the account entry to the adopter.\n   */\n  supportedPaymentTerms?: ReadonlyArray<PaymentTerms>;\n\n  /**\n   * If true, this platform refuses transactions without an authenticated\n   * operator principal (operator-billed retail-media). Framework emits\n   * `AUTH_REQUIRED` envelope before dispatching to the platform.\n   */\n  requireOperatorAuth?: boolean;\n\n  /**\n   * Media-buy feature flags forwarded into `get_adcp_capabilities.media_buy.features`.\n   * Adopter values serve as the base; auto-derived `audience_targeting`,\n   * `conversion_tracking`, and `content_standards` booleans take precedence\n   * for those three keys (overlaid by the framework via the per-domain\n   * `media_buy` override on the inner createAdcpServer call). Use this to\n   * declare `inlineCreativeManagement` and `propertyListFiltering` directly\n   * from `definePlatform`; declare not-supported feature blocks (e.g.\n   * `inlineCreativeManagement: false`) so the conformance runner grades\n   * them `not_applicable` instead of `fail`.\n   *\n   * Resolves the `definePlatform` passthrough gap noted in adcp-client#2199.\n   */\n  features?: Partial<MediaBuyFeatures>;\n\n  /**\n   * Creative-protocol capabilities forwarded into `get_adcp_capabilities.creative`.\n   * Use to declare `supportsCompliance`, `hasCreativeLibrary`,\n   * `supportsGeneration`, and `supportsTransformation` from `definePlatform`.\n   * Adopters that don't run a provenance-verification pipeline should\n   * declare the relevant fields as `false` so creative storyboards gate\n   * cleanly.\n   *\n   * Resolves the `definePlatform` passthrough gap noted in adcp-client#2199.\n   */\n  creative?: Partial<CreativeCapabilities>;\n\n  /**\n   * Account capabilities forwarded into `get_adcp_capabilities.account` as a\n   * base layer. The framework's existing `requireOperatorAuth` and\n   * `supportedBillings` projections overlay on top via the per-domain\n   * `account` override, so explicit projections win on those keys.\n   * `authorizationEndpoint`, `defaultBilling`, `requiredForProducts`, and\n   * `sandbox` are pure adopter-driven additions exposed through this slot.\n   *\n   * Resolves the `definePlatform` passthrough gap noted in adcp-client#2199.\n   */\n  account?: Partial<AccountCapabilities>;\n\n  /**\n   * Deep-merge overrides applied to the wire `get_adcp_capabilities`\n   * response. Use this for fields that the top-level `DecisioningCapabilities`\n   * shape doesn't model — `media_buy.propagation_surfaces`,\n   * `media_buy.measurement_terms`, `signals.discovery_modes`, etc. The\n   * framework's per-domain projections (auto-derived `media_buy`, `brand`,\n   * `account`, `compliance_testing` blocks) are merged AFTER adopter\n   * overrides, so framework-derived values remain authoritative on the keys\n   * the projection engine handles.\n   *\n   * Mirrors `AdcpCapabilitiesConfig.overrides` on the lower-level\n   * `createAdcpServer` API. Resolves the `definePlatform` passthrough gap\n   * noted in adcp-client#2199.\n   */\n  overrides?: AdcpCapabilitiesOverrides;\n\n  /**\n   * Release-precision AdCP versions this platform supports (e.g. `[\"3.0\", \"3.1\"]`).\n   * Forwarded into `get_adcp_capabilities.adcp.supported_versions`. 3.1+\n   * sellers should declare here the same release-precision strings they\n   * emit in `adcp_version` on responses; 3.0-pinned sellers can omit.\n   *\n   * Resolves the same gap previously noted for `supported_versions` —\n   * was unreachable through `definePlatform` because\n   * `CreateAdcpServerFromPlatformOptions` omits `'capabilities'` from\n   * `AdcpServerConfig`. See adcp-client#2199.\n   */\n  supported_versions?: string[];\n\n  /**\n   * Platform-specific config. Strongly typed when the adopter uses the generic.\n   * Example: `class GAM extends DecisioningPlatform<{ networkId: string }>`.\n   */\n  config: TConfig;\n\n  /**\n   * Optional Zod schema for runtime validation of `config`. When provided,\n   * framework validates at platform construction time; missing or wrong-shaped\n   * config rejects the agent at boot rather than at first request.\n   */\n  configSchema?: ZodSchema<TConfig>;\n}\n\nexport interface CreativeAgentRef {\n  agent_url: string;\n  /** Human-readable label for this creative agent. */\n  name?: string;\n  /** Optional allowlist of `format_id.id` values from THIS agent's catalog. Omit to include all. */\n  format_ids?: string[];\n}\n\n/**\n * Targeting capabilities the platform supports in `create_media_buy`. Maps\n * to AdCP `GetAdcpCapabilitiesResponse.media_buy.execution.targeting`.\n *\n * Shape converged across two independently-evolved peer codebases (Scope3\n * `agentic-adapters`, Prebid `salesagent`). Per-geo-system flags rather than\n * coarse enums because the two implementations agreed: real platforms support\n * specific geo identifier formats (Nielsen DMA, Eurostat NUTS2, US ZIP+4), not\n * abstract \"metro\" / \"postal\" categories.\n */\nexport interface TargetingCapabilities {\n  geo_countries?: boolean;\n  geo_regions?: boolean;\n\n  /** Metro / DMA identifier systems. */\n  geo_metros?: {\n    nielsen_dma?: boolean;\n    uk_itl1?: boolean;\n    uk_itl2?: boolean;\n    eurostat_nuts2?: boolean;\n  };\n\n  /**\n   * Postal-code identifier systems.\n   *\n   * AdCP 3.1.0-rc.10 prefers country-keyed arrays, e.g.\n   * `{ US: ['zip'], GB: ['outward'] }`. Deprecated country-fused booleans\n   * such as `{ us_zip: true }` remain accepted for 3.x adopters; the\n   * framework projects both forms with `normalizePostalAreaSupport()` so old\n   * and new buyers can read the capability safely during the migration.\n   */\n  geo_postal_areas?: TargetingPostalAreaSupport;\n\n  /** Geographic-proximity targeting (radius / drive-time / arbitrary geometry). */\n  geo_proximity?: {\n    radius?: boolean;\n    travel_time?: boolean;\n    geometry?: boolean;\n    transport_modes?: ReadonlyArray<'walking' | 'cycling' | 'driving' | 'public_transport'>;\n  };\n\n  /** Age-restriction targeting; `verification_methods` enumerates the assurance levels accepted. */\n  age_restriction?: {\n    supported?: boolean;\n    verification_methods?: ReadonlyArray<\n      'facial_age_estimation' | 'id_document' | 'digital_id' | 'credit_card' | 'world_id'\n    >;\n  };\n\n  device_platform?: boolean;\n  device_type?: boolean;\n  language?: boolean;\n  audience_include?: boolean;\n  audience_exclude?: boolean;\n\n  /** Keyword-targeting match types accepted on positive-match terms. */\n  keyword_targets?: {\n    supported_match_types: ReadonlyArray<'broad' | 'phrase' | 'exact'>;\n  };\n\n  /** Negative-keyword match types accepted. */\n  negative_keywords?: {\n    supported_match_types: ReadonlyArray<'broad' | 'phrase' | 'exact'>;\n  };\n}\n\nexport type TargetingPostalAreaSupport = {\n  US?: readonly ('zip' | 'zip_plus_four')[];\n  GB?: readonly ('outward' | 'full')[];\n  CA?: readonly ('fsa' | 'full')[];\n  DE?: readonly 'plz'[];\n  CH?: readonly 'plz'[];\n  AT?: readonly 'plz'[];\n  FR?: readonly 'code_postal'[];\n  AU?: readonly 'postcode'[];\n  BR?: readonly 'cep'[];\n  IN?: readonly 'pin'[];\n  ZA?: readonly 'postal_code'[];\n  /** @deprecated Use `US: ['zip']`. */\n  us_zip?: boolean;\n  /** @deprecated Use `US: ['zip_plus_four']`. */\n  us_zip_plus_four?: boolean;\n  /** @deprecated Use `GB: ['outward']`. */\n  gb_outward?: boolean;\n  /** @deprecated Use `GB: ['full']`. */\n  gb_full?: boolean;\n  /** @deprecated Use `CA: ['fsa']`. */\n  ca_fsa?: boolean;\n  /** @deprecated Use `CA: ['full']`. */\n  ca_full?: boolean;\n  /** @deprecated Use `DE: ['plz']`. */\n  de_plz?: boolean;\n  /** @deprecated Use `FR: ['code_postal']`. */\n  fr_code_postal?: boolean;\n  /** @deprecated Use `AU: ['postcode']`. */\n  au_postcode?: boolean;\n  /** @deprecated Use `CH: ['plz']`. */\n  ch_plz?: boolean;\n  /** @deprecated Use `AT: ['plz']`. */\n  at_plz?: boolean;\n  [country: `${Uppercase<string>}`]:\n    | readonly (\n        | 'zip'\n        | 'zip_plus_four'\n        | 'outward'\n        | 'full'\n        | 'fsa'\n        | 'plz'\n        | 'code_postal'\n        | 'postcode'\n        | 'cep'\n        | 'pin'\n        | 'postal_code'\n        | 'custom'\n      )[]\n    | undefined;\n};\n\nconst LEGACY_POSTAL_SYSTEMS = {\n  us_zip: { country: 'US', system: 'zip' },\n  us_zip_plus_four: { country: 'US', system: 'zip_plus_four' },\n  gb_outward: { country: 'GB', system: 'outward' },\n  gb_full: { country: 'GB', system: 'full' },\n  ca_fsa: { country: 'CA', system: 'fsa' },\n  ca_full: { country: 'CA', system: 'full' },\n  de_plz: { country: 'DE', system: 'plz' },\n  fr_code_postal: { country: 'FR', system: 'code_postal' },\n  au_postcode: { country: 'AU', system: 'postcode' },\n  ch_plz: { country: 'CH', system: 'plz' },\n  at_plz: { country: 'AT', system: 'plz' },\n} as const;\n\nconst LEGACY_POSTAL_BY_COUNTRY_SYSTEM = new Map(\n  Object.entries(LEGACY_POSTAL_SYSTEMS).map(([legacy, { country, system }]) => [`${country}:${system}`, legacy])\n);\n\nconst POSTAL_SYSTEMS_BY_COUNTRY: Record<string, readonly string[]> = {\n  US: ['zip', 'zip_plus_four'],\n  GB: ['outward', 'full'],\n  CA: ['fsa', 'full'],\n  DE: ['plz'],\n  CH: ['plz'],\n  AT: ['plz'],\n  FR: ['code_postal'],\n  AU: ['postcode'],\n  BR: ['cep'],\n  IN: ['pin'],\n  ZA: ['postal_code'],\n};\n\nconst GENERIC_POSTAL_SYSTEMS = ['postal_code', 'custom'] as const;\nconst POSTAL_COUNTRY_KEY_PATTERN = /^[A-Z]{2}$/;\n\nfunction appendUnique(target: string[], value: string): void {\n  if (!target.includes(value)) target.push(value);\n}\n\nfunction assertSupportedPostalSystems(country: string, systems: readonly string[]): void {\n  const allowed = POSTAL_SYSTEMS_BY_COUNTRY[country] ?? GENERIC_POSTAL_SYSTEMS;\n  const invalid = systems.filter(system => !allowed.includes(system));\n  if (invalid.length > 0) {\n    throw new Error(\n      `Invalid geo_postal_areas support for ${country}: ${invalid.join(', ')}. ` +\n        `Supported systems are: ${allowed.join(', ')}.`\n    );\n  }\n}\n\n/**\n * Normalize postal-area capabilities across the AdCP 3.1.0-rc.10 migration.\n *\n * The wire schema now prefers `{ US: ['zip'] }` style country-local systems,\n * while the old `{ us_zip: true }` booleans stay deprecated but accepted\n * through 3.x. This helper is deliberately bidirectional:\n *\n * - legacy booleans add their country-keyed system;\n * - country-keyed systems backfill the matching legacy boolean when one exists;\n * - explicit unsupported legacy booleans are omitted unless the system is\n *   otherwise advertised.\n */\nexport function normalizePostalAreaSupport(input: TargetingPostalAreaSupport): PostalAreaSupport {\n  const normalized: Record<string, string[] | boolean> = {};\n\n  for (const [key, value] of Object.entries(input)) {\n    if (Array.isArray(value)) {\n      if (!POSTAL_COUNTRY_KEY_PATTERN.test(key)) {\n        throw new Error(\n          `Invalid geo_postal_areas key \"${key}\". Use an ISO 3166-1 alpha-2 country code or a deprecated legacy boolean alias.`\n        );\n      }\n      assertSupportedPostalSystems(key, value);\n      const systems = (normalized[key] = Array.isArray(normalized[key]) ? (normalized[key] as string[]) : []);\n      for (const system of value) appendUnique(systems, system);\n      continue;\n    }\n    if (value === true && key in LEGACY_POSTAL_SYSTEMS) {\n      const { country, system } = LEGACY_POSTAL_SYSTEMS[key as keyof typeof LEGACY_POSTAL_SYSTEMS];\n      const systems = (normalized[country] = Array.isArray(normalized[country])\n        ? (normalized[country] as string[])\n        : []);\n      appendUnique(systems, system);\n      continue;\n    }\n    if (value === true) {\n      throw new Error(\n        `Invalid geo_postal_areas legacy alias \"${key}\". Use an ISO 3166-1 alpha-2 country key with supported postal systems.`\n      );\n    }\n  }\n\n  for (const [country, value] of Object.entries(normalized)) {\n    if (!Array.isArray(value)) continue;\n    for (const system of value) {\n      const legacy = LEGACY_POSTAL_BY_COUNTRY_SYSTEM.get(`${country}:${system}`);\n      if (legacy) normalized[legacy] = true;\n    }\n  }\n\n  return normalized as PostalAreaSupport;\n}\n\nexport function normalizeTargetingCapabilities(input: TargetingCapabilities): _MediaBuyTargetingCapabilities {\n  return {\n    ...input,\n    ...(input.geo_postal_areas && { geo_postal_areas: normalizePostalAreaSupport(input.geo_postal_areas) }),\n  } as _MediaBuyTargetingCapabilities;\n}\n\n/**\n * Reporting capabilities the platform supports in `get_media_buy_delivery`.\n *\n * `availableDimensions` is the breakdown axes the platform can group\n * delivery rows by. Vocabulary converged across Scope3 and Prebid.\n */\nexport interface ReportingCapabilities {\n  frequencies: ReadonlyArray<'hourly' | 'daily' | 'weekly'>;\n  expected_delay_minutes: number;\n  timezone: string;\n  metrics: string[];\n  date_range_support: 'date_range' | 'fixed_only';\n  supports_webhooks: boolean;\n  availableDimensions?: ReadonlyArray<\n    'geo' | 'device_type' | 'device_platform' | 'audience' | 'placement' | 'creative' | 'keyword' | 'catalog_item'\n  >;\n}\n\n/**\n * Brand-protocol capabilities — projected onto the wire `brand` block of\n * `get_adcp_capabilities` via the framework's `overrides.brand` deep-merge\n * seam. Adopters who also implement `BrandRightsPlatform` get\n * `rights: true` auto-derived; the other four fields (`right_types`,\n * `available_uses`, `generation_providers`, `description`) are\n * adopter-declared.\n *\n * Wire spec: `protocol/get-adcp-capabilities-response.json#brand`.\n */\nexport type BrandCapabilities = NonNullable<NonNullable<GetAdCPCapabilitiesResponse['brand']>>;\n\n/**\n * Compliance-testing capabilities — projected onto the wire-side\n * `compliance_testing` block of `get_adcp_capabilities` so buyers and\n * conformance harnesses can discover which `comply_test_controller`\n * scenarios the agent supports.\n *\n * Wire spec: `core/get-adcp-capabilities-response.json#compliance_testing`.\n *\n * The `scenarios` array MUST be non-empty when this block is declared\n * (per the spec). `'list_scenarios'` is implicit — adopters don't need\n * to enumerate it.\n */\nexport interface ComplianceTestingCapabilities {\n  /**\n   * Scenarios this agent advertises support for. Wire enum is the\n   * canonical scenario enum, excluding `list_scenarios` because that\n   * is a discovery operation rather than a test capability. Framework\n   * defaults this from the adopter-supplied `complyTest` adapter set\n   * when omitted.\n   */\n  scenarios?: ReadonlyArray<_ComplianceTestingScenario>;\n}\n"],"mappings":"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","names":[]}

package/dist/lib/server/decisioning/compose.mjs

@@ -1,9 +1,3 @@
-import { fileURLToPath as __adcpFileURLToPath } from 'node:url';
-import { dirname as __adcpDirname } from 'node:path';
-import { createRequire as __adcpCreateRequire } from 'node:module';
-const __filename = __adcpFileURLToPath(import.meta.url);
-const __dirname = __adcpDirname(__filename);
-const require = __adcpCreateRequire(import.meta.url);
 function composeSingle(inner, hooks) {
   return async (params, ctx) => {
     let result;

package/dist/lib/server/decisioning/compose.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/server/decisioning/compose.ts"],"sourcesContent":["/**\n * Method-level composition helpers for {@link DecisioningPlatform} adopters\n * who need to wrap individual platform methods with pre/post hooks — typical\n * shapes are early-return short-circuits (price-optimization paths skipping\n * the inner call), response enrichment (carbon emissions, brand-manifest\n * merging), and response-level caching.\n *\n * Closes adcp-client#1314.\n *\n * @public\n */\n\n/**\n * Wrapper returned by a `before` hook to short-circuit the wrapped method.\n *\n * Returning a wrapped object (e.g. `{ shortCircuit: cachedPriceOpt }`) skips\n * the inner method and feeds the wrapped value through `after` (if any)\n * back to the caller. Returning `undefined` (or no return) falls through.\n *\n * Discriminated wrapper rather than a sentinel symbol because the wrapper\n * is unambiguous even when `TResult` itself includes `undefined`, and\n * adopters can't accidentally short-circuit by forgetting an import.\n *\n * @public\n */\nexport interface ComposeShortCircuit<TResult> {\n  shortCircuit: TResult;\n}\n\n/**\n * Hooks accepted by {@link composeMethod}.\n *\n * `before` returning `undefined` (or no return) falls through to the wrapped\n * method. Returning `{ shortCircuit: value }` short-circuits — `after` (if\n * any) still runs on the short-circuit value before it flows back to the\n * caller.\n *\n * `after` runs on the result whether it came from the wrapped method or\n * from a `before` short-circuit. Receives the original `params` and `ctx`\n * for context-dependent enrichment.\n *\n * The `after` hook runs BEFORE response-schema validation. The wrapped\n * value still has to satisfy the wire schema for the tool — adopters\n * decorating responses with vendor-specific data should put it under\n * `ext` (the spec's typed extension surface) rather than at the top level.\n *\n * @public\n */\nexport interface ComposeHooks<TParams, TCtx, TResult> {\n  before?: (params: TParams, ctx: TCtx) => Promise<ComposeShortCircuit<TResult> | undefined>;\n  after?: (result: TResult, params: TParams, ctx: TCtx) => Promise<TResult>;\n}\n\ntype MethodFn<TParams, TCtx, TResult> = (params: TParams, ctx: TCtx) => Promise<TResult>;\n\nfunction composeSingle<TParams, TCtx, TResult>(\n  inner: MethodFn<TParams, TCtx, TResult>,\n  hooks: ComposeHooks<TParams, TCtx, TResult>\n): MethodFn<TParams, TCtx, TResult> {\n  return async (params, ctx) => {\n    let result: TResult;\n    if (hooks.before) {\n      const early = await hooks.before(params, ctx);\n      if (early === undefined) {\n        result = await inner(params, ctx);\n      } else {\n        result = early.shortCircuit;\n      }\n    } else {\n      result = await inner(params, ctx);\n    }\n    if (hooks.after) {\n      result = await hooks.after(result, params, ctx);\n    }\n    return result;\n  };\n}\n\n/**\n * Wrap a single platform method with optional `before` / `after` hooks.\n *\n * Type-preserving: the returned function has the same `(params, ctx) =>\n * Promise<TResult>` signature as `inner`, so it slots into a typed\n * `DecisioningPlatform` shape without `as` casts.\n *\n * Validates `inner` is a function eagerly (at wrap time, not at first\n * invocation) so adopters who reference an optional method that wasn't\n * implemented on the underlying platform get a clear error at module load\n * rather than the first traffic to hit the method.\n *\n * **Variadic overload** — pass multiple hooks to chain them without nesting.\n * `before` hooks run left-to-right (first argument runs first); `after`\n * hooks run right-to-left (last argument runs first), matching standard\n * middleware-stack semantics. A short-circuit from a `before` hook skips\n * remaining `before` hooks and the `after` hooks of inner wrappers that\n * were never entered; `after` hooks for the short-circuiting wrapper and\n * any outer wrappers still run. Equivalent to manually nesting\n * `composeMethod` calls right-to-left:\n *\n * ```ts\n * // These are identical:\n * composeMethod(inner, hookA, hookB, hookC)\n * composeMethod(composeMethod(composeMethod(inner, hookC), hookB), hookA)\n * ```\n *\n * @example Short-circuit + enrichment (single hook)\n * ```ts\n * import { composeMethod } from '@adcp/sdk/server';\n *\n * const wrapped = {\n *   ...basePlatform,\n *   sales: {\n *     ...basePlatform.sales,\n *     getMediaBuyDelivery: composeMethod(basePlatform.sales.getMediaBuyDelivery, {\n *       before: async (params) =>\n *         params.optimization === 'price'\n *           ? { shortCircuit: cachedPriceOpt }\n *           : undefined,\n *       after: async (result) => ({\n *         ...result,\n *         ext: { ...result.ext, carbon_grams_per_impression: await score(result) },\n *       }),\n *     }),\n *     getProducts: composeMethod(basePlatform.sales.getProducts, {\n *       after: async (result) => mergeBrandManifest(result, await brandCache.get()),\n *     }),\n *   },\n * };\n *\n * createAdcpServerFromPlatform(wrapped, opts);\n * ```\n *\n * @example Stacking multiple security gates (variadic)\n * ```ts\n * import { composeMethod, requireAdvertiserMatch } from '@adcp/sdk/server';\n *\n * accounts: {\n *   resolve: composeMethod(\n *     baseResolve,\n *     { before: async (_p, ctx) => ctx.token ? undefined : { shortCircuit: null } },\n *     requireAdvertiserMatch(async (ctx) => tenantRoster.for(ctx?.agent)),\n *   ),\n * }\n * ```\n *\n * @public\n */\nexport function composeMethod<TParams, TCtx, TResult>(\n  inner: MethodFn<TParams, TCtx, TResult>,\n  hooks: ComposeHooks<TParams, TCtx, TResult>\n): MethodFn<TParams, TCtx, TResult>;\nexport function composeMethod<TParams, TCtx, TResult>(\n  inner: MethodFn<TParams, TCtx, TResult>,\n  first: ComposeHooks<TParams, TCtx, TResult>,\n  ...rest: ComposeHooks<TParams, TCtx, TResult>[]\n): MethodFn<TParams, TCtx, TResult>;\nexport function composeMethod<TParams, TCtx, TResult>(\n  inner: MethodFn<TParams, TCtx, TResult>,\n  first: ComposeHooks<TParams, TCtx, TResult>,\n  ...rest: ComposeHooks<TParams, TCtx, TResult>[]\n): MethodFn<TParams, TCtx, TResult> {\n  if (typeof inner !== 'function') {\n    throw new TypeError(\n      `composeMethod: 'inner' must be a function, got ${inner === null ? 'null' : typeof inner}. ` +\n        `Did you reference an optional method that wasn't implemented on the platform?`\n    );\n  }\n  if (rest.length === 0) {\n    return composeSingle(inner, first);\n  }\n  // Fold right so the first argument becomes the outermost wrapper (runs first).\n  // Equivalent to: composeMethod(composeMethod(composeMethod(inner, hookC), hookB), hookA)\n  return [first, ...rest].reduceRight<MethodFn<TParams, TCtx, TResult>>(\n    (acc, hooks) => composeSingle(acc, hooks),\n    inner\n  );\n}\n"],"mappings":";;;;;;AAuDA,SAAS,cACP,OACA,OACkC;AAClC,SAAO,OAAO,QAAQ,QAAQ;AAC5B,QAAI;AACJ,QAAI,MAAM,QAAQ;AAChB,YAAM,QAAQ,MAAM,MAAM,OAAO,QAAQ,GAAG;AAC5C,UAAI,UAAU,QAAW;AACvB,iBAAS,MAAM,MAAM,QAAQ,GAAG;AAAA,MAClC,OAAO;AACL,iBAAS,MAAM;AAAA,MACjB;AAAA,IACF,OAAO;AACL,eAAS,MAAM,MAAM,QAAQ,GAAG;AAAA,IAClC;AACA,QAAI,MAAM,OAAO;AACf,eAAS,MAAM,MAAM,MAAM,QAAQ,QAAQ,GAAG;AAAA,IAChD;AACA,WAAO;AAAA,EACT;AACF;AAgFO,SAAS,cACd,OACA,UACG,MAC+B;AAClC,MAAI,OAAO,UAAU,YAAY;AAC/B,UAAM,IAAI;AAAA,MACR,kDAAkD,UAAU,OAAO,SAAS,OAAO,KAAK;AAAA,IAE1F;AAAA,EACF;AACA,MAAI,KAAK,WAAW,GAAG;AACrB,WAAO,cAAc,OAAO,KAAK;AAAA,EACnC;AAGA,SAAO,CAAC,OAAO,GAAG,IAAI,EAAE;AAAA,IACtB,CAAC,KAAK,UAAU,cAAc,KAAK,KAAK;AAAA,IACxC;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../../../src/lib/server/decisioning/compose.ts"],"sourcesContent":["/**\n * Method-level composition helpers for {@link DecisioningPlatform} adopters\n * who need to wrap individual platform methods with pre/post hooks — typical\n * shapes are early-return short-circuits (price-optimization paths skipping\n * the inner call), response enrichment (carbon emissions, brand-manifest\n * merging), and response-level caching.\n *\n * Closes adcp-client#1314.\n *\n * @public\n */\n\n/**\n * Wrapper returned by a `before` hook to short-circuit the wrapped method.\n *\n * Returning a wrapped object (e.g. `{ shortCircuit: cachedPriceOpt }`) skips\n * the inner method and feeds the wrapped value through `after` (if any)\n * back to the caller. Returning `undefined` (or no return) falls through.\n *\n * Discriminated wrapper rather than a sentinel symbol because the wrapper\n * is unambiguous even when `TResult` itself includes `undefined`, and\n * adopters can't accidentally short-circuit by forgetting an import.\n *\n * @public\n */\nexport interface ComposeShortCircuit<TResult> {\n  shortCircuit: TResult;\n}\n\n/**\n * Hooks accepted by {@link composeMethod}.\n *\n * `before` returning `undefined` (or no return) falls through to the wrapped\n * method. Returning `{ shortCircuit: value }` short-circuits — `after` (if\n * any) still runs on the short-circuit value before it flows back to the\n * caller.\n *\n * `after` runs on the result whether it came from the wrapped method or\n * from a `before` short-circuit. Receives the original `params` and `ctx`\n * for context-dependent enrichment.\n *\n * The `after` hook runs BEFORE response-schema validation. The wrapped\n * value still has to satisfy the wire schema for the tool — adopters\n * decorating responses with vendor-specific data should put it under\n * `ext` (the spec's typed extension surface) rather than at the top level.\n *\n * @public\n */\nexport interface ComposeHooks<TParams, TCtx, TResult> {\n  before?: (params: TParams, ctx: TCtx) => Promise<ComposeShortCircuit<TResult> | undefined>;\n  after?: (result: TResult, params: TParams, ctx: TCtx) => Promise<TResult>;\n}\n\ntype MethodFn<TParams, TCtx, TResult> = (params: TParams, ctx: TCtx) => Promise<TResult>;\n\nfunction composeSingle<TParams, TCtx, TResult>(\n  inner: MethodFn<TParams, TCtx, TResult>,\n  hooks: ComposeHooks<TParams, TCtx, TResult>\n): MethodFn<TParams, TCtx, TResult> {\n  return async (params, ctx) => {\n    let result: TResult;\n    if (hooks.before) {\n      const early = await hooks.before(params, ctx);\n      if (early === undefined) {\n        result = await inner(params, ctx);\n      } else {\n        result = early.shortCircuit;\n      }\n    } else {\n      result = await inner(params, ctx);\n    }\n    if (hooks.after) {\n      result = await hooks.after(result, params, ctx);\n    }\n    return result;\n  };\n}\n\n/**\n * Wrap a single platform method with optional `before` / `after` hooks.\n *\n * Type-preserving: the returned function has the same `(params, ctx) =>\n * Promise<TResult>` signature as `inner`, so it slots into a typed\n * `DecisioningPlatform` shape without `as` casts.\n *\n * Validates `inner` is a function eagerly (at wrap time, not at first\n * invocation) so adopters who reference an optional method that wasn't\n * implemented on the underlying platform get a clear error at module load\n * rather than the first traffic to hit the method.\n *\n * **Variadic overload** — pass multiple hooks to chain them without nesting.\n * `before` hooks run left-to-right (first argument runs first); `after`\n * hooks run right-to-left (last argument runs first), matching standard\n * middleware-stack semantics. A short-circuit from a `before` hook skips\n * remaining `before` hooks and the `after` hooks of inner wrappers that\n * were never entered; `after` hooks for the short-circuiting wrapper and\n * any outer wrappers still run. Equivalent to manually nesting\n * `composeMethod` calls right-to-left:\n *\n * ```ts\n * // These are identical:\n * composeMethod(inner, hookA, hookB, hookC)\n * composeMethod(composeMethod(composeMethod(inner, hookC), hookB), hookA)\n * ```\n *\n * @example Short-circuit + enrichment (single hook)\n * ```ts\n * import { composeMethod } from '@adcp/sdk/server';\n *\n * const wrapped = {\n *   ...basePlatform,\n *   sales: {\n *     ...basePlatform.sales,\n *     getMediaBuyDelivery: composeMethod(basePlatform.sales.getMediaBuyDelivery, {\n *       before: async (params) =>\n *         params.optimization === 'price'\n *           ? { shortCircuit: cachedPriceOpt }\n *           : undefined,\n *       after: async (result) => ({\n *         ...result,\n *         ext: { ...result.ext, carbon_grams_per_impression: await score(result) },\n *       }),\n *     }),\n *     getProducts: composeMethod(basePlatform.sales.getProducts, {\n *       after: async (result) => mergeBrandManifest(result, await brandCache.get()),\n *     }),\n *   },\n * };\n *\n * createAdcpServerFromPlatform(wrapped, opts);\n * ```\n *\n * @example Stacking multiple security gates (variadic)\n * ```ts\n * import { composeMethod, requireAdvertiserMatch } from '@adcp/sdk/server';\n *\n * accounts: {\n *   resolve: composeMethod(\n *     baseResolve,\n *     { before: async (_p, ctx) => ctx.token ? undefined : { shortCircuit: null } },\n *     requireAdvertiserMatch(async (ctx) => tenantRoster.for(ctx?.agent)),\n *   ),\n * }\n * ```\n *\n * @public\n */\nexport function composeMethod<TParams, TCtx, TResult>(\n  inner: MethodFn<TParams, TCtx, TResult>,\n  hooks: ComposeHooks<TParams, TCtx, TResult>\n): MethodFn<TParams, TCtx, TResult>;\nexport function composeMethod<TParams, TCtx, TResult>(\n  inner: MethodFn<TParams, TCtx, TResult>,\n  first: ComposeHooks<TParams, TCtx, TResult>,\n  ...rest: ComposeHooks<TParams, TCtx, TResult>[]\n): MethodFn<TParams, TCtx, TResult>;\nexport function composeMethod<TParams, TCtx, TResult>(\n  inner: MethodFn<TParams, TCtx, TResult>,\n  first: ComposeHooks<TParams, TCtx, TResult>,\n  ...rest: ComposeHooks<TParams, TCtx, TResult>[]\n): MethodFn<TParams, TCtx, TResult> {\n  if (typeof inner !== 'function') {\n    throw new TypeError(\n      `composeMethod: 'inner' must be a function, got ${inner === null ? 'null' : typeof inner}. ` +\n        `Did you reference an optional method that wasn't implemented on the platform?`\n    );\n  }\n  if (rest.length === 0) {\n    return composeSingle(inner, first);\n  }\n  // Fold right so the first argument becomes the outermost wrapper (runs first).\n  // Equivalent to: composeMethod(composeMethod(composeMethod(inner, hookC), hookB), hookA)\n  return [first, ...rest].reduceRight<MethodFn<TParams, TCtx, TResult>>(\n    (acc, hooks) => composeSingle(acc, hooks),\n    inner\n  );\n}\n"],"mappings":"AAuDA,SAAS,cACP,OACA,OACkC;AAClC,SAAO,OAAO,QAAQ,QAAQ;AAC5B,QAAI;AACJ,QAAI,MAAM,QAAQ;AAChB,YAAM,QAAQ,MAAM,MAAM,OAAO,QAAQ,GAAG;AAC5C,UAAI,UAAU,QAAW;AACvB,iBAAS,MAAM,MAAM,QAAQ,GAAG;AAAA,MAClC,OAAO;AACL,iBAAS,MAAM;AAAA,MACjB;AAAA,IACF,OAAO;AACL,eAAS,MAAM,MAAM,QAAQ,GAAG;AAAA,IAClC;AACA,QAAI,MAAM,OAAO;AACf,eAAS,MAAM,MAAM,MAAM,QAAQ,QAAQ,GAAG;AAAA,IAChD;AACA,WAAO;AAAA,EACT;AACF;AAgFO,SAAS,cACd,OACA,UACG,MAC+B;AAClC,MAAI,OAAO,UAAU,YAAY;AAC/B,UAAM,IAAI;AAAA,MACR,kDAAkD,UAAU,OAAO,SAAS,OAAO,KAAK;AAAA,IAE1F;AAAA,EACF;AACA,MAAI,KAAK,WAAW,GAAG;AACrB,WAAO,cAAc,OAAO,KAAK;AAAA,EACnC;AAGA,SAAO,CAAC,OAAO,GAAG,IAAI,EAAE;AAAA,IACtB,CAAC,KAAK,UAAU,cAAc,KAAK,KAAK;AAAA,IACxC;AAAA,EACF;AACF;","names":[]}

package/dist/lib/server/decisioning/context.mjs

@@ -1,7 +1 @@
-import { fileURLToPath as __adcpFileURLToPath } from 'node:url';
-import { dirname as __adcpDirname } from 'node:path';
-import { createRequire as __adcpCreateRequire } from 'node:module';
-const __filename = __adcpFileURLToPath(import.meta.url);
-const __dirname = __adcpDirname(__filename);
-const require = __adcpCreateRequire(import.meta.url);
 //# sourceMappingURL=context.mjs.map

package/dist/lib/server/decisioning/errors-typed.mjs

@@ -1,9 +1,3 @@
-import { fileURLToPath as __adcpFileURLToPath } from 'node:url';
-import { dirname as __adcpDirname } from 'node:path';
-import { createRequire as __adcpCreateRequire } from 'node:module';
-const __filename = __adcpFileURLToPath(import.meta.url);
-const __dirname = __adcpDirname(__filename);
-const require = __adcpCreateRequire(import.meta.url);
 import { AdcpError } from "./async-outcome.mjs";
 class PackageNotFoundError extends AdcpError {
   constructor(packageId, opts = {}) {

package/dist/lib/server/decisioning/errors-typed.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/server/decisioning/errors-typed.ts"],"sourcesContent":["/**\n * Typed `AdcpError` subclasses. Adopters pick from a closed set of class\n * imports rather than memorizing string codes + recovery semantics.\n *\n * Each class encodes the canonical `code` / `field` / `suggestion` shape\n * for its scenario. `recovery` is inherited from the spec via\n * `getErrorRecovery(code)` — these classes never hardcode it. That keeps\n * the typed-class hierarchy in lockstep with the canonical recovery\n * classifications in `STANDARD_ERROR_CODES` (which derives from the\n * generated `ErrorCodeValues`). When the spec rev changes a recovery\n * value, every typed class picks it up automatically.\n *\n * LLM-generated platforms get autocomplete on the import; humans skim\n * the list to find the right class for their case.\n *\n * Empirical baseline (Emma matrix v17, 2026-04-30): LLM-generated\n * sellers throw generic `Error` because the AdcpError code catalog\n * isn't visible at the throw site. Framework auto-maps generic throws\n * to `SERVICE_UNAVAILABLE`, which storyboards reject because (e.g.)\n * the right code for \"package_id doesn't exist\" is `PACKAGE_NOT_FOUND`.\n * Typed classes close the gap: the LLM imports `PackageNotFoundError`\n * and the right code is implicit.\n *\n * **Coverage**: the ~20 highest-traffic codes from the v3 spec. Adopters\n * needing a code not in this list still construct `AdcpError(code, ...)`\n * directly with the full code vocabulary; this module is a convenience\n * over the typed-class subset.\n *\n * @public\n */\n\nimport { AdcpError } from './async-outcome';\n\ninterface CommonOpts {\n  /** Override the default message. Most callers use the default. */\n  message?: string;\n  /** Suggested fix surfaced to the buyer. */\n  suggestion?: string;\n  /** Additional structured context. */\n  details?: Record<string, unknown>;\n}\n\n// ---------------------------------------------------------------------------\n// Resource-not-found family.\n// ---------------------------------------------------------------------------\n\nexport class PackageNotFoundError extends AdcpError {\n  constructor(packageId: string, opts: CommonOpts = {}) {\n    super('PACKAGE_NOT_FOUND', {\n      message: opts.message ?? `Package not found: ${packageId}`,\n      field: 'package_id',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class MediaBuyNotFoundError extends AdcpError {\n  constructor(mediaBuyId: string, opts: CommonOpts = {}) {\n    super('MEDIA_BUY_NOT_FOUND', {\n      message: opts.message ?? `Media buy not found: ${mediaBuyId}`,\n      field: 'media_buy_id',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class ProductNotFoundError extends AdcpError {\n  constructor(productId: string, opts: CommonOpts = {}) {\n    super('PRODUCT_NOT_FOUND', {\n      message: opts.message ?? `Product not found: ${productId}`,\n      field: 'product_id',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class CreativeNotFoundError extends AdcpError {\n  constructor(creativeId: string, opts: CommonOpts = {}) {\n    super('CREATIVE_NOT_FOUND', {\n      message: opts.message ?? `Creative not found: ${creativeId}`,\n      field: 'creative_id',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n// Note: an `AccountNotFoundError` already exists in `./account` as a plain\n// `Error` subclass for the framework's `accounts.resolve()` path (caught\n// and translated internally). Adopters who need the wire-facing\n// `ACCOUNT_NOT_FOUND` error code throw `new AdcpError('ACCOUNT_NOT_FOUND',\n// { message: '...', field: 'account.id' })` directly — recovery defaults\n// to the spec value (`terminal`) via `getErrorRecovery`.\n\n// ---------------------------------------------------------------------------\n// Resource-unavailable family — id is right but state precludes use.\n// ---------------------------------------------------------------------------\n\nexport class ProductUnavailableError extends AdcpError {\n  constructor(productId: string, opts: CommonOpts = {}) {\n    super('PRODUCT_UNAVAILABLE', {\n      message: opts.message ?? `Product unavailable (sold out / no inventory): ${productId}`,\n      field: 'product_id',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class CreativeRejectedError extends AdcpError {\n  constructor(creativeId: string, reason: string, opts: CommonOpts = {}) {\n    super('CREATIVE_REJECTED', {\n      message: opts.message ?? `Creative ${creativeId} rejected: ${reason}`,\n      field: 'creative_id',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      details: { ...(opts.details ?? {}), reason },\n    });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Budget family\n// ---------------------------------------------------------------------------\n\nexport class BudgetTooLowError extends AdcpError {\n  constructor(opts: CommonOpts & { floor?: number; currency?: string } = {}) {\n    const floorStr =\n      opts.floor != null && opts.currency != null\n        ? `Floor is ${opts.floor} ${opts.currency}.`\n        : opts.floor != null\n          ? `Floor is ${opts.floor}.`\n          : 'Budget below required floor.';\n    super('BUDGET_TOO_LOW', {\n      message: opts.message ?? floorStr,\n      field: 'total_budget',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.floor != null && { details: { ...(opts.details ?? {}), floor: opts.floor, currency: opts.currency } }),\n    });\n  }\n}\n\nexport class BudgetExhaustedError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('BUDGET_EXHAUSTED', {\n      message: opts.message ?? 'Budget exhausted.',\n      field: 'total_budget',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Idempotency family\n// ---------------------------------------------------------------------------\n\nexport class IdempotencyConflictError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('IDEMPOTENCY_CONFLICT', {\n      message: opts.message ?? 'Same idempotency_key with different payload.',\n      field: 'idempotency_key',\n      suggestion: opts.suggestion ?? 'Use a fresh idempotency_key for the new payload.',\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Validation / state family\n// ---------------------------------------------------------------------------\n\nexport class InvalidRequestError extends AdcpError {\n  constructor(field: string, message: string, opts: CommonOpts = {}) {\n    super('INVALID_REQUEST', {\n      message,\n      field,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class InvalidStateError extends AdcpError {\n  constructor(field: string, message: string, opts: CommonOpts = {}) {\n    super('INVALID_STATE', {\n      message,\n      field,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n/**\n * Convenience for the common `start_time >= end_time` case. Use\n * `InvalidRequestError` for arbitrary field-level validation.\n */\nexport class BackwardsTimeRangeError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('INVALID_REQUEST', {\n      message: opts.message ?? 'start_time must be before end_time.',\n      field: 'start_time',\n      suggestion: opts.suggestion ?? 'Verify the buyer-provided campaign window.',\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Auth / permission family\n// ---------------------------------------------------------------------------\n\n/**\n * No credentials were presented. Sellers MUST return this when no\n * `Authorization` header was included on the request. Recovery:\n * correctable (provide credentials via the auth header and retry).\n *\n * @since AdCP 3.1 (adcp#3730 splits `AUTH_REQUIRED`).\n */\nexport class AuthMissingError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('AUTH_MISSING', {\n      message: opts.message ?? 'Authentication required: no credentials presented.',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n/**\n * 3.0.x-era authentication error that conflates missing credentials with\n * rejected credentials. AdCP 3.1 splits this into {@link AuthMissingError}\n * (correctable; no `Authorization` header presented) and\n * {@link AuthInvalidError} (terminal; credentials presented but rejected).\n *\n * This deprecated convenience remains wire-compatible and still emits\n * `AUTH_REQUIRED`. New seller code should throw {@link AuthMissingError}\n * or {@link AuthInvalidError} explicitly; buyer code should continue to\n * handle wire `AUTH_REQUIRED` for older sellers and SDK compatibility paths.\n *\n * @deprecated Prefer `AuthMissingError` (missing credentials) or\n *   `AuthInvalidError` (rejected credentials). Retained as a source-compatible\n *   alias for older adopter code during the 3.x deprecation window.\n */\nexport class AuthRequiredError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('AUTH_REQUIRED', {\n      message: opts.message ?? 'Authentication required.',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n/**\n * Credentials were presented but rejected — revoked, malformed signature,\n * or a key no longer in the seller's keystore. Recovery: terminal — do NOT\n * auto-retry. Auto-retry creates an SSO retry-storm indistinguishable from\n * brute-force probing. The decisioning runtime treats this as terminal even\n * when an account store has a refresh hook.\n *\n * **Credential-leak guard.** `opts.message` and `opts.details` cross to\n * the buyer verbatim on the wire envelope. Do NOT place rejected\n * credentials, token fragments, JWT payload material, or upstream\n * identity-provider error bodies in either field — log those server-side\n * instead. The framework is a witness, not a redactor.\n *\n * @since AdCP 3.1 (adcp#3730 splits `AUTH_REQUIRED`).\n */\nexport class AuthInvalidError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('AUTH_INVALID', {\n      message: opts.message ?? 'Authentication failed: credentials rejected.',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class PermissionDeniedError extends AdcpError {\n  constructor(action: string, opts: CommonOpts = {}) {\n    super('PERMISSION_DENIED', {\n      message: opts.message ?? `Permission denied for ${action}.`,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      details: { ...(opts.details ?? {}), action },\n    });\n  }\n}\n\n/**\n * The buyer agent's commercial relationship with the seller is suspended.\n * Recovery: terminal at the wire level — a buyer cannot \"wait out\" a\n * suspension by retrying the same request. The transient-vs-permanent\n * distinction lives at the seller's `BuyerAgent.status` record, not on the\n * wire.\n *\n * Consolidates the 3.0.5 placeholder shape\n * `PERMISSION_DENIED + details.scope:'agent' + details.status:'suspended'`,\n * which is removed in 3.1 (envelopes carrying `details.status` fail schema\n * validation).\n *\n * @since AdCP 3.1 (adcp#3906 consolidates the `details.status` placeholder).\n */\nexport class AgentSuspendedError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('AGENT_SUSPENDED', {\n      message: opts.message ?? 'Buyer agent is suspended. Contact the seller to restore access.',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n/**\n * The buyer agent is permanently denied by the seller. Recovery: terminal —\n * re-onboarding under a new agent identity is the only recovery path.\n *\n * Consolidates the 3.0.5 placeholder shape\n * `PERMISSION_DENIED + details.scope:'agent' + details.status:'blocked'`,\n * which is removed in 3.1.\n *\n * @since AdCP 3.1 (adcp#3906 consolidates the `details.status` placeholder).\n */\nexport class AgentBlockedError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('AGENT_BLOCKED', {\n      message: opts.message ?? 'Buyer agent is blocked.',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Throttling / availability family\n// ---------------------------------------------------------------------------\n\nexport class RateLimitedError extends AdcpError {\n  constructor(retryAfterSeconds: number, opts: CommonOpts = {}) {\n    super('RATE_LIMITED', {\n      message: opts.message ?? `Rate limited. Retry after ${retryAfterSeconds}s.`,\n      retry_after: Math.max(1, Math.min(3600, Math.floor(retryAfterSeconds))),\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class ServiceUnavailableError extends AdcpError {\n  constructor(opts: CommonOpts & { retryAfterSeconds?: number } = {}) {\n    super('SERVICE_UNAVAILABLE', {\n      message: opts.message ?? 'Service temporarily unavailable.',\n      retry_after:\n        opts.retryAfterSeconds != null ? Math.max(1, Math.min(3600, Math.floor(opts.retryAfterSeconds))) : 60,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class UnsupportedFeatureError extends AdcpError {\n  constructor(feature: string, opts: CommonOpts = {}) {\n    super('UNSUPPORTED_FEATURE', {\n      message: opts.message ?? `Feature not supported: ${feature}.`,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      details: { ...(opts.details ?? {}), feature },\n    });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Compliance / governance family\n// ---------------------------------------------------------------------------\n\nexport class ComplianceUnsatisfiedError extends AdcpError {\n  constructor(reason: string, opts: CommonOpts = {}) {\n    super('COMPLIANCE_UNSATISFIED', {\n      message: opts.message ?? `Compliance not satisfied: ${reason}`,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      details: { ...(opts.details ?? {}), reason },\n    });\n  }\n}\n\nexport class GovernanceDeniedError extends AdcpError {\n  constructor(reason: string, opts: CommonOpts = {}) {\n    super('GOVERNANCE_DENIED', {\n      message: opts.message ?? `Governance denied: ${reason}`,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      details: { ...(opts.details ?? {}), reason },\n    });\n  }\n}\n\nexport class PolicyViolationError extends AdcpError {\n  constructor(policy: string, opts: CommonOpts = {}) {\n    super('POLICY_VIOLATION', {\n      message: opts.message ?? `Policy violation: ${policy}`,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      details: { ...(opts.details ?? {}), policy },\n    });\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../../../src/lib/server/decisioning/errors-typed.ts"],"sourcesContent":["/**\n * Typed `AdcpError` subclasses. Adopters pick from a closed set of class\n * imports rather than memorizing string codes + recovery semantics.\n *\n * Each class encodes the canonical `code` / `field` / `suggestion` shape\n * for its scenario. `recovery` is inherited from the spec via\n * `getErrorRecovery(code)` — these classes never hardcode it. That keeps\n * the typed-class hierarchy in lockstep with the canonical recovery\n * classifications in `STANDARD_ERROR_CODES` (which derives from the\n * generated `ErrorCodeValues`). When the spec rev changes a recovery\n * value, every typed class picks it up automatically.\n *\n * LLM-generated platforms get autocomplete on the import; humans skim\n * the list to find the right class for their case.\n *\n * Empirical baseline (Emma matrix v17, 2026-04-30): LLM-generated\n * sellers throw generic `Error` because the AdcpError code catalog\n * isn't visible at the throw site. Framework auto-maps generic throws\n * to `SERVICE_UNAVAILABLE`, which storyboards reject because (e.g.)\n * the right code for \"package_id doesn't exist\" is `PACKAGE_NOT_FOUND`.\n * Typed classes close the gap: the LLM imports `PackageNotFoundError`\n * and the right code is implicit.\n *\n * **Coverage**: the ~20 highest-traffic codes from the v3 spec. Adopters\n * needing a code not in this list still construct `AdcpError(code, ...)`\n * directly with the full code vocabulary; this module is a convenience\n * over the typed-class subset.\n *\n * @public\n */\n\nimport { AdcpError } from './async-outcome';\n\ninterface CommonOpts {\n  /** Override the default message. Most callers use the default. */\n  message?: string;\n  /** Suggested fix surfaced to the buyer. */\n  suggestion?: string;\n  /** Additional structured context. */\n  details?: Record<string, unknown>;\n}\n\n// ---------------------------------------------------------------------------\n// Resource-not-found family.\n// ---------------------------------------------------------------------------\n\nexport class PackageNotFoundError extends AdcpError {\n  constructor(packageId: string, opts: CommonOpts = {}) {\n    super('PACKAGE_NOT_FOUND', {\n      message: opts.message ?? `Package not found: ${packageId}`,\n      field: 'package_id',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class MediaBuyNotFoundError extends AdcpError {\n  constructor(mediaBuyId: string, opts: CommonOpts = {}) {\n    super('MEDIA_BUY_NOT_FOUND', {\n      message: opts.message ?? `Media buy not found: ${mediaBuyId}`,\n      field: 'media_buy_id',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class ProductNotFoundError extends AdcpError {\n  constructor(productId: string, opts: CommonOpts = {}) {\n    super('PRODUCT_NOT_FOUND', {\n      message: opts.message ?? `Product not found: ${productId}`,\n      field: 'product_id',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class CreativeNotFoundError extends AdcpError {\n  constructor(creativeId: string, opts: CommonOpts = {}) {\n    super('CREATIVE_NOT_FOUND', {\n      message: opts.message ?? `Creative not found: ${creativeId}`,\n      field: 'creative_id',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n// Note: an `AccountNotFoundError` already exists in `./account` as a plain\n// `Error` subclass for the framework's `accounts.resolve()` path (caught\n// and translated internally). Adopters who need the wire-facing\n// `ACCOUNT_NOT_FOUND` error code throw `new AdcpError('ACCOUNT_NOT_FOUND',\n// { message: '...', field: 'account.id' })` directly — recovery defaults\n// to the spec value (`terminal`) via `getErrorRecovery`.\n\n// ---------------------------------------------------------------------------\n// Resource-unavailable family — id is right but state precludes use.\n// ---------------------------------------------------------------------------\n\nexport class ProductUnavailableError extends AdcpError {\n  constructor(productId: string, opts: CommonOpts = {}) {\n    super('PRODUCT_UNAVAILABLE', {\n      message: opts.message ?? `Product unavailable (sold out / no inventory): ${productId}`,\n      field: 'product_id',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class CreativeRejectedError extends AdcpError {\n  constructor(creativeId: string, reason: string, opts: CommonOpts = {}) {\n    super('CREATIVE_REJECTED', {\n      message: opts.message ?? `Creative ${creativeId} rejected: ${reason}`,\n      field: 'creative_id',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      details: { ...(opts.details ?? {}), reason },\n    });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Budget family\n// ---------------------------------------------------------------------------\n\nexport class BudgetTooLowError extends AdcpError {\n  constructor(opts: CommonOpts & { floor?: number; currency?: string } = {}) {\n    const floorStr =\n      opts.floor != null && opts.currency != null\n        ? `Floor is ${opts.floor} ${opts.currency}.`\n        : opts.floor != null\n          ? `Floor is ${opts.floor}.`\n          : 'Budget below required floor.';\n    super('BUDGET_TOO_LOW', {\n      message: opts.message ?? floorStr,\n      field: 'total_budget',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.floor != null && { details: { ...(opts.details ?? {}), floor: opts.floor, currency: opts.currency } }),\n    });\n  }\n}\n\nexport class BudgetExhaustedError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('BUDGET_EXHAUSTED', {\n      message: opts.message ?? 'Budget exhausted.',\n      field: 'total_budget',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Idempotency family\n// ---------------------------------------------------------------------------\n\nexport class IdempotencyConflictError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('IDEMPOTENCY_CONFLICT', {\n      message: opts.message ?? 'Same idempotency_key with different payload.',\n      field: 'idempotency_key',\n      suggestion: opts.suggestion ?? 'Use a fresh idempotency_key for the new payload.',\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Validation / state family\n// ---------------------------------------------------------------------------\n\nexport class InvalidRequestError extends AdcpError {\n  constructor(field: string, message: string, opts: CommonOpts = {}) {\n    super('INVALID_REQUEST', {\n      message,\n      field,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class InvalidStateError extends AdcpError {\n  constructor(field: string, message: string, opts: CommonOpts = {}) {\n    super('INVALID_STATE', {\n      message,\n      field,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n/**\n * Convenience for the common `start_time >= end_time` case. Use\n * `InvalidRequestError` for arbitrary field-level validation.\n */\nexport class BackwardsTimeRangeError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('INVALID_REQUEST', {\n      message: opts.message ?? 'start_time must be before end_time.',\n      field: 'start_time',\n      suggestion: opts.suggestion ?? 'Verify the buyer-provided campaign window.',\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Auth / permission family\n// ---------------------------------------------------------------------------\n\n/**\n * No credentials were presented. Sellers MUST return this when no\n * `Authorization` header was included on the request. Recovery:\n * correctable (provide credentials via the auth header and retry).\n *\n * @since AdCP 3.1 (adcp#3730 splits `AUTH_REQUIRED`).\n */\nexport class AuthMissingError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('AUTH_MISSING', {\n      message: opts.message ?? 'Authentication required: no credentials presented.',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n/**\n * 3.0.x-era authentication error that conflates missing credentials with\n * rejected credentials. AdCP 3.1 splits this into {@link AuthMissingError}\n * (correctable; no `Authorization` header presented) and\n * {@link AuthInvalidError} (terminal; credentials presented but rejected).\n *\n * This deprecated convenience remains wire-compatible and still emits\n * `AUTH_REQUIRED`. New seller code should throw {@link AuthMissingError}\n * or {@link AuthInvalidError} explicitly; buyer code should continue to\n * handle wire `AUTH_REQUIRED` for older sellers and SDK compatibility paths.\n *\n * @deprecated Prefer `AuthMissingError` (missing credentials) or\n *   `AuthInvalidError` (rejected credentials). Retained as a source-compatible\n *   alias for older adopter code during the 3.x deprecation window.\n */\nexport class AuthRequiredError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('AUTH_REQUIRED', {\n      message: opts.message ?? 'Authentication required.',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n/**\n * Credentials were presented but rejected — revoked, malformed signature,\n * or a key no longer in the seller's keystore. Recovery: terminal — do NOT\n * auto-retry. Auto-retry creates an SSO retry-storm indistinguishable from\n * brute-force probing. The decisioning runtime treats this as terminal even\n * when an account store has a refresh hook.\n *\n * **Credential-leak guard.** `opts.message` and `opts.details` cross to\n * the buyer verbatim on the wire envelope. Do NOT place rejected\n * credentials, token fragments, JWT payload material, or upstream\n * identity-provider error bodies in either field — log those server-side\n * instead. The framework is a witness, not a redactor.\n *\n * @since AdCP 3.1 (adcp#3730 splits `AUTH_REQUIRED`).\n */\nexport class AuthInvalidError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('AUTH_INVALID', {\n      message: opts.message ?? 'Authentication failed: credentials rejected.',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class PermissionDeniedError extends AdcpError {\n  constructor(action: string, opts: CommonOpts = {}) {\n    super('PERMISSION_DENIED', {\n      message: opts.message ?? `Permission denied for ${action}.`,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      details: { ...(opts.details ?? {}), action },\n    });\n  }\n}\n\n/**\n * The buyer agent's commercial relationship with the seller is suspended.\n * Recovery: terminal at the wire level — a buyer cannot \"wait out\" a\n * suspension by retrying the same request. The transient-vs-permanent\n * distinction lives at the seller's `BuyerAgent.status` record, not on the\n * wire.\n *\n * Consolidates the 3.0.5 placeholder shape\n * `PERMISSION_DENIED + details.scope:'agent' + details.status:'suspended'`,\n * which is removed in 3.1 (envelopes carrying `details.status` fail schema\n * validation).\n *\n * @since AdCP 3.1 (adcp#3906 consolidates the `details.status` placeholder).\n */\nexport class AgentSuspendedError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('AGENT_SUSPENDED', {\n      message: opts.message ?? 'Buyer agent is suspended. Contact the seller to restore access.',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n/**\n * The buyer agent is permanently denied by the seller. Recovery: terminal —\n * re-onboarding under a new agent identity is the only recovery path.\n *\n * Consolidates the 3.0.5 placeholder shape\n * `PERMISSION_DENIED + details.scope:'agent' + details.status:'blocked'`,\n * which is removed in 3.1.\n *\n * @since AdCP 3.1 (adcp#3906 consolidates the `details.status` placeholder).\n */\nexport class AgentBlockedError extends AdcpError {\n  constructor(opts: CommonOpts = {}) {\n    super('AGENT_BLOCKED', {\n      message: opts.message ?? 'Buyer agent is blocked.',\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Throttling / availability family\n// ---------------------------------------------------------------------------\n\nexport class RateLimitedError extends AdcpError {\n  constructor(retryAfterSeconds: number, opts: CommonOpts = {}) {\n    super('RATE_LIMITED', {\n      message: opts.message ?? `Rate limited. Retry after ${retryAfterSeconds}s.`,\n      retry_after: Math.max(1, Math.min(3600, Math.floor(retryAfterSeconds))),\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class ServiceUnavailableError extends AdcpError {\n  constructor(opts: CommonOpts & { retryAfterSeconds?: number } = {}) {\n    super('SERVICE_UNAVAILABLE', {\n      message: opts.message ?? 'Service temporarily unavailable.',\n      retry_after:\n        opts.retryAfterSeconds != null ? Math.max(1, Math.min(3600, Math.floor(opts.retryAfterSeconds))) : 60,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      ...(opts.details !== undefined && { details: opts.details }),\n    });\n  }\n}\n\nexport class UnsupportedFeatureError extends AdcpError {\n  constructor(feature: string, opts: CommonOpts = {}) {\n    super('UNSUPPORTED_FEATURE', {\n      message: opts.message ?? `Feature not supported: ${feature}.`,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      details: { ...(opts.details ?? {}), feature },\n    });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Compliance / governance family\n// ---------------------------------------------------------------------------\n\nexport class ComplianceUnsatisfiedError extends AdcpError {\n  constructor(reason: string, opts: CommonOpts = {}) {\n    super('COMPLIANCE_UNSATISFIED', {\n      message: opts.message ?? `Compliance not satisfied: ${reason}`,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      details: { ...(opts.details ?? {}), reason },\n    });\n  }\n}\n\nexport class GovernanceDeniedError extends AdcpError {\n  constructor(reason: string, opts: CommonOpts = {}) {\n    super('GOVERNANCE_DENIED', {\n      message: opts.message ?? `Governance denied: ${reason}`,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      details: { ...(opts.details ?? {}), reason },\n    });\n  }\n}\n\nexport class PolicyViolationError extends AdcpError {\n  constructor(policy: string, opts: CommonOpts = {}) {\n    super('POLICY_VIOLATION', {\n      message: opts.message ?? `Policy violation: ${policy}`,\n      ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),\n      details: { ...(opts.details ?? {}), policy },\n    });\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/lib/server/decisioning/helpers.mjs

@@ -1,9 +1,3 @@
-import { fileURLToPath as __adcpFileURLToPath } from 'node:url';
-import { dirname as __adcpDirname } from 'node:path';
-import { createRequire as __adcpCreateRequire } from 'node:module';
-const __filename = __adcpFileURLToPath(import.meta.url);
-const __dirname = __adcpDirname(__filename);
-const require = __adcpCreateRequire(import.meta.url);
 import { AdcpError } from "./async-outcome.mjs";
 import { pickSafeDetails } from "../pick-safe-details.mjs";
 async function batchPoll(ids, lookup) {

package/dist/lib/server/decisioning/helpers.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/server/decisioning/helpers.ts"],"sourcesContent":["/**\n * Adopter utility helpers for DecisioningPlatform implementations.\n *\n * All exports are opt-in convenience — nothing in the framework calls\n * these internally. They lift boilerplate that every adopter with the\n * corresponding pattern would otherwise rewrite from scratch.\n *\n * @public\n */\n\nimport { AdcpError, type ErrorCode } from './async-outcome';\nimport { pickSafeDetails } from '../pick-safe-details';\n\n// ---------------------------------------------------------------------------\n// batchPoll\n// ---------------------------------------------------------------------------\n\n/**\n * Project a per-id Result-returning lookup into the `pollAudienceStatuses`\n * `Map<id, status>` shape.\n *\n * Runs all lookups in parallel. Drops entries where `result.isOk()` is\n * false OR `result.value` is `undefined` — per the SDK contract, not-found\n * entries are omitted from the map (callers handle missing keys via\n * `Map.prototype.get`).\n *\n * Typical use in `AudiencePlatform.pollAudienceStatuses`:\n *\n * ```ts\n * import { batchPoll } from '@adcp/sdk/server/decisioning';\n *\n * async pollAudienceStatuses(audienceIds, ctx) {\n *   return batchPoll(audienceIds, async (id) =>\n *     this.myPlatform.getAudienceStatus(id, ctx.account.ctx_metadata.token)\n *   );\n * }\n * ```\n *\n * The `lookup` return type is structural — any object with `isOk(): boolean`\n * and `value?: TValue` matches (`neverthrow`, `fp-ts`, or custom Result types\n * all work without wrapping).\n *\n * @public\n */\nexport async function batchPoll<TKey extends string, TValue>(\n  ids: readonly TKey[],\n  lookup: (id: TKey) => Promise<{ isOk(): boolean; value?: TValue }>\n): Promise<Map<TKey, TValue>> {\n  const pairs = await Promise.all(\n    ids.map(async id => {\n      const r = await lookup(id);\n      return [id, r] as const;\n    })\n  );\n  const result = new Map<TKey, TValue>();\n  for (const [id, r] of pairs) {\n    if (r.isOk() && r.value !== undefined) {\n      result.set(id, r.value);\n    }\n  }\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// Error factory helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Construct an `AdcpError` for a buyer-correctable validation failure.\n * Shorthand for `new AdcpError('VALIDATION_ERROR', { recovery: 'correctable', ... })`.\n *\n * ```ts\n * import { validationError } from '@adcp/sdk/server/decisioning';\n *\n * if (!req.targeting?.geos?.length) {\n *   throw validationError('At least one geo is required', {\n *     field: 'targeting.geos',\n *   });\n * }\n * ```\n *\n * @param message - Human-readable explanation of the validation failure.\n * @param opts.field - Wire `field` path (e.g. `'targeting.geos'`).\n * @param opts.code - Override the error code (default `'VALIDATION_ERROR'`).\n * @public\n */\nexport function validationError(\n  message: string,\n  opts?: { field?: string; code?: ErrorCode | (string & {}) }\n): AdcpError {\n  return new AdcpError((opts?.code ?? 'VALIDATION_ERROR') as ErrorCode, {\n    message,\n    ...(opts?.field !== undefined && { field: opts.field }),\n  });\n}\n\n/**\n * Construct an `AdcpError` for an upstream-platform failure (5xx /\n * rate-limited). `extraDetails` is run through {@link pickSafeDetails}\n * internally — depth-capped and size-capped — so credentials or stack\n * traces the caller accidentally included don't cross the wire boundary.\n *\n * HTTP 429 maps to `RATE_LIMITED` (with `retry_after: 60`). All other\n * upstream failures map to `SERVICE_UNAVAILABLE`. Both use\n * `recovery: 'transient'`.\n *\n * ```ts\n * import { upstreamError } from '@adcp/sdk/server/decisioning';\n *\n * try {\n *   return await this.gam.createOrder(req);\n * } catch (e) {\n *   throw upstreamError('GAM order creation failed', e, {\n *     gam_error_code: e.errorCode,\n *     request_id: e.requestId,\n *   });\n * }\n * ```\n *\n * @param prefix - Short description of the operation that failed\n *   (e.g. `'GAM order creation failed'`). Prepended to the upstream message.\n * @param e - Upstream error. Only `message`, `code`, and `status` are read;\n *   all other fields are ignored.\n * @param extraDetails - Optional pre-selected safe fields to surface to the\n *   buyer. Run through `pickSafeDetails` with depth/size caps before attaching\n *   to the wire envelope.\n * @public\n */\nexport function upstreamError(\n  prefix: string,\n  e: { message?: string; code?: number | string; status?: number },\n  extraDetails?: Record<string, unknown>\n): AdcpError {\n  const statusCode = e.status ?? (typeof e.code === 'number' ? e.code : undefined);\n  const isRateLimited = statusCode === 429;\n  const errorCode: ErrorCode = isRateLimited ? 'RATE_LIMITED' : 'SERVICE_UNAVAILABLE';\n  const upstreamMsg = typeof e.message === 'string' && e.message.length > 0 ? e.message : 'upstream error';\n  const details = extraDetails !== undefined ? pickSafeDetails(extraDetails, Object.keys(extraDetails)) : undefined;\n\n  return new AdcpError(errorCode, {\n    message: `${prefix}: ${upstreamMsg}`,\n    ...(isRateLimited && { retry_after: 60 }),\n    ...(details !== undefined && { details }),\n  });\n}\n\n// ---------------------------------------------------------------------------\n// RequestShape<T>\n// ---------------------------------------------------------------------------\n\n/**\n * Strip index signatures from a wire request type for back-compat with\n * v5-era task functions whose parameter types don't carry the spec's\n * `additionalProperties: true` index signature (`[x: string]: unknown`).\n *\n * Without this, passing a v6 wire type directly to a v5 task fn produces:\n *\n * ```\n * Type 'CreateMediaBuyRequest' is not assignable to type\n *   'Parameters<typeof createMediaBuyTask>[1]'\n * ```\n *\n * because generated v6 types include `[x: string]: unknown` for\n * forward-compat but v5 fn signatures were authored without it.\n *\n * ```ts\n * import type { RequestShape } from '@adcp/sdk/server/decisioning';\n *\n * const result = await createMediaBuyTask(\n *   snapCtx(account),\n *   req as RequestShape<typeof req>, // drops index sig for v5 adapter compat\n * );\n * ```\n *\n * @public\n */\nexport type RequestShape<T> = { [K in keyof T]: T[K] };\n"],"mappings":";;;;;;AAUA,SAAS,iBAAiC;AAC1C,SAAS,uBAAuB;AAiChC,eAAsB,UACpB,KACA,QAC4B;AAC5B,QAAM,QAAQ,MAAM,QAAQ;AAAA,IAC1B,IAAI,IAAI,OAAM,OAAM;AAClB,YAAM,IAAI,MAAM,OAAO,EAAE;AACzB,aAAO,CAAC,IAAI,CAAC;AAAA,IACf,CAAC;AAAA,EACH;AACA,QAAM,SAAS,oBAAI,IAAkB;AACrC,aAAW,CAAC,IAAI,CAAC,KAAK,OAAO;AAC3B,QAAI,EAAE,KAAK,KAAK,EAAE,UAAU,QAAW;AACrC,aAAO,IAAI,IAAI,EAAE,KAAK;AAAA,IACxB;AAAA,EACF;AACA,SAAO;AACT;AAyBO,SAAS,gBACd,SACA,MACW;AACX,SAAO,IAAI,UAAW,MAAM,QAAQ,oBAAkC;AAAA,IACpE;AAAA,IACA,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,KAAK,MAAM;AAAA,EACvD,CAAC;AACH;AAkCO,SAAS,cACd,QACA,GACA,cACW;AACX,QAAM,aAAa,EAAE,WAAW,OAAO,EAAE,SAAS,WAAW,EAAE,OAAO;AACtE,QAAM,gBAAgB,eAAe;AACrC,QAAM,YAAuB,gBAAgB,iBAAiB;AAC9D,QAAM,cAAc,OAAO,EAAE,YAAY,YAAY,EAAE,QAAQ,SAAS,IAAI,EAAE,UAAU;AACxF,QAAM,UAAU,iBAAiB,SAAY,gBAAgB,cAAc,OAAO,KAAK,YAAY,CAAC,IAAI;AAExG,SAAO,IAAI,UAAU,WAAW;AAAA,IAC9B,SAAS,GAAG,MAAM,KAAK,WAAW;AAAA,IAClC,GAAI,iBAAiB,EAAE,aAAa,GAAG;AAAA,IACvC,GAAI,YAAY,UAAa,EAAE,QAAQ;AAAA,EACzC,CAAC;AACH;","names":[]}
+{"version":3,"sources":["../../../../src/lib/server/decisioning/helpers.ts"],"sourcesContent":["/**\n * Adopter utility helpers for DecisioningPlatform implementations.\n *\n * All exports are opt-in convenience — nothing in the framework calls\n * these internally. They lift boilerplate that every adopter with the\n * corresponding pattern would otherwise rewrite from scratch.\n *\n * @public\n */\n\nimport { AdcpError, type ErrorCode } from './async-outcome';\nimport { pickSafeDetails } from '../pick-safe-details';\n\n// ---------------------------------------------------------------------------\n// batchPoll\n// ---------------------------------------------------------------------------\n\n/**\n * Project a per-id Result-returning lookup into the `pollAudienceStatuses`\n * `Map<id, status>` shape.\n *\n * Runs all lookups in parallel. Drops entries where `result.isOk()` is\n * false OR `result.value` is `undefined` — per the SDK contract, not-found\n * entries are omitted from the map (callers handle missing keys via\n * `Map.prototype.get`).\n *\n * Typical use in `AudiencePlatform.pollAudienceStatuses`:\n *\n * ```ts\n * import { batchPoll } from '@adcp/sdk/server/decisioning';\n *\n * async pollAudienceStatuses(audienceIds, ctx) {\n *   return batchPoll(audienceIds, async (id) =>\n *     this.myPlatform.getAudienceStatus(id, ctx.account.ctx_metadata.token)\n *   );\n * }\n * ```\n *\n * The `lookup` return type is structural — any object with `isOk(): boolean`\n * and `value?: TValue` matches (`neverthrow`, `fp-ts`, or custom Result types\n * all work without wrapping).\n *\n * @public\n */\nexport async function batchPoll<TKey extends string, TValue>(\n  ids: readonly TKey[],\n  lookup: (id: TKey) => Promise<{ isOk(): boolean; value?: TValue }>\n): Promise<Map<TKey, TValue>> {\n  const pairs = await Promise.all(\n    ids.map(async id => {\n      const r = await lookup(id);\n      return [id, r] as const;\n    })\n  );\n  const result = new Map<TKey, TValue>();\n  for (const [id, r] of pairs) {\n    if (r.isOk() && r.value !== undefined) {\n      result.set(id, r.value);\n    }\n  }\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// Error factory helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Construct an `AdcpError` for a buyer-correctable validation failure.\n * Shorthand for `new AdcpError('VALIDATION_ERROR', { recovery: 'correctable', ... })`.\n *\n * ```ts\n * import { validationError } from '@adcp/sdk/server/decisioning';\n *\n * if (!req.targeting?.geos?.length) {\n *   throw validationError('At least one geo is required', {\n *     field: 'targeting.geos',\n *   });\n * }\n * ```\n *\n * @param message - Human-readable explanation of the validation failure.\n * @param opts.field - Wire `field` path (e.g. `'targeting.geos'`).\n * @param opts.code - Override the error code (default `'VALIDATION_ERROR'`).\n * @public\n */\nexport function validationError(\n  message: string,\n  opts?: { field?: string; code?: ErrorCode | (string & {}) }\n): AdcpError {\n  return new AdcpError((opts?.code ?? 'VALIDATION_ERROR') as ErrorCode, {\n    message,\n    ...(opts?.field !== undefined && { field: opts.field }),\n  });\n}\n\n/**\n * Construct an `AdcpError` for an upstream-platform failure (5xx /\n * rate-limited). `extraDetails` is run through {@link pickSafeDetails}\n * internally — depth-capped and size-capped — so credentials or stack\n * traces the caller accidentally included don't cross the wire boundary.\n *\n * HTTP 429 maps to `RATE_LIMITED` (with `retry_after: 60`). All other\n * upstream failures map to `SERVICE_UNAVAILABLE`. Both use\n * `recovery: 'transient'`.\n *\n * ```ts\n * import { upstreamError } from '@adcp/sdk/server/decisioning';\n *\n * try {\n *   return await this.gam.createOrder(req);\n * } catch (e) {\n *   throw upstreamError('GAM order creation failed', e, {\n *     gam_error_code: e.errorCode,\n *     request_id: e.requestId,\n *   });\n * }\n * ```\n *\n * @param prefix - Short description of the operation that failed\n *   (e.g. `'GAM order creation failed'`). Prepended to the upstream message.\n * @param e - Upstream error. Only `message`, `code`, and `status` are read;\n *   all other fields are ignored.\n * @param extraDetails - Optional pre-selected safe fields to surface to the\n *   buyer. Run through `pickSafeDetails` with depth/size caps before attaching\n *   to the wire envelope.\n * @public\n */\nexport function upstreamError(\n  prefix: string,\n  e: { message?: string; code?: number | string; status?: number },\n  extraDetails?: Record<string, unknown>\n): AdcpError {\n  const statusCode = e.status ?? (typeof e.code === 'number' ? e.code : undefined);\n  const isRateLimited = statusCode === 429;\n  const errorCode: ErrorCode = isRateLimited ? 'RATE_LIMITED' : 'SERVICE_UNAVAILABLE';\n  const upstreamMsg = typeof e.message === 'string' && e.message.length > 0 ? e.message : 'upstream error';\n  const details = extraDetails !== undefined ? pickSafeDetails(extraDetails, Object.keys(extraDetails)) : undefined;\n\n  return new AdcpError(errorCode, {\n    message: `${prefix}: ${upstreamMsg}`,\n    ...(isRateLimited && { retry_after: 60 }),\n    ...(details !== undefined && { details }),\n  });\n}\n\n// ---------------------------------------------------------------------------\n// RequestShape<T>\n// ---------------------------------------------------------------------------\n\n/**\n * Strip index signatures from a wire request type for back-compat with\n * v5-era task functions whose parameter types don't carry the spec's\n * `additionalProperties: true` index signature (`[x: string]: unknown`).\n *\n * Without this, passing a v6 wire type directly to a v5 task fn produces:\n *\n * ```\n * Type 'CreateMediaBuyRequest' is not assignable to type\n *   'Parameters<typeof createMediaBuyTask>[1]'\n * ```\n *\n * because generated v6 types include `[x: string]: unknown` for\n * forward-compat but v5 fn signatures were authored without it.\n *\n * ```ts\n * import type { RequestShape } from '@adcp/sdk/server/decisioning';\n *\n * const result = await createMediaBuyTask(\n *   snapCtx(account),\n *   req as RequestShape<typeof req>, // drops index sig for v5 adapter compat\n * );\n * ```\n *\n * @public\n */\nexport type RequestShape<T> = { [K in keyof T]: T[K] };\n"],"mappings":"AAUA,SAAS,iBAAiC;AAC1C,SAAS,uBAAuB;AAiChC,eAAsB,UACpB,KACA,QAC4B;AAC5B,QAAM,QAAQ,MAAM,QAAQ;AAAA,IAC1B,IAAI,IAAI,OAAM,OAAM;AAClB,YAAM,IAAI,MAAM,OAAO,EAAE;AACzB,aAAO,CAAC,IAAI,CAAC;AAAA,IACf,CAAC;AAAA,EACH;AACA,QAAM,SAAS,oBAAI,IAAkB;AACrC,aAAW,CAAC,IAAI,CAAC,KAAK,OAAO;AAC3B,QAAI,EAAE,KAAK,KAAK,EAAE,UAAU,QAAW;AACrC,aAAO,IAAI,IAAI,EAAE,KAAK;AAAA,IACxB;AAAA,EACF;AACA,SAAO;AACT;AAyBO,SAAS,gBACd,SACA,MACW;AACX,SAAO,IAAI,UAAW,MAAM,QAAQ,oBAAkC;AAAA,IACpE;AAAA,IACA,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,KAAK,MAAM;AAAA,EACvD,CAAC;AACH;AAkCO,SAAS,cACd,QACA,GACA,cACW;AACX,QAAM,aAAa,EAAE,WAAW,OAAO,EAAE,SAAS,WAAW,EAAE,OAAO;AACtE,QAAM,gBAAgB,eAAe;AACrC,QAAM,YAAuB,gBAAgB,iBAAiB;AAC9D,QAAM,cAAc,OAAO,EAAE,YAAY,YAAY,EAAE,QAAQ,SAAS,IAAI,EAAE,UAAU;AACxF,QAAM,UAAU,iBAAiB,SAAY,gBAAgB,cAAc,OAAO,KAAK,YAAY,CAAC,IAAI;AAExG,SAAO,IAAI,UAAU,WAAW;AAAA,IAC9B,SAAS,GAAG,MAAM,KAAK,WAAW;AAAA,IAClC,GAAI,iBAAiB,EAAE,aAAa,GAAG;AAAA,IACvC,GAAI,YAAY,UAAa,EAAE,QAAQ;AAAA,EACzC,CAAC;AACH;","names":[]}