@agentcash/discovery 0.1.0

package/dist/index.js

@@ -0,0 +1,1415 @@
+// src/flags.ts
+var LEGACY_SUNSET_DATE = "2026-03-24";
+var DEFAULT_COMPAT_MODE = "on";
+var STRICT_ESCALATION_CODES = [
+  "LEGACY_WELL_KNOWN_USED",
+  "LEGACY_DNS_USED",
+  "LEGACY_DNS_PLAIN_URL",
+  "LEGACY_MISSING_METHOD",
+  "LEGACY_INSTRUCTIONS_USED",
+  "LEGACY_OWNERSHIP_PROOFS_USED",
+  "INTEROP_MPP_USED"
+];
+
+// src/core/constants.ts
+var OPENAPI_PATH_CANDIDATES = ["/openapi.json", "/.well-known/openapi.json"];
+var WELL_KNOWN_MPP_PATH = "/.well-known/mpp";
+var LLMS_TOKEN_WARNING_THRESHOLD = 2500;
+var HTTP_METHODS = /* @__PURE__ */ new Set([
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "HEAD",
+  "OPTIONS",
+  "TRACE"
+]);
+var DEFAULT_PROBE_METHODS = ["GET", "POST"];
+var DEFAULT_MISSING_METHOD = "POST";
+
+// src/core/url.ts
+function normalizeOrigin(target) {
+  const trimmed = target.trim();
+  const withProtocol = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+  const url = new URL(withProtocol);
+  url.pathname = "";
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+function normalizePath(pathname) {
+  const parsed = pathname.trim();
+  if (parsed.length === 0 || parsed === "/") return "/";
+  const pathOnly = parsed.split("?")[0]?.split("#")[0] ?? "/";
+  const prefixed = pathOnly.startsWith("/") ? pathOnly : `/${pathOnly}`;
+  const normalized = prefixed.replace(/\/+/g, "/");
+  return normalized !== "/" ? normalized.replace(/\/$/, "") : "/";
+}
+function toResourceKey(origin, method, path) {
+  return `${origin} ${method} ${normalizePath(path)}`;
+}
+function parseMethod(value) {
+  if (!value) return void 0;
+  const upper = value.toUpperCase();
+  return HTTP_METHODS.has(upper) ? upper : void 0;
+}
+function toAbsoluteUrl(origin, value) {
+  try {
+    if (/^https?:\/\//i.test(value)) return new URL(value);
+    return new URL(normalizePath(value), `${origin}/`);
+  } catch {
+    return null;
+  }
+}
+
+// src/core/warnings.ts
+function warning(code, severity, message, options) {
+  return {
+    code,
+    severity,
+    message,
+    ...options?.hint ? { hint: options.hint } : {},
+    ...options?.stage ? { stage: options.stage } : {},
+    ...options?.resourceKey ? { resourceKey: options.resourceKey } : {}
+  };
+}
+function applyStrictEscalation(warnings, strict) {
+  if (!strict) return warnings;
+  return warnings.map((entry) => {
+    if (!STRICT_ESCALATION_CODES.includes(entry.code)) {
+      return entry;
+    }
+    if (entry.severity === "error") return entry;
+    return {
+      ...entry,
+      severity: "error",
+      message: `${entry.message} (strict mode escalated)`
+    };
+  });
+}
+function dedupeWarnings(warnings) {
+  const seen = /* @__PURE__ */ new Set();
+  const output = [];
+  for (const item of warnings) {
+    const key = `${item.code}|${item.severity}|${item.stage ?? ""}|${item.resourceKey ?? ""}|${item.message}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    output.push(item);
+  }
+  return output;
+}
+
+// src/core/normalize.ts
+function createResource(input, confidence, trustTier) {
+  const normalizedOrigin = normalizeOrigin(input.origin);
+  const normalizedPath = normalizePath(input.path);
+  return {
+    resourceKey: toResourceKey(normalizedOrigin, input.method, normalizedPath),
+    origin: normalizedOrigin,
+    method: input.method,
+    path: normalizedPath,
+    source: input.source,
+    verified: false,
+    ...input.protocolHints?.length ? { protocolHints: [...new Set(input.protocolHints)] } : {},
+    ...input.priceHint ? { priceHint: input.priceHint } : {},
+    ...input.pricing ? { pricing: input.pricing } : {},
+    ...input.authHint ? { authHint: input.authHint } : {},
+    ...input.summary ? { summary: input.summary } : {},
+    confidence,
+    trustTier,
+    ...input.links ? { links: input.links } : {}
+  };
+}
+
+// src/compat/legacy-x402scan/wellKnown.ts
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseLegacyResourceEntry(entry) {
+  const trimmed = entry.trim();
+  if (!trimmed) return null;
+  const parts = trimmed.split(/\s+/);
+  if (parts.length >= 2) {
+    const maybeMethod = parseMethod(parts[0]);
+    if (maybeMethod) {
+      const target = parts.slice(1).join(" ");
+      return { method: maybeMethod, target };
+    }
+  }
+  if (trimmed.startsWith("/") || /^https?:\/\//i.test(trimmed)) {
+    return { target: trimmed };
+  }
+  return null;
+}
+function parseWellKnownPayload(payload, origin, sourceUrl) {
+  const warnings = [
+    warning(
+      "LEGACY_WELL_KNOWN_USED",
+      "warn",
+      "Using legacy /.well-known/x402 compatibility path. Migrate to OpenAPI-first.",
+      {
+        stage: "well-known/x402"
+      }
+    )
+  ];
+  if (!isRecord(payload)) {
+    warnings.push(
+      warning("PARSE_FAILED", "error", "Legacy well-known payload is not an object", {
+        stage: "well-known/x402"
+      })
+    );
+    return { resources: [], warnings, raw: payload };
+  }
+  const resourcesRaw = Array.isArray(payload.resources) ? payload.resources.filter((entry) => typeof entry === "string") : [];
+  if (resourcesRaw.length === 0) {
+    warnings.push(
+      warning("STAGE_EMPTY", "warn", "Legacy well-known has no valid resources array", {
+        stage: "well-known/x402"
+      })
+    );
+  }
+  const instructions = typeof payload.instructions === "string" ? payload.instructions : void 0;
+  const ownershipProofs = Array.isArray(payload.ownershipProofs) ? payload.ownershipProofs.filter((entry) => typeof entry === "string") : [];
+  if (instructions) {
+    warnings.push(
+      warning(
+        "LEGACY_INSTRUCTIONS_USED",
+        "warn",
+        "Using /.well-known/x402.instructions as compatibility guidance fallback. Prefer llms.txt.",
+        {
+          stage: "well-known/x402",
+          hint: "Move guidance to llms.txt and reference via x-agentcash-guidance.llmsTxtUrl."
+        }
+      )
+    );
+  }
+  if (ownershipProofs.length > 0) {
+    warnings.push(
+      warning(
+        "LEGACY_OWNERSHIP_PROOFS_USED",
+        "warn",
+        "Using /.well-known/x402.ownershipProofs compatibility field. Prefer OpenAPI provenance extension.",
+        {
+          stage: "well-known/x402",
+          hint: "Move ownership proofs to x-agentcash-provenance.ownershipProofs in OpenAPI."
+        }
+      )
+    );
+  }
+  const resources = [];
+  for (const rawEntry of resourcesRaw) {
+    const parsed = parseLegacyResourceEntry(rawEntry);
+    if (!parsed) {
+      warnings.push(
+        warning("PARSE_FAILED", "warn", `Invalid legacy resource entry: ${rawEntry}`, {
+          stage: "well-known/x402"
+        })
+      );
+      continue;
+    }
+    const absolute = toAbsoluteUrl(origin, parsed.target);
+    if (!absolute) {
+      warnings.push(
+        warning("PARSE_FAILED", "warn", `Invalid legacy resource URL: ${rawEntry}`, {
+          stage: "well-known/x402"
+        })
+      );
+      continue;
+    }
+    const method = parsed.method ?? DEFAULT_MISSING_METHOD;
+    if (!parsed.method) {
+      warnings.push(
+        warning(
+          "LEGACY_MISSING_METHOD",
+          "warn",
+          `Legacy resource '${rawEntry}' missing method. Defaulting to ${DEFAULT_MISSING_METHOD}.`,
+          {
+            stage: "well-known/x402"
+          }
+        )
+      );
+    }
+    const path = normalizePath(absolute.pathname);
+    resources.push(
+      createResource(
+        {
+          origin: absolute.origin,
+          method,
+          path,
+          source: "well-known/x402",
+          summary: `${method} ${path}`,
+          authHint: "paid",
+          protocolHints: ["x402"],
+          links: {
+            wellKnownUrl: sourceUrl,
+            discoveryUrl: sourceUrl
+          }
+        },
+        0.65,
+        ownershipProofs.length > 0 ? "ownership_verified" : "origin_hosted"
+      )
+    );
+  }
+  return {
+    resources,
+    warnings,
+    raw: payload
+  };
+}
+async function runWellKnownX402Stage(options) {
+  const stageUrl = options.url ?? `${options.origin}/.well-known/x402`;
+  try {
+    const response = await options.fetcher(stageUrl, {
+      method: "GET",
+      headers: { Accept: "application/json", ...options.headers },
+      signal: options.signal
+    });
+    if (!response.ok) {
+      if (response.status === 404) {
+        return {
+          stage: "well-known/x402",
+          valid: false,
+          resources: [],
+          warnings: [],
+          links: { wellKnownUrl: stageUrl }
+        };
+      }
+      return {
+        stage: "well-known/x402",
+        valid: false,
+        resources: [],
+        warnings: [
+          warning("FETCH_FAILED", "warn", `Legacy well-known fetch failed (${response.status})`, {
+            stage: "well-known/x402"
+          })
+        ],
+        links: { wellKnownUrl: stageUrl }
+      };
+    }
+    const payload = await response.json();
+    const parsed = parseWellKnownPayload(payload, options.origin, stageUrl);
+    return {
+      stage: "well-known/x402",
+      valid: parsed.resources.length > 0,
+      resources: parsed.resources,
+      warnings: parsed.warnings,
+      links: { wellKnownUrl: stageUrl },
+      ...options.includeRaw ? { raw: parsed.raw } : {}
+    };
+  } catch (error) {
+    return {
+      stage: "well-known/x402",
+      valid: false,
+      resources: [],
+      warnings: [
+        warning(
+          "FETCH_FAILED",
+          "warn",
+          `Legacy well-known fetch exception: ${error instanceof Error ? error.message : String(error)}`,
+          {
+            stage: "well-known/x402"
+          }
+        )
+      ],
+      links: { wellKnownUrl: stageUrl }
+    };
+  }
+}
+
+// src/compat/legacy-x402scan/dns.ts
+function parseDnsRecord(record) {
+  const trimmed = record.trim();
+  if (!trimmed) return null;
+  if (/^https?:\/\//i.test(trimmed)) {
+    return { url: trimmed, legacyPlainUrl: true };
+  }
+  const parts = trimmed.split(";").map((entry) => entry.trim()).filter(Boolean);
+  const keyValues = /* @__PURE__ */ new Map();
+  for (const part of parts) {
+    const separator = part.indexOf("=");
+    if (separator <= 0) continue;
+    const key = part.slice(0, separator).trim().toLowerCase();
+    const value = part.slice(separator + 1).trim();
+    if (key && value) keyValues.set(key, value);
+  }
+  if (keyValues.get("v") !== "x4021") return null;
+  const url = keyValues.get("url");
+  if (!url || !/^https?:\/\//i.test(url)) return null;
+  return { url, legacyPlainUrl: false };
+}
+async function runDnsStage(options) {
+  if (!options.txtResolver) {
+    return {
+      stage: "dns/_x402",
+      valid: false,
+      resources: [],
+      warnings: []
+    };
+  }
+  const origin = normalizeOrigin(options.origin);
+  const hostname = new URL(origin).hostname;
+  const fqdn = `_x402.${hostname}`;
+  let records;
+  try {
+    records = await options.txtResolver(fqdn);
+  } catch (error) {
+    return {
+      stage: "dns/_x402",
+      valid: false,
+      resources: [],
+      warnings: [
+        warning(
+          "FETCH_FAILED",
+          "warn",
+          `DNS TXT lookup failed for ${fqdn}: ${error instanceof Error ? error.message : String(error)}`,
+          { stage: "dns/_x402" }
+        )
+      ]
+    };
+  }
+  if (records.length === 0) {
+    return {
+      stage: "dns/_x402",
+      valid: false,
+      resources: [],
+      warnings: []
+    };
+  }
+  const warnings = [
+    warning(
+      "LEGACY_DNS_USED",
+      "warn",
+      "Using DNS _x402 compatibility path. Migrate to OpenAPI-first discovery.",
+      {
+        stage: "dns/_x402"
+      }
+    )
+  ];
+  const urls = [];
+  for (const record of records) {
+    const parsed = parseDnsRecord(record);
+    if (!parsed) {
+      warnings.push(
+        warning("PARSE_FAILED", "warn", `Invalid DNS _x402 TXT record: ${record}`, {
+          stage: "dns/_x402"
+        })
+      );
+      continue;
+    }
+    urls.push(parsed.url);
+    if (parsed.legacyPlainUrl) {
+      warnings.push(
+        warning("LEGACY_DNS_PLAIN_URL", "warn", `Legacy plain URL TXT format used: ${record}`, {
+          stage: "dns/_x402",
+          hint: "Use v=x4021;url=<https-url> format."
+        })
+      );
+    }
+  }
+  if (urls.length === 0) {
+    return {
+      stage: "dns/_x402",
+      valid: false,
+      resources: [],
+      warnings,
+      ...options.includeRaw ? { raw: { dnsRecords: records } } : {}
+    };
+  }
+  const mergedWarnings = [...warnings];
+  const mergedResources = [];
+  const rawDocuments = [];
+  for (const url of urls) {
+    const stageResult = await runWellKnownX402Stage({
+      origin,
+      url,
+      fetcher: options.fetcher,
+      headers: options.headers,
+      signal: options.signal,
+      includeRaw: options.includeRaw
+    });
+    mergedResources.push(...stageResult.resources);
+    mergedWarnings.push(...stageResult.warnings);
+    if (options.includeRaw && stageResult.raw !== void 0) {
+      rawDocuments.push({ url, document: stageResult.raw });
+    }
+  }
+  const deduped = /* @__PURE__ */ new Map();
+  for (const resource of mergedResources) {
+    if (!deduped.has(resource.resourceKey)) {
+      deduped.set(resource.resourceKey, {
+        ...resource,
+        source: "dns/_x402",
+        links: {
+          ...resource.links,
+          discoveryUrl: resource.links?.discoveryUrl
+        }
+      });
+    }
+  }
+  return {
+    stage: "dns/_x402",
+    valid: deduped.size > 0,
+    resources: [...deduped.values()],
+    warnings: mergedWarnings,
+    ...options.includeRaw ? { raw: { dnsRecords: records, documents: rawDocuments } } : {}
+  };
+}
+
+// src/compat/interop-mpp/wellKnownMpp.ts
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+async function runInteropMppStage(options) {
+  const url = `${options.origin}${WELL_KNOWN_MPP_PATH}`;
+  try {
+    const response = await options.fetcher(url, {
+      method: "GET",
+      headers: { Accept: "application/json", ...options.headers },
+      signal: options.signal
+    });
+    if (!response.ok) {
+      return {
+        stage: "interop/mpp",
+        valid: false,
+        resources: [],
+        warnings: []
+      };
+    }
+    const payload = await response.json();
+    if (!isRecord2(payload)) {
+      return {
+        stage: "interop/mpp",
+        valid: false,
+        resources: [],
+        warnings: [
+          warning("PARSE_FAILED", "warn", "Interop /.well-known/mpp payload is not an object", {
+            stage: "interop/mpp"
+          })
+        ],
+        ...options.includeRaw ? { raw: payload } : {}
+      };
+    }
+    const warnings = [
+      warning(
+        "INTEROP_MPP_USED",
+        "info",
+        "Using /.well-known/mpp interop adapter. This is additive and non-canonical.",
+        {
+          stage: "interop/mpp",
+          hint: "Use for registry indexing only, not canonical runtime routing."
+        }
+      )
+    ];
+    const resources = [];
+    const fromStringResources = Array.isArray(payload.resources) ? payload.resources.filter((entry) => typeof entry === "string") : [];
+    for (const entry of fromStringResources) {
+      const parts = entry.trim().split(/\s+/);
+      let method = parseMethod(parts[0]);
+      let path = parts.join(" ");
+      if (method) {
+        path = parts.slice(1).join(" ");
+      } else {
+        method = "POST";
+      }
+      const normalizedPath = normalizePath(path);
+      resources.push(
+        createResource(
+          {
+            origin: options.origin,
+            method,
+            path: normalizedPath,
+            source: "interop/mpp",
+            summary: `${method} ${normalizedPath}`,
+            authHint: "paid",
+            protocolHints: ["mpp"],
+            links: { discoveryUrl: url }
+          },
+          0.45,
+          "unverified"
+        )
+      );
+    }
+    const fromServiceObjects = Array.isArray(payload.services) ? payload.services.filter((entry) => isRecord2(entry)) : [];
+    for (const service of fromServiceObjects) {
+      const path = typeof service.path === "string" ? service.path : void 0;
+      const method = parseMethod(typeof service.method === "string" ? service.method : void 0) ?? "POST";
+      if (!path) continue;
+      const normalizedPath = normalizePath(path);
+      resources.push(
+        createResource(
+          {
+            origin: options.origin,
+            method,
+            path: normalizedPath,
+            source: "interop/mpp",
+            summary: typeof service.summary === "string" ? service.summary : `${method} ${normalizedPath}`,
+            authHint: "paid",
+            protocolHints: ["mpp"],
+            links: { discoveryUrl: url }
+          },
+          0.45,
+          "unverified"
+        )
+      );
+    }
+    const deduped = /* @__PURE__ */ new Map();
+    for (const resource of resources) {
+      if (!deduped.has(resource.resourceKey)) deduped.set(resource.resourceKey, resource);
+    }
+    return {
+      stage: "interop/mpp",
+      valid: deduped.size > 0,
+      resources: [...deduped.values()],
+      warnings,
+      ...options.includeRaw ? { raw: payload } : {}
+    };
+  } catch (error) {
+    return {
+      stage: "interop/mpp",
+      valid: false,
+      resources: [],
+      warnings: [
+        warning(
+          "FETCH_FAILED",
+          "warn",
+          `Interop /.well-known/mpp fetch failed: ${error instanceof Error ? error.message : String(error)}`,
+          {
+            stage: "interop/mpp"
+          }
+        )
+      ]
+    };
+  }
+}
+
+// src/core/token.ts
+function estimateTokenCount(text) {
+  return Math.ceil(text.length / 4);
+}
+
+// src/core/openapi.ts
+function isRecord3(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function parsePriceValue(value) {
+  if (typeof value === "string" && value.length > 0) return value;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return void 0;
+}
+function require402Response(operation) {
+  const responses = operation.responses;
+  if (!isRecord3(responses)) return false;
+  return Boolean(responses["402"]);
+}
+function parseProtocols(paymentInfo) {
+  const protocols = paymentInfo.protocols;
+  if (!Array.isArray(protocols)) return [];
+  return protocols.filter(
+    (entry) => typeof entry === "string" && entry.length > 0
+  );
+}
+function parseAuthMode(operation) {
+  const auth = operation["x-agentcash-auth"];
+  if (!isRecord3(auth)) return void 0;
+  const mode = auth.mode;
+  if (mode === "paid" || mode === "siwx" || mode === "apiKey" || mode === "unprotected") {
+    return mode;
+  }
+  return void 0;
+}
+async function runOpenApiStage(options) {
+  const warnings = [];
+  const resources = [];
+  let fetchedUrl;
+  let document;
+  for (const path of OPENAPI_PATH_CANDIDATES) {
+    const url = `${options.origin}${path}`;
+    try {
+      const response = await options.fetcher(url, {
+        method: "GET",
+        headers: { Accept: "application/json", ...options.headers },
+        signal: options.signal
+      });
+      if (!response.ok) {
+        if (response.status !== 404) {
+          warnings.push(
+            warning("FETCH_FAILED", "warn", `OpenAPI fetch failed (${response.status}) at ${url}`, {
+              stage: "openapi"
+            })
+          );
+        }
+        continue;
+      }
+      const payload = await response.json();
+      if (!isRecord3(payload)) {
+        warnings.push(
+          warning("PARSE_FAILED", "error", `OpenAPI payload at ${url} is not a JSON object`, {
+            stage: "openapi"
+          })
+        );
+        continue;
+      }
+      document = payload;
+      fetchedUrl = url;
+      break;
+    } catch (error) {
+      warnings.push(
+        warning(
+          "FETCH_FAILED",
+          "warn",
+          `OpenAPI fetch exception at ${url}: ${error instanceof Error ? error.message : String(error)}`,
+          { stage: "openapi" }
+        )
+      );
+    }
+  }
+  if (!document || !fetchedUrl) {
+    return {
+      stage: "openapi",
+      valid: false,
+      resources: [],
+      warnings
+    };
+  }
+  const hasTopLevel = typeof document.openapi === "string" && isRecord3(document.info) && typeof document.info.title === "string" && typeof document.info.version === "string" && isRecord3(document.paths);
+  if (!hasTopLevel) {
+    warnings.push(
+      warning("OPENAPI_TOP_LEVEL_INVALID", "error", "OpenAPI required fields are missing", {
+        stage: "openapi"
+      })
+    );
+    return {
+      stage: "openapi",
+      valid: false,
+      resources: [],
+      warnings,
+      links: { openapiUrl: fetchedUrl },
+      ...options.includeRaw ? { raw: document } : {}
+    };
+  }
+  const paths = document.paths;
+  const provenance = isRecord3(document["x-agentcash-provenance"]) ? document["x-agentcash-provenance"] : void 0;
+  const ownershipProofs = Array.isArray(provenance?.ownershipProofs) ? provenance.ownershipProofs.filter((entry) => typeof entry === "string") : [];
+  const guidance = isRecord3(document["x-agentcash-guidance"]) ? document["x-agentcash-guidance"] : void 0;
+  const llmsTxtUrl = asString(guidance?.llmsTxtUrl);
+  if (ownershipProofs.length > 0) {
+    warnings.push(
+      warning("OPENAPI_OWNERSHIP_PROOFS_PRESENT", "info", "OpenAPI ownership proofs detected", {
+        stage: "openapi"
+      })
+    );
+  }
+  for (const [rawPath, rawPathItem] of Object.entries(paths)) {
+    if (!isRecord3(rawPathItem)) {
+      warnings.push(
+        warning("OPENAPI_OPERATION_INVALID", "warn", `Path item ${rawPath} is not an object`, {
+          stage: "openapi"
+        })
+      );
+      continue;
+    }
+    for (const [rawMethod, rawOperation] of Object.entries(rawPathItem)) {
+      const method = parseMethod(rawMethod);
+      if (!method) continue;
+      if (!isRecord3(rawOperation)) {
+        warnings.push(
+          warning(
+            "OPENAPI_OPERATION_INVALID",
+            "warn",
+            `${rawMethod.toUpperCase()} ${rawPath} is not an object`,
+            {
+              stage: "openapi"
+            }
+          )
+        );
+        continue;
+      }
+      const operation = rawOperation;
+      const summary = asString(operation.summary) ?? asString(operation.description);
+      if (!summary) {
+        warnings.push(
+          warning(
+            "OPENAPI_SUMMARY_MISSING",
+            "warn",
+            `${method} ${rawPath} missing summary/description, using fallback summary`,
+            { stage: "openapi" }
+          )
+        );
+      }
+      const authMode = parseAuthMode(operation);
+      if (!authMode) {
+        warnings.push(
+          warning(
+            "OPENAPI_AUTH_MODE_MISSING",
+            "error",
+            `${method} ${rawPath} missing x-agentcash-auth.mode`,
+            {
+              stage: "openapi"
+            }
+          )
+        );
+        continue;
+      }
+      if ((authMode === "paid" || authMode === "siwx") && !require402Response(operation)) {
+        warnings.push(
+          warning(
+            "OPENAPI_402_MISSING",
+            "error",
+            `${method} ${rawPath} requires 402 response for authMode=${authMode}`,
+            { stage: "openapi" }
+          )
+        );
+        continue;
+      }
+      const paymentInfo = isRecord3(operation["x-payment-info"]) ? operation["x-payment-info"] : void 0;
+      const protocols = paymentInfo ? parseProtocols(paymentInfo) : [];
+      if (authMode === "paid" && protocols.length === 0) {
+        warnings.push(
+          warning(
+            "OPENAPI_PAID_PROTOCOLS_MISSING",
+            "error",
+            `${method} ${rawPath} must define x-payment-info.protocols when authMode=paid`,
+            { stage: "openapi" }
+          )
+        );
+        continue;
+      }
+      let pricing;
+      let priceHint;
+      if (paymentInfo && authMode === "paid") {
+        const pricingModeRaw = asString(paymentInfo.pricingMode);
+        const price = parsePriceValue(paymentInfo.price);
+        const minPrice = parsePriceValue(paymentInfo.minPrice);
+        const maxPrice = parsePriceValue(paymentInfo.maxPrice);
+        const inferredPricingMode = pricingModeRaw ?? (price ? "fixed" : minPrice && maxPrice ? "range" : "quote");
+        if (inferredPricingMode !== "fixed" && inferredPricingMode !== "range" && inferredPricingMode !== "quote") {
+          warnings.push(
+            warning(
+              "OPENAPI_PRICING_INVALID",
+              "error",
+              `${method} ${rawPath} has invalid pricingMode`,
+              {
+                stage: "openapi"
+              }
+            )
+          );
+          continue;
+        }
+        if (inferredPricingMode === "fixed" && !price) {
+          warnings.push(
+            warning(
+              "OPENAPI_PRICING_INVALID",
+              "error",
+              `${method} ${rawPath} fixed pricing requires price`,
+              {
+                stage: "openapi"
+              }
+            )
+          );
+          continue;
+        }
+        if (inferredPricingMode === "range") {
+          if (!minPrice || !maxPrice) {
+            warnings.push(
+              warning(
+                "OPENAPI_PRICING_INVALID",
+                "error",
+                `${method} ${rawPath} range pricing requires minPrice and maxPrice`,
+                { stage: "openapi" }
+              )
+            );
+            continue;
+          }
+          const min = Number(minPrice);
+          const max = Number(maxPrice);
+          if (!Number.isFinite(min) || !Number.isFinite(max) || min > max) {
+            warnings.push(
+              warning(
+                "OPENAPI_PRICING_INVALID",
+                "error",
+                `${method} ${rawPath} range pricing requires numeric minPrice <= maxPrice`,
+                { stage: "openapi" }
+              )
+            );
+            continue;
+          }
+        }
+        pricing = {
+          pricingMode: inferredPricingMode,
+          ...price ? { price } : {},
+          ...minPrice ? { minPrice } : {},
+          ...maxPrice ? { maxPrice } : {}
+        };
+        priceHint = inferredPricingMode === "fixed" ? price : inferredPricingMode === "range" ? `${minPrice}-${maxPrice}` : maxPrice;
+      }
+      const resource = createResource(
+        {
+          origin: options.origin,
+          method,
+          path: normalizePath(rawPath),
+          source: "openapi",
+          summary: summary ?? `${method} ${normalizePath(rawPath)}`,
+          authHint: authMode,
+          protocolHints: protocols,
+          ...priceHint ? { priceHint } : {},
+          ...pricing ? { pricing } : {},
+          links: {
+            openapiUrl: fetchedUrl,
+            ...llmsTxtUrl ? { llmsTxtUrl } : {}
+          }
+        },
+        0.95,
+        ownershipProofs.length > 0 ? "ownership_verified" : "origin_hosted"
+      );
+      resources.push(resource);
+    }
+  }
+  if (llmsTxtUrl) {
+    try {
+      const llmsResponse = await options.fetcher(llmsTxtUrl, {
+        method: "GET",
+        headers: { Accept: "text/plain", ...options.headers },
+        signal: options.signal
+      });
+      if (llmsResponse.ok) {
+        const llmsText = await llmsResponse.text();
+        const tokenCount = estimateTokenCount(llmsText);
+        if (tokenCount > LLMS_TOKEN_WARNING_THRESHOLD) {
+          warnings.push(
+            warning(
+              "LLMSTXT_TOO_LARGE",
+              "warn",
+              `llms.txt estimated ${tokenCount} tokens (threshold ${LLMS_TOKEN_WARNING_THRESHOLD})`,
+              {
+                stage: "openapi",
+                hint: "Keep llms.txt concise and domain-level only."
+              }
+            )
+          );
+        }
+        if (options.includeRaw) {
+          return {
+            stage: "openapi",
+            valid: resources.length > 0,
+            resources,
+            warnings,
+            links: { openapiUrl: fetchedUrl, llmsTxtUrl },
+            raw: {
+              openapi: document,
+              llmsTxt: llmsText
+            }
+          };
+        }
+      } else {
+        warnings.push(
+          warning(
+            "LLMSTXT_FETCH_FAILED",
+            "warn",
+            `llms.txt fetch failed (${llmsResponse.status})`,
+            {
+              stage: "openapi"
+            }
+          )
+        );
+      }
+    } catch (error) {
+      warnings.push(
+        warning(
+          "LLMSTXT_FETCH_FAILED",
+          "warn",
+          `llms.txt fetch failed: ${error instanceof Error ? error.message : String(error)}`,
+          { stage: "openapi" }
+        )
+      );
+    }
+  }
+  return {
+    stage: "openapi",
+    valid: resources.length > 0,
+    resources,
+    warnings,
+    links: {
+      openapiUrl: fetchedUrl,
+      ...llmsTxtUrl ? { llmsTxtUrl } : {}
+    },
+    ...options.includeRaw ? { raw: { openapi: document } } : {}
+  };
+}
+
+// src/core/probe.ts
+function detectAuthHintFrom402Payload(payload) {
+  if (payload && typeof payload === "object") {
+    const asRecord = payload;
+    const extensions = asRecord.extensions;
+    if (extensions && typeof extensions === "object") {
+      const extRecord = extensions;
+      if (extRecord["sign-in-with-x"]) return "siwx";
+    }
+  }
+  return "paid";
+}
+function detectProtocols(response) {
+  const protocols = /* @__PURE__ */ new Set();
+  const directHeader = response.headers.get("x-payment-protocol");
+  if (directHeader) {
+    for (const part of directHeader.split(",")) {
+      const protocol = part.trim().toLowerCase();
+      if (protocol) protocols.add(protocol);
+    }
+  }
+  const authHeader = response.headers.get("www-authenticate")?.toLowerCase() ?? "";
+  if (authHeader.includes("x402")) protocols.add("x402");
+  if (authHeader.includes("mpp")) protocols.add("mpp");
+  return [...protocols];
+}
+async function runProbeStage(options) {
+  const candidates = options.probeCandidates ?? [];
+  if (candidates.length === 0) {
+    return {
+      stage: "probe",
+      valid: false,
+      resources: [],
+      warnings: [
+        warning(
+          "PROBE_STAGE_SKIPPED",
+          "info",
+          "Probe stage skipped because no probe candidates were provided.",
+          { stage: "probe" }
+        )
+      ]
+    };
+  }
+  const resources = [];
+  const warnings = [];
+  for (const candidate of candidates) {
+    const path = normalizePath(candidate.path);
+    const methods = candidate.methods?.length ? candidate.methods : DEFAULT_PROBE_METHODS;
+    for (const method of methods) {
+      const url = `${options.origin}${path}`;
+      try {
+        const response = await options.fetcher(url, {
+          method,
+          headers: {
+            Accept: "application/json, text/plain;q=0.9, */*;q=0.8",
+            ...options.headers
+          },
+          signal: options.signal
+        });
+        if (response.status !== 402 && (response.status < 200 || response.status >= 300)) {
+          continue;
+        }
+        let authHint = response.status === 402 ? "paid" : "unprotected";
+        if (response.status === 402) {
+          try {
+            const payload = await response.clone().json();
+            authHint = detectAuthHintFrom402Payload(payload);
+          } catch {
+          }
+        }
+        const protocolHints = detectProtocols(response);
+        resources.push(
+          createResource(
+            {
+              origin: options.origin,
+              method,
+              path,
+              source: "probe",
+              summary: `${method} ${path}`,
+              authHint,
+              ...protocolHints.length ? { protocolHints } : {}
+            },
+            0.6,
+            "runtime_verified"
+          )
+        );
+      } catch (error) {
+        warnings.push(
+          warning(
+            "FETCH_FAILED",
+            "info",
+            `Probe ${method} ${path} failed: ${error instanceof Error ? error.message : String(error)}`,
+            { stage: "probe" }
+          )
+        );
+      }
+    }
+  }
+  return {
+    stage: "probe",
+    valid: resources.length > 0,
+    resources,
+    warnings
+  };
+}
+
+// src/core/upgrade.ts
+var UPGRADE_WARNING_CODES = [
+  "LEGACY_WELL_KNOWN_USED",
+  "LEGACY_DNS_USED",
+  "LEGACY_DNS_PLAIN_URL",
+  "LEGACY_INSTRUCTIONS_USED",
+  "LEGACY_OWNERSHIP_PROOFS_USED",
+  "OPENAPI_AUTH_MODE_MISSING",
+  "OPENAPI_TOP_LEVEL_INVALID"
+];
+var UPGRADE_WARNING_CODE_SET = new Set(UPGRADE_WARNING_CODES);
+function computeUpgradeSignal(warnings) {
+  const reasons = warnings.map((entry) => entry.code).filter((code, index, list) => list.indexOf(code) === index).filter((code) => UPGRADE_WARNING_CODE_SET.has(code));
+  return {
+    upgradeSuggested: reasons.length > 0,
+    upgradeReasons: reasons
+  };
+}
+
+// src/core/discovery.ts
+function mergeResources(target, incoming, resourceWarnings) {
+  const warnings = [];
+  for (const resource of incoming) {
+    const existing = target.get(resource.resourceKey);
+    if (!existing) {
+      target.set(resource.resourceKey, resource);
+      continue;
+    }
+    const conflict = existing.authHint !== resource.authHint || existing.priceHint !== resource.priceHint || JSON.stringify(existing.protocolHints ?? []) !== JSON.stringify(resource.protocolHints ?? []);
+    if (conflict) {
+      const conflictWarning = warning(
+        "CROSS_SOURCE_CONFLICT",
+        "warn",
+        `Resource conflict for ${resource.resourceKey}; keeping higher-precedence source ${existing.source} over ${resource.source}.`,
+        {
+          resourceKey: resource.resourceKey
+        }
+      );
+      warnings.push(conflictWarning);
+      resourceWarnings[resource.resourceKey] = [
+        ...resourceWarnings[resource.resourceKey] ?? [],
+        conflictWarning
+      ];
+      continue;
+    }
+    target.set(resource.resourceKey, {
+      ...existing,
+      summary: existing.summary ?? resource.summary,
+      links: { ...resource.links, ...existing.links },
+      confidence: Math.max(existing.confidence ?? 0, resource.confidence ?? 0)
+    });
+  }
+  return warnings;
+}
+function toTrace(stageResult, startedAt) {
+  return {
+    stage: stageResult.stage,
+    attempted: true,
+    valid: stageResult.valid,
+    resourceCount: stageResult.resources.length,
+    durationMs: Date.now() - startedAt,
+    warnings: stageResult.warnings,
+    ...stageResult.links ? { links: stageResult.links } : {}
+  };
+}
+async function runOverrideStage(options) {
+  const warnings = [];
+  for (const overrideUrl of options.overrideUrls) {
+    const normalized = overrideUrl.trim();
+    if (!normalized) continue;
+    try {
+      const response = await options.fetcher(normalized, {
+        method: "GET",
+        headers: { Accept: "application/json, text/plain;q=0.9", ...options.headers },
+        signal: options.signal
+      });
+      if (!response.ok) {
+        warnings.push(
+          warning(
+            "FETCH_FAILED",
+            "warn",
+            `Override fetch failed (${response.status}) at ${normalized}`,
+            {
+              stage: "override"
+            }
+          )
+        );
+        continue;
+      }
+      const bodyText = await response.text();
+      let parsedJson;
+      try {
+        parsedJson = JSON.parse(bodyText);
+      } catch {
+        parsedJson = void 0;
+      }
+      if (parsedJson && typeof parsedJson === "object" && !Array.isArray(parsedJson) && "openapi" in parsedJson && "paths" in parsedJson) {
+        const openapiResult = await runOpenApiStage({
+          origin: options.origin,
+          fetcher: async (input, init) => {
+            const inputString = String(input);
+            if (inputString === `${options.origin}/openapi.json` || inputString === `${options.origin}/.well-known/openapi.json`) {
+              return new Response(bodyText, {
+                status: 200,
+                headers: { "content-type": "application/json" }
+              });
+            }
+            return options.fetcher(input, init);
+          },
+          headers: options.headers,
+          signal: options.signal,
+          includeRaw: options.includeRaw
+        });
+        return {
+          ...openapiResult,
+          stage: "override",
+          warnings: [
+            warning("OVERRIDE_USED", "info", `Using explicit override source ${normalized}`, {
+              stage: "override"
+            }),
+            ...openapiResult.warnings
+          ]
+        };
+      }
+      if (parsedJson && typeof parsedJson === "object" && !Array.isArray(parsedJson)) {
+        const parsedWellKnown = parseWellKnownPayload(parsedJson, options.origin, normalized);
+        if (parsedWellKnown.resources.length > 0) {
+          return {
+            stage: "override",
+            valid: true,
+            resources: parsedWellKnown.resources,
+            warnings: [
+              warning("OVERRIDE_USED", "info", `Using explicit override source ${normalized}`, {
+                stage: "override"
+              }),
+              ...parsedWellKnown.warnings
+            ],
+            links: { discoveryUrl: normalized },
+            ...options.includeRaw ? { raw: parsedWellKnown.raw } : {}
+          };
+        }
+      }
+    } catch (error) {
+      warnings.push(
+        warning(
+          "FETCH_FAILED",
+          "warn",
+          `Override fetch exception at ${normalized}: ${error instanceof Error ? error.message : String(error)}`,
+          { stage: "override" }
+        )
+      );
+      continue;
+    }
+    const fallbackWellKnownResult = await runWellKnownX402Stage({
+      origin: options.origin,
+      url: normalized,
+      fetcher: options.fetcher,
+      headers: options.headers,
+      signal: options.signal,
+      includeRaw: options.includeRaw
+    });
+    if (fallbackWellKnownResult.valid) {
+      return {
+        ...fallbackWellKnownResult,
+        stage: "override",
+        warnings: [
+          warning("OVERRIDE_USED", "info", `Using explicit override source ${normalized}`, {
+            stage: "override"
+          }),
+          ...fallbackWellKnownResult.warnings
+        ]
+      };
+    }
+    warnings.push(...fallbackWellKnownResult.warnings);
+  }
+  return {
+    stage: "override",
+    valid: false,
+    resources: [],
+    warnings
+  };
+}
+async function runDiscovery({
+  detailed,
+  options
+}) {
+  const fetcher = options.fetcher ?? fetch;
+  const compatMode = options.compatMode ?? DEFAULT_COMPAT_MODE;
+  const strictCompat = compatMode === "strict";
+  const rawView = detailed ? options.rawView ?? "none" : "none";
+  const includeRaw = rawView === "full";
+  const includeInteropMpp = detailed && Boolean(options.includeInteropMpp);
+  const origin = normalizeOrigin(options.target);
+  const warnings = [];
+  const trace = [];
+  const resourceWarnings = {};
+  const rawSources = {};
+  const merged = /* @__PURE__ */ new Map();
+  if (compatMode !== "off") {
+    warnings.push(
+      warning(
+        "COMPAT_MODE_ENABLED",
+        compatMode === "strict" ? "warn" : "info",
+        `Compatibility mode is '${compatMode}'. Legacy adapters are active.`
+      )
+    );
+  }
+  const stages = [];
+  if (options.overrideUrls && options.overrideUrls.length > 0) {
+    stages.push(
+      () => runOverrideStage({
+        origin,
+        overrideUrls: options.overrideUrls ?? [],
+        fetcher,
+        headers: options.headers,
+        signal: options.signal,
+        includeRaw
+      })
+    );
+  }
+  stages.push(
+    () => runOpenApiStage({
+      origin,
+      fetcher,
+      headers: options.headers,
+      signal: options.signal,
+      includeRaw
+    })
+  );
+  if (compatMode !== "off") {
+    stages.push(
+      () => runWellKnownX402Stage({
+        origin,
+        fetcher,
+        headers: options.headers,
+        signal: options.signal,
+        includeRaw
+      })
+    );
+    stages.push(
+      () => runDnsStage({
+        origin,
+        fetcher,
+        txtResolver: options.txtResolver,
+        headers: options.headers,
+        signal: options.signal,
+        includeRaw
+      })
+    );
+    if (includeInteropMpp) {
+      stages.push(
+        () => runInteropMppStage({
+          origin,
+          fetcher,
+          headers: options.headers,
+          signal: options.signal,
+          includeRaw
+        })
+      );
+    }
+  }
+  stages.push(
+    () => runProbeStage({
+      origin,
+      fetcher,
+      headers: options.headers,
+      signal: options.signal,
+      probeCandidates: options.probeCandidates
+    })
+  );
+  let selectedStage;
+  for (const runStage of stages) {
+    const startedAt = Date.now();
+    const stageResult = await runStage();
+    stageResult.warnings = applyStrictEscalation(stageResult.warnings, strictCompat);
+    trace.push(toTrace(stageResult, startedAt));
+    warnings.push(...stageResult.warnings);
+    if (stageResult.resources.length > 0) {
+      for (const stageWarning of stageResult.warnings) {
+        if (stageWarning.resourceKey) {
+          resourceWarnings[stageWarning.resourceKey] = [
+            ...resourceWarnings[stageWarning.resourceKey] ?? [],
+            stageWarning
+          ];
+        }
+      }
+    }
+    if (!stageResult.valid) {
+      continue;
+    }
+    const mergeWarnings = mergeResources(merged, stageResult.resources, resourceWarnings);
+    warnings.push(...mergeWarnings);
+    if (includeRaw && stageResult.raw !== void 0) {
+      if (stageResult.stage === "openapi" || stageResult.stage === "override") {
+        const rawObject = stageResult.raw;
+        if (rawObject.openapi !== void 0) rawSources.openapi = rawObject.openapi;
+        if (typeof rawObject.llmsTxt === "string") rawSources.llmsTxt = rawObject.llmsTxt;
+      }
+      if (stageResult.stage === "well-known/x402" || stageResult.stage === "override") {
+        rawSources.wellKnownX402 = [...rawSources.wellKnownX402 ?? [], stageResult.raw];
+      }
+      if (stageResult.stage === "dns/_x402") {
+        const rawObject = stageResult.raw;
+        if (Array.isArray(rawObject.dnsRecords)) {
+          rawSources.dnsRecords = rawObject.dnsRecords;
+        }
+      }
+      if (stageResult.stage === "interop/mpp") {
+        rawSources.interopMpp = stageResult.raw;
+      }
+    }
+    if (!detailed) {
+      selectedStage = selectedStage ?? stageResult.stage;
+      break;
+    }
+  }
+  if (merged.size === 0) {
+    warnings.push(
+      warning(
+        "NO_DISCOVERY_SOURCES",
+        "error",
+        "No discovery stage returned first-valid-non-empty results."
+      )
+    );
+  }
+  const dedupedWarnings = dedupeWarnings(warnings);
+  const upgradeSignal = computeUpgradeSignal(dedupedWarnings);
+  const resources = [...merged.values()];
+  if (!detailed) {
+    return {
+      origin,
+      resources,
+      warnings: dedupedWarnings,
+      compatMode,
+      ...upgradeSignal,
+      ...selectedStage ? { selectedStage } : {}
+    };
+  }
+  return {
+    origin,
+    resources,
+    warnings: dedupedWarnings,
+    compatMode,
+    ...upgradeSignal,
+    selectedStage: trace.find((entry) => entry.valid)?.stage,
+    trace,
+    resourceWarnings,
+    ...includeRaw ? { rawSources } : {}
+  };
+}
+
+// src/index.ts
+async function discover(options) {
+  return await runDiscovery({ detailed: false, options });
+}
+async function discoverDetailed(options) {
+  return await runDiscovery({ detailed: true, options });
+}
+export {
+  DEFAULT_COMPAT_MODE,
+  LEGACY_SUNSET_DATE,
+  STRICT_ESCALATION_CODES,
+  UPGRADE_WARNING_CODES,
+  computeUpgradeSignal,
+  discover,
+  discoverDetailed
+};