@adcp/sdk 14.0.0-rc.41 → 14.0.0-rc.42

package/bin/adcp-grade.js

@@ -43,7 +43,8 @@ Options:
   --transport <mode>         \`mcp\` (default) wraps each vector body in a
                              JSON-RPC tools/call envelope and posts to the
                              agent's MCP mount (see #612); \`raw\` posts to
-                             per-operation AdCP endpoints (REST-binding agents).
+                             per-operation AdCP endpoints (REST-binding agents);
+                             \`a2a\` signs the official A2A client's request.
   --timeout <ms>             Per-probe timeout (default 10000)
   --json                     Emit the full GradeReport as JSON
   -h, --help                 Show this help
@@ -199,8 +200,8 @@ async function runRequestSigningGrader(args) {
         break;
       case '--transport': {
         const mode = args[++i];
-        if (mode !== 'raw' && mode !== 'mcp') {
-          console.error(`ERROR: --transport must be \"raw\" or \"mcp\", got \"${mode}\"\n`);
+        if (mode !== 'raw' && mode !== 'mcp' && mode !== 'a2a') {
+          console.error(`ERROR: --transport must be \"raw\", \"mcp\", or \"a2a\", got \"${mode}\"\n`);
           process.exit(2);
         }
         options.transport = mode;

package/bin/adcp-storyboard-summary.js

@@ -350,7 +350,7 @@ function formatStepVerdictLines(step, options = {}) {
   return [`${step?.passed ? '✅ Passed' : '❌ Failed'}${suffix}`];
 }
 
-const SIGNING_TRANSPORTS = ['raw', 'mcp'];
+const SIGNING_TRANSPORTS = ['raw', 'mcp', 'a2a'];
 
 // Tokens only ever passed as a (rejected) value for a boolean flag — no
 // storyboard id or agent URL looks like these, so treating them as a misuse

package/bin/adcp.js

@@ -2180,17 +2180,15 @@ WEBHOOK OPTIONS:
                                   HTTP-on-the-wire — spec-compliant.
 
 REQUEST-SIGNING VECTOR OPTIONS (signed_requests storyboard):
-  --signing-transport raw|mcp     How the RFC 9421 conformance vectors are
+  --signing-transport raw|mcp|a2a How the RFC 9421 conformance vectors are
                                   framed on the wire. NOT the same as
                                   --transport/--protocol, which selects how the
                                   storyboard itself talks to the agent. Default:
                                   inferred from the resolved protocol — an MCP
                                   run wraps each vector in a tools/call envelope
-                                  (mcp); an A2A run reports the vectors
-                                  signing_transport_unavailable (COVERAGE
-                                  UNAVAILABLE; the track cannot pass) because
-                                  the fixtures have no A2A framing. Pass raw for
-                                  agents that
+                                  (mcp); an A2A run signs the exact request the
+                                  official A2A client emits after Agent Card
+                                  discovery. Pass raw for agents that
                                   expose AdCP tools as per-operation HTTP
                                   endpoints. Mirrors
                                   \`adcp grade request-signing --transport\`.

package/dist/lib/conformance/index.d.mts

@@ -21,6 +21,8 @@
 export { runConformance } from './runConformance.mjs';
 export { runWebhookConformance } from './webhook.mjs';
 export { seedFixtures } from './seeder.mjs';
+export { TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS, buildTargetingInputConformanceVectors, runTargetingInputConformance, } from './targeting.mjs';
+export type { TargetingConformanceOutcome, TargetingConformanceOperation, TargetingDimensionSample, TargetingDimensionSamples, TargetingInputConformanceAdapter, TargetingInputConformanceCaseResult, TargetingInputConformanceObservation, TargetingInputConformanceOptions, TargetingInputConformanceReport, TargetingInputConformanceVector, } from './targeting.mjs';
 export type { SeedOptions, SeedResult, SeederName, SeedWarning } from './seeder.mjs';
 export type { ConformanceSchemaOptions } from './schemaLoader.mjs';
 export { STATELESS_TIER_TOOLS, REFERENTIAL_STATELESS_TOOLS, UPDATE_TIER_TOOLS, COMPACT_STATELESS_TIER_TOOLS, COMPACT_UPDATE_TIER_TOOLS, COMPACT_LIFECYCLE_TOOLS, DEFAULT_TOOLS, DEFAULT_TOOLS_WITH_UPDATES, } from './types.mjs';

package/dist/lib/conformance/index.d.ts

@@ -21,6 +21,8 @@
 export { runConformance } from './runConformance';
 export { runWebhookConformance } from './webhook';
 export { seedFixtures } from './seeder';
+export { TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS, buildTargetingInputConformanceVectors, runTargetingInputConformance, } from './targeting';
+export type { TargetingConformanceOutcome, TargetingConformanceOperation, TargetingDimensionSample, TargetingDimensionSamples, TargetingInputConformanceAdapter, TargetingInputConformanceCaseResult, TargetingInputConformanceObservation, TargetingInputConformanceOptions, TargetingInputConformanceReport, TargetingInputConformanceVector, } from './targeting';
 export type { SeedOptions, SeedResult, SeederName, SeedWarning } from './seeder';
 export type { ConformanceSchemaOptions } from './schemaLoader';
 export { STATELESS_TIER_TOOLS, REFERENTIAL_STATELESS_TOOLS, UPDATE_TIER_TOOLS, COMPACT_STATELESS_TIER_TOOLS, COMPACT_UPDATE_TIER_TOOLS, COMPACT_LIFECYCLE_TOOLS, DEFAULT_TOOLS, DEFAULT_TOOLS_WITH_UPDATES, } from './types';

package/dist/lib/conformance/index.js

@@ -25,8 +25,11 @@ __export(conformance_exports, {
   DEFAULT_TOOLS_WITH_UPDATES: () => import_types.DEFAULT_TOOLS_WITH_UPDATES,
   REFERENTIAL_STATELESS_TOOLS: () => import_types.REFERENTIAL_STATELESS_TOOLS,
   STATELESS_TIER_TOOLS: () => import_types.STATELESS_TIER_TOOLS,
+  TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS: () => import_targeting.TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS,
   UPDATE_TIER_TOOLS: () => import_types.UPDATE_TIER_TOOLS,
+  buildTargetingInputConformanceVectors: () => import_targeting.buildTargetingInputConformanceVectors,
   runConformance: () => import_runConformance.runConformance,
+  runTargetingInputConformance: () => import_targeting.runTargetingInputConformance,
   runWebhookConformance: () => import_webhook.runWebhookConformance,
   seedFixtures: () => import_seeder.seedFixtures
 });
@@ -34,6 +37,7 @@ module.exports = __toCommonJS(conformance_exports);
 var import_runConformance = require('./runConformance.js');
 var import_webhook = require('./webhook.js');
 var import_seeder = require('./seeder.js');
+var import_targeting = require('./targeting.js');
 var import_types = require('./types.js');
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -44,8 +48,11 @@ var import_types = require('./types.js');
   DEFAULT_TOOLS_WITH_UPDATES,
   REFERENTIAL_STATELESS_TOOLS,
   STATELESS_TIER_TOOLS,
+  TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS,
   UPDATE_TIER_TOOLS,
+  buildTargetingInputConformanceVectors,
   runConformance,
+  runTargetingInputConformance,
   runWebhookConformance,
   seedFixtures
 });

package/dist/lib/conformance/index.mjs

@@ -1,6 +1,11 @@
 import { runConformance } from "./runConformance.mjs";
 import { runWebhookConformance } from "./webhook.mjs";
 import { seedFixtures } from "./seeder.mjs";
+import {
+  TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS,
+  buildTargetingInputConformanceVectors,
+  runTargetingInputConformance
+} from "./targeting.mjs";
 import {
   STATELESS_TIER_TOOLS,
   REFERENTIAL_STATELESS_TOOLS,
@@ -19,8 +24,11 @@ export {
   DEFAULT_TOOLS_WITH_UPDATES,
   REFERENTIAL_STATELESS_TOOLS,
   STATELESS_TIER_TOOLS,
+  TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS,
   UPDATE_TIER_TOOLS,
+  buildTargetingInputConformanceVectors,
   runConformance,
+  runTargetingInputConformance,
   runWebhookConformance,
   seedFixtures
 };

package/dist/lib/conformance/targeting.d.mts

@@ -0,0 +1,72 @@
+import type { TargetingOverlayInput } from '../types/core.generated.mjs';
+export type TargetingConformanceOperation = 'create' | 'update';
+export type TargetingConformanceOutcome = 'accepted' | 'rejected';
+export interface TargetingDimensionSample<T> {
+    /** Strict configured/stored value used as the vector baseline. */
+    initialValue: NonNullable<T>;
+    /** Distinct valid request value used to prove complete replacement. */
+    replacementValue: NonNullable<T>;
+    /** Canonical readback value when it differs from the request value. */
+    expectedReplacementValue?: NonNullable<T>;
+    /** Whole canonical readback state for cross-dimension materialization. */
+    expectedReplacementState?: Record<string, unknown>;
+    /** Override for products that cannot execute a clear against inherent scope. */
+    expectedNullOutcome?: TargetingConformanceOutcome;
+    /** Override for replacements that require renegotiation in the selected fixture. */
+    expectedReplacementOutcome?: TargetingConformanceOutcome;
+}
+export type TargetingDimensionSamples = {
+    [K in keyof TargetingOverlayInput]?: TargetingDimensionSample<TargetingOverlayInput[K]>;
+};
+export interface TargetingInputConformanceVector {
+    id: string;
+    operation: TargetingConformanceOperation;
+    dimension?: keyof TargetingOverlayInput & string;
+    baseline?: Record<string, unknown>;
+    /** Present request overlay; `{}` means this dimension was omitted. */
+    input?: Record<string, unknown>;
+    expectedOutcome: TargetingConformanceOutcome;
+    /** Accepted strict state, unchanged update state, or absent state after a rejected create. */
+    expectedState: Record<string, unknown> | undefined;
+    description: string;
+}
+export interface TargetingInputConformanceObservation {
+    outcome: TargetingConformanceOutcome;
+    /** Strict durable/readback state after the attempted operation. */
+    state?: Record<string, unknown>;
+    /** Exact request-only overlay observed at the seller/provider dispatch seam. */
+    dispatchedInput?: Record<string, unknown>;
+}
+export interface TargetingInputConformanceAdapter {
+    create(vector: TargetingInputConformanceVector): Promise<TargetingInputConformanceObservation>;
+    update(vector: TargetingInputConformanceVector): Promise<TargetingInputConformanceObservation>;
+}
+export interface TargetingInputConformanceOptions {
+    /** Override when a seller has a documented canonical ordering/materialization policy. */
+    compareState?: (observed: Record<string, unknown> | undefined, expected: Record<string, unknown> | undefined, vector: TargetingInputConformanceVector) => boolean;
+}
+export interface TargetingInputConformanceCaseResult {
+    id: string;
+    passed: boolean;
+    failures: string[];
+    vector: TargetingInputConformanceVector;
+    observation?: TargetingInputConformanceObservation;
+}
+export interface TargetingInputConformanceReport {
+    passed: boolean;
+    cases: TargetingInputConformanceCaseResult[];
+}
+/**
+ * Generate create/update omit, null, and value vectors for every supplied
+ * targeting dimension. Samples are schema-typed and share one multi-dimension
+ * baseline so the corpus catches adapters that clear unrelated omitted axes.
+ */
+export declare function buildTargetingInputConformanceVectors(samples: TargetingDimensionSamples): TargetingInputConformanceVector[];
+/**
+ * Cross-dimension vectors requested by the targeting command-state contract:
+ * an omitted region axis is preserved, and an invalid combined projection is
+ * rejected without mutating either stored axis.
+ */
+export declare const TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS: readonly TargetingInputConformanceVector[];
+/** Run vectors through distinct create and update adapter seams. */
+export declare function runTargetingInputConformance(vectors: readonly TargetingInputConformanceVector[], adapter: TargetingInputConformanceAdapter, options?: TargetingInputConformanceOptions): Promise<TargetingInputConformanceReport>;

package/dist/lib/conformance/targeting.d.ts

@@ -0,0 +1,72 @@
+import type { TargetingOverlayInput } from '../types/core.generated';
+export type TargetingConformanceOperation = 'create' | 'update';
+export type TargetingConformanceOutcome = 'accepted' | 'rejected';
+export interface TargetingDimensionSample<T> {
+    /** Strict configured/stored value used as the vector baseline. */
+    initialValue: NonNullable<T>;
+    /** Distinct valid request value used to prove complete replacement. */
+    replacementValue: NonNullable<T>;
+    /** Canonical readback value when it differs from the request value. */
+    expectedReplacementValue?: NonNullable<T>;
+    /** Whole canonical readback state for cross-dimension materialization. */
+    expectedReplacementState?: Record<string, unknown>;
+    /** Override for products that cannot execute a clear against inherent scope. */
+    expectedNullOutcome?: TargetingConformanceOutcome;
+    /** Override for replacements that require renegotiation in the selected fixture. */
+    expectedReplacementOutcome?: TargetingConformanceOutcome;
+}
+export type TargetingDimensionSamples = {
+    [K in keyof TargetingOverlayInput]?: TargetingDimensionSample<TargetingOverlayInput[K]>;
+};
+export interface TargetingInputConformanceVector {
+    id: string;
+    operation: TargetingConformanceOperation;
+    dimension?: keyof TargetingOverlayInput & string;
+    baseline?: Record<string, unknown>;
+    /** Present request overlay; `{}` means this dimension was omitted. */
+    input?: Record<string, unknown>;
+    expectedOutcome: TargetingConformanceOutcome;
+    /** Accepted strict state, unchanged update state, or absent state after a rejected create. */
+    expectedState: Record<string, unknown> | undefined;
+    description: string;
+}
+export interface TargetingInputConformanceObservation {
+    outcome: TargetingConformanceOutcome;
+    /** Strict durable/readback state after the attempted operation. */
+    state?: Record<string, unknown>;
+    /** Exact request-only overlay observed at the seller/provider dispatch seam. */
+    dispatchedInput?: Record<string, unknown>;
+}
+export interface TargetingInputConformanceAdapter {
+    create(vector: TargetingInputConformanceVector): Promise<TargetingInputConformanceObservation>;
+    update(vector: TargetingInputConformanceVector): Promise<TargetingInputConformanceObservation>;
+}
+export interface TargetingInputConformanceOptions {
+    /** Override when a seller has a documented canonical ordering/materialization policy. */
+    compareState?: (observed: Record<string, unknown> | undefined, expected: Record<string, unknown> | undefined, vector: TargetingInputConformanceVector) => boolean;
+}
+export interface TargetingInputConformanceCaseResult {
+    id: string;
+    passed: boolean;
+    failures: string[];
+    vector: TargetingInputConformanceVector;
+    observation?: TargetingInputConformanceObservation;
+}
+export interface TargetingInputConformanceReport {
+    passed: boolean;
+    cases: TargetingInputConformanceCaseResult[];
+}
+/**
+ * Generate create/update omit, null, and value vectors for every supplied
+ * targeting dimension. Samples are schema-typed and share one multi-dimension
+ * baseline so the corpus catches adapters that clear unrelated omitted axes.
+ */
+export declare function buildTargetingInputConformanceVectors(samples: TargetingDimensionSamples): TargetingInputConformanceVector[];
+/**
+ * Cross-dimension vectors requested by the targeting command-state contract:
+ * an omitted region axis is preserved, and an invalid combined projection is
+ * rejected without mutating either stored axis.
+ */
+export declare const TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS: readonly TargetingInputConformanceVector[];
+/** Run vectors through distinct create and update adapter seams. */
+export declare function runTargetingInputConformance(vectors: readonly TargetingInputConformanceVector[], adapter: TargetingInputConformanceAdapter, options?: TargetingInputConformanceOptions): Promise<TargetingInputConformanceReport>;

package/dist/lib/conformance/targeting.js

@@ -0,0 +1,163 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var targeting_exports = {};
+__export(targeting_exports, {
+  TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS: () => TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS,
+  buildTargetingInputConformanceVectors: () => buildTargetingInputConformanceVectors,
+  runTargetingInputConformance: () => runTargetingInputConformance
+});
+module.exports = __toCommonJS(targeting_exports);
+var import_node_util = require("node:util");
+function buildTargetingInputConformanceVectors(samples) {
+  const entries = Object.entries(samples).filter(([, sample]) => sample !== void 0);
+  const baseline = Object.fromEntries(entries.map(([dimension, sample]) => [dimension, clone(sample.initialValue)]));
+  const vectors = [];
+  for (const [dimension, sample] of entries) {
+    const clearedState = withoutKey(baseline, dimension);
+    const replacementState = sample.expectedReplacementState ? clone(sample.expectedReplacementState) : {
+      ...clone(baseline),
+      [dimension]: clone(sample.expectedReplacementValue ?? sample.replacementValue)
+    };
+    for (const operation of ["create", "update"]) {
+      const omittedMeaning = operation === "create" ? "inherits configured/product defaults" : "preserves stored state";
+      const nullOutcome = sample.expectedNullOutcome ?? "accepted";
+      const replacementOutcome = sample.expectedReplacementOutcome ?? "accepted";
+      const rejectedState = operation === "create" ? void 0 : baseline;
+      vectors.push(
+        {
+          id: `${operation}/${dimension}/omitted`,
+          operation,
+          dimension,
+          baseline: clone(baseline),
+          input: {},
+          expectedOutcome: "accepted",
+          expectedState: clone(baseline),
+          description: `${operation}: omitted ${dimension} ${omittedMeaning}`
+        },
+        {
+          id: `${operation}/${dimension}/null`,
+          operation,
+          dimension,
+          baseline: clone(baseline),
+          input: { [dimension]: null },
+          expectedOutcome: nullOutcome,
+          expectedState: clone(nullOutcome === "accepted" ? clearedState : rejectedState),
+          description: `${operation}: null ${dimension} clears/suppresses only that effective dimension`
+        },
+        {
+          id: `${operation}/${dimension}/value`,
+          operation,
+          dimension,
+          baseline: clone(baseline),
+          input: { [dimension]: clone(sample.replacementValue) },
+          expectedOutcome: replacementOutcome,
+          expectedState: clone(replacementOutcome === "accepted" ? replacementState : rejectedState),
+          description: `${operation}: a non-null ${dimension} value replaces only that complete dimension`
+        }
+      );
+    }
+  }
+  return vectors;
+}
+const TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS = deepFreeze([
+  {
+    id: "update/geo_countries/preserve-compatible-regions",
+    operation: "update",
+    baseline: { geo_countries: ["US"], geo_regions: ["US-NY"] },
+    input: { geo_countries: ["US", "CA"] },
+    expectedOutcome: "accepted",
+    expectedState: { geo_countries: ["US", "CA"], geo_regions: ["US-NY"] },
+    description: "Changing countries preserves an omitted compatible geo_regions dimension."
+  },
+  {
+    id: "update/geo_countries/reject-incompatible-preserved-regions",
+    operation: "update",
+    baseline: { geo_countries: ["US"], geo_regions: ["US-NY"] },
+    input: { geo_countries: ["CA"] },
+    expectedOutcome: "rejected",
+    expectedState: { geo_countries: ["US"], geo_regions: ["US-NY"] },
+    description: "An invalid country/region result is rejected atomically instead of clearing the omitted region axis."
+  }
+]);
+async function runTargetingInputConformance(vectors, adapter, options = {}) {
+  if (vectors.length === 0) throw new TypeError("Targeting conformance requires at least one vector.");
+  const compareState = options.compareState ?? defaultStateComparison;
+  const cases = [];
+  for (const sourceVector of vectors) {
+    const vector = clone(sourceVector);
+    const failures = [];
+    try {
+      const observation = await adapter[vector.operation](clone(vector));
+      if (observation.outcome !== vector.expectedOutcome) {
+        failures.push(`expected ${vector.expectedOutcome}, observed ${observation.outcome}`);
+      }
+      if (!compareState(observation.state, vector.expectedState, vector)) {
+        failures.push(
+          `strict state mismatch: expected ${formatDiagnosticValue(vector.expectedState)}, observed ${formatDiagnosticValue(observation.state)}`
+        );
+      }
+      if (containsNull(observation.state)) {
+        failures.push("durable/readback state retained a request-only null command");
+      }
+      if (observation.outcome === "accepted" && !(0, import_node_util.isDeepStrictEqual)(observation.dispatchedInput, vector.input)) {
+        failures.push(
+          `dispatch changed the request overlay: expected ${formatDiagnosticValue(vector.input)}, observed ${formatDiagnosticValue(observation.dispatchedInput)}`
+        );
+      }
+      cases.push({ id: vector.id, passed: failures.length === 0, failures, vector, observation });
+    } catch (error) {
+      const name = error instanceof Error ? error.name : typeof error;
+      failures.push(`adapter execution failed (${name}); inspect adapter logs for details`);
+      cases.push({ id: vector.id, passed: false, failures, vector });
+    }
+  }
+  return { passed: cases.every((result) => result.passed), cases };
+}
+function defaultStateComparison(observed, expected) {
+  return (0, import_node_util.isDeepStrictEqual)(normalizeEmptyState(observed), normalizeEmptyState(expected));
+}
+function normalizeEmptyState(state) {
+  return state && Object.keys(state).length === 0 ? void 0 : state;
+}
+function containsNull(value) {
+  if (value === null) return true;
+  if (Array.isArray(value)) return value.some(containsNull);
+  return typeof value === "object" && Object.values(value).some(containsNull);
+}
+function withoutKey(state, key) {
+  const result = Object.fromEntries(Object.entries(state).filter(([candidate]) => candidate !== key));
+  return Object.keys(result).length === 0 ? void 0 : result;
+}
+function clone(value) {
+  return structuredClone(value);
+}
+function formatDiagnosticValue(value) {
+  return value === void 0 ? "undefined" : JSON.stringify(value);
+}
+function deepFreeze(value) {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS,
+  buildTargetingInputConformanceVectors,
+  runTargetingInputConformance
+});

package/dist/lib/conformance/targeting.mjs

@@ -0,0 +1,137 @@
+import { isDeepStrictEqual } from "node:util";
+function buildTargetingInputConformanceVectors(samples) {
+  const entries = Object.entries(samples).filter(([, sample]) => sample !== void 0);
+  const baseline = Object.fromEntries(entries.map(([dimension, sample]) => [dimension, clone(sample.initialValue)]));
+  const vectors = [];
+  for (const [dimension, sample] of entries) {
+    const clearedState = withoutKey(baseline, dimension);
+    const replacementState = sample.expectedReplacementState ? clone(sample.expectedReplacementState) : {
+      ...clone(baseline),
+      [dimension]: clone(sample.expectedReplacementValue ?? sample.replacementValue)
+    };
+    for (const operation of ["create", "update"]) {
+      const omittedMeaning = operation === "create" ? "inherits configured/product defaults" : "preserves stored state";
+      const nullOutcome = sample.expectedNullOutcome ?? "accepted";
+      const replacementOutcome = sample.expectedReplacementOutcome ?? "accepted";
+      const rejectedState = operation === "create" ? void 0 : baseline;
+      vectors.push(
+        {
+          id: `${operation}/${dimension}/omitted`,
+          operation,
+          dimension,
+          baseline: clone(baseline),
+          input: {},
+          expectedOutcome: "accepted",
+          expectedState: clone(baseline),
+          description: `${operation}: omitted ${dimension} ${omittedMeaning}`
+        },
+        {
+          id: `${operation}/${dimension}/null`,
+          operation,
+          dimension,
+          baseline: clone(baseline),
+          input: { [dimension]: null },
+          expectedOutcome: nullOutcome,
+          expectedState: clone(nullOutcome === "accepted" ? clearedState : rejectedState),
+          description: `${operation}: null ${dimension} clears/suppresses only that effective dimension`
+        },
+        {
+          id: `${operation}/${dimension}/value`,
+          operation,
+          dimension,
+          baseline: clone(baseline),
+          input: { [dimension]: clone(sample.replacementValue) },
+          expectedOutcome: replacementOutcome,
+          expectedState: clone(replacementOutcome === "accepted" ? replacementState : rejectedState),
+          description: `${operation}: a non-null ${dimension} value replaces only that complete dimension`
+        }
+      );
+    }
+  }
+  return vectors;
+}
+const TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS = deepFreeze([
+  {
+    id: "update/geo_countries/preserve-compatible-regions",
+    operation: "update",
+    baseline: { geo_countries: ["US"], geo_regions: ["US-NY"] },
+    input: { geo_countries: ["US", "CA"] },
+    expectedOutcome: "accepted",
+    expectedState: { geo_countries: ["US", "CA"], geo_regions: ["US-NY"] },
+    description: "Changing countries preserves an omitted compatible geo_regions dimension."
+  },
+  {
+    id: "update/geo_countries/reject-incompatible-preserved-regions",
+    operation: "update",
+    baseline: { geo_countries: ["US"], geo_regions: ["US-NY"] },
+    input: { geo_countries: ["CA"] },
+    expectedOutcome: "rejected",
+    expectedState: { geo_countries: ["US"], geo_regions: ["US-NY"] },
+    description: "An invalid country/region result is rejected atomically instead of clearing the omitted region axis."
+  }
+]);
+async function runTargetingInputConformance(vectors, adapter, options = {}) {
+  if (vectors.length === 0) throw new TypeError("Targeting conformance requires at least one vector.");
+  const compareState = options.compareState ?? defaultStateComparison;
+  const cases = [];
+  for (const sourceVector of vectors) {
+    const vector = clone(sourceVector);
+    const failures = [];
+    try {
+      const observation = await adapter[vector.operation](clone(vector));
+      if (observation.outcome !== vector.expectedOutcome) {
+        failures.push(`expected ${vector.expectedOutcome}, observed ${observation.outcome}`);
+      }
+      if (!compareState(observation.state, vector.expectedState, vector)) {
+        failures.push(
+          `strict state mismatch: expected ${formatDiagnosticValue(vector.expectedState)}, observed ${formatDiagnosticValue(observation.state)}`
+        );
+      }
+      if (containsNull(observation.state)) {
+        failures.push("durable/readback state retained a request-only null command");
+      }
+      if (observation.outcome === "accepted" && !isDeepStrictEqual(observation.dispatchedInput, vector.input)) {
+        failures.push(
+          `dispatch changed the request overlay: expected ${formatDiagnosticValue(vector.input)}, observed ${formatDiagnosticValue(observation.dispatchedInput)}`
+        );
+      }
+      cases.push({ id: vector.id, passed: failures.length === 0, failures, vector, observation });
+    } catch (error) {
+      const name = error instanceof Error ? error.name : typeof error;
+      failures.push(`adapter execution failed (${name}); inspect adapter logs for details`);
+      cases.push({ id: vector.id, passed: false, failures, vector });
+    }
+  }
+  return { passed: cases.every((result) => result.passed), cases };
+}
+function defaultStateComparison(observed, expected) {
+  return isDeepStrictEqual(normalizeEmptyState(observed), normalizeEmptyState(expected));
+}
+function normalizeEmptyState(state) {
+  return state && Object.keys(state).length === 0 ? void 0 : state;
+}
+function containsNull(value) {
+  if (value === null) return true;
+  if (Array.isArray(value)) return value.some(containsNull);
+  return typeof value === "object" && Object.values(value).some(containsNull);
+}
+function withoutKey(state, key) {
+  const result = Object.fromEntries(Object.entries(state).filter(([candidate]) => candidate !== key));
+  return Object.keys(result).length === 0 ? void 0 : result;
+}
+function clone(value) {
+  return structuredClone(value);
+}
+function formatDiagnosticValue(value) {
+  return value === void 0 ? "undefined" : JSON.stringify(value);
+}
+function deepFreeze(value) {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+export {
+  TARGETING_GEOGRAPHY_CONFORMANCE_VECTORS,
+  buildTargetingInputConformanceVectors,
+  runTargetingInputConformance
+};

package/dist/lib/core/AgentClient.d.mts

@@ -2,7 +2,7 @@ import type { Client as MCPClient } from '@modelcontextprotocol/sdk/client/index
 import type { AgentConfig } from '../types/index.mjs';
 import type { MCPWebhookPayload, GetBrandIdentityRequest, GetBrandIdentityResponse, ContextMatchRequest, ContextMatchResponse, IdentityMatchRequest, IdentityMatchResponseRouterPublisher } from '../types/core.generated.mjs';
 import type { Task as A2ATask, TaskStatusUpdateEvent } from '@a2a-js/sdk';
-import { type CanonicalReadTaskOptions, type CreativeDeliveryTaskOptions, type SingleAgentClientConfig, type SyncCreativesTaskOptions, type VerifyAndParseWebhookOptions, type WebhookHandlerAdapter, type WebhookParseResult, type WebhookRequestContext } from './SingleAgentClient.mjs';
+import { type CapabilityEvidenceScope, type CapabilityEvidenceSnapshot, type CanonicalReadTaskOptions, type CreativeDeliveryTaskOptions, type SingleAgentClientConfig, type SyncCreativesTaskOptions, type VerifyAndParseWebhookOptions, type WebhookHandlerAdapter, type WebhookParseResult, type WebhookRequestContext } from './SingleAgentClient.mjs';
 import type { InputHandler, TaskOptions, TaskResult, TaskInfo, Message, DirectPauseRecoveryRequest } from './ConversationTypes.mjs';
 import type { AdcpCapabilities } from '../utils/capabilities.mjs';
 import type { WebhookHeaderValue } from '../webhooks/index.mjs';
@@ -167,6 +167,22 @@ export type InProcessAgentClientConfig = Pick<SingleAgentClientConfig, 'adcpVers
      */
     agentId?: string;
 };
+/** Context passed to {@link AgentClient.createWithCapabilityPreflight}. */
+export interface CapabilityPreflightContext {
+    /** The exact client instance that will be returned by the factory. */
+    client: AgentClient;
+    /** Opaque authorization/transport scope the returned snapshot must carry. */
+    scope: CapabilityEvidenceScope;
+}
+/** Load or perform capability discovery for one newly constructed client. */
+export type CapabilityPreflightLoader = (context: CapabilityPreflightContext) => CapabilityEvidenceSnapshot | Promise<CapabilityEvidenceSnapshot>;
+export type CapabilityPreflightErrorCode = 'scoped_transport' | 'scope_rotated' | 'invalid_evidence';
+/** Actionable factory failure without weakening the same-instance invariant. */
+export declare class CapabilityPreflightError extends Error {
+    readonly code: CapabilityPreflightErrorCode;
+    readonly name = "CapabilityPreflightError";
+    constructor(code: CapabilityPreflightErrorCode, message: string);
+}
 export declare class AgentClient {
     private agent;
     private config;
@@ -176,6 +192,16 @@ export declare class AgentClient {
     private readonly sessionTrackedDeferredContinuations;
     private readonly _isInProcess;
     constructor(agent: AgentConfig, config?: SingleAgentClientConfig);
+    /**
+     * Construct and prime one client before exposing it for task dispatch.
+     *
+     * Capability evidence is intentionally bound to a client instance. This
+     * factory gives application factories the instance and its opaque scope
+     * before the first task can be sent, then installs the callback's snapshot
+     * on that same instance. Evidence from an otherwise identical client is
+     * rejected rather than silently falling back to redundant discovery.
+     */
+    static createWithCapabilityPreflight(agent: AgentConfig, loadEvidence: CapabilityPreflightLoader, config?: SingleAgentClientConfig): Promise<AgentClient>;
     /**
      * Recover the current A2A pause generation for a direct mutation that opted
      * into `TaskOptions.durableContinuationRecovery`.