@adcp/sdk 13.0.0-rc.13 → 13.0.0-rc.15

package/dist/lib/schemas-data/3.1/trusted-match/offer-price.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.11/trusted-match/offer-price.json",
+  "$id": "/schemas/3.1.13/trusted-match/offer-price.json",
   "title": "Offer Price",
   "description": "Lightweight price for a TMP offer. Used when the product supports variable pricing and the buyer specifies a price at match time.",
   "x-status": "experimental",

package/dist/lib/schemas-data/3.1/trusted-match/offer.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.11/trusted-match/offer.json",
+  "$id": "/schemas/3.1.13/trusted-match/offer.json",
   "title": "Offer",
   "description": "A buyer's response to a context match request. Generalizes package activation — a simple activation is an offer with just package_id. A rich response includes brand, price, summary, and optionally an inline creative manifest.",
   "x-status": "experimental",
@@ -11,15 +11,15 @@
       "description": "Package identifier from the media buy."
     },
     "seller_agent": {
-      "$ref": "/schemas/3.1.11/core/seller-agent-ref.json",
+      "$ref": "/schemas/3.1.13/core/seller-agent-ref.json",
       "description": "Optional echo of the package's seller agent from sync-time metadata. Provided for publisher-side observability so log pipelines can attribute offers to sellers without round-tripping to the media-buy store. Non-authoritative: the binding on the cached AvailablePackage is source of truth. When omitted, the router MAY stamp this field from its cached package→seller map."
     },
     "brand": {
-      "$ref": "/schemas/3.1.11/core/brand-ref.json",
+      "$ref": "/schemas/3.1.13/core/brand-ref.json",
       "description": "Brand for this offer. Required when the product allows dynamic brands (brand selected at match time rather than fixed on the package). For single-brand packages, the brand is already known from the media buy."
     },
     "price": {
-      "$ref": "/schemas/3.1.11/trusted-match/offer-price.json",
+      "$ref": "/schemas/3.1.13/trusted-match/offer-price.json",
       "description": "Price for this offer. Only present when the product supports variable pricing. For fixed-price packages, price is already set on the media buy."
     },
     "summary": {
@@ -27,7 +27,7 @@
       "description": "Buyer-generated description of the offer, for the publisher to judge relevance. E.g., '50% off Goldenfield mayo — recipe integration'. The publisher (or their AI assistant) uses this to decide whether the offer fits the context."
     },
     "creative_manifest": {
-      "$ref": "/schemas/3.1.11/core/creative-manifest.json",
+      "$ref": "/schemas/3.1.13/core/creative-manifest.json",
       "description": "Full creative details, inline. When present, the publisher has everything needed to render. Inline for small creatives (markdown, product card). For large creatives (VAST, video), the manifest references external assets via URLs."
     },
     "macros": {

package/dist/lib/schemas-data/3.1/trusted-match/provider-identity-match-response.json

@@ -1,15 +1,15 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.11/trusted-match/provider-identity-match-response.json",
+  "$id": "/schemas/3.1.13/trusted-match/provider-identity-match-response.json",
   "title": "Identity Match Response (Provider → Router)",
   "description": "Provider-to-router shape of the Identity Match response. An identity agent returns eligibility, the per-package serve-window throttle, and — when it mints one — an ordered list of TMPX chunks. Each chunk pairs a provider-local `slot_id` (declared at registration in `tmpx_slots`) with an opaque URL-safe `value`. Publisher-local destination names (ad-server macros, GAM key-values, VAST URL macros, DOOH play-log fields) MUST NOT appear on this hop; the router keys chunks under the emitting `provider_id` and the publisher's deployment configuration resolves `(provider_id, slot_id)` to the local destination (see publisher-tmpx-config.json). Router-hop fields (`tmpx_providers`, `tmpx`) MUST NOT appear on this shape — a router receiving them from a provider MUST reject the response. Envelope extension fields (`context`, `ext`) are intentionally omitted to prevent data leakage across the identity privacy boundary; they are forbidden by this schema.",
   "type": "object",
   "allOf": [
     {
-      "$ref": "/schemas/3.1.11/core/version-envelope.json"
+      "$ref": "/schemas/3.1.13/core/version-envelope.json"
     },
     {
-      "$ref": "/schemas/3.1.11/core/protocol-envelope.json"
+      "$ref": "/schemas/3.1.13/core/protocol-envelope.json"
     }
   ],
   "x-status": "experimental",
@@ -40,7 +40,7 @@
       "type": "array",
       "description": "Ordered TMPX chunk/value pairs this identity agent mints. Each entry names the provider-local `slot_id` the value fills (from the provider's registered `tmpx_slots` in provider-registration.json). Ordered-prefix invariant: a response that carries fewer chunks than the provider registered MUST emit an ordered prefix of the registered `tmpx_slots` — routers MUST NOT reorder or fill gaps. The router MUST validate this contract before forwarding: if the provider has no `tmpx_slots` registration, or if the chunk `slot_id` sequence is not an exact non-empty ordered prefix of the registered list (duplicate, reordered, sparse, or unregistered slot IDs), the router MUST drop that provider's chunks atomically and MUST NOT forward them into `tmpx_providers`. Cap of 2 chunks in v1 aligned with the GAM macro-slot budget; the cap MAY rise without a shape change. Omitted when this provider mints no TMPX (e.g. no eligible packages).",
       "items": {
-        "$ref": "/schemas/3.1.11/trusted-match/tmpx-chunk.json"
+        "$ref": "/schemas/3.1.13/trusted-match/tmpx-chunk.json"
       },
       "minItems": 1,
       "maxItems": 2

package/dist/lib/schemas-data/3.1/trusted-match/provider-registration.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.11/trusted-match/provider-registration.json",
+  "$id": "/schemas/3.1.13/trusted-match/provider-registration.json",
   "title": "TMP Provider Registration",
   "description": "Declares a TMP provider's endpoint, capabilities, and operational parameters. Used in router configuration (static YAML or dynamic API) and referenced by product-level provider entries. The publisher controls which providers participate in their ad decisioning. Endpoint URLs MUST be validated against SSRF, and dynamic registration endpoints MUST authenticate callers — see docs/trusted-match/specification#provider-registration-security.",
   "x-status": "experimental",
@@ -39,7 +39,7 @@
       "type": "array",
       "description": "Identity types this provider can resolve. The router selects Identity Match providers whose uid_types overlaps with any uid_type in the request's identities array. MUST be present and non-empty when identity_match is true.",
       "items": {
-        "$ref": "/schemas/3.1.11/enums/uid-type.json"
+        "$ref": "/schemas/3.1.13/enums/uid-type.json"
       },
       "minItems": 1
     },

package/dist/lib/schemas-data/3.1/trusted-match/publisher-tmpx-config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.11/trusted-match/publisher-tmpx-config.json",
+  "$id": "/schemas/3.1.13/trusted-match/publisher-tmpx-config.json",
   "title": "Publisher TMPX Macro Mapping",
   "description": "Publisher-owned deployment configuration that maps each identity provider's TMPX slots to the ad-server macro names (or targeting keys, VAST substitutions, DOOH play-log fields) the publisher wants those chunks fired into on this surface. Mapping is authored by the publisher — the same operator who trafficks the corresponding ad-server line items — and never travels on the wire between identity provider and router. This keeps macro naming a deployment concern rather than a protocol identifier: providers emit chunks as `{slot_id, value}` pairs (see provider-identity-match-response.json), the router preserves ordering and slot IDs under the emitting `provider_id` (see identity-match-response.json), and this configuration resolves each `(provider_id, slot_id)` to a local destination on the way to the ad server. A publisher may map the same provider to different destinations across surfaces (GAM key-values vs. VAST macros vs. DOOH play-log fields) by carrying one instance of this configuration per surface.",
   "x-status": "experimental",

package/dist/lib/schemas-data/3.1/trusted-match/tmpx-chunk.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.11/trusted-match/tmpx-chunk.json",
+  "$id": "/schemas/3.1.13/trusted-match/tmpx-chunk.json",
   "title": "TMPX Chunk",
   "description": "A single provider TMPX chunk — the provider-local `slot_id` (declared at registration in `tmpx_slots`) and its opaque URL-safe `value`. Same shape on both hops of the Identity Match response: providers emit `tmpx_chunks[]` on the provider→router shape, the router forwards them under `tmpx_providers[provider_id].chunks[]` on the router→publisher shape. Publisher-local destination names never appear here — the publisher's deployment configuration resolves `(provider_id, slot_id)` → local destination via publisher-tmpx-config.json.",
   "x-status": "experimental",

package/dist/lib/schemas-data/v2.5/_provenance.json

@@ -4,5 +4,5 @@
   "source_sha": "4e553ad955f83b49c7d221ab5c3ff78237ad02e3",
   "source_tarball_sha256": "580656d6466ef9f0d1119985e6726c2efea718dc671e2ad30957fcb2fd54af0f",
   "upstream_adcp_version": "2.5.3",
-  "synced_at": "2026-08-10T05:48:43.171Z"
+  "synced_at": "2026-08-11T19:47:16.023Z"
 }

package/dist/lib/server/decisioning/runtime/entity-hydration.generated.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../src/lib/server/decisioning/runtime/entity-hydration.generated.ts"],"sourcesContent":["// Generated entity-hydration field map — do NOT edit by hand\n//\n// Source: `schemas/cache/3.1.11/manifest.json` + per-tool request\n// schemas. Every top-level `x-entity`-tagged string field on a request\n// schema lands here. The runtime hydrator (`from-platform.ts` →\n// `hydrateForTool`) walks this map plus the hand-curated\n// `ENTITY_TO_RESOURCE_KIND` table to drive auto-hydration without\n// re-walking schemas at startup.\n//\n// Renaming-firewall: if the spec renames `media_buy_id` → `mediabuy_id`,\n// the `x-entity` tag travels with it; the next codegen run picks up\n// the new field name automatically.\n//\n// Regenerate with: npm run generate-entity-hydration\n\nexport interface EntityHydrationField {\n  /** Top-level property on the wire request object. */\n  readonly field: string;\n  /** Spec `x-entity` annotation — maps to `ResourceKind` at runtime. */\n  readonly xEntity: string;\n}\n\nexport const TOOL_ENTITY_FIELDS: Readonly<Record<string, ReadonlyArray<EntityHydrationField>>> = {\n  acquire_rights: [\n    { field: \"pricing_option_id\", xEntity: \"vendor_pricing_option\" },\n    { field: \"rights_id\", xEntity: \"rights_grant\" },\n  ],\n  activate_signal: [\n    { field: \"pricing_option_id\", xEntity: \"vendor_pricing_option\" },\n    { field: \"signal_agent_segment_id\", xEntity: \"signal_activation_id\" },\n  ],\n  build_creative: [\n    { field: \"creative_id\", xEntity: \"creative\" },\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n    { field: \"package_id\", xEntity: \"package\" },\n    { field: \"refine_from_build_variant_id\", xEntity: \"build_variant\" },\n    { field: \"transformer_id\", xEntity: \"transformer\" },\n  ],\n  check_governance: [\n    { field: \"plan_id\", xEntity: \"governance_plan\" },\n  ],\n  create_media_buy: [\n    { field: \"plan_id\", xEntity: \"governance_plan\" },\n  ],\n  delete_collection_list: [\n    { field: \"list_id\", xEntity: \"collection_list\" },\n  ],\n  delete_property_list: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n  get_brand_identity: [\n    { field: \"brand_id\", xEntity: \"advertiser_brand\" },\n  ],\n  get_collection_list: [\n    { field: \"list_id\", xEntity: \"collection_list\" },\n  ],\n  get_property_list: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n  get_rights: [\n    { field: \"brand_id\", xEntity: \"rights_holder_brand\" },\n  ],\n  get_task_status: [\n    { field: \"task_id\", xEntity: \"task\" },\n  ],\n  log_event: [\n    { field: \"event_source_id\", xEntity: \"event_source\" },\n  ],\n  preview_creative: [\n    { field: \"creative_id\", xEntity: \"creative\" },\n  ],\n  provide_performance_feedback: [\n    { field: \"creative_id\", xEntity: \"creative\" },\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n    { field: \"package_id\", xEntity: \"package\" },\n  ],\n  report_plan_outcome: [\n    { field: \"check_id\", xEntity: \"governance_check\" },\n    { field: \"plan_id\", xEntity: \"governance_plan\" },\n  ],\n  si_get_offering: [\n    { field: \"offering_id\", xEntity: \"offering\" },\n  ],\n  si_initiate_session: [\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n    { field: \"offering_id\", xEntity: \"offering\" },\n  ],\n  si_send_message: [\n    { field: \"session_id\", xEntity: \"si_session\" },\n  ],\n  si_terminate_session: [\n    { field: \"session_id\", xEntity: \"si_session\" },\n  ],\n  update_collection_list: [\n    { field: \"list_id\", xEntity: \"collection_list\" },\n  ],\n  update_media_buy: [\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n  ],\n  update_property_list: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n  update_rights: [\n    { field: \"pricing_option_id\", xEntity: \"vendor_pricing_option\" },\n    { field: \"rights_id\", xEntity: \"rights_grant\" },\n  ],\n  validate_property_delivery: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n};\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../../../../src/lib/server/decisioning/runtime/entity-hydration.generated.ts"],"sourcesContent":["// Generated entity-hydration field map — do NOT edit by hand\n//\n// Source: `schemas/cache/3.1.13/manifest.json` + per-tool request\n// schemas. Every top-level `x-entity`-tagged string field on a request\n// schema lands here. The runtime hydrator (`from-platform.ts` →\n// `hydrateForTool`) walks this map plus the hand-curated\n// `ENTITY_TO_RESOURCE_KIND` table to drive auto-hydration without\n// re-walking schemas at startup.\n//\n// Renaming-firewall: if the spec renames `media_buy_id` → `mediabuy_id`,\n// the `x-entity` tag travels with it; the next codegen run picks up\n// the new field name automatically.\n//\n// Regenerate with: npm run generate-entity-hydration\n\nexport interface EntityHydrationField {\n  /** Top-level property on the wire request object. */\n  readonly field: string;\n  /** Spec `x-entity` annotation — maps to `ResourceKind` at runtime. */\n  readonly xEntity: string;\n}\n\nexport const TOOL_ENTITY_FIELDS: Readonly<Record<string, ReadonlyArray<EntityHydrationField>>> = {\n  acquire_rights: [\n    { field: \"pricing_option_id\", xEntity: \"vendor_pricing_option\" },\n    { field: \"rights_id\", xEntity: \"rights_grant\" },\n  ],\n  activate_signal: [\n    { field: \"pricing_option_id\", xEntity: \"vendor_pricing_option\" },\n    { field: \"signal_agent_segment_id\", xEntity: \"signal_activation_id\" },\n  ],\n  build_creative: [\n    { field: \"creative_id\", xEntity: \"creative\" },\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n    { field: \"package_id\", xEntity: \"package\" },\n    { field: \"refine_from_build_variant_id\", xEntity: \"build_variant\" },\n    { field: \"transformer_id\", xEntity: \"transformer\" },\n  ],\n  check_governance: [\n    { field: \"plan_id\", xEntity: \"governance_plan\" },\n  ],\n  create_media_buy: [\n    { field: \"plan_id\", xEntity: \"governance_plan\" },\n  ],\n  delete_collection_list: [\n    { field: \"list_id\", xEntity: \"collection_list\" },\n  ],\n  delete_property_list: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n  get_brand_identity: [\n    { field: \"brand_id\", xEntity: \"advertiser_brand\" },\n  ],\n  get_collection_list: [\n    { field: \"list_id\", xEntity: \"collection_list\" },\n  ],\n  get_property_list: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n  get_rights: [\n    { field: \"brand_id\", xEntity: \"rights_holder_brand\" },\n  ],\n  get_task_status: [\n    { field: \"task_id\", xEntity: \"task\" },\n  ],\n  log_event: [\n    { field: \"event_source_id\", xEntity: \"event_source\" },\n  ],\n  preview_creative: [\n    { field: \"creative_id\", xEntity: \"creative\" },\n  ],\n  provide_performance_feedback: [\n    { field: \"creative_id\", xEntity: \"creative\" },\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n    { field: \"package_id\", xEntity: \"package\" },\n  ],\n  report_plan_outcome: [\n    { field: \"check_id\", xEntity: \"governance_check\" },\n    { field: \"plan_id\", xEntity: \"governance_plan\" },\n  ],\n  si_get_offering: [\n    { field: \"offering_id\", xEntity: \"offering\" },\n  ],\n  si_initiate_session: [\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n    { field: \"offering_id\", xEntity: \"offering\" },\n  ],\n  si_send_message: [\n    { field: \"session_id\", xEntity: \"si_session\" },\n  ],\n  si_terminate_session: [\n    { field: \"session_id\", xEntity: \"si_session\" },\n  ],\n  update_collection_list: [\n    { field: \"list_id\", xEntity: \"collection_list\" },\n  ],\n  update_media_buy: [\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n  ],\n  update_property_list: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n  update_rights: [\n    { field: \"pricing_option_id\", xEntity: \"vendor_pricing_option\" },\n    { field: \"rights_id\", xEntity: \"rights_grant\" },\n  ],\n  validate_property_delivery: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n};\n"],"mappings":"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","names":[]}

package/dist/lib/server/decisioning/runtime/entity-hydration.generated.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../src/lib/server/decisioning/runtime/entity-hydration.generated.ts"],"sourcesContent":["// Generated entity-hydration field map — do NOT edit by hand\n//\n// Source: `schemas/cache/3.1.11/manifest.json` + per-tool request\n// schemas. Every top-level `x-entity`-tagged string field on a request\n// schema lands here. The runtime hydrator (`from-platform.ts` →\n// `hydrateForTool`) walks this map plus the hand-curated\n// `ENTITY_TO_RESOURCE_KIND` table to drive auto-hydration without\n// re-walking schemas at startup.\n//\n// Renaming-firewall: if the spec renames `media_buy_id` → `mediabuy_id`,\n// the `x-entity` tag travels with it; the next codegen run picks up\n// the new field name automatically.\n//\n// Regenerate with: npm run generate-entity-hydration\n\nexport interface EntityHydrationField {\n  /** Top-level property on the wire request object. */\n  readonly field: string;\n  /** Spec `x-entity` annotation — maps to `ResourceKind` at runtime. */\n  readonly xEntity: string;\n}\n\nexport const TOOL_ENTITY_FIELDS: Readonly<Record<string, ReadonlyArray<EntityHydrationField>>> = {\n  acquire_rights: [\n    { field: \"pricing_option_id\", xEntity: \"vendor_pricing_option\" },\n    { field: \"rights_id\", xEntity: \"rights_grant\" },\n  ],\n  activate_signal: [\n    { field: \"pricing_option_id\", xEntity: \"vendor_pricing_option\" },\n    { field: \"signal_agent_segment_id\", xEntity: \"signal_activation_id\" },\n  ],\n  build_creative: [\n    { field: \"creative_id\", xEntity: \"creative\" },\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n    { field: \"package_id\", xEntity: \"package\" },\n    { field: \"refine_from_build_variant_id\", xEntity: \"build_variant\" },\n    { field: \"transformer_id\", xEntity: \"transformer\" },\n  ],\n  check_governance: [\n    { field: \"plan_id\", xEntity: \"governance_plan\" },\n  ],\n  create_media_buy: [\n    { field: \"plan_id\", xEntity: \"governance_plan\" },\n  ],\n  delete_collection_list: [\n    { field: \"list_id\", xEntity: \"collection_list\" },\n  ],\n  delete_property_list: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n  get_brand_identity: [\n    { field: \"brand_id\", xEntity: \"advertiser_brand\" },\n  ],\n  get_collection_list: [\n    { field: \"list_id\", xEntity: \"collection_list\" },\n  ],\n  get_property_list: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n  get_rights: [\n    { field: \"brand_id\", xEntity: \"rights_holder_brand\" },\n  ],\n  get_task_status: [\n    { field: \"task_id\", xEntity: \"task\" },\n  ],\n  log_event: [\n    { field: \"event_source_id\", xEntity: \"event_source\" },\n  ],\n  preview_creative: [\n    { field: \"creative_id\", xEntity: \"creative\" },\n  ],\n  provide_performance_feedback: [\n    { field: \"creative_id\", xEntity: \"creative\" },\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n    { field: \"package_id\", xEntity: \"package\" },\n  ],\n  report_plan_outcome: [\n    { field: \"check_id\", xEntity: \"governance_check\" },\n    { field: \"plan_id\", xEntity: \"governance_plan\" },\n  ],\n  si_get_offering: [\n    { field: \"offering_id\", xEntity: \"offering\" },\n  ],\n  si_initiate_session: [\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n    { field: \"offering_id\", xEntity: \"offering\" },\n  ],\n  si_send_message: [\n    { field: \"session_id\", xEntity: \"si_session\" },\n  ],\n  si_terminate_session: [\n    { field: \"session_id\", xEntity: \"si_session\" },\n  ],\n  update_collection_list: [\n    { field: \"list_id\", xEntity: \"collection_list\" },\n  ],\n  update_media_buy: [\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n  ],\n  update_property_list: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n  update_rights: [\n    { field: \"pricing_option_id\", xEntity: \"vendor_pricing_option\" },\n    { field: \"rights_id\", xEntity: \"rights_grant\" },\n  ],\n  validate_property_delivery: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n};\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../../../../src/lib/server/decisioning/runtime/entity-hydration.generated.ts"],"sourcesContent":["// Generated entity-hydration field map — do NOT edit by hand\n//\n// Source: `schemas/cache/3.1.13/manifest.json` + per-tool request\n// schemas. Every top-level `x-entity`-tagged string field on a request\n// schema lands here. The runtime hydrator (`from-platform.ts` →\n// `hydrateForTool`) walks this map plus the hand-curated\n// `ENTITY_TO_RESOURCE_KIND` table to drive auto-hydration without\n// re-walking schemas at startup.\n//\n// Renaming-firewall: if the spec renames `media_buy_id` → `mediabuy_id`,\n// the `x-entity` tag travels with it; the next codegen run picks up\n// the new field name automatically.\n//\n// Regenerate with: npm run generate-entity-hydration\n\nexport interface EntityHydrationField {\n  /** Top-level property on the wire request object. */\n  readonly field: string;\n  /** Spec `x-entity` annotation — maps to `ResourceKind` at runtime. */\n  readonly xEntity: string;\n}\n\nexport const TOOL_ENTITY_FIELDS: Readonly<Record<string, ReadonlyArray<EntityHydrationField>>> = {\n  acquire_rights: [\n    { field: \"pricing_option_id\", xEntity: \"vendor_pricing_option\" },\n    { field: \"rights_id\", xEntity: \"rights_grant\" },\n  ],\n  activate_signal: [\n    { field: \"pricing_option_id\", xEntity: \"vendor_pricing_option\" },\n    { field: \"signal_agent_segment_id\", xEntity: \"signal_activation_id\" },\n  ],\n  build_creative: [\n    { field: \"creative_id\", xEntity: \"creative\" },\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n    { field: \"package_id\", xEntity: \"package\" },\n    { field: \"refine_from_build_variant_id\", xEntity: \"build_variant\" },\n    { field: \"transformer_id\", xEntity: \"transformer\" },\n  ],\n  check_governance: [\n    { field: \"plan_id\", xEntity: \"governance_plan\" },\n  ],\n  create_media_buy: [\n    { field: \"plan_id\", xEntity: \"governance_plan\" },\n  ],\n  delete_collection_list: [\n    { field: \"list_id\", xEntity: \"collection_list\" },\n  ],\n  delete_property_list: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n  get_brand_identity: [\n    { field: \"brand_id\", xEntity: \"advertiser_brand\" },\n  ],\n  get_collection_list: [\n    { field: \"list_id\", xEntity: \"collection_list\" },\n  ],\n  get_property_list: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n  get_rights: [\n    { field: \"brand_id\", xEntity: \"rights_holder_brand\" },\n  ],\n  get_task_status: [\n    { field: \"task_id\", xEntity: \"task\" },\n  ],\n  log_event: [\n    { field: \"event_source_id\", xEntity: \"event_source\" },\n  ],\n  preview_creative: [\n    { field: \"creative_id\", xEntity: \"creative\" },\n  ],\n  provide_performance_feedback: [\n    { field: \"creative_id\", xEntity: \"creative\" },\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n    { field: \"package_id\", xEntity: \"package\" },\n  ],\n  report_plan_outcome: [\n    { field: \"check_id\", xEntity: \"governance_check\" },\n    { field: \"plan_id\", xEntity: \"governance_plan\" },\n  ],\n  si_get_offering: [\n    { field: \"offering_id\", xEntity: \"offering\" },\n  ],\n  si_initiate_session: [\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n    { field: \"offering_id\", xEntity: \"offering\" },\n  ],\n  si_send_message: [\n    { field: \"session_id\", xEntity: \"si_session\" },\n  ],\n  si_terminate_session: [\n    { field: \"session_id\", xEntity: \"si_session\" },\n  ],\n  update_collection_list: [\n    { field: \"list_id\", xEntity: \"collection_list\" },\n  ],\n  update_media_buy: [\n    { field: \"media_buy_id\", xEntity: \"media_buy\" },\n  ],\n  update_property_list: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n  update_rights: [\n    { field: \"pricing_option_id\", xEntity: \"vendor_pricing_option\" },\n    { field: \"rights_id\", xEntity: \"rights_grant\" },\n  ],\n  validate_property_delivery: [\n    { field: \"list_id\", xEntity: \"property_list\" },\n  ],\n};\n"],"mappings":"AAsBO,MAAM,qBAAoF;AAAA,EAC/F,gBAAgB;AAAA,IACd,EAAE,OAAO,qBAAqB,SAAS,wBAAwB;AAAA,IAC/D,EAAE,OAAO,aAAa,SAAS,eAAe;AAAA,EAChD;AAAA,EACA,iBAAiB;AAAA,IACf,EAAE,OAAO,qBAAqB,SAAS,wBAAwB;AAAA,IAC/D,EAAE,OAAO,2BAA2B,SAAS,uBAAuB;AAAA,EACtE;AAAA,EACA,gBAAgB;AAAA,IACd,EAAE,OAAO,eAAe,SAAS,WAAW;AAAA,IAC5C,EAAE,OAAO,gBAAgB,SAAS,YAAY;AAAA,IAC9C,EAAE,OAAO,cAAc,SAAS,UAAU;AAAA,IAC1C,EAAE,OAAO,gCAAgC,SAAS,gBAAgB;AAAA,IAClE,EAAE,OAAO,kBAAkB,SAAS,cAAc;AAAA,EACpD;AAAA,EACA,kBAAkB;AAAA,IAChB,EAAE,OAAO,WAAW,SAAS,kBAAkB;AAAA,EACjD;AAAA,EACA,kBAAkB;AAAA,IAChB,EAAE,OAAO,WAAW,SAAS,kBAAkB;AAAA,EACjD;AAAA,EACA,wBAAwB;AAAA,IACtB,EAAE,OAAO,WAAW,SAAS,kBAAkB;AAAA,EACjD;AAAA,EACA,sBAAsB;AAAA,IACpB,EAAE,OAAO,WAAW,SAAS,gBAAgB;AAAA,EAC/C;AAAA,EACA,oBAAoB;AAAA,IAClB,EAAE,OAAO,YAAY,SAAS,mBAAmB;AAAA,EACnD;AAAA,EACA,qBAAqB;AAAA,IACnB,EAAE,OAAO,WAAW,SAAS,kBAAkB;AAAA,EACjD;AAAA,EACA,mBAAmB;AAAA,IACjB,EAAE,OAAO,WAAW,SAAS,gBAAgB;AAAA,EAC/C;AAAA,EACA,YAAY;AAAA,IACV,EAAE,OAAO,YAAY,SAAS,sBAAsB;AAAA,EACtD;AAAA,EACA,iBAAiB;AAAA,IACf,EAAE,OAAO,WAAW,SAAS,OAAO;AAAA,EACtC;AAAA,EACA,WAAW;AAAA,IACT,EAAE,OAAO,mBAAmB,SAAS,eAAe;AAAA,EACtD;AAAA,EACA,kBAAkB;AAAA,IAChB,EAAE,OAAO,eAAe,SAAS,WAAW;AAAA,EAC9C;AAAA,EACA,8BAA8B;AAAA,IAC5B,EAAE,OAAO,eAAe,SAAS,WAAW;AAAA,IAC5C,EAAE,OAAO,gBAAgB,SAAS,YAAY;AAAA,IAC9C,EAAE,OAAO,cAAc,SAAS,UAAU;AAAA,EAC5C;AAAA,EACA,qBAAqB;AAAA,IACnB,EAAE,OAAO,YAAY,SAAS,mBAAmB;AAAA,IACjD,EAAE,OAAO,WAAW,SAAS,kBAAkB;AAAA,EACjD;AAAA,EACA,iBAAiB;AAAA,IACf,EAAE,OAAO,eAAe,SAAS,WAAW;AAAA,EAC9C;AAAA,EACA,qBAAqB;AAAA,IACnB,EAAE,OAAO,gBAAgB,SAAS,YAAY;AAAA,IAC9C,EAAE,OAAO,eAAe,SAAS,WAAW;AAAA,EAC9C;AAAA,EACA,iBAAiB;AAAA,IACf,EAAE,OAAO,cAAc,SAAS,aAAa;AAAA,EAC/C;AAAA,EACA,sBAAsB;AAAA,IACpB,EAAE,OAAO,cAAc,SAAS,aAAa;AAAA,EAC/C;AAAA,EACA,wBAAwB;AAAA,IACtB,EAAE,OAAO,WAAW,SAAS,kBAAkB;AAAA,EACjD;AAAA,EACA,kBAAkB;AAAA,IAChB,EAAE,OAAO,gBAAgB,SAAS,YAAY;AAAA,EAChD;AAAA,EACA,sBAAsB;AAAA,IACpB,EAAE,OAAO,WAAW,SAAS,gBAAgB;AAAA,EAC/C;AAAA,EACA,eAAe;AAAA,IACb,EAAE,OAAO,qBAAqB,SAAS,wBAAwB;AAAA,IAC/D,EAAE,OAAO,aAAa,SAAS,eAAe;AAAA,EAChD;AAAA,EACA,4BAA4B;AAAA,IAC1B,EAAE,OAAO,WAAW,SAAS,gBAAgB;AAAA,EAC/C;AACF;","names":[]}

package/dist/lib/server/errors.d.mts

@@ -8,6 +8,11 @@ import { type StandardErrorCode, type ErrorRecovery } from '../types/error-codes
 import type { ValidationIssue } from '../validation/schema-validator.mjs';
 export interface AdcpErrorOptions {
     message: string;
+    /**
+     * Opaque request context to echo beside `adcp_error`. Only a non-null,
+     * non-array object is echoable, matching the framework envelope behavior.
+     */
+    context?: unknown;
     /**
      * Override the recovery classification. Defaults to
      * `STANDARD_ERROR_CODES[code].recovery` for known codes, `'terminal'`
@@ -89,6 +94,7 @@ export interface AdcpErrorResponse {
     isError: true;
     structuredContent: {
         adcp_error: AdcpErrorPayload;
+        context?: object;
     };
 }
 /**
@@ -123,15 +129,17 @@ export interface AdcpErrorResponse {
  * ```typescript
  * import { adcpError } from '@adcp/sdk';
  *
- * server.registerTool("get_products", { inputSchema: schema }, async ({ query }) => {
+ * server.registerTool("get_products", { inputSchema: schema }, async request => {
+ *   const { query, context } = request;
  *   if (!products.length) {
  *     return adcpError('PRODUCT_NOT_FOUND', {
  *       message: 'No products match query',
  *       field: 'query',
  *       suggestion: 'Try a broader search term',
+ *       context,
  *     });
  *   }
- *   return { content: [...], structuredContent: { products } };
+ *   return { content: [...], structuredContent: { products, context } };
  * });
  * ```
  */

package/dist/lib/server/errors.d.ts

@@ -8,6 +8,11 @@ import { type StandardErrorCode, type ErrorRecovery } from '../types/error-codes
 import type { ValidationIssue } from '../validation/schema-validator';
 export interface AdcpErrorOptions {
     message: string;
+    /**
+     * Opaque request context to echo beside `adcp_error`. Only a non-null,
+     * non-array object is echoable, matching the framework envelope behavior.
+     */
+    context?: unknown;
     /**
      * Override the recovery classification. Defaults to
      * `STANDARD_ERROR_CODES[code].recovery` for known codes, `'terminal'`
@@ -89,6 +94,7 @@ export interface AdcpErrorResponse {
     isError: true;
     structuredContent: {
         adcp_error: AdcpErrorPayload;
+        context?: object;
     };
 }
 /**
@@ -123,15 +129,17 @@ export interface AdcpErrorResponse {
  * ```typescript
  * import { adcpError } from '@adcp/sdk';
  *
- * server.registerTool("get_products", { inputSchema: schema }, async ({ query }) => {
+ * server.registerTool("get_products", { inputSchema: schema }, async request => {
+ *   const { query, context } = request;
  *   if (!products.length) {
  *     return adcpError('PRODUCT_NOT_FOUND', {
  *       message: 'No products match query',
  *       field: 'query',
  *       suggestion: 'Try a broader search term',
+ *       context,
  *     });
  *   }
- *   return { content: [...], structuredContent: { products } };
+ *   return { content: [...], structuredContent: { products, context } };
  * });
  * ```
  */

package/dist/lib/server/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/lib/server/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAItE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,YAAY,CAAC,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,YAAY,CAAC,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,iBAAiB;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,IAAI,CAAC;IACd,iBAAiB,EAAE;QACjB,UAAU,EAAE,gBAAgB,CAAC;KAC9B,CAAC;CACH;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,iBAAiB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,iBAAiB,CAqB/G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,CAUxG;AAED,wBAAgB,2BAA2B,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEpG"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/lib/server/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAItE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,YAAY,CAAC,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,YAAY,CAAC,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,iBAAiB;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,IAAI,CAAC;IACd,iBAAiB,EAAE;QACjB,UAAU,EAAE,gBAAgB,CAAC;QAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,iBAAiB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,iBAAiB,CAyB/G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,CAUxG;AAED,wBAAgB,2BAA2B,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEpG"}

package/dist/lib/server/errors.js

@@ -26,6 +26,9 @@ module.exports = __toCommonJS(errors_exports);
 var import_error_codes = require('../types/error-codes.js');
 var import_envelope_allowlist = require('./envelope-allowlist.js');
 var import_pick_safe_details = require('./pick-safe-details.js');
+function isEchoableContext(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 const AUTHORIZATION_REQUIRED_DETAIL_KEYS = [
   "required_connections",
   "missing_connections",
@@ -60,10 +63,14 @@ function adcpError(code, options) {
     ...options.details != null && { details: options.details }
   };
   const filtered = applyAdcpErrorAllowlist(code, adcp_error);
+  const structuredContent = {
+    adcp_error: filtered,
+    ...isEchoableContext(options.context) ? { context: options.context } : {}
+  };
   return {
-    content: [{ type: "text", text: JSON.stringify({ adcp_error: filtered }) }],
+    content: [{ type: "text", text: JSON.stringify(structuredContent) }],
     isError: true,
-    structuredContent: { adcp_error: filtered }
+    structuredContent
   };
 }
 function applyAdcpErrorAllowlist(code, payload) {

package/dist/lib/server/errors.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/server/errors.ts"],"sourcesContent":["/**\n * Server-side helpers for producing L3-compliant AdCP error responses.\n *\n * Use `adcpError()` in MCP tool handlers to return structured errors\n * that clients can automatically detect, classify, and act on.\n */\n\nimport {\n  STANDARD_ERROR_CODES,\n  isStandardErrorCode,\n  type StandardErrorCode,\n  type ErrorRecovery,\n} from '../types/error-codes';\nimport type { ValidationIssue } from '../validation/schema-validator';\nimport { ADCP_ERROR_FIELD_ALLOWLIST } from './envelope-allowlist';\nimport { pickSafeDetails } from './pick-safe-details';\n\nexport interface AdcpErrorOptions {\n  message: string;\n  /**\n   * Override the recovery classification. Defaults to\n   * `STANDARD_ERROR_CODES[code].recovery` for known codes, `'terminal'`\n   * otherwise. Dropped from the wire shape for codes whose entry in\n   * `ADCP_ERROR_FIELD_ALLOWLIST` excludes it; normalized back to the\n   * standard table value for allowlisted standard-code envelopes.\n   */\n  recovery?: ErrorRecovery;\n  /**\n   * Name of the request field the error applies to (validation /\n   * constraint errors). Dropped from the wire shape for codes whose\n   * `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g. `IDEMPOTENCY_CONFLICT`\n   * — a conflict response MUST NOT echo prior payload state).\n   */\n  field?: string;\n  /**\n   * Human-readable remediation hint. Dropped from the wire shape for\n   * codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g.\n   * `IDEMPOTENCY_CONFLICT`).\n   */\n  suggestion?: string;\n  /**\n   * Seconds to wait before retrying a transient error. Only meaningful\n   * on retryable codes (`RATE_LIMITED`, `SERVICE_UNAVAILABLE`); dropped\n   * on terminal codes whose allowlist excludes it (`IDEMPOTENCY_CONFLICT`\n   * — a computed `retry_after` on conflict would leak cached-entry age).\n   */\n  retry_after?: number;\n  /**\n   * Code-specific diagnostic payload. Dropped from the wire shape for\n   * codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it\n   * (`IDEMPOTENCY_CONFLICT` — a conflict response MUST NOT echo the\n   * prior request payload or cached response body).\n   */\n  details?: Record<string, unknown>;\n  /**\n   * Schema validation issues surfaced at the top level of `adcp_error`\n   * so operators see JSON Pointers on the first render. Primary use is\n   * `VALIDATION_ERROR`; framework validation hooks populate this\n   * automatically and also mirror the same array to `details.issues`\n   * for buyers that already index into `details` per AdCP spec\n   * convention.\n   */\n  issues?: Array<Omit<ValidationIssue, 'schemaPath'> & { schemaPath?: string }>;\n}\n\nexport interface AdcpErrorPayload {\n  code: string;\n  message: string;\n  /**\n   * Closed-enum classifier. Populated by `adcpError()` from\n   * `STANDARD_ERROR_CODES[code].recovery` unless the caller provides an\n   * override. Marked optional because per-code inside-`adcp_error`\n   * allowlists may deliberately drop it from the wire shape — consumers\n   * reading a payload parsed off the wire MUST tolerate `undefined`.\n   */\n  recovery?: ErrorRecovery;\n  field?: string;\n  suggestion?: string;\n  retry_after?: number;\n  details?: Record<string, unknown>;\n  /**\n   * Schema validation issues (`VALIDATION_ERROR`) exposed at the top\n   * level so the list is the first thing a reader sees when inspecting\n   * the envelope. Also mirrored at `details.issues` for spec-convention\n   * compatibility.\n   */\n  issues?: Array<Omit<ValidationIssue, 'schemaPath'> & { schemaPath?: string }>;\n}\n\nexport interface AdcpErrorResponse {\n  [key: string]: unknown;\n  content: Array<{ type: 'text'; text: string }>;\n  isError: true;\n  structuredContent: {\n    adcp_error: AdcpErrorPayload;\n  };\n}\n\nconst AUTHORIZATION_REQUIRED_DETAIL_KEYS = [\n  'required_connections',\n  'missing_connections',\n  'provider',\n  'connection_type',\n  'required_for',\n  'scope',\n  'status',\n  'resource_ref',\n  'platform_account_id',\n  'identity_id',\n  'handle',\n  'profile_url',\n  'post_id',\n  'post_url',\n  'authorization_url',\n  'authorization_instructions',\n  'checked_at',\n  'expires_at',\n  'reference_authorization',\n] as const;\n\n/**\n * Build an L3-compliant MCP tool error response with all three transport layers:\n *\n * 1. `structuredContent.adcp_error` — programmatic extraction (L3)\n * 2. `content[0].text` — JSON text fallback (L2)\n * 3. `isError: true` — MCP error signal\n *\n * Recovery is auto-populated from the standard error code table when not provided.\n *\n * Before returning, any field NOT allowlisted for the given code in\n * {@link ADCP_ERROR_FIELD_ALLOWLIST} is dropped — sellers get the builder's\n * ergonomics for every code AND the strict wire shape for codes that have\n * a registered allowlist. `IDEMPOTENCY_CONFLICT` is the canonical case:\n * payload-shaped diagnostics like `field`, `suggestion`, and `details`\n * silently drop while standard `recovery` metadata is preserved as the\n * canonical standard-table value. Codes without a registered allowlist\n * pass through unchanged.\n *\n * **Two-layer wire shape.** This builder emits the envelope layer\n * (`structuredContent.adcp_error`) only. For tools whose response\n * schema declares a typed Error arm (`errors[]` required at the top\n * level), the framework dispatcher synthesises the payload-layer\n * `errors[]` from the same data at finalize time, so the wire carries\n * both the envelope marker and the typed Error arm together — no\n * adopter code change required. The list of affected tools is derived\n * at server build from the bundled schema cache. RFC:\n * `docs/proposals/adcperror-two-layer-emission.md`.\n *\n * @example\n * ```typescript\n * import { adcpError } from '@adcp/sdk';\n *\n * server.registerTool(\"get_products\", { inputSchema: schema }, async ({ query }) => {\n *   if (!products.length) {\n *     return adcpError('PRODUCT_NOT_FOUND', {\n *       message: 'No products match query',\n *       field: 'query',\n *       suggestion: 'Try a broader search term',\n *     });\n *   }\n *   return { content: [...], structuredContent: { products } };\n * });\n * ```\n */\nexport function adcpError(code: StandardErrorCode | (string & {}), options: AdcpErrorOptions): AdcpErrorResponse {\n  const recovery = normalizeRecoveryForCode(code, options.recovery);\n\n  const adcp_error: AdcpErrorPayload = {\n    code,\n    message: options.message,\n    recovery,\n    ...(options.field != null && { field: options.field }),\n    ...(options.suggestion != null && { suggestion: options.suggestion }),\n    ...(options.retry_after != null && { retry_after: options.retry_after }),\n    ...(options.issues != null && { issues: options.issues }),\n    ...(options.details != null && { details: options.details }),\n  };\n\n  const filtered = applyAdcpErrorAllowlist(code, adcp_error as unknown as Record<string, unknown>);\n\n  return {\n    content: [{ type: 'text', text: JSON.stringify({ adcp_error: filtered }) }],\n    isError: true,\n    structuredContent: { adcp_error: filtered },\n  };\n}\n\n/**\n * Drop every field not in {@link ADCP_ERROR_FIELD_ALLOWLIST} for `code`.\n * When an allowlisted standard code carries `recovery`, normalize it to\n * the fixed classifier from `STANDARD_ERROR_CODES` instead of trusting a\n * caller-supplied value.\n * Codes without an entry pass through unchanged — the allowlist is\n * opt-in per code, not a global filter. The returned object is re-typed\n * as `AdcpErrorPayload` on the assumption that `code` and `message`\n * (the only required fields) are in every registered allowlist; that\n * invariant is re-asserted at runtime by the module-load check in\n * `envelope-allowlist.ts`.\n */\nexport function applyAdcpErrorAllowlist(code: string, payload: Record<string, unknown>): AdcpErrorPayload {\n  payload = sanitizeAdcpErrorDetails(code, payload);\n  const allowlist = ADCP_ERROR_FIELD_ALLOWLIST[code];\n  if (!allowlist) return payload as unknown as AdcpErrorPayload;\n  const out: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(payload)) {\n    if (!allowlist.has(key)) continue;\n    out[key] = key === 'recovery' ? normalizeAllowlistedRecoveryForCode(code, value) : value;\n  }\n  return out as unknown as AdcpErrorPayload;\n}\n\nexport function sanitizeStructuredAdcpError<T extends { code: string; message: string }>(error: T): T {\n  return applyAdcpErrorAllowlist(error.code, error as unknown as Record<string, unknown>) as unknown as T;\n}\n\nfunction sanitizeAdcpErrorDetails(code: string, payload: Record<string, unknown>): Record<string, unknown> {\n  if (code !== 'AUTHORIZATION_REQUIRED' || payload.details === undefined) return payload;\n\n  const sanitizedDetails = pickSafeDetails(payload.details, AUTHORIZATION_REQUIRED_DETAIL_KEYS, {\n    maxDepth: 4,\n    maxSizeBytes: 4096,\n  });\n  const { details: _details, ...rest } = payload;\n  return sanitizedDetails === undefined ? rest : { ...rest, details: sanitizedDetails };\n}\n\nfunction isErrorRecovery(value: unknown): value is ErrorRecovery {\n  return value === 'transient' || value === 'correctable' || value === 'terminal';\n}\n\nfunction normalizeRecoveryForCode(code: string, value: unknown): ErrorRecovery {\n  return isErrorRecovery(value) ? value : isStandardErrorCode(code) ? STANDARD_ERROR_CODES[code].recovery : 'terminal';\n}\n\nfunction normalizeAllowlistedRecoveryForCode(code: string, value: unknown): ErrorRecovery {\n  if (isStandardErrorCode(code)) {\n    return STANDARD_ERROR_CODES[code].recovery;\n  }\n  return normalizeRecoveryForCode(code, value);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,yBAKO;AAEP,gCAA2C;AAC3C,+BAAgC;AAmFhC,MAAM,qCAAqC;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AA8CO,SAAS,UAAU,MAAyC,SAA8C;AAC/G,QAAM,WAAW,yBAAyB,MAAM,QAAQ,QAAQ;AAEhE,QAAM,aAA+B;AAAA,IACnC;AAAA,IACA,SAAS,QAAQ;AAAA,IACjB;AAAA,IACA,GAAI,QAAQ,SAAS,QAAQ,EAAE,OAAO,QAAQ,MAAM;AAAA,IACpD,GAAI,QAAQ,cAAc,QAAQ,EAAE,YAAY,QAAQ,WAAW;AAAA,IACnE,GAAI,QAAQ,eAAe,QAAQ,EAAE,aAAa,QAAQ,YAAY;AAAA,IACtE,GAAI,QAAQ,UAAU,QAAQ,EAAE,QAAQ,QAAQ,OAAO;AAAA,IACvD,GAAI,QAAQ,WAAW,QAAQ,EAAE,SAAS,QAAQ,QAAQ;AAAA,EAC5D;AAEA,QAAM,WAAW,wBAAwB,MAAM,UAAgD;AAE/F,SAAO;AAAA,IACL,SAAS,CAAC,EAAE,MAAM,QAAQ,MAAM,KAAK,UAAU,EAAE,YAAY,SAAS,CAAC,EAAE,CAAC;AAAA,IAC1E,SAAS;AAAA,IACT,mBAAmB,EAAE,YAAY,SAAS;AAAA,EAC5C;AACF;AAcO,SAAS,wBAAwB,MAAc,SAAoD;AACxG,YAAU,yBAAyB,MAAM,OAAO;AAChD,QAAM,YAAY,qDAA2B,IAAI;AACjD,MAAI,CAAC,UAAW,QAAO;AACvB,QAAM,MAA+B,CAAC;AACtC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AAClD,QAAI,CAAC,UAAU,IAAI,GAAG,EAAG;AACzB,QAAI,GAAG,IAAI,QAAQ,aAAa,oCAAoC,MAAM,KAAK,IAAI;AAAA,EACrF;AACA,SAAO;AACT;AAEO,SAAS,4BAAyE,OAAa;AACpG,SAAO,wBAAwB,MAAM,MAAM,KAA2C;AACxF;AAEA,SAAS,yBAAyB,MAAc,SAA2D;AACzG,MAAI,SAAS,4BAA4B,QAAQ,YAAY,OAAW,QAAO;AAE/E,QAAM,uBAAmB,0CAAgB,QAAQ,SAAS,oCAAoC;AAAA,IAC5F,UAAU;AAAA,IACV,cAAc;AAAA,EAChB,CAAC;AACD,QAAM,EAAE,SAAS,UAAU,GAAG,KAAK,IAAI;AACvC,SAAO,qBAAqB,SAAY,OAAO,EAAE,GAAG,MAAM,SAAS,iBAAiB;AACtF;AAEA,SAAS,gBAAgB,OAAwC;AAC/D,SAAO,UAAU,eAAe,UAAU,iBAAiB,UAAU;AACvE;AAEA,SAAS,yBAAyB,MAAc,OAA+B;AAC7E,SAAO,gBAAgB,KAAK,IAAI,YAAQ,wCAAoB,IAAI,IAAI,wCAAqB,IAAI,EAAE,WAAW;AAC5G;AAEA,SAAS,oCAAoC,MAAc,OAA+B;AACxF,UAAI,wCAAoB,IAAI,GAAG;AAC7B,WAAO,wCAAqB,IAAI,EAAE;AAAA,EACpC;AACA,SAAO,yBAAyB,MAAM,KAAK;AAC7C;","names":[]}
+{"version":3,"sources":["../../../src/lib/server/errors.ts"],"sourcesContent":["/**\n * Server-side helpers for producing L3-compliant AdCP error responses.\n *\n * Use `adcpError()` in MCP tool handlers to return structured errors\n * that clients can automatically detect, classify, and act on.\n */\n\nimport {\n  STANDARD_ERROR_CODES,\n  isStandardErrorCode,\n  type StandardErrorCode,\n  type ErrorRecovery,\n} from '../types/error-codes';\nimport type { ValidationIssue } from '../validation/schema-validator';\nimport { ADCP_ERROR_FIELD_ALLOWLIST } from './envelope-allowlist';\nimport { pickSafeDetails } from './pick-safe-details';\n\nexport interface AdcpErrorOptions {\n  message: string;\n  /**\n   * Opaque request context to echo beside `adcp_error`. Only a non-null,\n   * non-array object is echoable, matching the framework envelope behavior.\n   */\n  context?: unknown;\n  /**\n   * Override the recovery classification. Defaults to\n   * `STANDARD_ERROR_CODES[code].recovery` for known codes, `'terminal'`\n   * otherwise. Dropped from the wire shape for codes whose entry in\n   * `ADCP_ERROR_FIELD_ALLOWLIST` excludes it; normalized back to the\n   * standard table value for allowlisted standard-code envelopes.\n   */\n  recovery?: ErrorRecovery;\n  /**\n   * Name of the request field the error applies to (validation /\n   * constraint errors). Dropped from the wire shape for codes whose\n   * `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g. `IDEMPOTENCY_CONFLICT`\n   * — a conflict response MUST NOT echo prior payload state).\n   */\n  field?: string;\n  /**\n   * Human-readable remediation hint. Dropped from the wire shape for\n   * codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g.\n   * `IDEMPOTENCY_CONFLICT`).\n   */\n  suggestion?: string;\n  /**\n   * Seconds to wait before retrying a transient error. Only meaningful\n   * on retryable codes (`RATE_LIMITED`, `SERVICE_UNAVAILABLE`); dropped\n   * on terminal codes whose allowlist excludes it (`IDEMPOTENCY_CONFLICT`\n   * — a computed `retry_after` on conflict would leak cached-entry age).\n   */\n  retry_after?: number;\n  /**\n   * Code-specific diagnostic payload. Dropped from the wire shape for\n   * codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it\n   * (`IDEMPOTENCY_CONFLICT` — a conflict response MUST NOT echo the\n   * prior request payload or cached response body).\n   */\n  details?: Record<string, unknown>;\n  /**\n   * Schema validation issues surfaced at the top level of `adcp_error`\n   * so operators see JSON Pointers on the first render. Primary use is\n   * `VALIDATION_ERROR`; framework validation hooks populate this\n   * automatically and also mirror the same array to `details.issues`\n   * for buyers that already index into `details` per AdCP spec\n   * convention.\n   */\n  issues?: Array<Omit<ValidationIssue, 'schemaPath'> & { schemaPath?: string }>;\n}\n\nexport interface AdcpErrorPayload {\n  code: string;\n  message: string;\n  /**\n   * Closed-enum classifier. Populated by `adcpError()` from\n   * `STANDARD_ERROR_CODES[code].recovery` unless the caller provides an\n   * override. Marked optional because per-code inside-`adcp_error`\n   * allowlists may deliberately drop it from the wire shape — consumers\n   * reading a payload parsed off the wire MUST tolerate `undefined`.\n   */\n  recovery?: ErrorRecovery;\n  field?: string;\n  suggestion?: string;\n  retry_after?: number;\n  details?: Record<string, unknown>;\n  /**\n   * Schema validation issues (`VALIDATION_ERROR`) exposed at the top\n   * level so the list is the first thing a reader sees when inspecting\n   * the envelope. Also mirrored at `details.issues` for spec-convention\n   * compatibility.\n   */\n  issues?: Array<Omit<ValidationIssue, 'schemaPath'> & { schemaPath?: string }>;\n}\n\nexport interface AdcpErrorResponse {\n  [key: string]: unknown;\n  content: Array<{ type: 'text'; text: string }>;\n  isError: true;\n  structuredContent: {\n    adcp_error: AdcpErrorPayload;\n    context?: object;\n  };\n}\n\nfunction isEchoableContext(value: unknown): value is object {\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\n}\n\nconst AUTHORIZATION_REQUIRED_DETAIL_KEYS = [\n  'required_connections',\n  'missing_connections',\n  'provider',\n  'connection_type',\n  'required_for',\n  'scope',\n  'status',\n  'resource_ref',\n  'platform_account_id',\n  'identity_id',\n  'handle',\n  'profile_url',\n  'post_id',\n  'post_url',\n  'authorization_url',\n  'authorization_instructions',\n  'checked_at',\n  'expires_at',\n  'reference_authorization',\n] as const;\n\n/**\n * Build an L3-compliant MCP tool error response with all three transport layers:\n *\n * 1. `structuredContent.adcp_error` — programmatic extraction (L3)\n * 2. `content[0].text` — JSON text fallback (L2)\n * 3. `isError: true` — MCP error signal\n *\n * Recovery is auto-populated from the standard error code table when not provided.\n *\n * Before returning, any field NOT allowlisted for the given code in\n * {@link ADCP_ERROR_FIELD_ALLOWLIST} is dropped — sellers get the builder's\n * ergonomics for every code AND the strict wire shape for codes that have\n * a registered allowlist. `IDEMPOTENCY_CONFLICT` is the canonical case:\n * payload-shaped diagnostics like `field`, `suggestion`, and `details`\n * silently drop while standard `recovery` metadata is preserved as the\n * canonical standard-table value. Codes without a registered allowlist\n * pass through unchanged.\n *\n * **Two-layer wire shape.** This builder emits the envelope layer\n * (`structuredContent.adcp_error`) only. For tools whose response\n * schema declares a typed Error arm (`errors[]` required at the top\n * level), the framework dispatcher synthesises the payload-layer\n * `errors[]` from the same data at finalize time, so the wire carries\n * both the envelope marker and the typed Error arm together — no\n * adopter code change required. The list of affected tools is derived\n * at server build from the bundled schema cache. RFC:\n * `docs/proposals/adcperror-two-layer-emission.md`.\n *\n * @example\n * ```typescript\n * import { adcpError } from '@adcp/sdk';\n *\n * server.registerTool(\"get_products\", { inputSchema: schema }, async request => {\n *   const { query, context } = request;\n *   if (!products.length) {\n *     return adcpError('PRODUCT_NOT_FOUND', {\n *       message: 'No products match query',\n *       field: 'query',\n *       suggestion: 'Try a broader search term',\n *       context,\n *     });\n *   }\n *   return { content: [...], structuredContent: { products, context } };\n * });\n * ```\n */\nexport function adcpError(code: StandardErrorCode | (string & {}), options: AdcpErrorOptions): AdcpErrorResponse {\n  const recovery = normalizeRecoveryForCode(code, options.recovery);\n\n  const adcp_error: AdcpErrorPayload = {\n    code,\n    message: options.message,\n    recovery,\n    ...(options.field != null && { field: options.field }),\n    ...(options.suggestion != null && { suggestion: options.suggestion }),\n    ...(options.retry_after != null && { retry_after: options.retry_after }),\n    ...(options.issues != null && { issues: options.issues }),\n    ...(options.details != null && { details: options.details }),\n  };\n\n  const filtered = applyAdcpErrorAllowlist(code, adcp_error as unknown as Record<string, unknown>);\n  const structuredContent = {\n    adcp_error: filtered,\n    ...(isEchoableContext(options.context) ? { context: options.context } : {}),\n  };\n\n  return {\n    content: [{ type: 'text', text: JSON.stringify(structuredContent) }],\n    isError: true,\n    structuredContent,\n  };\n}\n\n/**\n * Drop every field not in {@link ADCP_ERROR_FIELD_ALLOWLIST} for `code`.\n * When an allowlisted standard code carries `recovery`, normalize it to\n * the fixed classifier from `STANDARD_ERROR_CODES` instead of trusting a\n * caller-supplied value.\n * Codes without an entry pass through unchanged — the allowlist is\n * opt-in per code, not a global filter. The returned object is re-typed\n * as `AdcpErrorPayload` on the assumption that `code` and `message`\n * (the only required fields) are in every registered allowlist; that\n * invariant is re-asserted at runtime by the module-load check in\n * `envelope-allowlist.ts`.\n */\nexport function applyAdcpErrorAllowlist(code: string, payload: Record<string, unknown>): AdcpErrorPayload {\n  payload = sanitizeAdcpErrorDetails(code, payload);\n  const allowlist = ADCP_ERROR_FIELD_ALLOWLIST[code];\n  if (!allowlist) return payload as unknown as AdcpErrorPayload;\n  const out: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(payload)) {\n    if (!allowlist.has(key)) continue;\n    out[key] = key === 'recovery' ? normalizeAllowlistedRecoveryForCode(code, value) : value;\n  }\n  return out as unknown as AdcpErrorPayload;\n}\n\nexport function sanitizeStructuredAdcpError<T extends { code: string; message: string }>(error: T): T {\n  return applyAdcpErrorAllowlist(error.code, error as unknown as Record<string, unknown>) as unknown as T;\n}\n\nfunction sanitizeAdcpErrorDetails(code: string, payload: Record<string, unknown>): Record<string, unknown> {\n  if (code !== 'AUTHORIZATION_REQUIRED' || payload.details === undefined) return payload;\n\n  const sanitizedDetails = pickSafeDetails(payload.details, AUTHORIZATION_REQUIRED_DETAIL_KEYS, {\n    maxDepth: 4,\n    maxSizeBytes: 4096,\n  });\n  const { details: _details, ...rest } = payload;\n  return sanitizedDetails === undefined ? rest : { ...rest, details: sanitizedDetails };\n}\n\nfunction isErrorRecovery(value: unknown): value is ErrorRecovery {\n  return value === 'transient' || value === 'correctable' || value === 'terminal';\n}\n\nfunction normalizeRecoveryForCode(code: string, value: unknown): ErrorRecovery {\n  return isErrorRecovery(value) ? value : isStandardErrorCode(code) ? STANDARD_ERROR_CODES[code].recovery : 'terminal';\n}\n\nfunction normalizeAllowlistedRecoveryForCode(code: string, value: unknown): ErrorRecovery {\n  if (isStandardErrorCode(code)) {\n    return STANDARD_ERROR_CODES[code].recovery;\n  }\n  return normalizeRecoveryForCode(code, value);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,yBAKO;AAEP,gCAA2C;AAC3C,+BAAgC;AAyFhC,SAAS,kBAAkB,OAAiC;AAC1D,SAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAEA,MAAM,qCAAqC;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAgDO,SAAS,UAAU,MAAyC,SAA8C;AAC/G,QAAM,WAAW,yBAAyB,MAAM,QAAQ,QAAQ;AAEhE,QAAM,aAA+B;AAAA,IACnC;AAAA,IACA,SAAS,QAAQ;AAAA,IACjB;AAAA,IACA,GAAI,QAAQ,SAAS,QAAQ,EAAE,OAAO,QAAQ,MAAM;AAAA,IACpD,GAAI,QAAQ,cAAc,QAAQ,EAAE,YAAY,QAAQ,WAAW;AAAA,IACnE,GAAI,QAAQ,eAAe,QAAQ,EAAE,aAAa,QAAQ,YAAY;AAAA,IACtE,GAAI,QAAQ,UAAU,QAAQ,EAAE,QAAQ,QAAQ,OAAO;AAAA,IACvD,GAAI,QAAQ,WAAW,QAAQ,EAAE,SAAS,QAAQ,QAAQ;AAAA,EAC5D;AAEA,QAAM,WAAW,wBAAwB,MAAM,UAAgD;AAC/F,QAAM,oBAAoB;AAAA,IACxB,YAAY;AAAA,IACZ,GAAI,kBAAkB,QAAQ,OAAO,IAAI,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;AAAA,EAC3E;AAEA,SAAO;AAAA,IACL,SAAS,CAAC,EAAE,MAAM,QAAQ,MAAM,KAAK,UAAU,iBAAiB,EAAE,CAAC;AAAA,IACnE,SAAS;AAAA,IACT;AAAA,EACF;AACF;AAcO,SAAS,wBAAwB,MAAc,SAAoD;AACxG,YAAU,yBAAyB,MAAM,OAAO;AAChD,QAAM,YAAY,qDAA2B,IAAI;AACjD,MAAI,CAAC,UAAW,QAAO;AACvB,QAAM,MAA+B,CAAC;AACtC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AAClD,QAAI,CAAC,UAAU,IAAI,GAAG,EAAG;AACzB,QAAI,GAAG,IAAI,QAAQ,aAAa,oCAAoC,MAAM,KAAK,IAAI;AAAA,EACrF;AACA,SAAO;AACT;AAEO,SAAS,4BAAyE,OAAa;AACpG,SAAO,wBAAwB,MAAM,MAAM,KAA2C;AACxF;AAEA,SAAS,yBAAyB,MAAc,SAA2D;AACzG,MAAI,SAAS,4BAA4B,QAAQ,YAAY,OAAW,QAAO;AAE/E,QAAM,uBAAmB,0CAAgB,QAAQ,SAAS,oCAAoC;AAAA,IAC5F,UAAU;AAAA,IACV,cAAc;AAAA,EAChB,CAAC;AACD,QAAM,EAAE,SAAS,UAAU,GAAG,KAAK,IAAI;AACvC,SAAO,qBAAqB,SAAY,OAAO,EAAE,GAAG,MAAM,SAAS,iBAAiB;AACtF;AAEA,SAAS,gBAAgB,OAAwC;AAC/D,SAAO,UAAU,eAAe,UAAU,iBAAiB,UAAU;AACvE;AAEA,SAAS,yBAAyB,MAAc,OAA+B;AAC7E,SAAO,gBAAgB,KAAK,IAAI,YAAQ,wCAAoB,IAAI,IAAI,wCAAqB,IAAI,EAAE,WAAW;AAC5G;AAEA,SAAS,oCAAoC,MAAc,OAA+B;AACxF,UAAI,wCAAoB,IAAI,GAAG;AAC7B,WAAO,wCAAqB,IAAI,EAAE;AAAA,EACpC;AACA,SAAO,yBAAyB,MAAM,KAAK;AAC7C;","names":[]}

package/dist/lib/server/errors.mjs

@@ -4,6 +4,9 @@ import {
 } from "../types/error-codes.mjs";
 import { ADCP_ERROR_FIELD_ALLOWLIST } from "./envelope-allowlist.mjs";
 import { pickSafeDetails } from "./pick-safe-details.mjs";
+function isEchoableContext(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 const AUTHORIZATION_REQUIRED_DETAIL_KEYS = [
   "required_connections",
   "missing_connections",
@@ -38,10 +41,14 @@ function adcpError(code, options) {
     ...options.details != null && { details: options.details }
   };
   const filtered = applyAdcpErrorAllowlist(code, adcp_error);
+  const structuredContent = {
+    adcp_error: filtered,
+    ...isEchoableContext(options.context) ? { context: options.context } : {}
+  };
   return {
-    content: [{ type: "text", text: JSON.stringify({ adcp_error: filtered }) }],
+    content: [{ type: "text", text: JSON.stringify(structuredContent) }],
     isError: true,
-    structuredContent: { adcp_error: filtered }
+    structuredContent
   };
 }
 function applyAdcpErrorAllowlist(code, payload) {

package/dist/lib/server/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/server/errors.ts"],"sourcesContent":["/**\n * Server-side helpers for producing L3-compliant AdCP error responses.\n *\n * Use `adcpError()` in MCP tool handlers to return structured errors\n * that clients can automatically detect, classify, and act on.\n */\n\nimport {\n  STANDARD_ERROR_CODES,\n  isStandardErrorCode,\n  type StandardErrorCode,\n  type ErrorRecovery,\n} from '../types/error-codes';\nimport type { ValidationIssue } from '../validation/schema-validator';\nimport { ADCP_ERROR_FIELD_ALLOWLIST } from './envelope-allowlist';\nimport { pickSafeDetails } from './pick-safe-details';\n\nexport interface AdcpErrorOptions {\n  message: string;\n  /**\n   * Override the recovery classification. Defaults to\n   * `STANDARD_ERROR_CODES[code].recovery` for known codes, `'terminal'`\n   * otherwise. Dropped from the wire shape for codes whose entry in\n   * `ADCP_ERROR_FIELD_ALLOWLIST` excludes it; normalized back to the\n   * standard table value for allowlisted standard-code envelopes.\n   */\n  recovery?: ErrorRecovery;\n  /**\n   * Name of the request field the error applies to (validation /\n   * constraint errors). Dropped from the wire shape for codes whose\n   * `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g. `IDEMPOTENCY_CONFLICT`\n   * — a conflict response MUST NOT echo prior payload state).\n   */\n  field?: string;\n  /**\n   * Human-readable remediation hint. Dropped from the wire shape for\n   * codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g.\n   * `IDEMPOTENCY_CONFLICT`).\n   */\n  suggestion?: string;\n  /**\n   * Seconds to wait before retrying a transient error. Only meaningful\n   * on retryable codes (`RATE_LIMITED`, `SERVICE_UNAVAILABLE`); dropped\n   * on terminal codes whose allowlist excludes it (`IDEMPOTENCY_CONFLICT`\n   * — a computed `retry_after` on conflict would leak cached-entry age).\n   */\n  retry_after?: number;\n  /**\n   * Code-specific diagnostic payload. Dropped from the wire shape for\n   * codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it\n   * (`IDEMPOTENCY_CONFLICT` — a conflict response MUST NOT echo the\n   * prior request payload or cached response body).\n   */\n  details?: Record<string, unknown>;\n  /**\n   * Schema validation issues surfaced at the top level of `adcp_error`\n   * so operators see JSON Pointers on the first render. Primary use is\n   * `VALIDATION_ERROR`; framework validation hooks populate this\n   * automatically and also mirror the same array to `details.issues`\n   * for buyers that already index into `details` per AdCP spec\n   * convention.\n   */\n  issues?: Array<Omit<ValidationIssue, 'schemaPath'> & { schemaPath?: string }>;\n}\n\nexport interface AdcpErrorPayload {\n  code: string;\n  message: string;\n  /**\n   * Closed-enum classifier. Populated by `adcpError()` from\n   * `STANDARD_ERROR_CODES[code].recovery` unless the caller provides an\n   * override. Marked optional because per-code inside-`adcp_error`\n   * allowlists may deliberately drop it from the wire shape — consumers\n   * reading a payload parsed off the wire MUST tolerate `undefined`.\n   */\n  recovery?: ErrorRecovery;\n  field?: string;\n  suggestion?: string;\n  retry_after?: number;\n  details?: Record<string, unknown>;\n  /**\n   * Schema validation issues (`VALIDATION_ERROR`) exposed at the top\n   * level so the list is the first thing a reader sees when inspecting\n   * the envelope. Also mirrored at `details.issues` for spec-convention\n   * compatibility.\n   */\n  issues?: Array<Omit<ValidationIssue, 'schemaPath'> & { schemaPath?: string }>;\n}\n\nexport interface AdcpErrorResponse {\n  [key: string]: unknown;\n  content: Array<{ type: 'text'; text: string }>;\n  isError: true;\n  structuredContent: {\n    adcp_error: AdcpErrorPayload;\n  };\n}\n\nconst AUTHORIZATION_REQUIRED_DETAIL_KEYS = [\n  'required_connections',\n  'missing_connections',\n  'provider',\n  'connection_type',\n  'required_for',\n  'scope',\n  'status',\n  'resource_ref',\n  'platform_account_id',\n  'identity_id',\n  'handle',\n  'profile_url',\n  'post_id',\n  'post_url',\n  'authorization_url',\n  'authorization_instructions',\n  'checked_at',\n  'expires_at',\n  'reference_authorization',\n] as const;\n\n/**\n * Build an L3-compliant MCP tool error response with all three transport layers:\n *\n * 1. `structuredContent.adcp_error` — programmatic extraction (L3)\n * 2. `content[0].text` — JSON text fallback (L2)\n * 3. `isError: true` — MCP error signal\n *\n * Recovery is auto-populated from the standard error code table when not provided.\n *\n * Before returning, any field NOT allowlisted for the given code in\n * {@link ADCP_ERROR_FIELD_ALLOWLIST} is dropped — sellers get the builder's\n * ergonomics for every code AND the strict wire shape for codes that have\n * a registered allowlist. `IDEMPOTENCY_CONFLICT` is the canonical case:\n * payload-shaped diagnostics like `field`, `suggestion`, and `details`\n * silently drop while standard `recovery` metadata is preserved as the\n * canonical standard-table value. Codes without a registered allowlist\n * pass through unchanged.\n *\n * **Two-layer wire shape.** This builder emits the envelope layer\n * (`structuredContent.adcp_error`) only. For tools whose response\n * schema declares a typed Error arm (`errors[]` required at the top\n * level), the framework dispatcher synthesises the payload-layer\n * `errors[]` from the same data at finalize time, so the wire carries\n * both the envelope marker and the typed Error arm together — no\n * adopter code change required. The list of affected tools is derived\n * at server build from the bundled schema cache. RFC:\n * `docs/proposals/adcperror-two-layer-emission.md`.\n *\n * @example\n * ```typescript\n * import { adcpError } from '@adcp/sdk';\n *\n * server.registerTool(\"get_products\", { inputSchema: schema }, async ({ query }) => {\n *   if (!products.length) {\n *     return adcpError('PRODUCT_NOT_FOUND', {\n *       message: 'No products match query',\n *       field: 'query',\n *       suggestion: 'Try a broader search term',\n *     });\n *   }\n *   return { content: [...], structuredContent: { products } };\n * });\n * ```\n */\nexport function adcpError(code: StandardErrorCode | (string & {}), options: AdcpErrorOptions): AdcpErrorResponse {\n  const recovery = normalizeRecoveryForCode(code, options.recovery);\n\n  const adcp_error: AdcpErrorPayload = {\n    code,\n    message: options.message,\n    recovery,\n    ...(options.field != null && { field: options.field }),\n    ...(options.suggestion != null && { suggestion: options.suggestion }),\n    ...(options.retry_after != null && { retry_after: options.retry_after }),\n    ...(options.issues != null && { issues: options.issues }),\n    ...(options.details != null && { details: options.details }),\n  };\n\n  const filtered = applyAdcpErrorAllowlist(code, adcp_error as unknown as Record<string, unknown>);\n\n  return {\n    content: [{ type: 'text', text: JSON.stringify({ adcp_error: filtered }) }],\n    isError: true,\n    structuredContent: { adcp_error: filtered },\n  };\n}\n\n/**\n * Drop every field not in {@link ADCP_ERROR_FIELD_ALLOWLIST} for `code`.\n * When an allowlisted standard code carries `recovery`, normalize it to\n * the fixed classifier from `STANDARD_ERROR_CODES` instead of trusting a\n * caller-supplied value.\n * Codes without an entry pass through unchanged — the allowlist is\n * opt-in per code, not a global filter. The returned object is re-typed\n * as `AdcpErrorPayload` on the assumption that `code` and `message`\n * (the only required fields) are in every registered allowlist; that\n * invariant is re-asserted at runtime by the module-load check in\n * `envelope-allowlist.ts`.\n */\nexport function applyAdcpErrorAllowlist(code: string, payload: Record<string, unknown>): AdcpErrorPayload {\n  payload = sanitizeAdcpErrorDetails(code, payload);\n  const allowlist = ADCP_ERROR_FIELD_ALLOWLIST[code];\n  if (!allowlist) return payload as unknown as AdcpErrorPayload;\n  const out: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(payload)) {\n    if (!allowlist.has(key)) continue;\n    out[key] = key === 'recovery' ? normalizeAllowlistedRecoveryForCode(code, value) : value;\n  }\n  return out as unknown as AdcpErrorPayload;\n}\n\nexport function sanitizeStructuredAdcpError<T extends { code: string; message: string }>(error: T): T {\n  return applyAdcpErrorAllowlist(error.code, error as unknown as Record<string, unknown>) as unknown as T;\n}\n\nfunction sanitizeAdcpErrorDetails(code: string, payload: Record<string, unknown>): Record<string, unknown> {\n  if (code !== 'AUTHORIZATION_REQUIRED' || payload.details === undefined) return payload;\n\n  const sanitizedDetails = pickSafeDetails(payload.details, AUTHORIZATION_REQUIRED_DETAIL_KEYS, {\n    maxDepth: 4,\n    maxSizeBytes: 4096,\n  });\n  const { details: _details, ...rest } = payload;\n  return sanitizedDetails === undefined ? rest : { ...rest, details: sanitizedDetails };\n}\n\nfunction isErrorRecovery(value: unknown): value is ErrorRecovery {\n  return value === 'transient' || value === 'correctable' || value === 'terminal';\n}\n\nfunction normalizeRecoveryForCode(code: string, value: unknown): ErrorRecovery {\n  return isErrorRecovery(value) ? value : isStandardErrorCode(code) ? STANDARD_ERROR_CODES[code].recovery : 'terminal';\n}\n\nfunction normalizeAllowlistedRecoveryForCode(code: string, value: unknown): ErrorRecovery {\n  if (isStandardErrorCode(code)) {\n    return STANDARD_ERROR_CODES[code].recovery;\n  }\n  return normalizeRecoveryForCode(code, value);\n}\n"],"mappings":"AAOA;AAAA,EACE;AAAA,EACA;AAAA,OAGK;AAEP,SAAS,kCAAkC;AAC3C,SAAS,uBAAuB;AAmFhC,MAAM,qCAAqC;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AA8CO,SAAS,UAAU,MAAyC,SAA8C;AAC/G,QAAM,WAAW,yBAAyB,MAAM,QAAQ,QAAQ;AAEhE,QAAM,aAA+B;AAAA,IACnC;AAAA,IACA,SAAS,QAAQ;AAAA,IACjB;AAAA,IACA,GAAI,QAAQ,SAAS,QAAQ,EAAE,OAAO,QAAQ,MAAM;AAAA,IACpD,GAAI,QAAQ,cAAc,QAAQ,EAAE,YAAY,QAAQ,WAAW;AAAA,IACnE,GAAI,QAAQ,eAAe,QAAQ,EAAE,aAAa,QAAQ,YAAY;AAAA,IACtE,GAAI,QAAQ,UAAU,QAAQ,EAAE,QAAQ,QAAQ,OAAO;AAAA,IACvD,GAAI,QAAQ,WAAW,QAAQ,EAAE,SAAS,QAAQ,QAAQ;AAAA,EAC5D;AAEA,QAAM,WAAW,wBAAwB,MAAM,UAAgD;AAE/F,SAAO;AAAA,IACL,SAAS,CAAC,EAAE,MAAM,QAAQ,MAAM,KAAK,UAAU,EAAE,YAAY,SAAS,CAAC,EAAE,CAAC;AAAA,IAC1E,SAAS;AAAA,IACT,mBAAmB,EAAE,YAAY,SAAS;AAAA,EAC5C;AACF;AAcO,SAAS,wBAAwB,MAAc,SAAoD;AACxG,YAAU,yBAAyB,MAAM,OAAO;AAChD,QAAM,YAAY,2BAA2B,IAAI;AACjD,MAAI,CAAC,UAAW,QAAO;AACvB,QAAM,MAA+B,CAAC;AACtC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AAClD,QAAI,CAAC,UAAU,IAAI,GAAG,EAAG;AACzB,QAAI,GAAG,IAAI,QAAQ,aAAa,oCAAoC,MAAM,KAAK,IAAI;AAAA,EACrF;AACA,SAAO;AACT;AAEO,SAAS,4BAAyE,OAAa;AACpG,SAAO,wBAAwB,MAAM,MAAM,KAA2C;AACxF;AAEA,SAAS,yBAAyB,MAAc,SAA2D;AACzG,MAAI,SAAS,4BAA4B,QAAQ,YAAY,OAAW,QAAO;AAE/E,QAAM,mBAAmB,gBAAgB,QAAQ,SAAS,oCAAoC;AAAA,IAC5F,UAAU;AAAA,IACV,cAAc;AAAA,EAChB,CAAC;AACD,QAAM,EAAE,SAAS,UAAU,GAAG,KAAK,IAAI;AACvC,SAAO,qBAAqB,SAAY,OAAO,EAAE,GAAG,MAAM,SAAS,iBAAiB;AACtF;AAEA,SAAS,gBAAgB,OAAwC;AAC/D,SAAO,UAAU,eAAe,UAAU,iBAAiB,UAAU;AACvE;AAEA,SAAS,yBAAyB,MAAc,OAA+B;AAC7E,SAAO,gBAAgB,KAAK,IAAI,QAAQ,oBAAoB,IAAI,IAAI,qBAAqB,IAAI,EAAE,WAAW;AAC5G;AAEA,SAAS,oCAAoC,MAAc,OAA+B;AACxF,MAAI,oBAAoB,IAAI,GAAG;AAC7B,WAAO,qBAAqB,IAAI,EAAE;AAAA,EACpC;AACA,SAAO,yBAAyB,MAAM,KAAK;AAC7C;","names":[]}
+{"version":3,"sources":["../../../src/lib/server/errors.ts"],"sourcesContent":["/**\n * Server-side helpers for producing L3-compliant AdCP error responses.\n *\n * Use `adcpError()` in MCP tool handlers to return structured errors\n * that clients can automatically detect, classify, and act on.\n */\n\nimport {\n  STANDARD_ERROR_CODES,\n  isStandardErrorCode,\n  type StandardErrorCode,\n  type ErrorRecovery,\n} from '../types/error-codes';\nimport type { ValidationIssue } from '../validation/schema-validator';\nimport { ADCP_ERROR_FIELD_ALLOWLIST } from './envelope-allowlist';\nimport { pickSafeDetails } from './pick-safe-details';\n\nexport interface AdcpErrorOptions {\n  message: string;\n  /**\n   * Opaque request context to echo beside `adcp_error`. Only a non-null,\n   * non-array object is echoable, matching the framework envelope behavior.\n   */\n  context?: unknown;\n  /**\n   * Override the recovery classification. Defaults to\n   * `STANDARD_ERROR_CODES[code].recovery` for known codes, `'terminal'`\n   * otherwise. Dropped from the wire shape for codes whose entry in\n   * `ADCP_ERROR_FIELD_ALLOWLIST` excludes it; normalized back to the\n   * standard table value for allowlisted standard-code envelopes.\n   */\n  recovery?: ErrorRecovery;\n  /**\n   * Name of the request field the error applies to (validation /\n   * constraint errors). Dropped from the wire shape for codes whose\n   * `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g. `IDEMPOTENCY_CONFLICT`\n   * — a conflict response MUST NOT echo prior payload state).\n   */\n  field?: string;\n  /**\n   * Human-readable remediation hint. Dropped from the wire shape for\n   * codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g.\n   * `IDEMPOTENCY_CONFLICT`).\n   */\n  suggestion?: string;\n  /**\n   * Seconds to wait before retrying a transient error. Only meaningful\n   * on retryable codes (`RATE_LIMITED`, `SERVICE_UNAVAILABLE`); dropped\n   * on terminal codes whose allowlist excludes it (`IDEMPOTENCY_CONFLICT`\n   * — a computed `retry_after` on conflict would leak cached-entry age).\n   */\n  retry_after?: number;\n  /**\n   * Code-specific diagnostic payload. Dropped from the wire shape for\n   * codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it\n   * (`IDEMPOTENCY_CONFLICT` — a conflict response MUST NOT echo the\n   * prior request payload or cached response body).\n   */\n  details?: Record<string, unknown>;\n  /**\n   * Schema validation issues surfaced at the top level of `adcp_error`\n   * so operators see JSON Pointers on the first render. Primary use is\n   * `VALIDATION_ERROR`; framework validation hooks populate this\n   * automatically and also mirror the same array to `details.issues`\n   * for buyers that already index into `details` per AdCP spec\n   * convention.\n   */\n  issues?: Array<Omit<ValidationIssue, 'schemaPath'> & { schemaPath?: string }>;\n}\n\nexport interface AdcpErrorPayload {\n  code: string;\n  message: string;\n  /**\n   * Closed-enum classifier. Populated by `adcpError()` from\n   * `STANDARD_ERROR_CODES[code].recovery` unless the caller provides an\n   * override. Marked optional because per-code inside-`adcp_error`\n   * allowlists may deliberately drop it from the wire shape — consumers\n   * reading a payload parsed off the wire MUST tolerate `undefined`.\n   */\n  recovery?: ErrorRecovery;\n  field?: string;\n  suggestion?: string;\n  retry_after?: number;\n  details?: Record<string, unknown>;\n  /**\n   * Schema validation issues (`VALIDATION_ERROR`) exposed at the top\n   * level so the list is the first thing a reader sees when inspecting\n   * the envelope. Also mirrored at `details.issues` for spec-convention\n   * compatibility.\n   */\n  issues?: Array<Omit<ValidationIssue, 'schemaPath'> & { schemaPath?: string }>;\n}\n\nexport interface AdcpErrorResponse {\n  [key: string]: unknown;\n  content: Array<{ type: 'text'; text: string }>;\n  isError: true;\n  structuredContent: {\n    adcp_error: AdcpErrorPayload;\n    context?: object;\n  };\n}\n\nfunction isEchoableContext(value: unknown): value is object {\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\n}\n\nconst AUTHORIZATION_REQUIRED_DETAIL_KEYS = [\n  'required_connections',\n  'missing_connections',\n  'provider',\n  'connection_type',\n  'required_for',\n  'scope',\n  'status',\n  'resource_ref',\n  'platform_account_id',\n  'identity_id',\n  'handle',\n  'profile_url',\n  'post_id',\n  'post_url',\n  'authorization_url',\n  'authorization_instructions',\n  'checked_at',\n  'expires_at',\n  'reference_authorization',\n] as const;\n\n/**\n * Build an L3-compliant MCP tool error response with all three transport layers:\n *\n * 1. `structuredContent.adcp_error` — programmatic extraction (L3)\n * 2. `content[0].text` — JSON text fallback (L2)\n * 3. `isError: true` — MCP error signal\n *\n * Recovery is auto-populated from the standard error code table when not provided.\n *\n * Before returning, any field NOT allowlisted for the given code in\n * {@link ADCP_ERROR_FIELD_ALLOWLIST} is dropped — sellers get the builder's\n * ergonomics for every code AND the strict wire shape for codes that have\n * a registered allowlist. `IDEMPOTENCY_CONFLICT` is the canonical case:\n * payload-shaped diagnostics like `field`, `suggestion`, and `details`\n * silently drop while standard `recovery` metadata is preserved as the\n * canonical standard-table value. Codes without a registered allowlist\n * pass through unchanged.\n *\n * **Two-layer wire shape.** This builder emits the envelope layer\n * (`structuredContent.adcp_error`) only. For tools whose response\n * schema declares a typed Error arm (`errors[]` required at the top\n * level), the framework dispatcher synthesises the payload-layer\n * `errors[]` from the same data at finalize time, so the wire carries\n * both the envelope marker and the typed Error arm together — no\n * adopter code change required. The list of affected tools is derived\n * at server build from the bundled schema cache. RFC:\n * `docs/proposals/adcperror-two-layer-emission.md`.\n *\n * @example\n * ```typescript\n * import { adcpError } from '@adcp/sdk';\n *\n * server.registerTool(\"get_products\", { inputSchema: schema }, async request => {\n *   const { query, context } = request;\n *   if (!products.length) {\n *     return adcpError('PRODUCT_NOT_FOUND', {\n *       message: 'No products match query',\n *       field: 'query',\n *       suggestion: 'Try a broader search term',\n *       context,\n *     });\n *   }\n *   return { content: [...], structuredContent: { products, context } };\n * });\n * ```\n */\nexport function adcpError(code: StandardErrorCode | (string & {}), options: AdcpErrorOptions): AdcpErrorResponse {\n  const recovery = normalizeRecoveryForCode(code, options.recovery);\n\n  const adcp_error: AdcpErrorPayload = {\n    code,\n    message: options.message,\n    recovery,\n    ...(options.field != null && { field: options.field }),\n    ...(options.suggestion != null && { suggestion: options.suggestion }),\n    ...(options.retry_after != null && { retry_after: options.retry_after }),\n    ...(options.issues != null && { issues: options.issues }),\n    ...(options.details != null && { details: options.details }),\n  };\n\n  const filtered = applyAdcpErrorAllowlist(code, adcp_error as unknown as Record<string, unknown>);\n  const structuredContent = {\n    adcp_error: filtered,\n    ...(isEchoableContext(options.context) ? { context: options.context } : {}),\n  };\n\n  return {\n    content: [{ type: 'text', text: JSON.stringify(structuredContent) }],\n    isError: true,\n    structuredContent,\n  };\n}\n\n/**\n * Drop every field not in {@link ADCP_ERROR_FIELD_ALLOWLIST} for `code`.\n * When an allowlisted standard code carries `recovery`, normalize it to\n * the fixed classifier from `STANDARD_ERROR_CODES` instead of trusting a\n * caller-supplied value.\n * Codes without an entry pass through unchanged — the allowlist is\n * opt-in per code, not a global filter. The returned object is re-typed\n * as `AdcpErrorPayload` on the assumption that `code` and `message`\n * (the only required fields) are in every registered allowlist; that\n * invariant is re-asserted at runtime by the module-load check in\n * `envelope-allowlist.ts`.\n */\nexport function applyAdcpErrorAllowlist(code: string, payload: Record<string, unknown>): AdcpErrorPayload {\n  payload = sanitizeAdcpErrorDetails(code, payload);\n  const allowlist = ADCP_ERROR_FIELD_ALLOWLIST[code];\n  if (!allowlist) return payload as unknown as AdcpErrorPayload;\n  const out: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(payload)) {\n    if (!allowlist.has(key)) continue;\n    out[key] = key === 'recovery' ? normalizeAllowlistedRecoveryForCode(code, value) : value;\n  }\n  return out as unknown as AdcpErrorPayload;\n}\n\nexport function sanitizeStructuredAdcpError<T extends { code: string; message: string }>(error: T): T {\n  return applyAdcpErrorAllowlist(error.code, error as unknown as Record<string, unknown>) as unknown as T;\n}\n\nfunction sanitizeAdcpErrorDetails(code: string, payload: Record<string, unknown>): Record<string, unknown> {\n  if (code !== 'AUTHORIZATION_REQUIRED' || payload.details === undefined) return payload;\n\n  const sanitizedDetails = pickSafeDetails(payload.details, AUTHORIZATION_REQUIRED_DETAIL_KEYS, {\n    maxDepth: 4,\n    maxSizeBytes: 4096,\n  });\n  const { details: _details, ...rest } = payload;\n  return sanitizedDetails === undefined ? rest : { ...rest, details: sanitizedDetails };\n}\n\nfunction isErrorRecovery(value: unknown): value is ErrorRecovery {\n  return value === 'transient' || value === 'correctable' || value === 'terminal';\n}\n\nfunction normalizeRecoveryForCode(code: string, value: unknown): ErrorRecovery {\n  return isErrorRecovery(value) ? value : isStandardErrorCode(code) ? STANDARD_ERROR_CODES[code].recovery : 'terminal';\n}\n\nfunction normalizeAllowlistedRecoveryForCode(code: string, value: unknown): ErrorRecovery {\n  if (isStandardErrorCode(code)) {\n    return STANDARD_ERROR_CODES[code].recovery;\n  }\n  return normalizeRecoveryForCode(code, value);\n}\n"],"mappings":"AAOA;AAAA,EACE;AAAA,EACA;AAAA,OAGK;AAEP,SAAS,kCAAkC;AAC3C,SAAS,uBAAuB;AAyFhC,SAAS,kBAAkB,OAAiC;AAC1D,SAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAEA,MAAM,qCAAqC;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAgDO,SAAS,UAAU,MAAyC,SAA8C;AAC/G,QAAM,WAAW,yBAAyB,MAAM,QAAQ,QAAQ;AAEhE,QAAM,aAA+B;AAAA,IACnC;AAAA,IACA,SAAS,QAAQ;AAAA,IACjB;AAAA,IACA,GAAI,QAAQ,SAAS,QAAQ,EAAE,OAAO,QAAQ,MAAM;AAAA,IACpD,GAAI,QAAQ,cAAc,QAAQ,EAAE,YAAY,QAAQ,WAAW;AAAA,IACnE,GAAI,QAAQ,eAAe,QAAQ,EAAE,aAAa,QAAQ,YAAY;AAAA,IACtE,GAAI,QAAQ,UAAU,QAAQ,EAAE,QAAQ,QAAQ,OAAO;AAAA,IACvD,GAAI,QAAQ,WAAW,QAAQ,EAAE,SAAS,QAAQ,QAAQ;AAAA,EAC5D;AAEA,QAAM,WAAW,wBAAwB,MAAM,UAAgD;AAC/F,QAAM,oBAAoB;AAAA,IACxB,YAAY;AAAA,IACZ,GAAI,kBAAkB,QAAQ,OAAO,IAAI,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;AAAA,EAC3E;AAEA,SAAO;AAAA,IACL,SAAS,CAAC,EAAE,MAAM,QAAQ,MAAM,KAAK,UAAU,iBAAiB,EAAE,CAAC;AAAA,IACnE,SAAS;AAAA,IACT;AAAA,EACF;AACF;AAcO,SAAS,wBAAwB,MAAc,SAAoD;AACxG,YAAU,yBAAyB,MAAM,OAAO;AAChD,QAAM,YAAY,2BAA2B,IAAI;AACjD,MAAI,CAAC,UAAW,QAAO;AACvB,QAAM,MAA+B,CAAC;AACtC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AAClD,QAAI,CAAC,UAAU,IAAI,GAAG,EAAG;AACzB,QAAI,GAAG,IAAI,QAAQ,aAAa,oCAAoC,MAAM,KAAK,IAAI;AAAA,EACrF;AACA,SAAO;AACT;AAEO,SAAS,4BAAyE,OAAa;AACpG,SAAO,wBAAwB,MAAM,MAAM,KAA2C;AACxF;AAEA,SAAS,yBAAyB,MAAc,SAA2D;AACzG,MAAI,SAAS,4BAA4B,QAAQ,YAAY,OAAW,QAAO;AAE/E,QAAM,mBAAmB,gBAAgB,QAAQ,SAAS,oCAAoC;AAAA,IAC5F,UAAU;AAAA,IACV,cAAc;AAAA,EAChB,CAAC;AACD,QAAM,EAAE,SAAS,UAAU,GAAG,KAAK,IAAI;AACvC,SAAO,qBAAqB,SAAY,OAAO,EAAE,GAAG,MAAM,SAAS,iBAAiB;AACtF;AAEA,SAAS,gBAAgB,OAAwC;AAC/D,SAAO,UAAU,eAAe,UAAU,iBAAiB,UAAU;AACvE;AAEA,SAAS,yBAAyB,MAAc,OAA+B;AAC7E,SAAO,gBAAgB,KAAK,IAAI,QAAQ,oBAAoB,IAAI,IAAI,qBAAqB,IAAI,EAAE,WAAW;AAC5G;AAEA,SAAS,oCAAoC,MAAc,OAA+B;AACxF,MAAI,oBAAoB,IAAI,GAAG;AAC7B,WAAO,qBAAqB,IAAI,EAAE;AAAA,EACpC;AACA,SAAO,yBAAyB,MAAM,KAAK;AAC7C;","names":[]}