@adcp/sdk 13.0.0-rc.7 → 13.0.0-rc.9

package/dist/lib/testing/storyboard/trusted-match-context-replay.mjs

@@ -0,0 +1,316 @@
+import { createServer } from "node:http";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, isAbsolute, join } from "node:path";
+import { getComplianceCacheDir } from "./compliance.mjs";
+const DEFAULT_VECTOR_REF = "test-vectors/trusted-match-context-merge/vectors.json";
+const DEFAULT_TIMEOUT_MS = 1e4;
+const MAX_ROUTER_RESPONSE_BYTES = 1024 * 1024;
+const MAX_PROVIDER_REQUEST_BYTES = 64 * 1024;
+async function replayTrustedMatchContextVector(step, options, params = {}) {
+  const vectorResult = loadVector(step.vector_ref, options.vectorsRoot, params.adcpVersion);
+  const emptyRequest = params.requestOverride ?? step.sample_request ?? {};
+  if ("error" in vectorResult) {
+    return {
+      request: emptyRequest,
+      httpResult: failedProbe(options.router_url, vectorResult.error)
+    };
+  }
+  const request = params.requestOverride ?? vectorResult.vector.request ?? step.sample_request;
+  if (!request || typeof request !== "object" || Array.isArray(request)) {
+    return {
+      request: {},
+      vectorSource: vectorResult.path,
+      httpResult: failedProbe(
+        options.router_url,
+        "`replay_trusted_match_context_vector` requires vector.request or step.sample_request."
+      )
+    };
+  }
+  let fixtureServer;
+  let cleanupRegistration = void 0;
+  let result;
+  try {
+    fixtureServer = await createProviderFixtureServer(vectorResult.vector, options.provider_server);
+    cleanupRegistration = await options.registerProviders({
+      profile: vectorResult.vector.profile,
+      providers: fixtureServer.providers,
+      request: structuredClone(request)
+    });
+    const httpResult = await postRouterContext(options, request, params.signal);
+    result = { httpResult, request, vectorSource: vectorResult.path };
+  } catch (error) {
+    result = {
+      request,
+      vectorSource: vectorResult.path,
+      httpResult: failedProbe(options.router_url, error instanceof Error ? error.message : String(error))
+    };
+  } finally {
+    const cleanupErrors = [];
+    try {
+      if (cleanupRegistration !== void 0) {
+        if (typeof cleanupRegistration !== "function") {
+          throw new Error("registerProviders must return void or a cleanup function.");
+        }
+        await cleanupRegistration();
+      }
+    } catch (error) {
+      cleanupErrors.push(`registration cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+      await fixtureServer?.close();
+    } catch (error) {
+      cleanupErrors.push(`provider fixture cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (cleanupErrors.length > 0) {
+      const priorError = result.httpResult.error;
+      result.httpResult.error = [...priorError ? [priorError] : [], ...cleanupErrors].join("; ");
+    }
+  }
+  return result;
+}
+function loadVector(vectorRef, vectorsRoot, adcpVersion) {
+  const rawRef = (vectorRef ?? DEFAULT_VECTOR_REF).split("#", 1)[0];
+  if (!rawRef || isAbsolute(rawRef) || rawRef.split(/[\\/]/).includes("..")) {
+    return { error: `Invalid Trusted Match Context vector_ref: ${vectorRef ?? rawRef}` };
+  }
+  const withoutStatic = rawRef.replace(/^static\//, "").replace(/^compliance\/source\//, "");
+  const candidates = [];
+  if (vectorsRoot) {
+    candidates.push(join(vectorsRoot, rawRef), join(vectorsRoot, withoutStatic), join(vectorsRoot, basename(rawRef)));
+  }
+  const complianceDir = getComplianceCacheDir({ ...adcpVersion && { version: adcpVersion } });
+  candidates.push(
+    join(complianceDir, withoutStatic),
+    join(complianceDir, rawRef),
+    join(process.cwd(), rawRef),
+    join(process.cwd(), withoutStatic)
+  );
+  for (const candidate of [...new Set(candidates)]) {
+    if (!existsSync(candidate)) continue;
+    try {
+      const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+      const validationError = validateVector(parsed);
+      if (validationError) return { error: `${candidate}: ${validationError}` };
+      return { vector: parsed, path: candidate };
+    } catch (error) {
+      return { error: `Failed to read Trusted Match Context vector ${candidate}: ${String(error)}` };
+    }
+  }
+  return { error: `Trusted Match Context vector file not found for ${rawRef}` };
+}
+function validateVector(value) {
+  if (!isRecord(value)) return "vector must be an object";
+  if (typeof value.profile !== "string" || value.profile.length === 0) return "profile must be a non-empty string";
+  if (!Array.isArray(value.registrations) || value.registrations.length === 0) {
+    return "registrations must be a non-empty array";
+  }
+  if (!Array.isArray(value.provider_responses) || value.provider_responses.length === 0) {
+    return "provider_responses must be a non-empty array";
+  }
+  const ids = /* @__PURE__ */ new Set();
+  for (const registration of value.registrations) {
+    if (!isRecord(registration) || typeof registration.provider_id !== "string" || !registration.provider_id) {
+      return "every registration requires a non-empty provider_id";
+    }
+    if (ids.has(registration.provider_id)) return `duplicate provider_id: ${registration.provider_id}`;
+    ids.add(registration.provider_id);
+  }
+  const responseIds = /* @__PURE__ */ new Set();
+  for (const entry of value.provider_responses) {
+    if (!isRecord(entry) || typeof entry.registration_provider_id !== "string" || !isRecord(entry.response)) {
+      return "every provider response requires registration_provider_id and an object response";
+    }
+    if (!ids.has(entry.registration_provider_id)) {
+      return `provider response has no matching registration: ${entry.registration_provider_id}`;
+    }
+    if (responseIds.has(entry.registration_provider_id)) {
+      return `duplicate provider response: ${entry.registration_provider_id}`;
+    }
+    responseIds.add(entry.registration_provider_id);
+  }
+  for (const providerId of ids) {
+    if (!responseIds.has(providerId)) return `registration has no provider response: ${providerId}`;
+  }
+  if ("request" in value && !isRecord(value.request)) return "request must be an object when present";
+  return void 0;
+}
+async function createProviderFixtureServer(vector, config) {
+  const host = config?.host ?? "127.0.0.1";
+  const port = config?.port ?? 0;
+  const mode = config?.mode ?? "loopback_mock";
+  if (mode === "proxy_url" && !config?.public_url) {
+    throw new Error("trusted_match_context_router_runner.provider_server.public_url is required in proxy_url mode.");
+  }
+  if (config?.public_url) assertHttpUrl(config.public_url, "provider_server.public_url");
+  const responses = new Map(
+    vector.provider_responses.map((entry) => [entry.registration_provider_id, entry.response])
+  );
+  const server = createServer((req, res) => {
+    void serveProviderFixture(req, res, responses).catch((error) => {
+      if (res.headersSent) {
+        res.destroy(error instanceof Error ? error : new Error(String(error)));
+      } else {
+        respondJson(res, 500, { error: "fixture_server_error" });
+      }
+    });
+  });
+  await listen(server, host, port);
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    await closeServer(server);
+    throw new Error("Provider fixture server did not expose a TCP address.");
+  }
+  const localBase = `http://${formatHost(host)}:${address.port}`;
+  const advertisedBase = (mode === "proxy_url" ? config.public_url : localBase).replace(/\/$/, "");
+  const providers = vector.registrations.map(({ provider_id }) => ({
+    provider_id,
+    context_url: `${advertisedBase}/providers/${encodeURIComponent(provider_id)}/context`
+  }));
+  return { providers, close: () => closeServer(server) };
+}
+async function serveProviderFixture(req, res, responses) {
+  const pathname = new URL(req.url ?? "/", "http://fixture.invalid").pathname;
+  const match = pathname.match(/^\/providers\/([^/]+)\/context$/);
+  if (req.method !== "POST" || !match) {
+    respondJson(res, req.method === "POST" ? 404 : 405, { error: "not_found" });
+    return;
+  }
+  try {
+    await consumeBody(req, MAX_PROVIDER_REQUEST_BYTES);
+  } catch {
+    respondJson(res, 413, { error: "request_too_large" });
+    return;
+  }
+  const providerId = decodeURIComponent(match[1]);
+  const response = responses.get(providerId);
+  if (!response) {
+    respondJson(res, 404, { error: "provider_not_found" });
+    return;
+  }
+  respondJson(res, 200, response);
+}
+async function postRouterContext(options, request, parentSignal) {
+  const routerUrl = `${options.router_url.replace(/\/$/, "")}/context`;
+  const parsed = new URL(routerUrl);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("trusted_match_context_router_runner.router_url must use http or https.");
+  }
+  const controller = new AbortController();
+  const abort = () => controller.abort(parentSignal?.reason);
+  if (parentSignal?.aborted) abort();
+  parentSignal?.addEventListener("abort", abort, { once: true });
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("trusted_match_context_router_runner.timeoutMs must be a positive finite number.");
+  }
+  const timer = setTimeout(
+    () => controller.abort(new Error(`Context router replay timed out after ${timeoutMs}ms`)),
+    timeoutMs
+  );
+  try {
+    const response = await (options.fetchImpl ?? fetch)(routerUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...options.headers ?? {} },
+      body: JSON.stringify(request),
+      signal: controller.signal
+    });
+    const body = await readResponseBody(response, MAX_ROUTER_RESPONSE_BYTES);
+    return {
+      url: routerUrl,
+      status: response.status,
+      headers: responseHeaders(response.headers),
+      body,
+      ...!response.ok && { error: `Context router returned HTTP ${response.status}.` }
+    };
+  } finally {
+    clearTimeout(timer);
+    parentSignal?.removeEventListener("abort", abort);
+  }
+}
+function assertHttpUrl(value, field) {
+  const parsed = new URL(value);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`trusted_match_context_router_runner.${field} must use http or https.`);
+  }
+}
+async function readResponseBody(response, maxBytes) {
+  if (!response.body) return null;
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    size += value.byteLength;
+    if (size > maxBytes) {
+      await reader.cancel();
+      throw new Error(`Context router response exceeded ${maxBytes} bytes.`);
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  const text = new TextDecoder().decode(bytes);
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function listen(server, host, port) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => reject(error);
+    server.once("error", onError);
+    server.listen(port, host, () => {
+      server.off("error", onError);
+      resolve();
+    });
+  });
+}
+function closeServer(server) {
+  return new Promise((resolve, reject) => {
+    server.close((error) => error ? reject(error) : resolve());
+  });
+}
+function consumeBody(req, maxBytes) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    req.on("data", (chunk) => {
+      size += Buffer.byteLength(chunk);
+      if (size > maxBytes) reject(new Error("request too large"));
+    });
+    req.on("end", resolve);
+    req.on("error", reject);
+  });
+}
+function respondJson(res, status, body) {
+  const encoded = JSON.stringify(body);
+  res.writeHead(status, { "content-type": "application/json", "content-length": Buffer.byteLength(encoded) });
+  res.end(encoded);
+}
+function formatHost(host) {
+  return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+function failedProbe(url, error) {
+  return { url, status: 0, headers: {}, body: null, error };
+}
+function responseHeaders(headers) {
+  const result = {};
+  headers.forEach((value, key) => {
+    result[key] = value;
+  });
+  return result;
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export {
+  replayTrustedMatchContextVector
+};
+//# sourceMappingURL=trusted-match-context-replay.mjs.map

package/dist/lib/testing/storyboard/trusted-match-context-replay.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/lib/testing/storyboard/trusted-match-context-replay.ts"],"sourcesContent":["import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';\nimport { existsSync, readFileSync } from 'node:fs';\nimport { basename, isAbsolute, join } from 'node:path';\nimport { getComplianceCacheDir } from './compliance';\nimport type {\n  HttpProbeResult,\n  StoryboardStep,\n  TrustedMatchContextProviderEndpoint,\n  TrustedMatchContextRouterRunnerOptions,\n} from './types';\n\nconst DEFAULT_VECTOR_REF = 'test-vectors/trusted-match-context-merge/vectors.json';\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst MAX_ROUTER_RESPONSE_BYTES = 1024 * 1024;\nconst MAX_PROVIDER_REQUEST_BYTES = 64 * 1024;\n\ninterface TrustedMatchContextVector {\n  profile: string;\n  registrations: Array<{ provider_id: string }>;\n  provider_responses: Array<{\n    registration_provider_id: string;\n    response: Record<string, unknown>;\n  }>;\n  request?: Record<string, unknown>;\n}\n\nexport interface TrustedMatchContextReplayResult {\n  httpResult: HttpProbeResult;\n  request: Record<string, unknown>;\n  vectorSource?: string;\n}\n\nexport async function replayTrustedMatchContextVector(\n  step: StoryboardStep,\n  options: TrustedMatchContextRouterRunnerOptions,\n  params: {\n    requestOverride?: Record<string, unknown>;\n    adcpVersion?: string;\n    signal?: AbortSignal;\n  } = {}\n): Promise<TrustedMatchContextReplayResult> {\n  const vectorResult = loadVector(step.vector_ref, options.vectorsRoot, params.adcpVersion);\n  const emptyRequest = params.requestOverride ?? step.sample_request ?? {};\n  if ('error' in vectorResult) {\n    return {\n      request: emptyRequest,\n      httpResult: failedProbe(options.router_url, vectorResult.error),\n    };\n  }\n\n  const request = params.requestOverride ?? vectorResult.vector.request ?? step.sample_request;\n  if (!request || typeof request !== 'object' || Array.isArray(request)) {\n    return {\n      request: {},\n      vectorSource: vectorResult.path,\n      httpResult: failedProbe(\n        options.router_url,\n        '`replay_trusted_match_context_vector` requires vector.request or step.sample_request.'\n      ),\n    };\n  }\n\n  let fixtureServer: ProviderFixtureServer | undefined;\n  let cleanupRegistration: void | (() => void | Promise<void>) = undefined;\n  let result: TrustedMatchContextReplayResult;\n  try {\n    fixtureServer = await createProviderFixtureServer(vectorResult.vector, options.provider_server);\n    cleanupRegistration = await options.registerProviders({\n      profile: vectorResult.vector.profile,\n      providers: fixtureServer.providers,\n      request: structuredClone(request),\n    });\n    const httpResult = await postRouterContext(options, request, params.signal);\n    result = { httpResult, request, vectorSource: vectorResult.path };\n  } catch (error) {\n    result = {\n      request,\n      vectorSource: vectorResult.path,\n      httpResult: failedProbe(options.router_url, error instanceof Error ? error.message : String(error)),\n    };\n  } finally {\n    const cleanupErrors: string[] = [];\n    try {\n      if (cleanupRegistration !== undefined) {\n        if (typeof cleanupRegistration !== 'function') {\n          throw new Error('registerProviders must return void or a cleanup function.');\n        }\n        await cleanupRegistration();\n      }\n    } catch (error) {\n      cleanupErrors.push(`registration cleanup failed: ${error instanceof Error ? error.message : String(error)}`);\n    }\n    try {\n      await fixtureServer?.close();\n    } catch (error) {\n      cleanupErrors.push(`provider fixture cleanup failed: ${error instanceof Error ? error.message : String(error)}`);\n    }\n    if (cleanupErrors.length > 0) {\n      const priorError = result!.httpResult.error;\n      result!.httpResult.error = [...(priorError ? [priorError] : []), ...cleanupErrors].join('; ');\n    }\n  }\n  return result!;\n}\n\nfunction loadVector(\n  vectorRef: string | undefined,\n  vectorsRoot: string | undefined,\n  adcpVersion: string | undefined\n): { vector: TrustedMatchContextVector; path: string } | { error: string } {\n  const rawRef = (vectorRef ?? DEFAULT_VECTOR_REF).split('#', 1)[0]!;\n  if (!rawRef || isAbsolute(rawRef) || rawRef.split(/[\\\\/]/).includes('..')) {\n    return { error: `Invalid Trusted Match Context vector_ref: ${vectorRef ?? rawRef}` };\n  }\n\n  const withoutStatic = rawRef.replace(/^static\\//, '').replace(/^compliance\\/source\\//, '');\n  const candidates: string[] = [];\n  if (vectorsRoot) {\n    candidates.push(join(vectorsRoot, rawRef), join(vectorsRoot, withoutStatic), join(vectorsRoot, basename(rawRef)));\n  }\n  const complianceDir = getComplianceCacheDir({ ...(adcpVersion && { version: adcpVersion }) });\n  candidates.push(\n    join(complianceDir, withoutStatic),\n    join(complianceDir, rawRef),\n    join(process.cwd(), rawRef),\n    join(process.cwd(), withoutStatic)\n  );\n\n  for (const candidate of [...new Set(candidates)]) {\n    if (!existsSync(candidate)) continue;\n    try {\n      const parsed = JSON.parse(readFileSync(candidate, 'utf8')) as unknown;\n      const validationError = validateVector(parsed);\n      if (validationError) return { error: `${candidate}: ${validationError}` };\n      return { vector: parsed as TrustedMatchContextVector, path: candidate };\n    } catch (error) {\n      return { error: `Failed to read Trusted Match Context vector ${candidate}: ${String(error)}` };\n    }\n  }\n  return { error: `Trusted Match Context vector file not found for ${rawRef}` };\n}\n\nfunction validateVector(value: unknown): string | undefined {\n  if (!isRecord(value)) return 'vector must be an object';\n  if (typeof value.profile !== 'string' || value.profile.length === 0) return 'profile must be a non-empty string';\n  if (!Array.isArray(value.registrations) || value.registrations.length === 0) {\n    return 'registrations must be a non-empty array';\n  }\n  if (!Array.isArray(value.provider_responses) || value.provider_responses.length === 0) {\n    return 'provider_responses must be a non-empty array';\n  }\n\n  const ids = new Set<string>();\n  for (const registration of value.registrations) {\n    if (!isRecord(registration) || typeof registration.provider_id !== 'string' || !registration.provider_id) {\n      return 'every registration requires a non-empty provider_id';\n    }\n    if (ids.has(registration.provider_id)) return `duplicate provider_id: ${registration.provider_id}`;\n    ids.add(registration.provider_id);\n  }\n  const responseIds = new Set<string>();\n  for (const entry of value.provider_responses) {\n    if (!isRecord(entry) || typeof entry.registration_provider_id !== 'string' || !isRecord(entry.response)) {\n      return 'every provider response requires registration_provider_id and an object response';\n    }\n    if (!ids.has(entry.registration_provider_id)) {\n      return `provider response has no matching registration: ${entry.registration_provider_id}`;\n    }\n    if (responseIds.has(entry.registration_provider_id)) {\n      return `duplicate provider response: ${entry.registration_provider_id}`;\n    }\n    responseIds.add(entry.registration_provider_id);\n  }\n  for (const providerId of ids) {\n    if (!responseIds.has(providerId)) return `registration has no provider response: ${providerId}`;\n  }\n  if ('request' in value && !isRecord(value.request)) return 'request must be an object when present';\n  return undefined;\n}\n\ninterface ProviderFixtureServer {\n  providers: TrustedMatchContextProviderEndpoint[];\n  close(): Promise<void>;\n}\n\nasync function createProviderFixtureServer(\n  vector: TrustedMatchContextVector,\n  config: TrustedMatchContextRouterRunnerOptions['provider_server']\n): Promise<ProviderFixtureServer> {\n  const host = config?.host ?? '127.0.0.1';\n  const port = config?.port ?? 0;\n  const mode = config?.mode ?? 'loopback_mock';\n  if (mode === 'proxy_url' && !config?.public_url) {\n    throw new Error('trusted_match_context_router_runner.provider_server.public_url is required in proxy_url mode.');\n  }\n  if (config?.public_url) assertHttpUrl(config.public_url, 'provider_server.public_url');\n\n  const responses = new Map(\n    vector.provider_responses.map(entry => [entry.registration_provider_id, entry.response] as const)\n  );\n  const server = createServer((req, res) => {\n    void serveProviderFixture(req, res, responses).catch(error => {\n      if (res.headersSent) {\n        res.destroy(error instanceof Error ? error : new Error(String(error)));\n      } else {\n        respondJson(res, 500, { error: 'fixture_server_error' });\n      }\n    });\n  });\n  await listen(server, host, port);\n  const address = server.address();\n  if (!address || typeof address === 'string') {\n    await closeServer(server);\n    throw new Error('Provider fixture server did not expose a TCP address.');\n  }\n  const localBase = `http://${formatHost(host)}:${address.port}`;\n  const advertisedBase = (mode === 'proxy_url' ? config!.public_url! : localBase).replace(/\\/$/, '');\n  const providers = vector.registrations.map(({ provider_id }) => ({\n    provider_id,\n    context_url: `${advertisedBase}/providers/${encodeURIComponent(provider_id)}/context`,\n  }));\n  return { providers, close: () => closeServer(server) };\n}\n\nasync function serveProviderFixture(\n  req: IncomingMessage,\n  res: ServerResponse,\n  responses: Map<string, Record<string, unknown>>\n): Promise<void> {\n  const pathname = new URL(req.url ?? '/', 'http://fixture.invalid').pathname;\n  const match = pathname.match(/^\\/providers\\/([^/]+)\\/context$/);\n  if (req.method !== 'POST' || !match) {\n    respondJson(res, req.method === 'POST' ? 404 : 405, { error: 'not_found' });\n    return;\n  }\n  try {\n    await consumeBody(req, MAX_PROVIDER_REQUEST_BYTES);\n  } catch {\n    respondJson(res, 413, { error: 'request_too_large' });\n    return;\n  }\n  const providerId = decodeURIComponent(match[1]!);\n  const response = responses.get(providerId);\n  if (!response) {\n    respondJson(res, 404, { error: 'provider_not_found' });\n    return;\n  }\n  respondJson(res, 200, response);\n}\n\nasync function postRouterContext(\n  options: TrustedMatchContextRouterRunnerOptions,\n  request: Record<string, unknown>,\n  parentSignal?: AbortSignal\n): Promise<HttpProbeResult> {\n  const routerUrl = `${options.router_url.replace(/\\/$/, '')}/context`;\n  const parsed = new URL(routerUrl);\n  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {\n    throw new Error('trusted_match_context_router_runner.router_url must use http or https.');\n  }\n  const controller = new AbortController();\n  const abort = () => controller.abort(parentSignal?.reason);\n  if (parentSignal?.aborted) abort();\n  parentSignal?.addEventListener('abort', abort, { once: true });\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {\n    throw new Error('trusted_match_context_router_runner.timeoutMs must be a positive finite number.');\n  }\n  const timer = setTimeout(\n    () => controller.abort(new Error(`Context router replay timed out after ${timeoutMs}ms`)),\n    timeoutMs\n  );\n  try {\n    const response = await (options.fetchImpl ?? fetch)(routerUrl, {\n      method: 'POST',\n      headers: { 'content-type': 'application/json', ...(options.headers ?? {}) },\n      body: JSON.stringify(request),\n      signal: controller.signal,\n    });\n    const body = await readResponseBody(response, MAX_ROUTER_RESPONSE_BYTES);\n    return {\n      url: routerUrl,\n      status: response.status,\n      headers: responseHeaders(response.headers),\n      body,\n      ...(!response.ok && { error: `Context router returned HTTP ${response.status}.` }),\n    };\n  } finally {\n    clearTimeout(timer);\n    parentSignal?.removeEventListener('abort', abort);\n  }\n}\n\nfunction assertHttpUrl(value: string, field: string): void {\n  const parsed = new URL(value);\n  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {\n    throw new Error(`trusted_match_context_router_runner.${field} must use http or https.`);\n  }\n}\n\nasync function readResponseBody(response: Response, maxBytes: number): Promise<unknown> {\n  if (!response.body) return null;\n  const reader = response.body.getReader();\n  const chunks: Uint8Array[] = [];\n  let size = 0;\n  while (true) {\n    const { value, done } = await reader.read();\n    if (done) break;\n    if (!value) continue;\n    size += value.byteLength;\n    if (size > maxBytes) {\n      await reader.cancel();\n      throw new Error(`Context router response exceeded ${maxBytes} bytes.`);\n    }\n    chunks.push(value);\n  }\n  const bytes = new Uint8Array(size);\n  let offset = 0;\n  for (const chunk of chunks) {\n    bytes.set(chunk, offset);\n    offset += chunk.byteLength;\n  }\n  const text = new TextDecoder().decode(bytes);\n  if (!text) return null;\n  try {\n    return JSON.parse(text) as unknown;\n  } catch {\n    return text;\n  }\n}\n\nfunction listen(server: Server, host: string, port: number): Promise<void> {\n  return new Promise((resolve, reject) => {\n    const onError = (error: Error) => reject(error);\n    server.once('error', onError);\n    server.listen(port, host, () => {\n      server.off('error', onError);\n      resolve();\n    });\n  });\n}\n\nfunction closeServer(server: Server): Promise<void> {\n  return new Promise((resolve, reject) => {\n    server.close(error => (error ? reject(error) : resolve()));\n  });\n}\n\nfunction consumeBody(req: IncomingMessage, maxBytes: number): Promise<void> {\n  return new Promise((resolve, reject) => {\n    let size = 0;\n    req.on('data', chunk => {\n      size += Buffer.byteLength(chunk);\n      if (size > maxBytes) reject(new Error('request too large'));\n    });\n    req.on('end', resolve);\n    req.on('error', reject);\n  });\n}\n\nfunction respondJson(res: ServerResponse, status: number, body: unknown): void {\n  const encoded = JSON.stringify(body);\n  res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(encoded) });\n  res.end(encoded);\n}\n\nfunction formatHost(host: string): string {\n  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;\n}\n\nfunction failedProbe(url: string, error: string): HttpProbeResult {\n  return { url, status: 0, headers: {}, body: null, error };\n}\n\nfunction responseHeaders(headers: Headers): Record<string, string> {\n  const result: Record<string, string> = {};\n  headers.forEach((value, key) => {\n    result[key] = value;\n  });\n  return result;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\n}\n"],"mappings":"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","names":[]}

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

@@ -83,6 +83,15 @@ export interface Storyboard {
      *     declares this requirement implicitly. Authors do not need to
      *     write `requires: [webhook_receiver]` — the tokens are
      *     self-describing.
+     *   - `webhook_replay_receiver` — the runner must be configured with an
+     *     inbound buyer/orchestrator receiver URL
+     *     (`StoryboardRunOptions.webhook_replay_receiver.url`). Autodetected
+     *     from any `replay_webhook_vector` step and graded not applicable when
+     *     absent. Spec: adcp-client#2356.
+     *   - `trusted_match_context_router_runner` — the runner must be configured
+     *     with a raw Context Match router URL and operator registration seam.
+     *     Autodetected from `replay_trusted_match_context_vector`; absent
+     *     harnesses grade not_applicable. Spec: adcp-client#2479.
      *   - `request_signer` — the agent under test MUST advertise
      *     `request_signing.supported: true` in `get_adcp_capabilities`.
      *     Autodetected: any storyboard whose `id === 'signed_requests'`
@@ -197,6 +206,13 @@ export interface Storyboard {
      * field(s) into `params.fixture` verbatim.
      */
     fixtures?: StoryboardFixtures;
+    /**
+     * AdCP 3.2 fixture-handle resolution policy. Fixture ids remain authored in
+     * `fixtures:` and in step payloads, but declarations here may allow the
+     * runner to bind those run-scoped handles to real seller catalog ids.
+     * Omitted handles retain the compatibility strategy `["seed"]`.
+     */
+    fixture_resolution?: StoryboardFixtureResolution;
     /**
      * Initial context values declared by the storyboard YAML. Runner callers may
      * override these defaults with `StoryboardRunOptions.context`.
@@ -333,6 +349,99 @@ export interface StoryboardFixtures {
     }>;
     buyer_agents?: StoryboardBuyerAgentFixture[];
 }
+/** Ordered setup strategies supported by the first AdCP 3.2 runner slice. */
+export type FixtureResolutionStrategy = 'seed' | 'discover';
+/** Operators supported by the closed AdCP 3.2 fixture predicate DSL. */
+export type FixtureMatchOperator = 'equals' | 'present' | 'contains_all' | 'any_match' | 'canonical_format_satisfies';
+export interface FixtureCanonicalFormatSelector extends Record<string, unknown> {
+    format_kind: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * One fixture-discovery predicate. `path` is an RFC 6901 JSON Pointer
+ * relative to the candidate entity. `any_match` uses `where` recursively,
+ * `present` is valueless, and the remaining operators use `value`.
+ */
+export type FixtureMatchClause = {
+    path: string;
+    operator: 'equals';
+    value: unknown;
+    where?: never;
+} | {
+    path: string;
+    operator: 'present';
+    value?: never;
+    where?: never;
+} | {
+    path: string;
+    operator: 'contains_all';
+    value: unknown[];
+    where?: never;
+} | {
+    path: string;
+    operator: 'canonical_format_satisfies';
+    value: FixtureCanonicalFormatSelector;
+    where?: never;
+} | {
+    path: string;
+    operator: 'any_match';
+    where: FixtureMatchClause[];
+    value?: never;
+};
+export interface FixtureResolutionDeclaration {
+    /** Authored run-scoped fixture handle. */
+    handle: string;
+    /** Ordered strategy ladder. Omission means `["seed"]`. */
+    strategies?: FixtureResolutionStrategy[];
+    /** Requirements a discovered seller entity must satisfy. */
+    match?: FixtureMatchClause[];
+    /** Default false: one seller entity cannot satisfy two handles. */
+    allow_reuse?: boolean;
+}
+export type ProductFixtureResolutionDeclaration = FixtureResolutionDeclaration;
+export interface PricingOptionFixtureResolutionDeclaration extends FixtureResolutionDeclaration {
+    /** Parent authored product handle for root-level pricing-option declarations. */
+    product_handle: string;
+}
+export interface StoryboardFixtureResolution {
+    products?: ProductFixtureResolutionDeclaration[];
+    pricing_options?: PricingOptionFixtureResolutionDeclaration[];
+}
+export type FixtureResolutionStatus = 'resolved' | 'unsatisfied' | 'failed';
+export interface FixtureResolutionAttempt {
+    strategy: FixtureResolutionStrategy;
+    disposition: 'resolved' | 'unavailable' | 'failed';
+    detail: string;
+    request?: Record<string, unknown>;
+    response?: unknown;
+}
+/** @deprecated Use FixtureResolutionAttempt. */
+export type FixtureResolutionEvidence = FixtureResolutionAttempt;
+/** Machine-readable record emitted exactly once for every fixture handle. */
+export interface FixtureResolutionRecord {
+    fixture_type: 'product' | 'pricing_option';
+    handle: string;
+    product_handle?: string;
+    requirements: FixtureMatchClause[];
+    strategies_attempted: FixtureResolutionAttempt[];
+    status: FixtureResolutionStatus;
+    strategy?: FixtureResolutionStrategy;
+    seller_ids?: {
+        product_id: string;
+        pricing_option_id?: string;
+    };
+}
+/** One storyboard-scoped coverage gap produced by fixture resolution. */
+export interface FixtureResolutionCoverageGap {
+    reason: 'fixture_unsatisfied';
+    detail: string;
+    fixtures: Array<{
+        fixture_type: FixtureResolutionRecord['fixture_type'];
+        handle: string;
+        product_handle?: string;
+        requirements: FixtureMatchClause[];
+    }>;
+}
 export interface StoryboardBuyerAgentFixture {
     agent_url?: string;
     display_name?: string;
@@ -727,7 +836,7 @@ export type StoryboardValidationCheck = 'response_schema' | 'field_present' | 'f
  * envelope fields such as `adcp_major_version` should use
  * `envelope_field_value`.
  */
- | 'envelope_field_pattern' | 'field_contains' | 'status_code' | 'error_code' | 'http_status' | 'http_status_in' | 'on_401_require_header' | 'resource_equals_agent_url' | 'any_of' | 'a2a_submitted_artifact' | 'a2a_context_continuity' | 'refs_resolve'
+ | 'envelope_field_pattern' | 'field_contains' | 'status_code' | 'error_code' | 'http_status' | 'http_status_in' | 'on_401_require_header' | 'resource_equals_agent_url' | 'oauth_metadata_graph' | 'any_of' | 'a2a_submitted_artifact' | 'a2a_context_continuity' | 'refs_resolve'
 /**
  * Assert a numeric field in the current step's response is strictly less than
  * a comparand. The comparand is either a context-captured runtime value
@@ -1208,6 +1317,51 @@ export interface AgentEntry {
     /** Per-tenant transport override; defaults to `StoryboardRunOptions.protocol`. */
     transport?: 'mcp' | 'a2a';
 }
+/** One runner-hosted Context Match provider fixture exposed to the router under test. */
+export interface TrustedMatchContextProviderEndpoint {
+    /** Publisher-controlled registration id from the packaged conformance vector. */
+    provider_id: string;
+    /** Absolute URL serving this provider's vector response at `POST /context`. */
+    context_url: string;
+}
+/** Input to the operator-owned router registration seam. */
+export interface TrustedMatchContextRegistrationContext {
+    /** Vector profile, currently `adcp/trusted-match/context-targeting-merge/v1`. */
+    profile: string;
+    /** Fixed provider ids paired with the runner-hosted fixture URLs. */
+    providers: TrustedMatchContextProviderEndpoint[];
+    /** Exact Context Match request the runner will send after registration completes. */
+    request: Record<string, unknown>;
+}
+export interface TrustedMatchContextRouterRunnerOptions {
+    /** Router base URL. The runner posts the vector request to `<router_url>/context`. */
+    router_url: string;
+    /**
+     * Operator-owned seam that installs the supplied provider registrations in
+     * the router under test. It may return a cleanup callback, which the runner
+     * invokes after the replay even when the router request fails.
+     */
+    registerProviders(context: TrustedMatchContextRegistrationContext): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
+    /** Extra headers sent to the router's `/context` endpoint. */
+    headers?: Record<string, string>;
+    /** Router request timeout in milliseconds. Defaults to 10000. */
+    timeoutMs?: number;
+    /** Optional root directory for resolving the packaged vector file. */
+    vectorsRoot?: string;
+    /** Override fetch for tests or custom runtimes. */
+    fetchImpl?: typeof fetch;
+    /** Configuration for the ephemeral provider fixture server. */
+    provider_server?: {
+        /** Loopback by default; proxy mode advertises `public_url` to remote routers. */
+        mode?: 'loopback_mock' | 'proxy_url';
+        /** Bind host for the local fixture listener. Defaults to `127.0.0.1`. */
+        host?: string;
+        /** Bind port. `0` (default) lets the kernel assign one. */
+        port?: number;
+        /** Public base URL routed to the local listener; required in proxy mode. */
+        public_url?: string;
+    };
+}
 export interface StoryboardRunOptions extends TestOptions {
     /** Initial context (e.g., from a previous step invocation) */
     context?: StoryboardContext;
@@ -1440,6 +1594,14 @@ export interface StoryboardRunOptions extends TestOptions {
         /** Override fetch for tests or custom runtimes. */
         fetchImpl?: typeof fetch;
     };
+    /**
+     * Raw-HTTP Trusted Match Context router harness used by
+     * `replay_trusted_match_context_vector`. The runner hosts the packaged
+     * provider fixtures, calls `registerProviders`, then posts the vector
+     * request to `<router_url>/context`. Without this option the storyboard
+     * grades `not_applicable`; it never falls back to MCP or A2A.
+     */
+    trusted_match_context_router_runner?: TrustedMatchContextRouterRunnerOptions;
     /**
      * Test-kit contract ids that are in scope for this run. A step with
      * `requires_contract: <id>` grades `not_applicable` when the id is not
@@ -1534,7 +1696,16 @@ export interface RunnerExtractionRecord {
  * whether a skip is informative (agent didn't claim the protocol) or masking
  * (runner couldn't apply the storyboard even though the agent claimed it).
  */
-export type RunnerSkipReason = 'not_applicable' | 'no_phases' | 'prerequisite_failed' | 'missing_tool' | 'missing_test_controller' | 'unsatisfied_contract'
+export type RunnerSkipReason = 'not_applicable' | 'no_phases' | 'prerequisite_failed' | 'missing_tool' | 'missing_test_controller'
+/**
+ * The runner selected the pathway but its test kit cannot synthesize a
+ * valid input for the seller-declared contract. This is a runner-owned
+ * coverage gap: it never fails validations or cascades prerequisites.
+ * Spec: AdCP runner-output-contract v2.8.0,
+ * `skip_result.reasons.fixture_unavailable` (adcp#6276). Early preflight
+ * and whole-storyboard termination semantics: adcp#6278.
+ */
+ | 'fixture_unavailable' | 'unsatisfied_contract'
 /**
  * A storyboard-level `requires:` tag named a requirement that is not
  * available on the current run (e.g. `controller` when the agent doesn't
@@ -1566,7 +1737,7 @@ export type RunnerSkipReason = 'not_applicable' | 'no_phases' | 'prerequisite_fa
  */
  | 'peer_substituted';
 /**
- * Grader-specific skip reasons. These are narrower than the six canonical
+ * Grader-specific skip reasons. These are narrower than the canonical
  * `RunnerSkipReason` values — they carry runner-local context (which probe,
  * which operator opt-out) that the contract neither requires nor forbids.
  * The runner records them on `skip_reason` for legacy consumers, and also
@@ -1601,6 +1772,8 @@ export type RunnerDetailedSkipReason = 'probe_skipped' | 'rate_abuse_opt_out' |
  * setup, so the storyboard is out of scope rather than failed.
  */
  | 'fixture_seed_unsupported'
+/** A valid fixture strategy ladder exhausted without finding a binding. */
+ | 'fixture_unsatisfied'
 /**
  * A `requires_capability` predicate on the storyboard evaluated to false —
  * the agent explicitly declared it does not support the capability this
@@ -1624,7 +1797,7 @@ export type RunnerDetailedSkipReason = 'probe_skipped' | 'rate_abuse_opt_out' |
  */
  | 'force_scenario_unsupported';
 /**
- * Map detailed grader skip reasons onto the six canonical spec values so
+ * Map detailed grader skip reasons onto the canonical spec values so
  * consumers reading `skip.reason` get a stable enum regardless of which
  * subsystem produced the skip.
  */
@@ -1655,9 +1828,9 @@ export interface RunnerSelectionResult {
  * surface change; coordinate with the upstream spec proposal before
  * extending.
  *
- * Spec: adcp-client#1626, adcp-client#2281.
+ * Spec: adcp-client#1626, adcp-client#2281, adcp-client#2356.
  */
-export type RequirementName = 'controller' | 'seeded_state' | 'real_wire' | 'webhook_receiver' | 'request_signer' | 'multi_agent';
+export type RequirementName = 'controller' | 'seeded_state' | 'real_wire' | 'webhook_receiver' | 'webhook_replay_receiver' | 'trusted_match_context_router_runner' | 'request_signer' | 'multi_agent';
 /**
  * Enumeration of every requirement this SDK knows how to satisfy. The loader
  * accepts other non-empty strings for forward compatibility; the runner treats
@@ -1799,13 +1972,11 @@ export interface ValidationResult {
     /** Optional remediation hint. */
     remediation?: string;
     /**
-     * Forward-compat marker: set when the runner did not implement the
-     * authored check kind and graded it as `not_applicable` (passed: true)
-     * to preserve forward compatibility with future spec additions. The
-     * companion `note` describes the coverage gap. Per
-     * runner-output-contract.yaml v2.0.0 these contribute to the run
-     * summary's `validations_not_applicable` counter so consumers can
-     * distinguish "runner is older than the storyboard" from clean passes.
+     * Marker for an implemented check whose declared applicability conditions
+     * were not met. Unknown authored check kinds fail closed; they never set
+     * this flag or contribute a false green result. Entries carrying this flag
+     * contribute to `validations_not_applicable` so consumers can distinguish
+     * inapplicable coverage from clean passes.
      */
     not_applicable?: boolean;
     /**
@@ -1887,8 +2058,8 @@ export interface StoryboardStepResult {
     /** True when the step was not executed */
     skipped?: boolean;
     /**
-     * Skip reason. Accepts either a canonical `RunnerSkipReason` (the six
-     * spec-required values) or one of the grader-specific variants introduced
+     * Skip reason. Accepts either a canonical `RunnerSkipReason` or one of the
+     * grader-specific variants introduced
      * by the RFC 9421 request-signing grader (#585, #617). The structured
      * `skip` field below always carries the canonical spec reason so consumers
      * of the runner-output contract don't need to know the grader vocabulary.
@@ -2409,6 +2580,10 @@ export interface StoryboardResult {
      */
     agent_map?: Record<string, string>;
     overall_passed: boolean;
+    /** AdCP 3.2 fixture-handle setup/discovery evidence, one row per handle. */
+    fixture_resolutions?: FixtureResolutionRecord[];
+    /** Storyboard-level fixture coverage gaps, emitted once per cause. */
+    coverage_gaps?: FixtureResolutionCoverageGap[];
     /**
      * Phases from the first pass. In `multi-pass` mode see `passes` for the full
      * per-pass detail; `passed_count`/`failed_count`/`skipped_count` and