@adcp/sdk 16.0.0-beta.8 → 16.0.0-beta.9

package/dist/lib/protocols/index.js

@@ -54,6 +54,7 @@ __export(protocols_exports, {
   wrapFetchWithTransportDiagnostics: () => import_transportDiagnostics2.wrapFetchWithTransportDiagnostics
 });
 module.exports = __toCommonJS(protocols_exports);
+var import_errors = require('../errors/index.js');
 var import_mcp = require('./mcp.js');
 var import_mcp2 = require('./mcp.js');
 var import_mcp_scope = require('./mcp-scope.js');
@@ -70,13 +71,13 @@ var import_auth = require('../auth/index.js');
 var import_oauth = require('../auth/oauth/index.js');
 var import_authorization_required = require('../auth/oauth/authorization-required.js');
 var import_provider_cache = require('../auth/oauth/provider-cache.js');
-var import_errors = require('../errors/index.js');
+var import_errors2 = require('../errors/index.js');
 var import_signedRequestRejection = require('./signedRequestRejection.js');
 var import_net = require('../net/index.js');
 var import_validation = require('../validation/index.js');
 var import_tracing = require('../observability/tracing.js');
 var import_version = require('../version.js');
-var import_errors2 = require('../errors/index.js');
+var import_errors3 = require('../errors/index.js');
 var import_schema_loader = require('../validation/schema-loader.js');
 var import_client = require('../signing/client.js');
 var import_responseSizeLimit2 = require('./responseSizeLimit.js');
@@ -109,7 +110,7 @@ function resolveWireMajor(adcpVersion) {
   if (adcpVersion === void 0) return import_version.ADCP_MAJOR_VERSION;
   const parsed = (0, import_version.parseAdcpMajorVersion)(adcpVersion);
   if (!Number.isFinite(parsed)) {
-    throw new import_errors2.ConfigurationError(
+    throw new import_errors3.ConfigurationError(
       `adcpVersion ${JSON.stringify(adcpVersion)} is not a valid AdCP version. Expected a semver string (e.g. '3.0.1', '3.1.0-beta.1') or a legacy alias (e.g. 'v3').`,
       "adcpVersion"
     );
@@ -126,7 +127,7 @@ function bundleSupportsAdcpVersionField(bundleKey) {
   return parseInt(minorMatch[1], 10) >= 1;
 }
 function buildVersionEnvelope(adcpVersion, serverVersion) {
-  if (serverVersion === "v2") return {};
+  if (serverVersion === "v2") throw new import_errors.VersionUnsupportedError("request", "version", "v2");
   const wireMajor = resolveWireMajor(adcpVersion);
   const bundleKey = (0, import_schema_loader.resolveBundleKey)(adcpVersion ?? import_version.ADCP_VERSION);
   if (!bundleSupportsAdcpVersionField(bundleKey)) {
@@ -136,16 +137,9 @@ function buildVersionEnvelope(adcpVersion, serverVersion) {
   (0, import_schema_loader.validateAdcpVersionWire)(wireValue);
   return { adcp_major_version: wireMajor, adcp_version: wireValue };
 }
-let hasWarnedAboutV2PushNotificationSecret = false;
-function warnV2PushNotificationNeedsSecret() {
-  if (hasWarnedAboutV2PushNotificationSecret) return;
-  hasWarnedAboutV2PushNotificationSecret = true;
-  console.warn(
-    "[adcp] Suppressing push_notification_config for a v2 seller: AdCP 2.5 requires an `authentication` block and no `webhookSecret` is configured. Set `webhookSecret` to register async task-status webhooks with this agent, or move the agent to an AdCP 3.x pin, where the RFC 9421 webhook profile needs no shared secret."
-  );
-}
 function buildVersionEnvelopeForMode(mode, adcpVersion, serverVersion) {
-  if (mode === "none" || serverVersion === "v2") return {};
+  if (serverVersion === "v2") throw new import_errors.VersionUnsupportedError("request", "version", "v2");
+  if (mode === "none") return {};
   if (mode === "major-only") return { adcp_major_version: resolveWireMajor(adcpVersion) };
   return buildVersionEnvelope(adcpVersion, serverVersion);
 }
@@ -182,7 +176,7 @@ function prepareProtocolToolCall(agent, args, options = {}) {
   const argsWithVersion = applyVersionEnvelope(args, envelope);
   applyPublishedSchemaCompatibility(options.toolName, argsWithVersion, args);
   const effectiveBundle = typeof argsWithVersion.adcp_version === "string" ? (0, import_schema_loader.resolveBundleKey)(argsWithVersion.adcp_version) : void 0;
-  const usesApplicationRegistration = options.serverVersion !== "v2" && (0, import_adcp_version_config.isAdcpVersionAtLeast)(effectiveBundle, "3.1.0");
+  const usesApplicationRegistration = (0, import_adcp_version_config.isAdcpVersionAtLeast)(effectiveBundle, "3.1.0");
   let pushNotificationConfig;
   let applicationPushNotificationConfig;
   let operationId;
@@ -196,8 +190,6 @@ function prepareProtocolToolCall(agent, args, options = {}) {
           credentials: options.webhookSecret
         }
       };
-    } else if (options.serverVersion === "v2") {
-      warnV2PushNotificationNeedsSecret();
     } else {
       pushNotificationConfig = {
         url: options.webhookUrl,
@@ -373,7 +365,7 @@ class ProtocolClient {
                   }
                 );
               } catch (err) {
-                if (agent.oauth_client_credentials && (0, import_errors.is401Error)(err) && (0, import_signedRequestRejection.getSignedRequestRejection)(err)?.challenge?.scheme !== "signature") {
+                if (agent.oauth_client_credentials && (0, import_errors2.is401Error)(err) && (0, import_signedRequestRejection.getSignedRequestRejection)(err)?.challenge?.scheme !== "signature") {
                   const ccStorage = (0, import_oauth.getAgentStorage)(agent);
                   const allowPrivateIp = transport?.allowPrivateIp ?? (0, import_net.isLikelyPrivateUrl)(agent.agent_uri);
                   await (0, import_oauth.ensureClientCredentialsTokens)(agent, {
@@ -405,7 +397,7 @@ class ProtocolClient {
                       }
                     );
                   } catch (retryErr) {
-                    const rejection = (0, import_signedRequestRejection.getSignedRequestRejection)(retryErr) ?? ((0, import_errors.is401Error)(retryErr) ? (0, import_signedRequestRejection.getSignedRequestRejection)(err) : void 0);
+                    const rejection = (0, import_signedRequestRejection.getSignedRequestRejection)(retryErr) ?? ((0, import_errors2.is401Error)(retryErr) ? (0, import_signedRequestRejection.getSignedRequestRejection)(err) : void 0);
                     if (rejection) throw rejection;
                     await rethrowAsNeedsAuthorization(
                       retryErr,
@@ -447,7 +439,7 @@ class ProtocolClient {
                   transport?.legacyCompat
                 );
               } catch (err) {
-                if (agent.oauth_client_credentials && (0, import_errors.is401Error)(err) && (0, import_signedRequestRejection.getSignedRequestRejection)(err)?.challenge?.scheme !== "signature") {
+                if (agent.oauth_client_credentials && (0, import_errors2.is401Error)(err) && (0, import_signedRequestRejection.getSignedRequestRejection)(err)?.challenge?.scheme !== "signature") {
                   const ccStorage = (0, import_oauth.getAgentStorage)(agent);
                   const allowPrivateIp = transport?.allowPrivateIp ?? (0, import_net.isLikelyPrivateUrl)(agent.agent_uri);
                   await (0, import_oauth.ensureClientCredentialsTokens)(agent, {
@@ -476,7 +468,7 @@ class ProtocolClient {
                       transport?.legacyCompat
                     );
                   } catch (retryErr) {
-                    const rejection = (0, import_signedRequestRejection.getSignedRequestRejection)(retryErr) ?? ((0, import_errors.is401Error)(retryErr) ? (0, import_signedRequestRejection.getSignedRequestRejection)(err) : void 0);
+                    const rejection = (0, import_signedRequestRejection.getSignedRequestRejection)(retryErr) ?? ((0, import_errors2.is401Error)(retryErr) ? (0, import_signedRequestRejection.getSignedRequestRejection)(err) : void 0);
                     if (rejection) throw rejection;
                     await rethrowAsNeedsAuthorization(
                       retryErr,
@@ -512,9 +504,9 @@ async function rethrowAsNeedsAuthorization(err, agentUrl, fetchFn, signal, confi
   const signedRejection = (0, import_signedRequestRejection.getSignedRequestRejection)(err);
   if (signedRejection) throw signedRejection;
   if (err instanceof import_oauth.NeedsAuthorizationError) throw err;
-  if (!(0, import_errors.is401Error)(err)) return;
+  if (!(0, import_errors2.is401Error)(err)) return;
   if (recoveryMode === "static") {
-    throw new import_errors.AuthenticationCredentialsRejectedError(agentUrl, err);
+    throw new import_errors2.AuthenticationCredentialsRejectedError(agentUrl, err);
   }
   const allowPrivateIp = configuredAllowPrivateIp ?? (0, import_net.isLikelyPrivateUrl)(agentUrl);
   const requirements = await (0, import_oauth.discoverAuthorizationRequirements)(agentUrl, { allowPrivateIp, fetchFn, signal });

package/dist/lib/protocols/index.mjs

@@ -3,6 +3,7 @@ import { dirname as __adcpDirname } from "node:path";
 import { createRequire as __adcpCreateRequire } from "node:module";
 const __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));
 const require2 = __adcpCreateRequire(import.meta.url);
+import { VersionUnsupportedError } from "../errors/index.mjs";
 import {
   callMCPTool,
   callMCPToolWithOAuth,
@@ -104,7 +105,7 @@ function bundleSupportsAdcpVersionField(bundleKey) {
   return parseInt(minorMatch[1], 10) >= 1;
 }
 function buildVersionEnvelope(adcpVersion, serverVersion) {
-  if (serverVersion === "v2") return {};
+  if (serverVersion === "v2") throw new VersionUnsupportedError("request", "version", "v2");
   const wireMajor = resolveWireMajor(adcpVersion);
   const bundleKey = resolveBundleKey(adcpVersion ?? ADCP_VERSION);
   if (!bundleSupportsAdcpVersionField(bundleKey)) {
@@ -114,16 +115,9 @@ function buildVersionEnvelope(adcpVersion, serverVersion) {
   validateAdcpVersionWire(wireValue);
   return { adcp_major_version: wireMajor, adcp_version: wireValue };
 }
-let hasWarnedAboutV2PushNotificationSecret = false;
-function warnV2PushNotificationNeedsSecret() {
-  if (hasWarnedAboutV2PushNotificationSecret) return;
-  hasWarnedAboutV2PushNotificationSecret = true;
-  console.warn(
-    "[adcp] Suppressing push_notification_config for a v2 seller: AdCP 2.5 requires an `authentication` block and no `webhookSecret` is configured. Set `webhookSecret` to register async task-status webhooks with this agent, or move the agent to an AdCP 3.x pin, where the RFC 9421 webhook profile needs no shared secret."
-  );
-}
 function buildVersionEnvelopeForMode(mode, adcpVersion, serverVersion) {
-  if (mode === "none" || serverVersion === "v2") return {};
+  if (serverVersion === "v2") throw new VersionUnsupportedError("request", "version", "v2");
+  if (mode === "none") return {};
   if (mode === "major-only") return { adcp_major_version: resolveWireMajor(adcpVersion) };
   return buildVersionEnvelope(adcpVersion, serverVersion);
 }
@@ -160,7 +154,7 @@ function prepareProtocolToolCall(agent, args, options = {}) {
   const argsWithVersion = applyVersionEnvelope(args, envelope);
   applyPublishedSchemaCompatibility(options.toolName, argsWithVersion, args);
   const effectiveBundle = typeof argsWithVersion.adcp_version === "string" ? resolveBundleKey(argsWithVersion.adcp_version) : void 0;
-  const usesApplicationRegistration = options.serverVersion !== "v2" && isAdcpVersionAtLeast(effectiveBundle, "3.1.0");
+  const usesApplicationRegistration = isAdcpVersionAtLeast(effectiveBundle, "3.1.0");
   let pushNotificationConfig;
   let applicationPushNotificationConfig;
   let operationId;
@@ -174,8 +168,6 @@ function prepareProtocolToolCall(agent, args, options = {}) {
           credentials: options.webhookSecret
         }
       };
-    } else if (options.serverVersion === "v2") {
-      warnV2PushNotificationNeedsSecret();
     } else {
       pushNotificationConfig = {
         url: options.webhookUrl,

package/dist/lib/registry/types.d.mts

@@ -144,9 +144,10 @@ export type SavePropertyRequest = Omit<RegistrySavePropertyRequest, 'authorized_
 /** Response from POST /api/properties/save (200) */
 export type SavePropertyResponse = operations['saveProperty']['responses']['200']['content']['application/json'];
 type RegistryResolveIdentifiersRequest = NonNullable<operations['resolveIdentifiers']['requestBody']>['content']['application/json'];
-/** Request body for POST /api/registry/resolve. `mode` defaults to `resolve` server-side. */
-export type ResolveIdentifiersRequest = Omit<RegistryResolveIdentifiersRequest, 'mode'> & {
+/** Request body for POST /api/registry/resolve. Mode and sandbox use the registry's defaults when omitted. */
+export type ResolveIdentifiersRequest = Omit<RegistryResolveIdentifiersRequest, 'mode' | 'sandbox'> & {
     mode?: RegistryResolveIdentifiersRequest['mode'];
+    sandbox?: RegistryResolveIdentifiersRequest['sandbox'];
 };
 /** Response from POST /api/registry/resolve (200) */
 export type ResolveIdentifiersResponse = operations['resolveIdentifiers']['responses']['200']['content']['application/json'];

package/dist/lib/registry/types.d.ts

@@ -144,9 +144,10 @@ export type SavePropertyRequest = Omit<RegistrySavePropertyRequest, 'authorized_
 /** Response from POST /api/properties/save (200) */
 export type SavePropertyResponse = operations['saveProperty']['responses']['200']['content']['application/json'];
 type RegistryResolveIdentifiersRequest = NonNullable<operations['resolveIdentifiers']['requestBody']>['content']['application/json'];
-/** Request body for POST /api/registry/resolve. `mode` defaults to `resolve` server-side. */
-export type ResolveIdentifiersRequest = Omit<RegistryResolveIdentifiersRequest, 'mode'> & {
+/** Request body for POST /api/registry/resolve. Mode and sandbox use the registry's defaults when omitted. */
+export type ResolveIdentifiersRequest = Omit<RegistryResolveIdentifiersRequest, 'mode' | 'sandbox'> & {
     mode?: RegistryResolveIdentifiersRequest['mode'];
+    sandbox?: RegistryResolveIdentifiersRequest['sandbox'];
 };
 /** Response from POST /api/registry/resolve (200) */
 export type ResolveIdentifiersResponse = operations['resolveIdentifiers']['responses']['200']['content']['application/json'];

package/dist/lib/registry/types.generated.d.mts

@@ -283,7 +283,7 @@ export interface paths {
         put?: never;
         /**
          * Save property
-         * @description Save or update a hosted property in the registry. Requires authentication. For existing properties, creates a revision-tracked edit. For new properties, creates the property directly. Cannot edit authoritative properties managed via adagents.json.
+         * @description Save or update a hosted property in the registry. Requires authentication. For bulk identifier contributions use resolveIdentifiers instead (up to 10,000 identifiers per request). This endpoint is limited to 60 requests/hour per user/IP. publisher_domain must be a lowercase hostname without a URL, port, whitespace, wildcard, or trailing dot. Reserved test domains are rejected unless sandbox is true. With sandbox: true the request is validated and a simulated result is returned without reading or writing a hosted property; the ID is ephemeral. For existing properties, creates a revision-tracked edit. For new properties, creates the property directly. Cannot edit authoritative properties managed via adagents.json.
          *
          *     This is an identity-only write surface: the stored document always carries `authorized_agents: []`. Sales authorization lives solely in the publisher's own origin `adagents.json`; the community registry cannot mint or carry it. Any `authorized_agents` sent in the request body is ignored.
          */
@@ -525,6 +525,8 @@ export interface paths {
          * @description Given a percent-encoded `agent_url`, returns the publishers whose adagents.json authorizes that agent, with provenance (`discovery_method`, `manager_domain`), per-publisher property counts (`properties_authorized`, `properties_total`, scoped to this publisher only — never network-wide), signing-key pin status, and lifecycle state (`authorized` / `revoked`).
          *
          *     Spec: [docs/aao/directory-api.mdx](/docs/aao/directory-api) (adcp#4823). This endpoint is the spec-compliant richer-shape replacement for the legacy `/api/registry/lookup/agent/{agentUrl}/domains`, which returns domain strings only.
+         *
+         *     `agent_url` is matched with [AdCP URL canonicalization](/docs/reference/url-canonicalization) and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets, the same rule the SDK applies in `verify_agent_authorization`. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
          */
         get: operations["getPublishersForAgentLegacyApiPrefix"];
         put?: never;
@@ -547,6 +549,8 @@ export interface paths {
          * @description Given a percent-encoded `agent_url`, returns the publishers whose adagents.json authorizes that agent, with provenance (`discovery_method`, `manager_domain`), per-publisher property counts (`properties_authorized`, `properties_total`, scoped to this publisher only — never network-wide), signing-key pin status, and lifecycle state (`authorized` / `revoked`).
          *
          *     Spec: [docs/aao/directory-api.mdx](/docs/aao/directory-api) (adcp#4823). This endpoint is the spec-compliant richer-shape replacement for the legacy `/api/registry/lookup/agent/{agentUrl}/domains`, which returns domain strings only.
+         *
+         *     `agent_url` is matched with [AdCP URL canonicalization](/docs/reference/url-canonicalization) and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets, the same rule the SDK applies in `verify_agent_authorization`. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
          */
         get: operations["getPublishersForAgent"];
         put?: never;
@@ -2526,6 +2530,8 @@ export interface components {
             stats?: components["schemas"]["AgentStats"];
             capabilities?: components["schemas"]["AgentCapabilities"];
             compliance?: components["schemas"]["AgentCompliance"];
+            /** @description Every raw agent_url spelling the directory has indexed under this agent's identity, with the listed (canonical) url first. The registry keys an agent by identity, folding a non-root trailing slash, but GET /v1/agents/{agent_url}/publishers matches spec-exactly with the slash significant — so a client answering "which publishers authorize this agent" must query once per spelling here and merge the results. */
+            declared_urls?: string[];
             publisher_domains?: string[];
             property_summary?: components["schemas"]["PropertySummary"];
         };
@@ -2661,6 +2667,8 @@ export interface components {
             timeout_ms: number | null;
             storyboard_start_offset: number | null;
             auth_type: string | null;
+            /** @description Declared specialisms the graded compliance release does not define. Capability resolution skipped them instead of voiding the run; they were not graded. Absent on ordinary runs. */
+            tolerated_undefined_specialisms?: string[];
         } | null;
         /** @enum {string} */
         BadgeRole: "media-buy" | "creative" | "signals" | "governance" | "brand" | "sponsored-intelligence";
@@ -4246,13 +4254,31 @@ export interface components {
                 storyboards_total: number | null;
                 first_blocker: string | null;
             } | null;
+            /** @description Owner/operator-only. Present while the newest scheduled heartbeat ran out of time, so the owner can see that the published result is not being refreshed. Null for other viewers and once a later heartbeat completes. This does not change the public verdict. */
+            heartbeat_timeout?: {
+                /** Format: uuid */
+                run_id: string;
+                /** Format: date-time */
+                timed_out_at: string;
+                duration_ms: number | null;
+                timeout_ms: number | null;
+                storyboards_completed: number | null;
+                storyboards_total: number | null;
+                consecutive: number;
+                /** @description True when the streak filled the lookback window, so the real run of timeouts may be longer than `consecutive`. */
+                consecutive_capped: boolean;
+                /** Format: date-time */
+                published_at: string | null;
+                /** @description Ready-to-render owner-facing sentence. Built only from platform- and runner-generated values; no agent response text. */
+                summary: string;
+            } | null;
             /** @description How often the heartbeat re-tests this agent, in hours */
             check_interval_hours?: number;
             /** @description Specialisms the agent declared in get_adcp_capabilities, from the latest run */
             declared_specialisms?: string[];
-            /** @description Per-specialism pass/fail/untested status — keyed on declared specialism, derived from the matching storyboard's status */
+            /** @description Per-specialism pass/fail/untested status — keyed on declared specialism, derived from the matching storyboard's status. `not_applicable` means AdCP introduced the specialism after the compliance release this run graded, so it could not be tested. */
             specialism_status?: {
-                [key: string]: "passing" | "failing" | "untested" | "unknown";
+                [key: string]: "passing" | "failing" | "untested" | "unknown" | "not_applicable";
             };
             eligibility?: components["schemas"]["ComplianceEligibility"];
             /** @description Public per-storyboard verdicts and aggregate step counts. First-failure diagnostic fields are populated only for owners; scalar diagnostics are null and validation evidence is empty for other callers. */
@@ -4892,6 +4918,11 @@ export interface components {
          */
         OrganizationRevenueTier: "under_1m" | "1m_5m" | "5m_50m" | "50m_250m" | "250m_1b" | "1b_plus";
         ResolveResponse: {
+            /**
+             * @description Present for a non-persistent sandbox simulation. New property handles are ephemeral.
+             * @enum {boolean}
+             */
+            sandbox?: true;
             resolved: components["schemas"]["ResolvedEntry"][];
             summary: {
                 total: number;
@@ -4915,30 +4946,30 @@ export interface components {
         CatalogIdentifier: {
             /** @example domain */
             type: string;
-            /** @example nytimes.com */
+            /** @example streamhaus.com */
             value: string;
         };
+        /** @description Up to 10,000 identifiers plus provenance. resolve requires authentication and contributes unknown identifiers; lookup is read-only. Domain/subdomain values must follow core/identifier.json; production rejects reserved test domains. sandbox: true simulates contributions without writes. */
         ResolveRequest: {
             /** @description Identifiers to resolve (and, in resolve mode, contribute). Max 10,000 per call for all callers. */
             identifiers: components["schemas"]["CatalogIdentifier"][];
             provenance: components["schemas"]["FactProvenance"];
             /**
-             * @description `resolve` (default) contributes the identifiers, auto-creates missing catalog entries, logs demand activity, and returns rids — requires authentication. `lookup` is a pure read: no write, no activity log, no auth.
+             * @description resolve (default) contributes identifiers, creates missing catalog entries, and logs activity; authentication is required. lookup is a public read with no writes or activity logging.
              * @default resolve
              * @enum {string}
              */
             mode: "resolve" | "lookup";
+            /** @description Simulate contributions without storing properties, identifiers, facts, or activity. Reads existing catalog data; new handles are ephemeral. Reserved test domains are allowed only in sandbox mode. Defaults to false when omitted. */
+            sandbox?: boolean;
         };
         FactProvenance: {
             /**
-             * @description How the caller knows these identifiers — the trust/audit envelope on the fact. Determines the confidence the catalog assigns. `crawl` is reserved for server-side pipelines; callers use the others.
+             * @description How the caller knows these identifiers — the trust/audit envelope on the fact. Determines the confidence the catalog assigns. crawl is reserved for server-side pipelines; callers use the others.
              * @enum {string}
              */
             type: "agency_allowlist" | "publisher_declaration" | "impression_log" | "ssp_inventory" | "deal_history" | "crawl" | "data_partner" | "member_assertion";
-            /**
-             * @description Optional free-text annotation (campaign, dataset).
-             * @example unilever_q3
-             */
+            /** @description Optional free-text annotation (campaign, dataset). */
             context?: string;
         };
         CatalogDisputeTriageResult: {
@@ -5731,6 +5762,11 @@ export interface operations {
                 "application/json": {
                     /** @example examplepub.com */
                     publisher_domain: string;
+                    /**
+                     * @description Validate and simulate a save without persisting it. Allows reserved test hostnames.
+                     * @default false
+                     */
+                    sandbox?: boolean;
                     /**
                      * @description Ignored. Community-registry rows never assert sales authorization — the owner's origin adagents.json is the sole authorization source — so any value here is dropped and the stored document carries authorized_agents:[].
                      * @example []
@@ -5770,6 +5806,8 @@ export interface operations {
                         success: true;
                         message: string;
                         id: string;
+                        /** @enum {boolean} */
+                        sandbox?: true;
                         revision_number?: number;
                     };
                 };
@@ -8475,7 +8513,7 @@ export interface operations {
     getAgentAuthorizations: {
         parameters: {
             query: {
-                /** @description Agent URL to look up. Canonicalized server-side (lowercased, trailing slashes trimmed). */
+                /** @description Agent URL to look up. Canonicalized server-side per AdCP URL canonicalization: the scheme and host fold, the path does not. */
                 agent_url: string;
                 /** @description `effective` (default) applies override layer; `raw` reads base table. */
                 include?: "raw" | "effective";
@@ -10954,6 +10992,8 @@ export interface operations {
                             }[];
                         }[];
                         total_storyboards: number;
+                        /** @description Declared specialisms AdCP introduced after this compliance release. They have no bundle to run here, so they are listed separately instead of failing resolution. */
+                        specialisms_not_applicable?: string[];
                     };
                 };
             };

package/dist/lib/registry/types.generated.d.ts

@@ -283,7 +283,7 @@ export interface paths {
         put?: never;
         /**
          * Save property
-         * @description Save or update a hosted property in the registry. Requires authentication. For existing properties, creates a revision-tracked edit. For new properties, creates the property directly. Cannot edit authoritative properties managed via adagents.json.
+         * @description Save or update a hosted property in the registry. Requires authentication. For bulk identifier contributions use resolveIdentifiers instead (up to 10,000 identifiers per request). This endpoint is limited to 60 requests/hour per user/IP. publisher_domain must be a lowercase hostname without a URL, port, whitespace, wildcard, or trailing dot. Reserved test domains are rejected unless sandbox is true. With sandbox: true the request is validated and a simulated result is returned without reading or writing a hosted property; the ID is ephemeral. For existing properties, creates a revision-tracked edit. For new properties, creates the property directly. Cannot edit authoritative properties managed via adagents.json.
          *
          *     This is an identity-only write surface: the stored document always carries `authorized_agents: []`. Sales authorization lives solely in the publisher's own origin `adagents.json`; the community registry cannot mint or carry it. Any `authorized_agents` sent in the request body is ignored.
          */
@@ -525,6 +525,8 @@ export interface paths {
          * @description Given a percent-encoded `agent_url`, returns the publishers whose adagents.json authorizes that agent, with provenance (`discovery_method`, `manager_domain`), per-publisher property counts (`properties_authorized`, `properties_total`, scoped to this publisher only — never network-wide), signing-key pin status, and lifecycle state (`authorized` / `revoked`).
          *
          *     Spec: [docs/aao/directory-api.mdx](/docs/aao/directory-api) (adcp#4823). This endpoint is the spec-compliant richer-shape replacement for the legacy `/api/registry/lookup/agent/{agentUrl}/domains`, which returns domain strings only.
+         *
+         *     `agent_url` is matched with [AdCP URL canonicalization](/docs/reference/url-canonicalization) and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets, the same rule the SDK applies in `verify_agent_authorization`. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
          */
         get: operations["getPublishersForAgentLegacyApiPrefix"];
         put?: never;
@@ -547,6 +549,8 @@ export interface paths {
          * @description Given a percent-encoded `agent_url`, returns the publishers whose adagents.json authorizes that agent, with provenance (`discovery_method`, `manager_domain`), per-publisher property counts (`properties_authorized`, `properties_total`, scoped to this publisher only — never network-wide), signing-key pin status, and lifecycle state (`authorized` / `revoked`).
          *
          *     Spec: [docs/aao/directory-api.mdx](/docs/aao/directory-api) (adcp#4823). This endpoint is the spec-compliant richer-shape replacement for the legacy `/api/registry/lookup/agent/{agentUrl}/domains`, which returns domain strings only.
+         *
+         *     `agent_url` is matched with [AdCP URL canonicalization](/docs/reference/url-canonicalization) and a **non-root trailing slash is significant**: `https://a.example/mcp` and `https://a.example/mcp/` are different agents and can return different publisher sets, the same rule the SDK applies in `verify_agent_authorization`. Ask for the spelling the publisher's adagents.json lists. (Through 2026-10-18 this endpoint folded the two spellings together and answered both with the slashless agent's publishers; that disagreed with the spec and with the validator.) The `agent_url` in the response echoes the canonicalized lookup key, slash included.
          */
         get: operations["getPublishersForAgent"];
         put?: never;
@@ -2526,6 +2530,8 @@ export interface components {
             stats?: components["schemas"]["AgentStats"];
             capabilities?: components["schemas"]["AgentCapabilities"];
             compliance?: components["schemas"]["AgentCompliance"];
+            /** @description Every raw agent_url spelling the directory has indexed under this agent's identity, with the listed (canonical) url first. The registry keys an agent by identity, folding a non-root trailing slash, but GET /v1/agents/{agent_url}/publishers matches spec-exactly with the slash significant — so a client answering "which publishers authorize this agent" must query once per spelling here and merge the results. */
+            declared_urls?: string[];
             publisher_domains?: string[];
             property_summary?: components["schemas"]["PropertySummary"];
         };
@@ -2661,6 +2667,8 @@ export interface components {
             timeout_ms: number | null;
             storyboard_start_offset: number | null;
             auth_type: string | null;
+            /** @description Declared specialisms the graded compliance release does not define. Capability resolution skipped them instead of voiding the run; they were not graded. Absent on ordinary runs. */
+            tolerated_undefined_specialisms?: string[];
         } | null;
         /** @enum {string} */
         BadgeRole: "media-buy" | "creative" | "signals" | "governance" | "brand" | "sponsored-intelligence";
@@ -4246,13 +4254,31 @@ export interface components {
                 storyboards_total: number | null;
                 first_blocker: string | null;
             } | null;
+            /** @description Owner/operator-only. Present while the newest scheduled heartbeat ran out of time, so the owner can see that the published result is not being refreshed. Null for other viewers and once a later heartbeat completes. This does not change the public verdict. */
+            heartbeat_timeout?: {
+                /** Format: uuid */
+                run_id: string;
+                /** Format: date-time */
+                timed_out_at: string;
+                duration_ms: number | null;
+                timeout_ms: number | null;
+                storyboards_completed: number | null;
+                storyboards_total: number | null;
+                consecutive: number;
+                /** @description True when the streak filled the lookback window, so the real run of timeouts may be longer than `consecutive`. */
+                consecutive_capped: boolean;
+                /** Format: date-time */
+                published_at: string | null;
+                /** @description Ready-to-render owner-facing sentence. Built only from platform- and runner-generated values; no agent response text. */
+                summary: string;
+            } | null;
             /** @description How often the heartbeat re-tests this agent, in hours */
             check_interval_hours?: number;
             /** @description Specialisms the agent declared in get_adcp_capabilities, from the latest run */
             declared_specialisms?: string[];
-            /** @description Per-specialism pass/fail/untested status — keyed on declared specialism, derived from the matching storyboard's status */
+            /** @description Per-specialism pass/fail/untested status — keyed on declared specialism, derived from the matching storyboard's status. `not_applicable` means AdCP introduced the specialism after the compliance release this run graded, so it could not be tested. */
             specialism_status?: {
-                [key: string]: "passing" | "failing" | "untested" | "unknown";
+                [key: string]: "passing" | "failing" | "untested" | "unknown" | "not_applicable";
             };
             eligibility?: components["schemas"]["ComplianceEligibility"];
             /** @description Public per-storyboard verdicts and aggregate step counts. First-failure diagnostic fields are populated only for owners; scalar diagnostics are null and validation evidence is empty for other callers. */
@@ -4892,6 +4918,11 @@ export interface components {
          */
         OrganizationRevenueTier: "under_1m" | "1m_5m" | "5m_50m" | "50m_250m" | "250m_1b" | "1b_plus";
         ResolveResponse: {
+            /**
+             * @description Present for a non-persistent sandbox simulation. New property handles are ephemeral.
+             * @enum {boolean}
+             */
+            sandbox?: true;
             resolved: components["schemas"]["ResolvedEntry"][];
             summary: {
                 total: number;
@@ -4915,30 +4946,30 @@ export interface components {
         CatalogIdentifier: {
             /** @example domain */
             type: string;
-            /** @example nytimes.com */
+            /** @example streamhaus.com */
             value: string;
         };
+        /** @description Up to 10,000 identifiers plus provenance. resolve requires authentication and contributes unknown identifiers; lookup is read-only. Domain/subdomain values must follow core/identifier.json; production rejects reserved test domains. sandbox: true simulates contributions without writes. */
         ResolveRequest: {
             /** @description Identifiers to resolve (and, in resolve mode, contribute). Max 10,000 per call for all callers. */
             identifiers: components["schemas"]["CatalogIdentifier"][];
             provenance: components["schemas"]["FactProvenance"];
             /**
-             * @description `resolve` (default) contributes the identifiers, auto-creates missing catalog entries, logs demand activity, and returns rids — requires authentication. `lookup` is a pure read: no write, no activity log, no auth.
+             * @description resolve (default) contributes identifiers, creates missing catalog entries, and logs activity; authentication is required. lookup is a public read with no writes or activity logging.
              * @default resolve
              * @enum {string}
              */
             mode: "resolve" | "lookup";
+            /** @description Simulate contributions without storing properties, identifiers, facts, or activity. Reads existing catalog data; new handles are ephemeral. Reserved test domains are allowed only in sandbox mode. Defaults to false when omitted. */
+            sandbox?: boolean;
         };
         FactProvenance: {
             /**
-             * @description How the caller knows these identifiers — the trust/audit envelope on the fact. Determines the confidence the catalog assigns. `crawl` is reserved for server-side pipelines; callers use the others.
+             * @description How the caller knows these identifiers — the trust/audit envelope on the fact. Determines the confidence the catalog assigns. crawl is reserved for server-side pipelines; callers use the others.
              * @enum {string}
              */
             type: "agency_allowlist" | "publisher_declaration" | "impression_log" | "ssp_inventory" | "deal_history" | "crawl" | "data_partner" | "member_assertion";
-            /**
-             * @description Optional free-text annotation (campaign, dataset).
-             * @example unilever_q3
-             */
+            /** @description Optional free-text annotation (campaign, dataset). */
             context?: string;
         };
         CatalogDisputeTriageResult: {
@@ -5731,6 +5762,11 @@ export interface operations {
                 "application/json": {
                     /** @example examplepub.com */
                     publisher_domain: string;
+                    /**
+                     * @description Validate and simulate a save without persisting it. Allows reserved test hostnames.
+                     * @default false
+                     */
+                    sandbox?: boolean;
                     /**
                      * @description Ignored. Community-registry rows never assert sales authorization — the owner's origin adagents.json is the sole authorization source — so any value here is dropped and the stored document carries authorized_agents:[].
                      * @example []
@@ -5770,6 +5806,8 @@ export interface operations {
                         success: true;
                         message: string;
                         id: string;
+                        /** @enum {boolean} */
+                        sandbox?: true;
                         revision_number?: number;
                     };
                 };
@@ -8475,7 +8513,7 @@ export interface operations {
     getAgentAuthorizations: {
         parameters: {
             query: {
-                /** @description Agent URL to look up. Canonicalized server-side (lowercased, trailing slashes trimmed). */
+                /** @description Agent URL to look up. Canonicalized server-side per AdCP URL canonicalization: the scheme and host fold, the path does not. */
                 agent_url: string;
                 /** @description `effective` (default) applies override layer; `raw` reads base table. */
                 include?: "raw" | "effective";
@@ -10954,6 +10992,8 @@ export interface operations {
                             }[];
                         }[];
                         total_storyboards: number;
+                        /** @description Declared specialisms AdCP introduced after this compliance release. They have no bundle to run here, so they are listed separately instead of failing resolution. */
+                        specialisms_not_applicable?: string[];
                     };
                 };
             };

package/dist/lib/reporting/source/conformance.d.mts

@@ -197,7 +197,7 @@ export declare function validateReportingRevisionSequenceV1(manifests: readonly
         semanticContractId: string;
         semanticContractVersion: string;
         semanticContractSha256: string;
-        status: "delayed" | "present" | "missing" | "unsupported" | "partial" | "stale" | "explicit_zero";
+        status: "delayed" | "partial" | "present" | "missing" | "unsupported" | "stale" | "explicit_zero";
         dataThrough?: string | undefined;
         reason?: string | undefined;
     }[];
@@ -209,7 +209,7 @@ export declare function validateReportingRevisionSequenceV1(manifests: readonly
             constituentId: string;
             constituentKind: "product";
             productId: string;
-            status: "delayed" | "present" | "missing" | "unsupported" | "partial" | "stale" | "explicit_zero";
+            status: "delayed" | "partial" | "present" | "missing" | "unsupported" | "stale" | "explicit_zero";
             packageId?: undefined;
             mediaBuyId?: undefined;
             productBinding?: undefined;
@@ -229,7 +229,7 @@ export declare function validateReportingRevisionSequenceV1(manifests: readonly
                 bindingSha256: string;
                 productId: string;
             };
-            status: "delayed" | "present" | "missing" | "unsupported" | "partial" | "stale" | "explicit_zero";
+            status: "delayed" | "partial" | "present" | "missing" | "unsupported" | "stale" | "explicit_zero";
             mediaBuyId?: undefined;
             dataThrough?: string | undefined;
             reason?: string | undefined;
@@ -247,7 +247,7 @@ export declare function validateReportingRevisionSequenceV1(manifests: readonly
                 bindingSha256: string;
                 productId: string;
             };
-            status: "delayed" | "present" | "missing" | "unsupported" | "partial" | "stale" | "explicit_zero";
+            status: "delayed" | "partial" | "present" | "missing" | "unsupported" | "stale" | "explicit_zero";
             packageId?: undefined;
             dataThrough?: string | undefined;
             reason?: string | undefined;
@@ -449,7 +449,7 @@ export declare function validateReportingRevisionSequenceV1(manifests: readonly
         semanticContractId: string;
         semanticContractVersion: string;
         semanticContractSha256: string;
-        status: "delayed" | "present" | "missing" | "unsupported" | "partial" | "stale" | "explicit_zero";
+        status: "delayed" | "partial" | "present" | "missing" | "unsupported" | "stale" | "explicit_zero";
         dataThrough?: string | undefined;
         reason?: string | undefined;
     }[];
@@ -461,7 +461,7 @@ export declare function validateReportingRevisionSequenceV1(manifests: readonly
             constituentId: string;
             constituentKind: "product";
             productId: string;
-            status: "delayed" | "present" | "missing" | "unsupported" | "partial" | "stale" | "explicit_zero";
+            status: "delayed" | "partial" | "present" | "missing" | "unsupported" | "stale" | "explicit_zero";
             packageId?: undefined;
             mediaBuyId?: undefined;
             productBinding?: undefined;
@@ -481,7 +481,7 @@ export declare function validateReportingRevisionSequenceV1(manifests: readonly
                 bindingSha256: string;
                 productId: string;
             };
-            status: "delayed" | "present" | "missing" | "unsupported" | "partial" | "stale" | "explicit_zero";
+            status: "delayed" | "partial" | "present" | "missing" | "unsupported" | "stale" | "explicit_zero";
             mediaBuyId?: undefined;
             dataThrough?: string | undefined;
             reason?: string | undefined;
@@ -499,7 +499,7 @@ export declare function validateReportingRevisionSequenceV1(manifests: readonly
                 bindingSha256: string;
                 productId: string;
             };
-            status: "delayed" | "present" | "missing" | "unsupported" | "partial" | "stale" | "explicit_zero";
+            status: "delayed" | "partial" | "present" | "missing" | "unsupported" | "stale" | "explicit_zero";
             packageId?: undefined;
             dataThrough?: string | undefined;
             reason?: string | undefined;