@adcp/sdk 14.0.0-rc.39 → 14.0.0-rc.40

package/dist/lib/supply-path/products.d.mts

@@ -0,0 +1,41 @@
+import type { ListProductsResponse } from '../types/index.mjs';
+import type { SupplyPathState, RegistrySupplyPathResult, AuthoritativeSupplyPathResult, RegistrySupplyPathOptions, AuthoritativeSupplyPathOptions } from './types.mjs';
+export interface ProductSupplyPathAnnotation {
+    /** Weakest external owner/host/collection path. Not a whole-product authorization decision. */
+    supply_path_state?: SupplyPathState;
+    supply_path_verification?: ({
+        source: 'registry';
+        scope: 'owner_host_collection';
+        paths: RegistrySupplyPathResult[];
+    } | {
+        source: 'authoritative';
+        scope: 'product_properties';
+        paths: AuthoritativeSupplyPathResult[];
+    }) & {
+        errors: string[];
+    };
+}
+export type AnnotatedSupplyPathProduct<T extends object> = Omit<T, keyof ProductSupplyPathAnnotation> & ProductSupplyPathAnnotation;
+type AnnotatedListProductsResponse<T> = T extends unknown ? {
+    [K in keyof T]: K extends 'products' ? Array<AnnotatedSupplyPathProduct<NonNullable<ListProductsResponse['products']>[number]>> : T[K];
+} : never;
+export type ListProductsResponseWithSupplyPath = AnnotatedListProductsResponse<ListProductsResponse>;
+type ProductSupplyPathVerificationOptions = RegistrySupplyPathOptions | Omit<AuthoritativeSupplyPathOptions, 'propertySelectors'>;
+export type ProductSupplyPathOptions = ProductSupplyPathVerificationOptions & {
+    /** Maximum distinct paths in one discovery response. Default 64, max 256. */
+    maxPaths?: number;
+    /** Overall batch deadline, including all paths. Default 15 seconds, max 60 seconds. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+/**
+ * Annotate products with external-domain collection paths. Preserves actual
+ * seller products, order, and all unrelated fields. Seller-authored verification
+ * fields are replaced. No result means no evidence, never a synthetic product.
+ *
+ * Authoritative mode also proves the selected host property scope. The registry
+ * endpoint accepts only path identity. Neither mode supplies placement, country,
+ * or time context or replaces the caller's buying policy.
+ */
+export declare function annotateProductsSupplyPaths<T extends object>(products: readonly T[], agentUrl: string, options?: ProductSupplyPathOptions): Promise<Array<AnnotatedSupplyPathProduct<T>>>;
+export {};

package/dist/lib/supply-path/products.d.ts

@@ -0,0 +1,41 @@
+import type { ListProductsResponse } from '../types';
+import type { SupplyPathState, RegistrySupplyPathResult, AuthoritativeSupplyPathResult, RegistrySupplyPathOptions, AuthoritativeSupplyPathOptions } from './types';
+export interface ProductSupplyPathAnnotation {
+    /** Weakest external owner/host/collection path. Not a whole-product authorization decision. */
+    supply_path_state?: SupplyPathState;
+    supply_path_verification?: ({
+        source: 'registry';
+        scope: 'owner_host_collection';
+        paths: RegistrySupplyPathResult[];
+    } | {
+        source: 'authoritative';
+        scope: 'product_properties';
+        paths: AuthoritativeSupplyPathResult[];
+    }) & {
+        errors: string[];
+    };
+}
+export type AnnotatedSupplyPathProduct<T extends object> = Omit<T, keyof ProductSupplyPathAnnotation> & ProductSupplyPathAnnotation;
+type AnnotatedListProductsResponse<T> = T extends unknown ? {
+    [K in keyof T]: K extends 'products' ? Array<AnnotatedSupplyPathProduct<NonNullable<ListProductsResponse['products']>[number]>> : T[K];
+} : never;
+export type ListProductsResponseWithSupplyPath = AnnotatedListProductsResponse<ListProductsResponse>;
+type ProductSupplyPathVerificationOptions = RegistrySupplyPathOptions | Omit<AuthoritativeSupplyPathOptions, 'propertySelectors'>;
+export type ProductSupplyPathOptions = ProductSupplyPathVerificationOptions & {
+    /** Maximum distinct paths in one discovery response. Default 64, max 256. */
+    maxPaths?: number;
+    /** Overall batch deadline, including all paths. Default 15 seconds, max 60 seconds. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+/**
+ * Annotate products with external-domain collection paths. Preserves actual
+ * seller products, order, and all unrelated fields. Seller-authored verification
+ * fields are replaced. No result means no evidence, never a synthetic product.
+ *
+ * Authoritative mode also proves the selected host property scope. The registry
+ * endpoint accepts only path identity. Neither mode supplies placement, country,
+ * or time context or replaces the caller's buying policy.
+ */
+export declare function annotateProductsSupplyPaths<T extends object>(products: readonly T[], agentUrl: string, options?: ProductSupplyPathOptions): Promise<Array<AnnotatedSupplyPathProduct<T>>>;
+export {};

package/dist/lib/supply-path/products.js

@@ -0,0 +1,228 @@
+"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 products_exports = {};
+__export(products_exports, {
+  annotateProductsSupplyPaths: () => annotateProductsSupplyPaths
+});
+module.exports = __toCommonJS(products_exports);
+var import_node_crypto = require("node:crypto");
+var import_verify = require('./verify.js');
+var import_evaluate = require('./evaluate.js');
+var import_fetch_evidence = require('./fetch-evidence.js');
+var import_validation = require('./validation.js');
+var import_publisher_property_selector = require('../discovery/publisher-property-selector.js');
+const MAX_SELECTOR_PREPROCESS_VALUES = 32768;
+const MAX_SELECTOR_PREPROCESS_BYTES = 4 * 1024 * 1024;
+function selectorPredicateFingerprint(selector) {
+  const predicate = selector.selection_type === "by_id" ? selector.property_ids : selector.selection_type === "by_tag" ? selector.property_tags : [];
+  const hash = (0, import_node_crypto.createHash)("sha256").update(selector.selection_type);
+  let bytes = selector.selection_type.length;
+  for (const value of predicate) {
+    if (value.length > 8192) throw new Error("selector_work_limit_exceeded");
+    hash.update("\0").update(value);
+    bytes += value.length;
+  }
+  return { key: hash.digest("hex"), values: predicate.length, bytes };
+}
+async function annotateProductsSupplyPaths(products, agentUrl, options = { source: "authoritative" }) {
+  if (!(0, import_validation.agentIdentity)(agentUrl)) throw new TypeError("agentUrl must be an HTTPS URL without credentials");
+  const maxPaths = (0, import_fetch_evidence.boundedOption)(options.maxPaths, 64, 256, "maxPaths");
+  const timeoutMs = (0, import_fetch_evidence.boundedOption)(options.timeoutMs, 15e3, 6e4, "timeoutMs");
+  if (options.source === "authoritative")
+    (0, import_fetch_evidence.boundedOption)(options.maxBodyBytes, 256 * 1024, 20 * 1024 * 1024, "maxBodyBytes");
+  const deadlineAt = Date.now() + timeoutMs;
+  const checkPreprocessingBudget = () => {
+    options.signal?.throwIfAborted();
+    if (Date.now() >= deadlineAt) throw new Error("Supply-path discovery deadline exceeded");
+  };
+  const requests = /* @__PURE__ */ new Map();
+  const selections = products.map((product) => {
+    checkPreprocessingBudget();
+    const value = product;
+    const keys = [];
+    const errors = [];
+    if (value.collections === void 0) return { keys, errors };
+    if (!Array.isArray(value.collections) || !value.collections.length || !Array.isArray(value.publisher_properties) || !value.publisher_properties.length || value.collections.length > 1024 || value.publisher_properties.length > 1024 || value.collections.some((s) => (0, import_validation.record)(s) && Array.isArray(s.collection_ids) && s.collection_ids.length > 1024) || value.publisher_properties.some(
+      (s) => (0, import_validation.record)(s) && [s.publisher_domains, s.property_ids, s.property_tags].some((v) => Array.isArray(v) && v.length > 1024)
+    )) {
+      return { keys, errors: ["invalid_product_selectors"] };
+    }
+    try {
+      if (!value.publisher_properties.every(import_evaluate.hasValidPropertySelectorPredicate))
+        throw new Error("invalid_product_selector_predicate");
+      const selectorsByHost = /* @__PURE__ */ new Map();
+      let selectorExpansions = 0;
+      let selectorValues = 0;
+      let selectorBytes = 0;
+      for (const raw of value.publisher_properties) {
+        checkPreprocessingBudget();
+        const parsed = (0, import_publisher_property_selector.parsePublisherPropertySelector)(raw);
+        const domains = "publisher_domains" in parsed ? parsed.publisher_domains : [parsed.publisher_domain];
+        const single = parsed.selection_type === "all" ? { selection_type: "all", publisher_domain: domains[0] } : parsed.selection_type === "by_id" ? {
+          selection_type: "by_id",
+          publisher_domain: domains[0],
+          property_ids: parsed.property_ids
+        } : {
+          selection_type: "by_tag",
+          publisher_domain: domains[0],
+          property_tags: parsed.property_tags
+        };
+        const predicate = selectorPredicateFingerprint(single);
+        selectorExpansions += domains.length;
+        selectorValues += domains.length + predicate.values * Math.min(domains.length, maxPaths);
+        selectorBytes += domains.reduce((total, publisher) => total + publisher.length, 0) + predicate.bytes * Math.min(domains.length, maxPaths);
+        if (selectorExpansions > 4096) throw new Error("selector_work_limit_exceeded");
+        if (selectorValues > MAX_SELECTOR_PREPROCESS_VALUES || selectorBytes > MAX_SELECTOR_PREPROCESS_BYTES)
+          throw new Error("selector_work_limit_exceeded");
+        for (const publisher_domain of domains) {
+          checkPreprocessingBudget();
+          let selectors = selectorsByHost.get(publisher_domain);
+          if (!selectors) {
+            selectors = /* @__PURE__ */ new Map();
+            selectorsByHost.set(publisher_domain, selectors);
+          }
+          selectors.set(predicate.key, { ...single, publisher_domain });
+        }
+      }
+      const collectionIdsByOwner = /* @__PURE__ */ new Map();
+      for (const selector of value.collections) {
+        checkPreprocessingBudget();
+        if (!(0, import_validation.record)(selector) || !Object.keys(selector).every((key) => ["publisher_domain", "collection_ids"].includes(key)) || !(0, import_validation.domain)(selector.publisher_domain) || !(0, import_validation.strings)(selector.collection_ids))
+          throw new Error("invalid_collection_selector");
+        const owner = (0, import_validation.domain)(selector.publisher_domain);
+        let ids = collectionIdsByOwner.get(owner);
+        if (!ids) {
+          ids = /* @__PURE__ */ new Set();
+          collectionIdsByOwner.set(owner, ids);
+        }
+        for (const id of selector.collection_ids) ids.add(id);
+      }
+      for (const [owner, collectionIds] of collectionIdsByOwner) {
+        for (const [host, selectorsByKey] of selectorsByHost) {
+          if ((0, import_validation.domain)(host) === owner) continue;
+          const selectorEntries = [...selectorsByKey.entries()].sort(([left], [right]) => left.localeCompare(right));
+          const selectors = selectorEntries.map(([, selector]) => selector);
+          const selectorKey = selectorEntries.map(([key]) => key).join(":");
+          for (const id of collectionIds) {
+            checkPreprocessingBudget();
+            const request = (0, import_validation.validateSupplyPathRequest)({
+              owner_domain: owner,
+              host_domain: host,
+              agent_url: agentUrl,
+              collection_id: id
+            });
+            const key = `${JSON.stringify(request)}\0${selectorKey}`;
+            if (!requests.has(key) && requests.size >= maxPaths) {
+              if (!errors.includes("path_limit_exceeded")) errors.push("path_limit_exceeded");
+              return { keys, errors };
+            }
+            requests.set(key, { request, selectors });
+            if (!keys.includes(key)) keys.push(key);
+          }
+        }
+      }
+    } catch (cause) {
+      const code = cause instanceof Error ? cause.message : "";
+      errors.push(
+        ["invalid_product_selector_predicate", "selector_work_limit_exceeded", "invalid_collection_selector"].includes(
+          code
+        ) ? code : "invalid_product_selectors"
+      );
+    }
+    return { keys, errors };
+  });
+  const outcomes = /* @__PURE__ */ new Map();
+  const pending = [...requests.entries()];
+  let position = 0;
+  checkPreprocessingBudget();
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  if (options.signal?.aborted) onAbort();
+  const timer = setTimeout(
+    () => controller.abort(new Error("Supply-path discovery deadline exceeded")),
+    Math.max(1, deadlineAt - Date.now())
+  );
+  let session;
+  let onDeadline = () => {
+  };
+  try {
+    session = options.source === "authoritative" ? new import_fetch_evidence.SupplyPathEvidenceSession({
+      ...options,
+      signal: controller.signal,
+      timeoutMs: Math.max(1, deadlineAt - Date.now())
+    }) : void 0;
+    controller.signal.throwIfAborted();
+    const aborted = new Promise((_, reject) => {
+      onDeadline = () => reject(controller.signal.reason);
+      controller.signal.addEventListener("abort", onDeadline, { once: true });
+    });
+    await Promise.race([
+      aborted,
+      Promise.all(
+        Array.from({ length: Math.min(4, pending.length) }, async () => {
+          while (position < pending.length) {
+            controller.signal.throwIfAborted();
+            const [key, { request, selectors }] = pending[position++];
+            outcomes.set(
+              key,
+              options.source === "authoritative" ? await (0, import_verify.verifyAuthoritativeSupplyPath)(request, { ...options, propertySelectors: selectors }, session) : await (0, import_verify.verifySupplyPath)(request, options)
+            );
+          }
+        })
+      )
+    ]);
+  } finally {
+    session?.close();
+    controller.abort(new Error("Supply-path annotation batch closed"));
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+    controller.signal.removeEventListener("abort", onDeadline);
+  }
+  return products.map((product, index) => {
+    const {
+      supply_path_state: _state,
+      supply_path_verification: _verification,
+      ...rest
+    } = product;
+    void _state;
+    void _verification;
+    const { keys, errors } = selections[index];
+    if (!keys.length && !errors.length) return rest;
+    const paths = keys.map((key) => outcomes.get(key));
+    const state = errors.length ? "unverified" : paths.reduce(
+      (least, result) => import_evaluate.SUPPLY_PATH_STATES.indexOf(result.state) < import_evaluate.SUPPLY_PATH_STATES.indexOf(least) ? result.state : least,
+      "verified_owner_sold"
+    );
+    return {
+      ...rest,
+      supply_path_state: state,
+      supply_path_verification: {
+        source: options.source,
+        scope: options.source === "authoritative" ? "product_properties" : "owner_host_collection",
+        paths,
+        errors
+      }
+    };
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  annotateProductsSupplyPaths
+});

package/dist/lib/supply-path/products.mjs

@@ -0,0 +1,204 @@
+import { createHash } from "node:crypto";
+import { verifySupplyPath, verifyAuthoritativeSupplyPath } from "./verify.mjs";
+import { SUPPLY_PATH_STATES, hasValidPropertySelectorPredicate } from "./evaluate.mjs";
+import { boundedOption, SupplyPathEvidenceSession } from "./fetch-evidence.mjs";
+import { agentIdentity, domain, record, strings, validateSupplyPathRequest } from "./validation.mjs";
+import { parsePublisherPropertySelector } from "../discovery/publisher-property-selector.mjs";
+const MAX_SELECTOR_PREPROCESS_VALUES = 32768;
+const MAX_SELECTOR_PREPROCESS_BYTES = 4 * 1024 * 1024;
+function selectorPredicateFingerprint(selector) {
+  const predicate = selector.selection_type === "by_id" ? selector.property_ids : selector.selection_type === "by_tag" ? selector.property_tags : [];
+  const hash = createHash("sha256").update(selector.selection_type);
+  let bytes = selector.selection_type.length;
+  for (const value of predicate) {
+    if (value.length > 8192) throw new Error("selector_work_limit_exceeded");
+    hash.update("\0").update(value);
+    bytes += value.length;
+  }
+  return { key: hash.digest("hex"), values: predicate.length, bytes };
+}
+async function annotateProductsSupplyPaths(products, agentUrl, options = { source: "authoritative" }) {
+  if (!agentIdentity(agentUrl)) throw new TypeError("agentUrl must be an HTTPS URL without credentials");
+  const maxPaths = boundedOption(options.maxPaths, 64, 256, "maxPaths");
+  const timeoutMs = boundedOption(options.timeoutMs, 15e3, 6e4, "timeoutMs");
+  if (options.source === "authoritative")
+    boundedOption(options.maxBodyBytes, 256 * 1024, 20 * 1024 * 1024, "maxBodyBytes");
+  const deadlineAt = Date.now() + timeoutMs;
+  const checkPreprocessingBudget = () => {
+    options.signal?.throwIfAborted();
+    if (Date.now() >= deadlineAt) throw new Error("Supply-path discovery deadline exceeded");
+  };
+  const requests = /* @__PURE__ */ new Map();
+  const selections = products.map((product) => {
+    checkPreprocessingBudget();
+    const value = product;
+    const keys = [];
+    const errors = [];
+    if (value.collections === void 0) return { keys, errors };
+    if (!Array.isArray(value.collections) || !value.collections.length || !Array.isArray(value.publisher_properties) || !value.publisher_properties.length || value.collections.length > 1024 || value.publisher_properties.length > 1024 || value.collections.some((s) => record(s) && Array.isArray(s.collection_ids) && s.collection_ids.length > 1024) || value.publisher_properties.some(
+      (s) => record(s) && [s.publisher_domains, s.property_ids, s.property_tags].some((v) => Array.isArray(v) && v.length > 1024)
+    )) {
+      return { keys, errors: ["invalid_product_selectors"] };
+    }
+    try {
+      if (!value.publisher_properties.every(hasValidPropertySelectorPredicate))
+        throw new Error("invalid_product_selector_predicate");
+      const selectorsByHost = /* @__PURE__ */ new Map();
+      let selectorExpansions = 0;
+      let selectorValues = 0;
+      let selectorBytes = 0;
+      for (const raw of value.publisher_properties) {
+        checkPreprocessingBudget();
+        const parsed = parsePublisherPropertySelector(raw);
+        const domains = "publisher_domains" in parsed ? parsed.publisher_domains : [parsed.publisher_domain];
+        const single = parsed.selection_type === "all" ? { selection_type: "all", publisher_domain: domains[0] } : parsed.selection_type === "by_id" ? {
+          selection_type: "by_id",
+          publisher_domain: domains[0],
+          property_ids: parsed.property_ids
+        } : {
+          selection_type: "by_tag",
+          publisher_domain: domains[0],
+          property_tags: parsed.property_tags
+        };
+        const predicate = selectorPredicateFingerprint(single);
+        selectorExpansions += domains.length;
+        selectorValues += domains.length + predicate.values * Math.min(domains.length, maxPaths);
+        selectorBytes += domains.reduce((total, publisher) => total + publisher.length, 0) + predicate.bytes * Math.min(domains.length, maxPaths);
+        if (selectorExpansions > 4096) throw new Error("selector_work_limit_exceeded");
+        if (selectorValues > MAX_SELECTOR_PREPROCESS_VALUES || selectorBytes > MAX_SELECTOR_PREPROCESS_BYTES)
+          throw new Error("selector_work_limit_exceeded");
+        for (const publisher_domain of domains) {
+          checkPreprocessingBudget();
+          let selectors = selectorsByHost.get(publisher_domain);
+          if (!selectors) {
+            selectors = /* @__PURE__ */ new Map();
+            selectorsByHost.set(publisher_domain, selectors);
+          }
+          selectors.set(predicate.key, { ...single, publisher_domain });
+        }
+      }
+      const collectionIdsByOwner = /* @__PURE__ */ new Map();
+      for (const selector of value.collections) {
+        checkPreprocessingBudget();
+        if (!record(selector) || !Object.keys(selector).every((key) => ["publisher_domain", "collection_ids"].includes(key)) || !domain(selector.publisher_domain) || !strings(selector.collection_ids))
+          throw new Error("invalid_collection_selector");
+        const owner = domain(selector.publisher_domain);
+        let ids = collectionIdsByOwner.get(owner);
+        if (!ids) {
+          ids = /* @__PURE__ */ new Set();
+          collectionIdsByOwner.set(owner, ids);
+        }
+        for (const id of selector.collection_ids) ids.add(id);
+      }
+      for (const [owner, collectionIds] of collectionIdsByOwner) {
+        for (const [host, selectorsByKey] of selectorsByHost) {
+          if (domain(host) === owner) continue;
+          const selectorEntries = [...selectorsByKey.entries()].sort(([left], [right]) => left.localeCompare(right));
+          const selectors = selectorEntries.map(([, selector]) => selector);
+          const selectorKey = selectorEntries.map(([key]) => key).join(":");
+          for (const id of collectionIds) {
+            checkPreprocessingBudget();
+            const request = validateSupplyPathRequest({
+              owner_domain: owner,
+              host_domain: host,
+              agent_url: agentUrl,
+              collection_id: id
+            });
+            const key = `${JSON.stringify(request)}\0${selectorKey}`;
+            if (!requests.has(key) && requests.size >= maxPaths) {
+              if (!errors.includes("path_limit_exceeded")) errors.push("path_limit_exceeded");
+              return { keys, errors };
+            }
+            requests.set(key, { request, selectors });
+            if (!keys.includes(key)) keys.push(key);
+          }
+        }
+      }
+    } catch (cause) {
+      const code = cause instanceof Error ? cause.message : "";
+      errors.push(
+        ["invalid_product_selector_predicate", "selector_work_limit_exceeded", "invalid_collection_selector"].includes(
+          code
+        ) ? code : "invalid_product_selectors"
+      );
+    }
+    return { keys, errors };
+  });
+  const outcomes = /* @__PURE__ */ new Map();
+  const pending = [...requests.entries()];
+  let position = 0;
+  checkPreprocessingBudget();
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  if (options.signal?.aborted) onAbort();
+  const timer = setTimeout(
+    () => controller.abort(new Error("Supply-path discovery deadline exceeded")),
+    Math.max(1, deadlineAt - Date.now())
+  );
+  let session;
+  let onDeadline = () => {
+  };
+  try {
+    session = options.source === "authoritative" ? new SupplyPathEvidenceSession({
+      ...options,
+      signal: controller.signal,
+      timeoutMs: Math.max(1, deadlineAt - Date.now())
+    }) : void 0;
+    controller.signal.throwIfAborted();
+    const aborted = new Promise((_, reject) => {
+      onDeadline = () => reject(controller.signal.reason);
+      controller.signal.addEventListener("abort", onDeadline, { once: true });
+    });
+    await Promise.race([
+      aborted,
+      Promise.all(
+        Array.from({ length: Math.min(4, pending.length) }, async () => {
+          while (position < pending.length) {
+            controller.signal.throwIfAborted();
+            const [key, { request, selectors }] = pending[position++];
+            outcomes.set(
+              key,
+              options.source === "authoritative" ? await verifyAuthoritativeSupplyPath(request, { ...options, propertySelectors: selectors }, session) : await verifySupplyPath(request, options)
+            );
+          }
+        })
+      )
+    ]);
+  } finally {
+    session?.close();
+    controller.abort(new Error("Supply-path annotation batch closed"));
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+    controller.signal.removeEventListener("abort", onDeadline);
+  }
+  return products.map((product, index) => {
+    const {
+      supply_path_state: _state,
+      supply_path_verification: _verification,
+      ...rest
+    } = product;
+    void _state;
+    void _verification;
+    const { keys, errors } = selections[index];
+    if (!keys.length && !errors.length) return rest;
+    const paths = keys.map((key) => outcomes.get(key));
+    const state = errors.length ? "unverified" : paths.reduce(
+      (least, result) => SUPPLY_PATH_STATES.indexOf(result.state) < SUPPLY_PATH_STATES.indexOf(least) ? result.state : least,
+      "verified_owner_sold"
+    );
+    return {
+      ...rest,
+      supply_path_state: state,
+      supply_path_verification: {
+        source: options.source,
+        scope: options.source === "authoritative" ? "product_properties" : "owner_host_collection",
+        paths,
+        errors
+      }
+    };
+  });
+}
+export {
+  annotateProductsSupplyPaths
+};

package/dist/lib/supply-path/revocations.d.mts

@@ -0,0 +1,55 @@
+export interface SupplyPathRevocation {
+    publisher_domain: string;
+    /** Publisher timestamp, or `unspecified` for a legacy domain-only declaration. Never use this as the hold expiry. */
+    revoked_at: string;
+}
+/**
+ * Atomic, authority-scoped seven-day revocation hold. Durable implementations
+ * must key by authority and publisher_domain, preserving first observation
+ * across changed publisher timestamps, and reject on storage failure instead of returning an empty set.
+ * Capture tenant identity from trusted application context in the store instance;
+ * include that tenant in every key and transaction. Publisher evidence must never select a tenant.
+ * Persist `revoked_at` as publisher metadata that may be the `unspecified` sentinel;
+ * maintain the seven-day first-observation expiry in a separate timestamp column.
+ */
+export interface SupplyPathRevocationStore {
+    observe(authority: string, revoked: readonly SupplyPathRevocation[]): Promise<readonly SupplyPathRevocation[]>;
+}
+/** Process-local default. Use a durable shared store across workers/restarts. */
+export declare class InMemorySupplyPathRevocationStore implements SupplyPathRevocationStore {
+    private readonly admission;
+    private readonly entries;
+    observe(authority: string, revoked: readonly SupplyPathRevocation[]): Promise<readonly SupplyPathRevocation[]>;
+}
+export declare const defaultSupplyPathRevocations: InMemorySupplyPathRevocationStore;
+export declare function parseRevocations(value: unknown): SupplyPathRevocation[] | null;
+/**
+ * Trust-on-first-successful-use storage. Capture the authenticated tenant in the
+ * store instance and namespace every pin by that tenant. Neither a read nor a
+ * failed fetch may create a pin. Storage failures must reject.
+ * Keys are the exact serialized HTTPS URL supplied by the verifier, with no
+ * fragment delimiter. Preserve query/path spelling; do not merge distinct URLs.
+ * A deadline may abandon an observe promise while its transaction completes.
+ * Such a commit still represents a validated manifest; retries must be idempotent.
+ */
+export interface SupplyPathAuthorityStore {
+    /** Read-only precheck: true if absent or equal; false for a different existing pin. */
+    check(publisherDomain: string, location: string): Promise<boolean>;
+    /**
+     * After successful manifest validation, atomically insert if absent or compare
+     * with the existing pin. Return false on mismatch, including a concurrent change
+     * since check(). A successful precheck is never a reservation or authorization.
+     */
+    observe(publisherDomain: string, location: string): Promise<boolean>;
+}
+/** Process-local pointer integrity. Use durable shared storage across workers/restarts. */
+export declare class InMemorySupplyPathAuthorityStore implements SupplyPathAuthorityStore {
+    private readonly admission;
+    private readonly locations;
+    check(publisherDomain: string, location: string): Promise<boolean>;
+    observe(publisherDomain: string, location: string): Promise<boolean>;
+    /** Call only after independently confirming a publisher's migration. Never call from an automatic retry. */
+    approveChange(publisherDomain: string, location: string): void;
+    private assertBoundedLocation;
+}
+export declare const defaultSupplyPathAuthorities: InMemorySupplyPathAuthorityStore;

package/dist/lib/supply-path/revocations.d.ts

@@ -0,0 +1,55 @@
+export interface SupplyPathRevocation {
+    publisher_domain: string;
+    /** Publisher timestamp, or `unspecified` for a legacy domain-only declaration. Never use this as the hold expiry. */
+    revoked_at: string;
+}
+/**
+ * Atomic, authority-scoped seven-day revocation hold. Durable implementations
+ * must key by authority and publisher_domain, preserving first observation
+ * across changed publisher timestamps, and reject on storage failure instead of returning an empty set.
+ * Capture tenant identity from trusted application context in the store instance;
+ * include that tenant in every key and transaction. Publisher evidence must never select a tenant.
+ * Persist `revoked_at` as publisher metadata that may be the `unspecified` sentinel;
+ * maintain the seven-day first-observation expiry in a separate timestamp column.
+ */
+export interface SupplyPathRevocationStore {
+    observe(authority: string, revoked: readonly SupplyPathRevocation[]): Promise<readonly SupplyPathRevocation[]>;
+}
+/** Process-local default. Use a durable shared store across workers/restarts. */
+export declare class InMemorySupplyPathRevocationStore implements SupplyPathRevocationStore {
+    private readonly admission;
+    private readonly entries;
+    observe(authority: string, revoked: readonly SupplyPathRevocation[]): Promise<readonly SupplyPathRevocation[]>;
+}
+export declare const defaultSupplyPathRevocations: InMemorySupplyPathRevocationStore;
+export declare function parseRevocations(value: unknown): SupplyPathRevocation[] | null;
+/**
+ * Trust-on-first-successful-use storage. Capture the authenticated tenant in the
+ * store instance and namespace every pin by that tenant. Neither a read nor a
+ * failed fetch may create a pin. Storage failures must reject.
+ * Keys are the exact serialized HTTPS URL supplied by the verifier, with no
+ * fragment delimiter. Preserve query/path spelling; do not merge distinct URLs.
+ * A deadline may abandon an observe promise while its transaction completes.
+ * Such a commit still represents a validated manifest; retries must be idempotent.
+ */
+export interface SupplyPathAuthorityStore {
+    /** Read-only precheck: true if absent or equal; false for a different existing pin. */
+    check(publisherDomain: string, location: string): Promise<boolean>;
+    /**
+     * After successful manifest validation, atomically insert if absent or compare
+     * with the existing pin. Return false on mismatch, including a concurrent change
+     * since check(). A successful precheck is never a reservation or authorization.
+     */
+    observe(publisherDomain: string, location: string): Promise<boolean>;
+}
+/** Process-local pointer integrity. Use durable shared storage across workers/restarts. */
+export declare class InMemorySupplyPathAuthorityStore implements SupplyPathAuthorityStore {
+    private readonly admission;
+    private readonly locations;
+    check(publisherDomain: string, location: string): Promise<boolean>;
+    observe(publisherDomain: string, location: string): Promise<boolean>;
+    /** Call only after independently confirming a publisher's migration. Never call from an automatic retry. */
+    approveChange(publisherDomain: string, location: string): void;
+    private assertBoundedLocation;
+}
+export declare const defaultSupplyPathAuthorities: InMemorySupplyPathAuthorityStore;