@adcp/sdk 16.0.0 → 16.1.0

package/dist/lib/identity-3.3/trust.mjs

@@ -70,8 +70,34 @@ function validateTrustRecord(value) {
     origins.add(origin);
   }
 }
-function createTrustRecord(record) {
+function registrableGrantee(grantee) {
+  try {
+    return eTldPlusOne(grantee) === grantee ? grantee : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function grantAgentOrigin(url) {
+  try {
+    return canonicalAgentOrigin(url);
+  } catch {
+    return void 0;
+  }
+}
+function assertPublishableTrustRecord(record) {
   validateTrustRecord(record);
+  for (const grant of record.grants ?? []) {
+    if (registrableGrantee(grant.grantee) === void 0)
+      throw new TypeError(
+        `Grant grantee "${grant.grantee}" is not a registrable domain; name the organization's registrable domain and narrow with agents[]`
+      );
+    for (const agent of grant.agents ?? [])
+      if (grantAgentOrigin(agent.url) === void 0)
+        throw new TypeError(`Grant agents[] URL "${agent.url}" is not a valid agent origin`);
+  }
+}
+function createTrustRecord(record) {
+  assertPublishableTrustRecord(record);
   return structuredClone(record);
 }
 class TrustEvaluator {
@@ -268,13 +294,15 @@ function authorityGroup(operator) {
   const provider = parseDomain(operator).domain;
   return `private:${provider ?? operator}`;
 }
+function grantsScope(grant, scope) {
+  return grant.scopes.some(
+    (granted) => granted === "*" || granted === scope || granted === "adcp:all" && scope.startsWith("adcp:")
+  );
+}
 function grantMatches(grant, target, claim, now) {
-  if (eTldPlusOne(grant.grantee) !== target) return false;
-  if (!grant.scopes.some(
-    (scope) => scope === "*" || scope === claim.scope || scope === "adcp:all" && claim.scope.startsWith("adcp:")
-  ))
-    return false;
-  if (grant.agents && !grant.agents.some((agent) => canonicalAgentOrigin(agent.url) === canonicalAgentOrigin(claim.signerOrigin)))
+  if (registrableGrantee(grant.grantee) !== target) return false;
+  if (!grantsScope(grant, claim.scope)) return false;
+  if (grant.agents && !grant.agents.some((agent) => grantAgentOrigin(agent.url) === canonicalAgentOrigin(claim.signerOrigin)))
     return false;
   const brands = grant.profiles?.adcp?.brands;
   if (brands && !brands.includes("*") && (!claim.brand.brand_id || !brands.includes(claim.brand.brand_id)))
@@ -321,11 +349,10 @@ async function authorizeDemandGrant(claim, options) {
       if (second) return result("trust", [brand, account, operator], [first[0], second]);
     }
   }
-  const covered = (record.record.grants ?? []).some(
-    (g) => (eTldPlusOne(g.grantee) === account || selfOperated && eTldPlusOne(g.grantee) === operator) && g.scopes.some(
-      (scope) => scope === "*" || scope === claim.scope || scope === "adcp:all" && claim.scope.startsWith("adcp:")
-    )
-  );
+  const covered = (record.record.grants ?? []).some((g) => {
+    const grantee = registrableGrantee(g.grantee);
+    return grantee !== void 0 && (grantee === account || selfOperated && grantee === operator) && grantsScope(g, claim.scope);
+  });
   if (!covered && !record.record.exclusive_grants && await options.sellerAuthorization?.(claim))
     return result("seller", [brand, account, operator]);
   throw new IdentityAuthorizationError("grant_absent");
@@ -335,6 +362,7 @@ export {
   TrustEvaluator,
   TrustMembershipError,
   TrustRecordUnavailableError,
+  assertPublishableTrustRecord,
   authorizeDemandGrant,
   createTrustRecord,
   validateIdentity33Schema,

package/dist/lib/index.d.mts

@@ -36,7 +36,7 @@ export { match, attachMatch } from './core/match.mjs';
 export type { MatchHandlers, PartialMatchHandlers } from './core/match.mjs';
 export { ProtocolResponseParser, responseParser, ADCP_STATUS, type ADCPStatus } from './core/ProtocolResponseParser.mjs';
 export { ResponseValidator, responseValidator, type ValidationResult, type ValidationOptions, } from './core/ResponseValidator.mjs';
-export type { Message, InputRequest, InputHandler, InputHandlerResponse, ConversationContext, TaskOptions, WebhookToolPredicate, WebhookUrlTemplate, TaskResult, TaskResultCompleted, TaskResultIntermediate, TaskResultFailure, TaskResultMetadata, DeferredContinuation, DirectPauseRecoveryRequest, TaskState, TaskStatus, ConversationConfig, AdcpErrorInfo, AdcpValidationIssue, } from './core/ConversationTypes.mjs';
+export type { Message, InputRequest, InputHandler, InputHandlerResponse, ConversationContext, TaskOptions, TrackTaskRequest, TrackedTask, SubmittedContinuation, TaskInfo, WebhookToolPredicate, WebhookUrlTemplate, TaskResult, TaskResultCompleted, TaskResultIntermediate, TaskResultFailure, TaskResultMetadata, DeferredContinuation, DirectPauseRecoveryRequest, TaskState, TaskStatus, ConversationConfig, AdcpErrorInfo, AdcpValidationIssue, } from './core/ConversationTypes.mjs';
 export type { GovernanceConfig, CampaignGovernanceConfig, GovernanceCheckResult, GovernanceOutcome, GovernanceFinding, GovernanceIntentDetails, GovernanceCondition, GovernanceEscalation, NormalizedGovernanceApproved, NormalizedGovernanceConditions, NormalizedGovernanceDenied, NormalizedGovernanceVerdict, } from './core/GovernanceTypes.mjs';
 export { GovernanceMiddleware } from './core/GovernanceMiddleware.mjs';
 export { isGovernanceApproved, isGovernanceConditions, isGovernanceDenied, normalizeGovernanceVerdict, } from './core/GovernanceTypes.mjs';

package/dist/lib/index.d.ts

@@ -36,7 +36,7 @@ export { match, attachMatch } from './core/match';
 export type { MatchHandlers, PartialMatchHandlers } from './core/match';
 export { ProtocolResponseParser, responseParser, ADCP_STATUS, type ADCPStatus } from './core/ProtocolResponseParser';
 export { ResponseValidator, responseValidator, type ValidationResult, type ValidationOptions, } from './core/ResponseValidator';
-export type { Message, InputRequest, InputHandler, InputHandlerResponse, ConversationContext, TaskOptions, WebhookToolPredicate, WebhookUrlTemplate, TaskResult, TaskResultCompleted, TaskResultIntermediate, TaskResultFailure, TaskResultMetadata, DeferredContinuation, DirectPauseRecoveryRequest, TaskState, TaskStatus, ConversationConfig, AdcpErrorInfo, AdcpValidationIssue, } from './core/ConversationTypes';
+export type { Message, InputRequest, InputHandler, InputHandlerResponse, ConversationContext, TaskOptions, TrackTaskRequest, TrackedTask, SubmittedContinuation, TaskInfo, WebhookToolPredicate, WebhookUrlTemplate, TaskResult, TaskResultCompleted, TaskResultIntermediate, TaskResultFailure, TaskResultMetadata, DeferredContinuation, DirectPauseRecoveryRequest, TaskState, TaskStatus, ConversationConfig, AdcpErrorInfo, AdcpValidationIssue, } from './core/ConversationTypes';
 export type { GovernanceConfig, CampaignGovernanceConfig, GovernanceCheckResult, GovernanceOutcome, GovernanceFinding, GovernanceIntentDetails, GovernanceCondition, GovernanceEscalation, NormalizedGovernanceApproved, NormalizedGovernanceConditions, NormalizedGovernanceDenied, NormalizedGovernanceVerdict, } from './core/GovernanceTypes';
 export { GovernanceMiddleware } from './core/GovernanceMiddleware';
 export { isGovernanceApproved, isGovernanceConditions, isGovernanceDenied, normalizeGovernanceVerdict, } from './core/GovernanceTypes';

package/dist/lib/server/account-sync-contract.js

@@ -28,6 +28,7 @@ module.exports = __toCommonJS(account_sync_contract_exports);
 var import_account_key = require('../core/account-key.js');
 var import_account = require('./decisioning/account.js');
 var import_async_outcome = require('./decisioning/async-outcome.js');
+const NATURAL_KEY_FIELDS = ["brand", "operator", "operator_unit", "currency", "timezone", "sandbox"];
 function isolateAccountCallbackInput(ctx) {
   const descriptors = Object.getOwnPropertyDescriptors(ctx);
   delete descriptors.input;
@@ -58,7 +59,9 @@ function naturalRef(entry) {
   const ref = entry.account ?? entry;
   if (!ref || "account_id" in ref || !("brand" in ref) || !ref.brand || typeof ref.operator !== "string")
     return void 0;
-  return ref;
+  return Object.fromEntries(
+    NATURAL_KEY_FIELDS.filter((field) => ref[field] !== void 0).map((field) => [field, ref[field]])
+  );
 }
 async function lookup(accounts, ref, ctx, onUnsupported) {
   try {

package/dist/lib/server/account-sync-contract.mjs

@@ -1,6 +1,7 @@
 import { accountReferenceKey } from "../core/account-key.mjs";
 import { AccountNotFoundError, toWireAccount } from "./decisioning/account.mjs";
 import { AdcpError } from "./decisioning/async-outcome.mjs";
+const NATURAL_KEY_FIELDS = ["brand", "operator", "operator_unit", "currency", "timezone", "sandbox"];
 function isolateAccountCallbackInput(ctx) {
   const descriptors = Object.getOwnPropertyDescriptors(ctx);
   delete descriptors.input;
@@ -31,7 +32,9 @@ function naturalRef(entry) {
   const ref = entry.account ?? entry;
   if (!ref || "account_id" in ref || !("brand" in ref) || !ref.brand || typeof ref.operator !== "string")
     return void 0;
-  return ref;
+  return Object.fromEntries(
+    NATURAL_KEY_FIELDS.filter((field) => ref[field] !== void 0).map((field) => [field, ref[field]])
+  );
 }
 async function lookup(accounts, ref, ctx, onUnsupported) {
   try {

package/dist/lib/server/decisioning/runtime/from-platform.js

@@ -1009,23 +1009,28 @@ function jsonValuesEqual(left, right) {
   return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(rightRecord, key) && jsonValuesEqual(leftRecord[key], rightRecord[key]));
 }
 function matchLegacyRefToDeclaration(declaration, ref, ownerId, legacyFormatConverter) {
-  const projected = (0, import_v1_to_v2.projectV1ProductToV2)(
-    {
-      product_id: ownerId,
-      name: ownerId,
-      description: ownerId,
-      format_ids: [ref]
-    },
-    { legacyFormatConverter }
-  );
-  if (projected.diagnostics.length > 0 || projected.v2.format_options.length !== 1) return "unresolved";
-  const expected = projected.v2.format_options[0];
-  if (declaration.format_kind !== expected.format_kind) return "kind_mismatch";
-  const params = declaration.params !== null && typeof declaration.params === "object" && !Array.isArray(declaration.params) ? declaration.params : {};
-  for (const [key, expectedValue] of Object.entries(expected.params)) {
-    if (!Object.hasOwn(params, key) || !jsonValuesEqual(params[key], expectedValue)) return "params_mismatch";
-  }
-  return "match";
+  const compare = (authoritativeOnly) => {
+    const projected = (0, import_v1_to_v2.projectV1ProductToV2)(
+      {
+        product_id: ownerId,
+        name: ownerId,
+        description: ownerId,
+        format_ids: [ref]
+      },
+      { legacyFormatConverter, _authoritativeOnly: authoritativeOnly }
+    );
+    if (projected.diagnostics.length > 0 || projected.v2.format_options.length !== 1) return "unresolved";
+    const expected = projected.v2.format_options[0];
+    if (declaration.format_kind !== expected.format_kind) return "kind_mismatch";
+    const params = declaration.params !== null && typeof declaration.params === "object" && !Array.isArray(declaration.params) ? declaration.params : {};
+    for (const [key, expectedValue] of Object.entries(expected.params)) {
+      if (!Object.hasOwn(params, key) || !jsonValuesEqual(params[key], expectedValue)) return "params_mismatch";
+    }
+    return "match";
+  };
+  const authoritative = compare(true);
+  if (authoritative !== "unresolved") return authoritative;
+  return compare(false) === "match" ? "match" : "unresolved";
 }
 function validateLegacyRefNarrowing(declaration, ref, ownerId, field, legacyFormatConverter) {
   const match = matchLegacyRefToDeclaration(declaration, ref, ownerId, legacyFormatConverter);

package/dist/lib/server/decisioning/runtime/from-platform.mjs

@@ -1041,23 +1041,28 @@ function jsonValuesEqual(left, right) {
   return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(rightRecord, key) && jsonValuesEqual(leftRecord[key], rightRecord[key]));
 }
 function matchLegacyRefToDeclaration(declaration, ref, ownerId, legacyFormatConverter) {
-  const projected = projectV1ProductToV2(
-    {
-      product_id: ownerId,
-      name: ownerId,
-      description: ownerId,
-      format_ids: [ref]
-    },
-    { legacyFormatConverter }
-  );
-  if (projected.diagnostics.length > 0 || projected.v2.format_options.length !== 1) return "unresolved";
-  const expected = projected.v2.format_options[0];
-  if (declaration.format_kind !== expected.format_kind) return "kind_mismatch";
-  const params = declaration.params !== null && typeof declaration.params === "object" && !Array.isArray(declaration.params) ? declaration.params : {};
-  for (const [key, expectedValue] of Object.entries(expected.params)) {
-    if (!Object.hasOwn(params, key) || !jsonValuesEqual(params[key], expectedValue)) return "params_mismatch";
-  }
-  return "match";
+  const compare = (authoritativeOnly) => {
+    const projected = projectV1ProductToV2(
+      {
+        product_id: ownerId,
+        name: ownerId,
+        description: ownerId,
+        format_ids: [ref]
+      },
+      { legacyFormatConverter, _authoritativeOnly: authoritativeOnly }
+    );
+    if (projected.diagnostics.length > 0 || projected.v2.format_options.length !== 1) return "unresolved";
+    const expected = projected.v2.format_options[0];
+    if (declaration.format_kind !== expected.format_kind) return "kind_mismatch";
+    const params = declaration.params !== null && typeof declaration.params === "object" && !Array.isArray(declaration.params) ? declaration.params : {};
+    for (const [key, expectedValue] of Object.entries(expected.params)) {
+      if (!Object.hasOwn(params, key) || !jsonValuesEqual(params[key], expectedValue)) return "params_mismatch";
+    }
+    return "match";
+  };
+  const authoritative = compare(true);
+  if (authoritative !== "unresolved") return authoritative;
+  return compare(false) === "match" ? "match" : "unresolved";
 }
 function validateLegacyRefNarrowing(declaration, ref, ownerId, field, legacyFormatConverter) {
   const match = matchLegacyRefToDeclaration(declaration, ref, ownerId, legacyFormatConverter);

package/dist/lib/signing/web-bot-auth.js

@@ -186,6 +186,14 @@ function jwkThumbprint(jwk) {
 function keyAlgorithm(jwk) {
   return jwk.kty === "OKP" && jwk.crv === "Ed25519" ? "ed25519" : void 0;
 }
+function importable(jwk) {
+  try {
+    (0, import_crypto2.jwkToPublicKey)(jwk);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function algorithm(jwk) {
   return keyAlgorithm(jwk) ?? denied("unsupported_key");
 }
@@ -590,25 +598,24 @@ async function verifyKeyDirectory(response, now = Date.now() / 1e3, options = {}
       if (!raw || typeof raw !== "object") denied("directory_key");
       if (Object.keys(raw).some((k) => PRIVATE_JWK_MEMBERS.has(k.toLowerCase()) || k.startsWith("_private")))
         denied("directory_key");
-      if (!keyAlgorithm(raw)) continue;
+      if (!keyAlgorithm(raw) || !importable(raw)) continue;
       const thumbprint = jwkThumbprint(raw);
       const key = { ...raw, kid: raw.kid ?? thumbprint };
       if (key.kid !== thumbprint || kids.has(key.kid) || key.adcp_use !== void 0 || !testKeysAllowed(options.allowTestKeys) && TEST_KIDS.has(key.kid))
         denied("directory_key");
       kids.add(key.kid);
-      keys.push(key);
       const proof = signatures.find((input) => input.params.keyid === key.kid && input.params.tag === DIRECTORY_TAG);
       if (!proof || !proof.components.includes("@authority;req") || !proof.components.includes("content-digest") || !Number.isSafeInteger(proof.params.created) || !Number.isSafeInteger(proof.params.expires) || proof.params.expires <= now || proof.params.expires <= proof.params.created)
-        denied("directory_proof");
+        continue;
       const proofComponents = [(0, import_http_message_sig.component)("@authority", { req: true }), (0, import_http_message_sig.component)("content-digest")];
       let covered;
       try {
         covered = proof.components.map(componentDescriptor);
       } catch {
-        return denied("directory_proof");
+        continue;
       }
       const requestHeaders = response.request.headers ?? {};
-      await verifyWithLibrary(
+      const proven = await verifyWithLibrary(
         {
           kind: "response",
           status: response.status,
@@ -634,7 +641,15 @@ async function verifyKeyDirectory(response, now = Date.now() / 1e3, options = {}
         // The library rejects a proof whose `created` is in the future (beyond skew).
         { requiredComponents: proofComponents, requiredParameters: ["created", "expires", "keyid", "tag"], now },
         async () => keyVerifier(key)
+      ).then(
+        () => true,
+        (error) => {
+          if (error instanceof WebBotAuthError) return false;
+          throw error;
+        }
       );
+      if (!proven) continue;
+      keys.push(key);
       expires = Math.min(expires, proof.params.expires);
     }
     if (!keys.length) denied("directory_keys");

package/dist/lib/signing/web-bot-auth.mjs

@@ -16,7 +16,7 @@ import { canonicalAgentUrl } from "./agent-resolver/select-agent.mjs";
 import { parseStrictJson } from "./agent-resolver/strict-json.mjs";
 import { getHeaderValue } from "./canonicalize.mjs";
 import { computeContentDigest, contentDigestMatches, contentDigestUsesEncoding } from "./content-digest.mjs";
-import { signWithPrivateJwkAsync, verifySignatureAsync } from "./crypto.mjs";
+import { jwkToPublicKey, signWithPrivateJwkAsync, verifySignatureAsync } from "./crypto.mjs";
 import {
   parseSignature,
   parseSignatureInputMember,
@@ -142,6 +142,14 @@ function jwkThumbprint(jwk) {
 function keyAlgorithm(jwk) {
   return jwk.kty === "OKP" && jwk.crv === "Ed25519" ? "ed25519" : void 0;
 }
+function importable(jwk) {
+  try {
+    jwkToPublicKey(jwk);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function algorithm(jwk) {
   return keyAlgorithm(jwk) ?? denied("unsupported_key");
 }
@@ -546,25 +554,24 @@ async function verifyKeyDirectory(response, now = Date.now() / 1e3, options = {}
       if (!raw || typeof raw !== "object") denied("directory_key");
       if (Object.keys(raw).some((k) => PRIVATE_JWK_MEMBERS.has(k.toLowerCase()) || k.startsWith("_private")))
         denied("directory_key");
-      if (!keyAlgorithm(raw)) continue;
+      if (!keyAlgorithm(raw) || !importable(raw)) continue;
       const thumbprint = jwkThumbprint(raw);
       const key = { ...raw, kid: raw.kid ?? thumbprint };
       if (key.kid !== thumbprint || kids.has(key.kid) || key.adcp_use !== void 0 || !testKeysAllowed(options.allowTestKeys) && TEST_KIDS.has(key.kid))
         denied("directory_key");
       kids.add(key.kid);
-      keys.push(key);
       const proof = signatures.find((input) => input.params.keyid === key.kid && input.params.tag === DIRECTORY_TAG);
       if (!proof || !proof.components.includes("@authority;req") || !proof.components.includes("content-digest") || !Number.isSafeInteger(proof.params.created) || !Number.isSafeInteger(proof.params.expires) || proof.params.expires <= now || proof.params.expires <= proof.params.created)
-        denied("directory_proof");
+        continue;
       const proofComponents = [component("@authority", { req: true }), component("content-digest")];
       let covered;
       try {
         covered = proof.components.map(componentDescriptor);
       } catch {
-        return denied("directory_proof");
+        continue;
       }
       const requestHeaders = response.request.headers ?? {};
-      await verifyWithLibrary(
+      const proven = await verifyWithLibrary(
         {
           kind: "response",
           status: response.status,
@@ -590,7 +597,15 @@ async function verifyKeyDirectory(response, now = Date.now() / 1e3, options = {}
         // The library rejects a proof whose `created` is in the future (beyond skew).
         { requiredComponents: proofComponents, requiredParameters: ["created", "expires", "keyid", "tag"], now },
         async () => keyVerifier(key)
+      ).then(
+        () => true,
+        (error) => {
+          if (error instanceof WebBotAuthError) return false;
+          throw error;
+        }
       );
+      if (!proven) continue;
+      keys.push(key);
       expires = Math.min(expires, proof.params.expires);
     }
     if (!keys.length) denied("directory_keys");

package/dist/lib/testing/storyboard/validations.d.mts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "16.0.0";
+export declare const RUNNER_CAPABILITY_VERSION = "16.1.0";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/testing/storyboard/validations.d.ts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "16.0.0";
+export declare const RUNNER_CAPABILITY_VERSION = "16.1.0";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/v2/projection/catalog.d.mts

@@ -91,6 +91,12 @@ interface CatalogIndex {
     byUniqueId: Map<string, V1FormatDefinition | null>;
     entries: V1FormatDefinition[];
 }
+/**
+ * True when `agentUrl` names the AAO reference format agent (including its
+ * folded historical hosts). Ids under any other agent URL belong to that
+ * agent, so AAO naming conventions say nothing about what they mean.
+ */
+export declare function isAaoAgentUrl(agentUrl: string): boolean;
 /**
  * Load the catalog from a known path. Resolution order:
  *

package/dist/lib/v2/projection/catalog.d.ts

@@ -91,6 +91,12 @@ interface CatalogIndex {
     byUniqueId: Map<string, V1FormatDefinition | null>;
     entries: V1FormatDefinition[];
 }
+/**
+ * True when `agentUrl` names the AAO reference format agent (including its
+ * folded historical hosts). Ids under any other agent URL belong to that
+ * agent, so AAO naming conventions say nothing about what they mean.
+ */
+export declare function isAaoAgentUrl(agentUrl: string): boolean;
 /**
  * Load the catalog from a known path. Resolution order:
  *

package/dist/lib/v2/projection/catalog.js

@@ -30,6 +30,7 @@ var catalog_exports = {};
 __export(catalog_exports, {
   _resetCatalogCache: () => _resetCatalogCache,
   findCatalogEntryByCanonicalAndSize: () => findCatalogEntryByCanonicalAndSize,
+  isAaoAgentUrl: () => isAaoAgentUrl,
   loadCatalog: () => loadCatalog,
   lookupUniqueV1FormatById: () => lookupUniqueV1FormatById,
   lookupV1Format: () => lookupV1Format,
@@ -52,6 +53,9 @@ function normalizeAgentUrl(u) {
   if (canonical === null) return void 0;
   return AAO_LEGACY_AGENT_URL_ALIASES.has(canonical) ? import_constants.AAO_CANONICAL_AGENT_URL : canonical;
 }
+function isAaoAgentUrl(agentUrl) {
+  return normalizeAgentUrl(agentUrl) === import_constants.AAO_CANONICAL_AGENT_URL;
+}
 function indexKey(agentUrl, id) {
   const normalized = normalizeAgentUrl(agentUrl);
   return normalized === void 0 ? void 0 : `${normalized}::${id}`;
@@ -136,6 +140,7 @@ function findCatalogEntryByCanonicalAndSize(canonical, width, height, agentUrl,
 0 && (module.exports = {
   _resetCatalogCache,
   findCatalogEntryByCanonicalAndSize,
+  isAaoAgentUrl,
   loadCatalog,
   lookupUniqueV1FormatById,
   lookupV1Format,

package/dist/lib/v2/projection/catalog.mjs

@@ -19,6 +19,9 @@ function normalizeAgentUrl(u) {
   if (canonical === null) return void 0;
   return AAO_LEGACY_AGENT_URL_ALIASES.has(canonical) ? AAO_CANONICAL_AGENT_URL : canonical;
 }
+function isAaoAgentUrl(agentUrl) {
+  return normalizeAgentUrl(agentUrl) === AAO_CANONICAL_AGENT_URL;
+}
 function indexKey(agentUrl, id) {
   const normalized = normalizeAgentUrl(agentUrl);
   return normalized === void 0 ? void 0 : `${normalized}::${id}`;
@@ -102,6 +105,7 @@ function findCatalogEntryByCanonicalAndSize(canonical, width, height, agentUrl,
 export {
   _resetCatalogCache,
   findCatalogEntryByCanonicalAndSize,
+  isAaoAgentUrl,
   loadCatalog,
   lookupUniqueV1FormatById,
   lookupV1Format,

package/dist/lib/v2/projection/v1-to-v2.js

@@ -219,7 +219,8 @@ function projectFormatId(fid, productId, field, options) {
   const exactCatalogEntry = (0, import_catalog.lookupV1Format)(fid, options?._catalogPath);
   const canonicalAgentUrl = (0, import_resolve_agent_properties.canonicalizeAgentUrl)(fid.agent_url);
   const mayUseUniqueAlias = canonicalAgentUrl !== null && new URL(canonicalAgentUrl).protocol === "https:" && !(0, import_address_guards.isLikelyPrivateUrl)(canonicalAgentUrl);
-  const uniqueAliasEntry = exactCatalogEntry === void 0 && mayUseUniqueAlias ? (0, import_catalog.lookupUniqueV1FormatById)(fid.id, options?._catalogPath) : void 0;
+  const aaoGuessesApply = options?._authoritativeOnly !== true || (0, import_catalog.isAaoAgentUrl)(fid.agent_url);
+  const uniqueAliasEntry = exactCatalogEntry === void 0 && mayUseUniqueAlias && aaoGuessesApply ? (0, import_catalog.lookupUniqueV1FormatById)(fid.id, options?._catalogPath) : void 0;
   if (uniqueAliasEntry) {
     const explicit = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
     if (explicit) return explicit;
@@ -277,7 +278,7 @@ function projectFormatId(fid, productId, field, options) {
       }
     };
   }
-  const globMatch = (0, import_registry.forwardLookupByGlob)(fid.id);
+  const globMatch = aaoGuessesApply ? (0, import_registry.forwardLookupByGlob)(fid.id) : void 0;
   if (globMatch) {
     return {
       decl: {

package/dist/lib/v2/projection/v1-to-v2.mjs

@@ -4,7 +4,7 @@ import { createRequire as __adcpCreateRequire } from "node:module";
 const __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));
 const require2 = __adcpCreateRequire(import.meta.url);
 import { forwardLookupByGlob, forwardLookupByStructural } from "./registry.mjs";
-import { lookupUniqueV1FormatById, lookupV1Format } from "./catalog.mjs";
+import { isAaoAgentUrl, lookupUniqueV1FormatById, lookupV1Format } from "./catalog.mjs";
 import { AAO_CANONICAL_AGENT_URL } from "./constants.mjs";
 import { LIBRARY_VERSION } from "../../version.mjs";
 import { legacyFormatConverterFromCatalogSnapshots } from "./catalog-snapshot.mjs";
@@ -202,7 +202,8 @@ function projectFormatId(fid, productId, field, options) {
   const exactCatalogEntry = lookupV1Format(fid, options?._catalogPath);
   const canonicalAgentUrl = canonicalizeAgentUrl(fid.agent_url);
   const mayUseUniqueAlias = canonicalAgentUrl !== null && new URL(canonicalAgentUrl).protocol === "https:" && !isLikelyPrivateUrl(canonicalAgentUrl);
-  const uniqueAliasEntry = exactCatalogEntry === void 0 && mayUseUniqueAlias ? lookupUniqueV1FormatById(fid.id, options?._catalogPath) : void 0;
+  const aaoGuessesApply = options?._authoritativeOnly !== true || isAaoAgentUrl(fid.agent_url);
+  const uniqueAliasEntry = exactCatalogEntry === void 0 && mayUseUniqueAlias && aaoGuessesApply ? lookupUniqueV1FormatById(fid.id, options?._catalogPath) : void 0;
   if (uniqueAliasEntry) {
     const explicit = projectWithLegacyConverter(fid, productId, field, options?.legacyFormatConverter);
     if (explicit) return explicit;
@@ -260,7 +261,7 @@ function projectFormatId(fid, productId, field, options) {
       }
     };
   }
-  const globMatch = forwardLookupByGlob(fid.id);
+  const globMatch = aaoGuessesApply ? forwardLookupByGlob(fid.id) : void 0;
   if (globMatch) {
     return {
       decl: {

package/dist/lib/version.d.mts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "16.0.0";
+export declare const LIBRARY_VERSION = "16.1.0";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "16.0.0";
+    readonly library: "16.1.0";
     readonly adcp: "3.2.5";
     readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5"];
-    readonly generatedAt: "2026-10-19T23:27:30.750Z";
+    readonly generatedAt: "2026-10-20T17:31:57.242Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.d.ts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "16.0.0";
+export declare const LIBRARY_VERSION = "16.1.0";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "16.0.0";
+    readonly library: "16.1.0";
     readonly adcp: "3.2.5";
     readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5"];
-    readonly generatedAt: "2026-10-19T23:27:30.750Z";
+    readonly generatedAt: "2026-10-20T17:31:57.242Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.js

@@ -31,7 +31,7 @@ __export(version_exports, {
   toReleasePrecisionVersion: () => toReleasePrecisionVersion
 });
 module.exports = __toCommonJS(version_exports);
-const LIBRARY_VERSION = "16.0.0";
+const LIBRARY_VERSION = "16.1.0";
 const ADCP_VERSION = "3.2.5";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -102,10 +102,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.5"
 ];
 const VERSION_INFO = {
-  library: "16.0.0",
+  library: "16.1.0",
   adcp: "3.2.5",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-19T23:27:30.750Z"
+  generatedAt: "2026-10-20T17:31:57.242Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "16.0.0";
+const LIBRARY_VERSION = "16.1.0";
 const ADCP_VERSION = "3.2.5";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -69,10 +69,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.5"
 ];
 const VERSION_INFO = {
-  library: "16.0.0",
+  library: "16.1.0",
   adcp: "3.2.5",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-19T23:27:30.750Z"
+  generatedAt: "2026-10-20T17:31:57.242Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-19
-> @adcp/sdk v16.0.0
+> Generated at: 2026-10-20
+> @adcp/sdk v16.1.0
 
 Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
 
@@ -95,6 +95,7 @@ interface AgentDiscoverySeed {
 // client.invalidateDiscoveryCache(): Promise<void>; refresh after a seller change.
 
 interface TaskOptions {
+  operationId?: string;        // Stable caller correlation id (otherwise a UUID); not an idempotency key
   skipStatusHandlers?: boolean; // Skip inline completion handlers, including continuations
   timeout?: number;             // Absolute whole-task deadline
   signal?: AbortSignal;         // Caller cancellation
@@ -106,6 +107,15 @@ interface TaskOptions {
   // ...deadline, cancellation, transport, and conversation options...
 }
 
+// Resume observation of persisted seller work (SingleAgentClient or AgentClient).
+// Save metadata.serverTaskId, metadata.taskName as taskType, and metadata.taskId as operationId.
+const tracked = await agent.trackTask({ taskId: saved.serverTaskId, taskType: saved.taskType, operationId: saved.operationId });
+await tracked.track(); // One status read; TaskInfo includes operationId and serverTaskId
+await tracked.waitForCompletion(1000, signal); // Same polling path as submitted continuations
+// No per-poll protocol activity. Terminal status_change carries operation_id and server_task_id.
+// Local observation errors do not terminalize seller work. Matching identities can reattach on the same client.
+// Results retain seller tool response shapes; tracking does not restore prior request context or handlers.
+
 interface DeferredContinuation<T> {
   token: string;
   question?: string;