@adcp/sdk 16.2.0 → 16.3.0

package/dist/lib/testing/storyboard/prepared-fixtures.js

@@ -0,0 +1,434 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var prepared_fixtures_exports = {};
+__export(prepared_fixtures_exports, {
+  PREPARED_FIXTURES_CONTRACT_VERSION: () => PREPARED_FIXTURES_CONTRACT_VERSION,
+  PreparedStoryboardFixtures: () => PreparedStoryboardFixtures,
+  buildPreparedBinding: () => buildPreparedBinding,
+  createPreparedStoryboardFixtures: () => createPreparedStoryboardFixtures,
+  diffPreparedBinding: () => diffPreparedBinding,
+  digestStoryboard: () => digestStoryboard,
+  fingerprintCredential: () => fingerprintCredential,
+  isTrustedPreparedFixtures: () => isTrustedPreparedFixtures,
+  preparedBindingRegistryFor: () => preparedBindingRegistryFor,
+  resolvePreparedFixtures: () => resolvePreparedFixtures,
+  resolveSchemaArtifact: () => resolveSchemaArtifact,
+  withPreparedFixtures: () => withPreparedFixtures
+});
+module.exports = __toCommonJS(prepared_fixtures_exports);
+var import_node_crypto = require("node:crypto");
+var import_node_fs = require("node:fs");
+var import_node_path = __toESM(require("node:path"));
+var import_schema_loader = require('../../validation/schema-loader.js');
+var import_version = require('../../version.js');
+const PREPARED_FIXTURES_CONTRACT_VERSION = "1.0.0";
+const REFERENCE_REFUSAL_DETAIL = "prepared fixture state was refused by the configured authorizer";
+const trustedStates = /* @__PURE__ */ new WeakSet();
+const registries = /* @__PURE__ */ new WeakMap();
+function freezeDeepLocal(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const nested of Object.values(value)) freezeDeepLocal(nested);
+  return value;
+}
+const CONSTRUCTION_TOKEN = /* @__PURE__ */ Symbol("adcp.preparedStoryboardFixtures");
+class PreparedStoryboardFixtures {
+  #binding;
+  #resolutions;
+  #coverageGaps;
+  #captures;
+  #captureProvenance;
+  #witnesses;
+  #disposition;
+  #phase;
+  /**
+   * @internal Constructed only by `prepareStoryboardFixtures`. The token is
+   * module-private, so an external `new` call cannot satisfy it.
+   */
+  constructor(init, token) {
+    if (token !== CONSTRUCTION_TOKEN) {
+      throw new Error(
+        "PreparedStoryboardFixtures cannot be constructed directly; call prepareStoryboardFixtures() to produce prepared state"
+      );
+    }
+    this.#binding = freezeDeepLocal(structuredClone(init.binding));
+    if (init.bindings) registries.set(this, init.bindings);
+    this.#resolutions = Object.freeze(structuredClone(init.resolutions));
+    this.#coverageGaps = Object.freeze(structuredClone(init.coverageGaps));
+    this.#captures = Object.freeze(structuredClone(init.captures));
+    this.#captureProvenance = Object.freeze(structuredClone(init.captureProvenance));
+    this.#witnesses = Object.freeze(structuredClone(init.witnesses));
+    this.#disposition = freezeDeepLocal(structuredClone(init.disposition));
+    this.#phase = init.phase === void 0 ? void 0 : structuredClone(init.phase);
+    trustedStates.add(this);
+    Object.freeze(this);
+  }
+  /** Nonsecret binding identity. Detached copy. */
+  get binding() {
+    return structuredClone(this.#binding);
+  }
+  get disposition() {
+    return structuredClone(this.#disposition);
+  }
+  /** Machine-readable per-handle resolution evidence. Detached copy. */
+  get resolutions() {
+    return structuredClone(this.#resolutions);
+  }
+  /** Coverage gaps observed during preparation. Detached copy. */
+  get coverageGaps() {
+    return structuredClone(this.#coverageGaps);
+  }
+  /** Pinned seller identities per handle. Detached copy. */
+  get selections() {
+    return this.#resolutions.filter((record) => record.seller_ids !== void 0).map((record) => ({
+      handle: record.handle,
+      fixture_type: record.fixture_type,
+      ...record.product_handle && { product_handle: record.product_handle },
+      seller_ids: structuredClone(record.seller_ids)
+    }));
+  }
+  /** Reserved-namespace captures. Detached copy. */
+  get captures() {
+    return structuredClone(this.#captures);
+  }
+  /** Capture provenance. Detached copy. */
+  get captureProvenance() {
+    return structuredClone(this.#captureProvenance);
+  }
+  /** Retained collection witnesses per handle. Detached copy. */
+  get witnesses() {
+    return structuredClone(this.#witnesses);
+  }
+  /**
+   * Detached copy of the synthetic pre-flight phase, for attachment to a
+   * full run's report. A live reference would let a report consumer mutate
+   * the preparation's own evidence — including a failed or no-match
+   * disposition's raw failure detail.
+   */
+  get phase() {
+    return this.#phase === void 0 ? void 0 : structuredClone(this.#phase);
+  }
+}
+Object.freeze(PreparedStoryboardFixtures.prototype);
+function readPreparedBindingRegistry(state) {
+  return registries.get(state);
+}
+function preparedBindingRegistryFor(state) {
+  return readPreparedBindingRegistry(state);
+}
+function createPreparedStoryboardFixtures(init) {
+  return new PreparedStoryboardFixtures(init, CONSTRUCTION_TOKEN);
+}
+function withPreparedFixtures(state, authorizer) {
+  return { prepared_fixtures: state, prepared_fixtures_authorizer: authorizer };
+}
+function isTrustedPreparedFixtures(value) {
+  return value instanceof PreparedStoryboardFixtures && trustedStates.has(value);
+}
+const CREDENTIAL_FINGERPRINT_KEY = (0, import_node_crypto.randomBytes)(32);
+function fingerprintCredential(secret) {
+  return (0, import_node_crypto.createHmac)("sha256", CREDENTIAL_FINGERPRINT_KEY).update(secret).digest("hex").slice(0, 32);
+}
+function redactRouteCredentials(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return raw;
+  }
+  url.username = "";
+  url.password = "";
+  for (const key of [...url.searchParams.keys()]) {
+    if (/(token|secret|key|password|credential|signature|auth)/i.test(key)) {
+      url.searchParams.set(key, "[redacted]");
+    }
+  }
+  url.hash = "";
+  return url.toString();
+}
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+  const entries = Object.entries(value).filter(([, nested]) => nested !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return `{${entries.map(([key, nested]) => `${JSON.stringify(key)}:${canonicalize(nested)}`).join(",")}}`;
+}
+function digestStoryboard(storyboard) {
+  return (0, import_node_crypto.createHash)("sha256").update(canonicalize(storyboard)).digest("hex");
+}
+const schemaDigestCache = /* @__PURE__ */ new Map();
+function digestSchemaRoot(root) {
+  const cached = schemaDigestCache.get(root);
+  if (cached !== void 0) return cached;
+  const lines = [`root\0${root}`];
+  const walk = (dir, rel) => {
+    let entries;
+    try {
+      entries = (0, import_node_fs.readdirSync)(dir, { withFileTypes: true });
+    } catch {
+      lines.push(`${rel || "."}\0unreadable-dir`);
+      return;
+    }
+    for (const entry of entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+      const absolute = import_node_path.default.join(dir, entry.name);
+      const relative = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(absolute, relative);
+        continue;
+      }
+      try {
+        const stat = (0, import_node_fs.statSync)(absolute);
+        lines.push(`${relative}\0${stat.size}\0${stat.mtimeMs}`);
+      } catch {
+        lines.push(`${relative}\0unreadable`);
+      }
+    }
+  };
+  walk(root, "");
+  const digest = (0, import_node_crypto.createHash)("sha256").update(lines.join("\n")).digest("hex");
+  schemaDigestCache.set(root, digest);
+  return digest;
+}
+function resolveSchemaArtifact(adcpVersion = import_version.ADCP_VERSION) {
+  const location = (0, import_schema_loader.getActiveSchemaArtifactLocation)(adcpVersion);
+  return {
+    adcp_version: adcpVersion,
+    bundle_key: location.bundle_key,
+    external: location.external,
+    digest: digestSchemaRoot(location.root)
+  };
+}
+function buildPreparedBinding(input) {
+  return {
+    storyboard_id: input.storyboard.id,
+    storyboard_digest: digestStoryboard(input.storyboard),
+    agent_urls: [...input.agentUrls].sort().map(redactRouteCredentials),
+    // The route the GRAPH was pinned against, positionally — preparation
+    // contacts exactly one agent, `agentUrls[0]`, and nothing else in the
+    // binding records which one that was. `agent_urls` is sorted and
+    // `agent_route_fingerprint` sorts by key, both deliberately
+    // order-insensitive, so two runs whose `agents` maps differ only in
+    // insertion order produced byte-identical bindings while preparation
+    // had actually read seller B's catalog for one and seller A's for the
+    // other. Reuse across them sent B's pinned product_id to A.
+    fixture_agent_url: redactRouteCredentials(input.agentUrls[0] ?? ""),
+    // Covers the specialism→URL PAIRING, not just the URL set. Sorting the
+    // set alone meant swapping two specialisms' routes left the fingerprint
+    // unchanged while every per-specialism credential went to a different
+    // seller.
+    agent_route_fingerprint: fingerprintCredential(
+      JSON.stringify([
+        [...input.agentUrls].sort(),
+        input.agentRouteMap ? [...input.agentRouteMap].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0) : null,
+        // The RAW positional first url — the one preparation contacts.
+        // `fixture_agent_url` beside it is redacted for the authorizer to
+        // read, so two routes differing only in userinfo or a credential
+        // query parameter render identically there and would have
+        // collapsed into one binding.
+        input.agentUrls[0] ?? null
+      ])
+    ),
+    schema_artifact: resolveSchemaArtifact(input.adcpVersion ?? import_version.ADCP_VERSION),
+    contract_version: PREPARED_FIXTURES_CONTRACT_VERSION,
+    account_scope: input.accountScope,
+    brand_scope: input.brandScope,
+    ...input.requestAccountScope !== void 0 && { request_account_scope: input.requestAccountScope },
+    sandbox: input.sandbox,
+    ...input.principal !== void 0 && { principal: input.principal },
+    credential_fingerprint: fingerprintCredential(input.credential),
+    ...input.stepCredential !== void 0 && {
+      step_credential_fingerprint: fingerprintCredential(input.stepCredential)
+    },
+    ...input.stepAuthKind !== void 0 && { step_auth_kind: input.stepAuthKind },
+    // Independent of the credential: a routed step whose credential happens
+    // to equal the run's still dispatches to one specific seller.
+    ...input.stepRoute !== void 0 && { step_route: input.stepRoute },
+    run_id: input.runId ?? (0, import_node_crypto.randomUUID)()
+  };
+}
+const BINDING_FIELDS = [
+  "storyboard_id",
+  "storyboard_digest",
+  "agent_urls",
+  "agent_route_fingerprint",
+  "fixture_agent_url",
+  "schema_artifact",
+  "contract_version",
+  "account_scope",
+  "brand_scope",
+  "sandbox",
+  "principal",
+  "credential_fingerprint"
+];
+function diffPreparedBinding(prepared, current) {
+  const mismatches = [];
+  for (const field of BINDING_FIELDS) {
+    if (canonicalize(prepared[field]) !== canonicalize(current[field])) mismatches.push(field);
+  }
+  return mismatches;
+}
+function isReference(value) {
+  return typeof value === "object" && value !== null && typeof value.ref === "string" && typeof value.resolve === "function";
+}
+async function resolvePreparedFixtures(input) {
+  const supplied = input.supplied;
+  if (supplied === void 0) return void 0;
+  const authorizer = input.authorizer;
+  if (!authorizer) {
+    return {
+      ok: false,
+      refusal: {
+        code: "authorizer_required",
+        detail: isReference(supplied) ? "prepared_fixtures was supplied as an opaque reference, but no prepared_fixtures_authorizer was configured. An opaque reference is never authorization: supply an authorizer, because the SDK has no session and no grant store and cannot decide whether this reference is still yours." : "prepared_fixtures reuse requires prepared_fixtures_authorizer. Trusted object identity proves the state came from prepareStoryboardFixtures in this process; it does not establish a current grant, and binding coherence cannot observe revocation. Supply an authorizer that re-checks live grant state on every lookup. If this run genuinely has no grant model (single-tenant CLI, local dev), either drop prepared_fixtures and let the runner re-resolve, or pass prepared_fixtures_authorizer: () => ({ authorized: true }) as an explicit, reviewable decision. See docs/guides/COLLECTION-FIXTURE-FOUNDATION.md section 4."
+      }
+    };
+  }
+  let state = supplied;
+  let reference;
+  if (isReference(supplied)) {
+    reference = supplied.ref;
+    try {
+      state = await supplied.resolve(supplied.ref);
+    } catch {
+      state = void 0;
+    }
+  }
+  const refuseReference = async () => {
+    try {
+      await authorizer({
+        // Cloned, and cloned SEPARATELY, exactly as the authorized path
+        // does: handing the same object twice would let an authorizer
+        // detect `binding === current` by reference.
+        //
+        // That closes the object-IDENTITY distinction and nothing more.
+        // The VALUES still differ by path — a resolving reference carries
+        // the stored preparation binding, this one carries a second copy
+        // of `current` — so an authorizer that deep-compares them can
+        // still tell a missing reference from a present one. That is not
+        // the oracle this branch exists to close: the authorizer IS the
+        // host, it owns the store it would be learning about, and it
+        // cannot be given a fabricated stored binding without being lied
+        // to. What is closed is the oracle available to the CALLER, who
+        // sees only the refusal: identical text, identical machine code,
+        // identical validation shape, same authorizer call count.
+        binding: structuredClone(input.current),
+        current: structuredClone(input.current),
+        ...input.stepId !== void 0 && { step_id: input.stepId },
+        ...input.gate !== void 0 && { gate: input.gate },
+        ...reference !== void 0 && { reference }
+      });
+    } catch {
+    }
+    return { ok: false, refusal: { code: "authorizer_denied", detail: REFERENCE_REFUSAL_DETAIL } };
+  };
+  if (!isTrustedPreparedFixtures(state)) {
+    if (reference !== void 0) return refuseReference();
+    return {
+      ok: false,
+      refusal: {
+        code: "untrusted_state",
+        detail: "prepared fixture state was not produced by prepareStoryboardFixtures in this process; a rehydrated, cloned or caller-constructed look-alike carries no preparation authority"
+      }
+    };
+  }
+  const binding = state.binding;
+  if (binding.contract_version !== PREPARED_FIXTURES_CONTRACT_VERSION) {
+    if (reference !== void 0) return refuseReference();
+    return {
+      ok: false,
+      refusal: {
+        code: "contract_version_mismatch",
+        detail: `prepared state declares contract version ${binding.contract_version}; this runner implements ${PREPARED_FIXTURES_CONTRACT_VERSION}`
+      }
+    };
+  }
+  let authorized = false;
+  let decisionDetail;
+  try {
+    const decision = await authorizer({
+      binding: structuredClone(binding),
+      current: structuredClone(input.current),
+      ...input.stepId !== void 0 && { step_id: input.stepId },
+      ...input.gate !== void 0 && { gate: input.gate },
+      ...reference !== void 0 && { reference }
+    });
+    authorized = decision?.authorized === true;
+    const detail = decision?.detail;
+    decisionDetail = typeof detail === "string" ? detail : void 0;
+  } catch {
+    return { ok: false, refusal: { code: "authorizer_denied", detail: REFERENCE_REFUSAL_DETAIL } };
+  }
+  if (!authorized) {
+    if (reference !== void 0) {
+      return { ok: false, refusal: { code: "authorizer_denied", detail: REFERENCE_REFUSAL_DETAIL } };
+    }
+    return {
+      ok: false,
+      refusal: {
+        code: "authorizer_denied",
+        // `detail` is optional, so an absent one must not render as the
+        // string "undefined" — a difference in text is a difference a
+        // caller can measure.
+        detail: decisionDetail !== void 0 && decisionDetail.length > 0 ? `prepared fixture state was refused by the configured authorizer: ${decisionDetail}` : REFERENCE_REFUSAL_DETAIL
+      }
+    };
+  }
+  const mismatches = diffPreparedBinding(binding, input.current);
+  if (mismatches.length > 0) {
+    if (reference !== void 0) {
+      return { ok: false, refusal: { code: "authorizer_denied", detail: REFERENCE_REFUSAL_DETAIL } };
+    }
+    return {
+      ok: false,
+      refusal: {
+        code: "binding_mismatch",
+        // Field names only. The values are another principal's identity when
+        // the caller guessed a reference, and `credential_fingerprint` must
+        // never reach operator-visible text at all.
+        detail: `prepared fixture state does not match the current run scope; differing binding field(s): ${mismatches.join(", ")}`
+      }
+    };
+  }
+  return { ok: true, state };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PREPARED_FIXTURES_CONTRACT_VERSION,
+  PreparedStoryboardFixtures,
+  buildPreparedBinding,
+  createPreparedStoryboardFixtures,
+  diffPreparedBinding,
+  digestStoryboard,
+  fingerprintCredential,
+  isTrustedPreparedFixtures,
+  preparedBindingRegistryFor,
+  resolvePreparedFixtures,
+  resolveSchemaArtifact,
+  withPreparedFixtures
+});