@agentcash/discovery 0.1.2 → 0.1.4

package/dist/index.js

@@ -12,7 +12,7 @@ var STRICT_ESCALATION_CODES = [
 ];
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "0.1.2".includes("-mmm");
+var isMmmEnabled = () => "0.1.4".includes("-mmm");
 
 // src/core/constants.ts
 var OPENAPI_PATH_CANDIDATES = ["/openapi.json", "/.well-known/openapi.json"];
@@ -182,7 +182,7 @@ function parseWellKnownPayload(payload, origin, sourceUrl) {
         "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."
+          hint: "Move guidance to llms.txt and reference via x-discovery.llmsTxtUrl in OpenAPI."
         }
       )
     );
@@ -195,7 +195,7 @@ function parseWellKnownPayload(payload, origin, sourceUrl) {
         "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."
+          hint: "Move ownership proofs to x-discovery.ownershipProofs in OpenAPI."
         }
       )
     );
@@ -591,10 +591,31 @@ function estimateTokenCount(text) {
   return Math.ceil(text.length / 4);
 }
 
-// src/core/openapi.ts
+// src/core/openapi-utils.ts
 function isRecord3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function hasSecurity(operation, scheme) {
+  const security = operation.security;
+  return Array.isArray(security) && security.some((s) => isRecord3(s) && scheme in s);
+}
+function has402Response(operation) {
+  const responses = operation.responses;
+  if (!isRecord3(responses)) return false;
+  return Boolean(responses["402"]);
+}
+function inferAuthMode(operation) {
+  if (isRecord3(operation["x-payment-info"])) return "paid";
+  if (has402Response(operation)) {
+    if (hasSecurity(operation, "siwx")) return "siwx";
+    return "paid";
+  }
+  if (hasSecurity(operation, "apiKey")) return "apiKey";
+  if (hasSecurity(operation, "siwx")) return "siwx";
+  return void 0;
+}
+
+// src/core/openapi.ts
 function asString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
@@ -603,11 +624,6 @@ function parsePriceValue(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 [];
@@ -615,15 +631,6 @@ function parseProtocols(paymentInfo) {
     (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 = [];
@@ -695,10 +702,9 @@ async function runOpenApiStage(options) {
     };
   }
   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);
+  const discovery = isRecord3(document["x-discovery"]) ? document["x-discovery"] : void 0;
+  const ownershipProofs = Array.isArray(discovery?.ownershipProofs) ? discovery.ownershipProofs.filter((entry) => typeof entry === "string") : [];
+  const llmsTxtUrl = asString(discovery?.llmsTxtUrl);
   if (ownershipProofs.length > 0) {
     warnings.push(
       warning("OPENAPI_OWNERSHIP_PROOFS_PRESENT", "info", "OpenAPI ownership proofs detected", {
@@ -743,13 +749,13 @@ async function runOpenApiStage(options) {
           )
         );
       }
-      const authMode = parseAuthMode(operation);
+      const authMode = inferAuthMode(operation);
       if (!authMode) {
         warnings.push(
           warning(
             "OPENAPI_AUTH_MODE_MISSING",
             "error",
-            `${method} ${rawPath} missing x-agentcash-auth.mode`,
+            `${method} ${rawPath} missing auth mode (no x-payment-info, 402 response, or security scheme)`,
             {
               stage: "openapi"
             }
@@ -757,7 +763,7 @@ async function runOpenApiStage(options) {
         );
         continue;
       }
-      if ((authMode === "paid" || authMode === "siwx") && !require402Response(operation)) {
+      if ((authMode === "paid" || authMode === "siwx") && !has402Response(operation)) {
         warnings.push(
           warning(
             "OPENAPI_402_MISSING",
@@ -1336,11 +1342,6 @@ async function runDiscovery({
         }
       }
     }
-    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;
@@ -1360,6 +1361,11 @@ async function runDiscovery({
         rawSources.interopMpp = stageResult.raw;
       }
     }
+    if (!stageResult.valid) {
+      continue;
+    }
+    const mergeWarnings = mergeResources(merged, stageResult.resources, resourceWarnings);
+    warnings.push(...mergeWarnings);
     if (!detailed) {
       selectedStage = selectedStage ?? stageResult.stage;
       break;
@@ -1400,6 +1406,471 @@ async function runDiscovery({
   };
 }
 
+// src/validation/codes.ts
+var VALIDATION_CODES = {
+  COINBASE_SCHEMA_INVALID: "COINBASE_SCHEMA_INVALID",
+  X402_NOT_OBJECT: "X402_NOT_OBJECT",
+  X402_VERSION_MISSING: "X402_VERSION_MISSING",
+  X402_VERSION_UNSUPPORTED: "X402_VERSION_UNSUPPORTED",
+  X402_ACCEPTS_MISSING: "X402_ACCEPTS_MISSING",
+  X402_ACCEPTS_INVALID: "X402_ACCEPTS_INVALID",
+  X402_ACCEPTS_EMPTY: "X402_ACCEPTS_EMPTY",
+  X402_ACCEPT_ENTRY_INVALID: "X402_ACCEPT_ENTRY_INVALID",
+  NETWORK_CAIP2_INVALID: "NETWORK_CAIP2_INVALID",
+  NETWORK_EIP155_REFERENCE_INVALID: "NETWORK_EIP155_REFERENCE_INVALID",
+  NETWORK_SOLANA_ALIAS_INVALID: "NETWORK_SOLANA_ALIAS_INVALID",
+  NETWORK_SOLANA_ALIAS_COMPAT: "NETWORK_SOLANA_ALIAS_COMPAT",
+  NETWORK_REFERENCE_UNKNOWN: "NETWORK_REFERENCE_UNKNOWN",
+  SCHEMA_INPUT_MISSING: "SCHEMA_INPUT_MISSING",
+  SCHEMA_OUTPUT_MISSING: "SCHEMA_OUTPUT_MISSING",
+  METADATA_TITLE_MISSING: "METADATA_TITLE_MISSING",
+  METADATA_DESCRIPTION_MISSING: "METADATA_DESCRIPTION_MISSING",
+  METADATA_FAVICON_MISSING: "METADATA_FAVICON_MISSING",
+  METADATA_OG_IMAGE_MISSING: "METADATA_OG_IMAGE_MISSING"
+};
+
+// src/validation/metadata.ts
+function hasText(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function hasOgImage(metadata) {
+  const images = metadata.ogImages;
+  if (!Array.isArray(images) || images.length === 0) return false;
+  return images.some((entry) => {
+    if (typeof entry === "string") {
+      return entry.trim().length > 0;
+    }
+    if (!entry || typeof entry !== "object") return false;
+    return hasText(entry.url);
+  });
+}
+function evaluateMetadataCompleteness(metadata) {
+  const issues = [];
+  if (!hasText(metadata.title)) {
+    issues.push({
+      code: VALIDATION_CODES.METADATA_TITLE_MISSING,
+      severity: "warn",
+      message: "Metadata title is missing",
+      hint: "Provide a page title to improve discovery quality and UX.",
+      path: "metadata.title",
+      stage: "metadata"
+    });
+  }
+  if (!hasText(metadata.description)) {
+    issues.push({
+      code: VALIDATION_CODES.METADATA_DESCRIPTION_MISSING,
+      severity: "warn",
+      message: "Metadata description is missing",
+      hint: "Provide a concise description for integrators and search previews.",
+      path: "metadata.description",
+      stage: "metadata"
+    });
+  }
+  if (!hasText(metadata.favicon)) {
+    issues.push({
+      code: VALIDATION_CODES.METADATA_FAVICON_MISSING,
+      severity: "warn",
+      message: "Metadata favicon is missing",
+      hint: "Expose a favicon URL for stronger brand attribution.",
+      path: "metadata.favicon",
+      stage: "metadata"
+    });
+  }
+  if (!hasOgImage(metadata)) {
+    issues.push({
+      code: VALIDATION_CODES.METADATA_OG_IMAGE_MISSING,
+      severity: "warn",
+      message: "Metadata OG image is missing",
+      hint: "Provide an Open Graph image to improve sharing previews.",
+      path: "metadata.ogImages",
+      stage: "metadata"
+    });
+  }
+  return issues;
+}
+
+// src/validation/payment-required.ts
+import { parsePaymentRequired } from "@x402/core/schemas";
+var SOLANA_CANONICAL_BY_REF = {
+  "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": "solana",
+  EtWTRABZaYq6iMfeYKouRu166VU2xqa1: "solana-devnet",
+  "4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z": "solana-testnet"
+};
+var SOLANA_ALIAS_BY_REF = {
+  mainnet: "solana",
+  devnet: "solana-devnet",
+  testnet: "solana-testnet"
+};
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asNonEmptyString(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function asPositiveNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function pushIssue(issues, issue) {
+  issues.push({
+    stage: issue.stage ?? "payment_required",
+    ...issue
+  });
+}
+function summarizeIssues(issues) {
+  const summary = {
+    errorCount: 0,
+    warnCount: 0,
+    infoCount: 0,
+    byCode: {}
+  };
+  for (const issue of issues) {
+    if (issue.severity === "error") summary.errorCount += 1;
+    else if (issue.severity === "warn") summary.warnCount += 1;
+    else summary.infoCount += 1;
+    summary.byCode[issue.code] = (summary.byCode[issue.code] ?? 0) + 1;
+  }
+  return summary;
+}
+function outputSchemaMissingSeverity(compatMode) {
+  return compatMode === "strict" ? "error" : "warn";
+}
+function zodPathToString(path) {
+  if (path.length === 0) return "$";
+  let out = "";
+  for (const segment of path) {
+    if (typeof segment === "number") out += `[${segment}]`;
+    else out += out.length === 0 ? segment : `.${segment}`;
+  }
+  return out;
+}
+function parseWithCoinbaseStructuralGate(payload, issues) {
+  const baseParsed = parsePaymentRequired(payload);
+  if (baseParsed.success) {
+    return baseParsed.data;
+  }
+  for (const issue of baseParsed.error.issues) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.COINBASE_SCHEMA_INVALID,
+      severity: "error",
+      message: `Coinbase schema validation failed: ${issue.message}`,
+      path: zodPathToString(issue.path),
+      actual: issue.code
+    });
+  }
+  return void 0;
+}
+function validateV2Network(networkRaw, index, issues) {
+  if (!/^[^:\s]+:[^:\s]+$/.test(networkRaw)) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.NETWORK_CAIP2_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} has invalid CAIP-2 network format`,
+      hint: "Expected '<namespace>:<reference>', e.g. 'eip155:8453' or 'solana:5eykt4...'.",
+      path: `accepts[${index}].network`,
+      expected: "<namespace>:<reference>",
+      actual: networkRaw
+    });
+    return void 0;
+  }
+  const [namespace, reference] = networkRaw.split(":");
+  if (namespace === "eip155") {
+    if (!/^\d+$/.test(reference)) {
+      pushIssue(issues, {
+        code: VALIDATION_CODES.NETWORK_EIP155_REFERENCE_INVALID,
+        severity: "error",
+        message: `Accept at index ${index} has invalid eip155 reference`,
+        hint: "Use a numeric chain id, e.g. 'eip155:8453'.",
+        path: `accepts[${index}].network`,
+        expected: "eip155:<numeric-chain-id>",
+        actual: networkRaw
+      });
+      return void 0;
+    }
+    return networkRaw;
+  }
+  if (namespace === "solana") {
+    const canonical = SOLANA_CANONICAL_BY_REF[reference];
+    if (canonical) return canonical;
+    const alias = SOLANA_ALIAS_BY_REF[reference];
+    if (alias) {
+      pushIssue(issues, {
+        code: VALIDATION_CODES.NETWORK_SOLANA_ALIAS_COMPAT,
+        severity: "warn",
+        message: `Accept at index ${index} uses compatibility Solana reference '${reference}'`,
+        hint: "Use canonical Solana CAIP references for deterministic behavior.",
+        path: `accepts[${index}].network`,
+        actual: networkRaw
+      });
+      return alias;
+    }
+    pushIssue(issues, {
+      code: VALIDATION_CODES.NETWORK_REFERENCE_UNKNOWN,
+      severity: "error",
+      message: `Accept at index ${index} uses unknown Solana reference '${reference}'`,
+      hint: "Use canonical references for mainnet/devnet/testnet.",
+      path: `accepts[${index}].network`,
+      actual: networkRaw
+    });
+    return void 0;
+  }
+  return networkRaw;
+}
+function validateV1Network(networkRaw, index, issues) {
+  if (networkRaw === "solana-mainnet-beta") {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.NETWORK_SOLANA_ALIAS_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} uses invalid Solana network alias`,
+      hint: "Use 'solana' (v1) or canonical Solana CAIP reference (v2).",
+      path: `accepts[${index}].network`,
+      expected: "solana",
+      actual: networkRaw
+    });
+    return void 0;
+  }
+  if (networkRaw.startsWith("solana-") && networkRaw !== "solana-devnet") {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.NETWORK_SOLANA_ALIAS_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} uses unsupported Solana network alias`,
+      hint: "Use 'solana' or 'solana-devnet' for v1 payloads.",
+      path: `accepts[${index}].network`,
+      actual: networkRaw
+    });
+    return void 0;
+  }
+  if (networkRaw.includes(":")) {
+    return validateV2Network(networkRaw, index, issues);
+  }
+  return networkRaw;
+}
+function validateAccept(acceptRaw, index, version, issues) {
+  if (!isRecord4(acceptRaw)) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} must be an object`,
+      path: `accepts[${index}]`
+    });
+    return null;
+  }
+  const scheme = asNonEmptyString(acceptRaw.scheme);
+  const networkRaw = asNonEmptyString(acceptRaw.network);
+  const payTo = asNonEmptyString(acceptRaw.payTo);
+  const asset = asNonEmptyString(acceptRaw.asset);
+  const maxTimeoutSeconds = asPositiveNumber(acceptRaw.maxTimeoutSeconds);
+  const amount = version === 2 ? asNonEmptyString(acceptRaw.amount) : asNonEmptyString(acceptRaw.maxAmountRequired);
+  if (!scheme) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} is missing scheme`,
+      path: `accepts[${index}].scheme`
+    });
+  }
+  if (!networkRaw) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} is missing network`,
+      path: `accepts[${index}].network`
+    });
+  }
+  if (!amount) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} is missing ${version === 2 ? "amount" : "maxAmountRequired"}`,
+      path: `accepts[${index}].${version === 2 ? "amount" : "maxAmountRequired"}`
+    });
+  }
+  if (!payTo) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} is missing payTo`,
+      path: `accepts[${index}].payTo`
+    });
+  }
+  if (!asset) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} is missing asset`,
+      path: `accepts[${index}].asset`
+    });
+  }
+  if (!maxTimeoutSeconds) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPT_ENTRY_INVALID,
+      severity: "error",
+      message: `Accept at index ${index} is missing or has invalid maxTimeoutSeconds`,
+      path: `accepts[${index}].maxTimeoutSeconds`
+    });
+  }
+  let normalizedNetwork;
+  if (networkRaw) {
+    normalizedNetwork = version === 2 ? validateV2Network(networkRaw, index, issues) : validateV1Network(networkRaw, index, issues);
+  }
+  return {
+    index,
+    network: normalizedNetwork ?? networkRaw ?? "unknown",
+    networkRaw: networkRaw ?? "unknown",
+    scheme,
+    asset,
+    payTo,
+    amount,
+    maxTimeoutSeconds
+  };
+}
+function getSchemaPresence(payload, accepts, version) {
+  if (version === 1) {
+    const first = accepts[0];
+    if (!isRecord4(first)) {
+      return { hasInputSchema: false, hasOutputSchema: false };
+    }
+    const outputSchema = isRecord4(first.outputSchema) ? first.outputSchema : void 0;
+    return {
+      hasInputSchema: outputSchema?.input !== void 0 && outputSchema.input !== null,
+      hasOutputSchema: outputSchema?.output !== void 0 && outputSchema.output !== null
+    };
+  }
+  const extensions = isRecord4(payload.extensions) ? payload.extensions : void 0;
+  const bazaar = extensions && isRecord4(extensions.bazaar) ? extensions.bazaar : void 0;
+  const info = bazaar && isRecord4(bazaar.info) ? bazaar.info : void 0;
+  return {
+    hasInputSchema: info?.input !== void 0 && info.input !== null,
+    hasOutputSchema: info?.output !== void 0 && info.output !== null
+  };
+}
+function validatePaymentRequiredDetailed(payload, options = {}) {
+  const issues = [];
+  const compatMode = options.compatMode ?? DEFAULT_COMPAT_MODE;
+  const requireInputSchema = options.requireInputSchema ?? true;
+  const requireOutputSchema = options.requireOutputSchema ?? true;
+  if (!isRecord4(payload)) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_NOT_OBJECT,
+      severity: "error",
+      message: "Payment required payload must be a JSON object",
+      path: "$"
+    });
+    if (options.metadata) {
+      issues.push(...evaluateMetadataCompleteness(options.metadata));
+    }
+    return {
+      valid: false,
+      issues,
+      summary: summarizeIssues(issues)
+    };
+  }
+  const coinbaseParsed = parseWithCoinbaseStructuralGate(payload, issues);
+  const versionRaw = payload.x402Version;
+  let version;
+  if (versionRaw === 1 || versionRaw === 2) {
+    version = versionRaw;
+  } else if (versionRaw === void 0) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_VERSION_MISSING,
+      severity: "error",
+      message: "x402Version is required",
+      path: "x402Version"
+    });
+  } else {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_VERSION_UNSUPPORTED,
+      severity: "error",
+      message: `Unsupported x402Version '${String(versionRaw)}'`,
+      path: "x402Version",
+      expected: "1 | 2",
+      actual: String(versionRaw)
+    });
+  }
+  const acceptsRaw = payload.accepts;
+  let accepts = [];
+  if (acceptsRaw === void 0) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPTS_MISSING,
+      severity: "error",
+      message: "accepts is required",
+      path: "accepts"
+    });
+  } else if (!Array.isArray(acceptsRaw)) {
+    pushIssue(issues, {
+      code: VALIDATION_CODES.X402_ACCEPTS_INVALID,
+      severity: "error",
+      message: "accepts must be an array",
+      path: "accepts"
+    });
+  } else {
+    accepts = acceptsRaw;
+    if (accepts.length === 0) {
+      pushIssue(issues, {
+        code: VALIDATION_CODES.X402_ACCEPTS_EMPTY,
+        severity: "error",
+        message: "accepts must contain at least one payment requirement",
+        path: "accepts"
+      });
+    }
+  }
+  const normalizedAccepts = [];
+  if (version && Array.isArray(accepts)) {
+    accepts.forEach((accept, index) => {
+      const normalized = validateAccept(accept, index, version, issues);
+      if (normalized) normalizedAccepts.push(normalized);
+    });
+    const schemaPresence = getSchemaPresence(payload, accepts, version);
+    if (requireInputSchema && !schemaPresence.hasInputSchema) {
+      pushIssue(issues, {
+        code: VALIDATION_CODES.SCHEMA_INPUT_MISSING,
+        severity: "error",
+        message: "Input schema is missing",
+        hint: "Include input schema details so clients can invoke the endpoint correctly.",
+        path: version === 1 ? "accepts[0].outputSchema.input" : "extensions.bazaar.info.input"
+      });
+    }
+    if (requireOutputSchema && !schemaPresence.hasOutputSchema) {
+      pushIssue(issues, {
+        code: VALIDATION_CODES.SCHEMA_OUTPUT_MISSING,
+        severity: outputSchemaMissingSeverity(compatMode),
+        message: "Output schema is missing",
+        hint: "Include output schema details so clients can validate responses.",
+        path: version === 1 ? "accepts[0].outputSchema.output" : "extensions.bazaar.info.output"
+      });
+    }
+    if (options.metadata) {
+      issues.push(...evaluateMetadataCompleteness(options.metadata));
+    }
+    const summary2 = summarizeIssues(issues);
+    return {
+      valid: summary2.errorCount === 0,
+      version,
+      parsed: coinbaseParsed ?? payload,
+      normalized: {
+        version,
+        accepts: normalizedAccepts,
+        hasInputSchema: schemaPresence.hasInputSchema,
+        hasOutputSchema: schemaPresence.hasOutputSchema
+      },
+      issues,
+      summary: summary2
+    };
+  }
+  if (options.metadata) {
+    issues.push(...evaluateMetadataCompleteness(options.metadata));
+  }
+  const summary = summarizeIssues(issues);
+  return {
+    valid: summary.errorCount === 0,
+    version,
+    parsed: coinbaseParsed ?? payload,
+    issues,
+    summary
+  };
+}
+
 // src/adapters/mcp.ts
 var DEFAULT_GUIDANCE_AUTO_INCLUDE_MAX_TOKENS = 1e3;
 var OPENAPI_METHODS = [
@@ -1412,9 +1883,6 @@ var OPENAPI_METHODS = [
   "OPTIONS",
   "TRACE"
 ];
-function isRecord4(value) {
-  return value != null && typeof value === "object" && !Array.isArray(value);
-}
 function toFiniteNumber(value) {
   if (typeof value === "number" && Number.isFinite(value)) return value;
   if (typeof value === "string" && value.trim().length > 0) {
@@ -1472,7 +1940,7 @@ function inferFailureCause(warnings) {
   return { cause: "not_found" };
 }
 function getOpenApiInfo(document) {
-  if (!isRecord4(document) || !isRecord4(document.info)) return void 0;
+  if (!isRecord3(document) || !isRecord3(document.info)) return void 0;
   if (typeof document.info.title !== "string") return void 0;
   return {
     title: document.info.title,
@@ -1515,15 +1983,15 @@ async function resolveGuidance(options) {
   };
 }
 function extractPathsDocument(document) {
-  if (!isRecord4(document)) return void 0;
-  if (!isRecord4(document.paths)) return void 0;
+  if (!isRecord3(document)) return void 0;
+  if (!isRecord3(document.paths)) return void 0;
   return document.paths;
 }
 function findMatchingOpenApiPath(paths, targetPath) {
   const exact = paths[targetPath];
-  if (isRecord4(exact)) return { matchedPath: targetPath, pathItem: exact };
+  if (isRecord3(exact)) return { matchedPath: targetPath, pathItem: exact };
   for (const [specPath, entry] of Object.entries(paths)) {
-    if (!isRecord4(entry)) continue;
+    if (!isRecord3(entry)) continue;
     const pattern = specPath.replace(/\{[^}]+\}/g, "[^/]+");
     const regex = new RegExp(`^${pattern}$`);
     if (regex.test(targetPath)) {
@@ -1539,11 +2007,11 @@ function resolveRef(document, ref, seen) {
   const parts = ref.slice(2).split("/");
   let current = document;
   for (const part of parts) {
-    if (!isRecord4(current)) return void 0;
+    if (!isRecord3(current)) return void 0;
     current = current[part];
     if (current === void 0) return void 0;
   }
-  if (isRecord4(current)) return resolveRefs(document, current, seen);
+  if (isRecord3(current)) return resolveRefs(document, current, seen);
   return current;
 }
 function resolveRefs(document, obj, seen, depth = 0) {
@@ -1552,20 +2020,20 @@ function resolveRefs(document, obj, seen, depth = 0) {
   for (const [key, value] of Object.entries(obj)) {
     if (key === "$ref" && typeof value === "string") {
       const deref = resolveRef(document, value, seen);
-      if (isRecord4(deref)) {
+      if (isRecord3(deref)) {
         Object.assign(resolved, deref);
       } else {
         resolved[key] = value;
       }
       continue;
     }
-    if (isRecord4(value)) {
+    if (isRecord3(value)) {
       resolved[key] = resolveRefs(document, value, seen, depth + 1);
       continue;
     }
     if (Array.isArray(value)) {
       resolved[key] = value.map(
-        (item) => isRecord4(item) ? resolveRefs(document, item, seen, depth + 1) : item
+        (item) => isRecord3(item) ? resolveRefs(document, item, seen, depth + 1) : item
       );
       continue;
     }
@@ -1575,15 +2043,15 @@ function resolveRefs(document, obj, seen, depth = 0) {
 }
 function extractRequestBodySchema(operationSchema) {
   const requestBody = operationSchema.requestBody;
-  if (!isRecord4(requestBody)) return void 0;
+  if (!isRecord3(requestBody)) return void 0;
   const content = requestBody.content;
-  if (!isRecord4(content)) return void 0;
+  if (!isRecord3(content)) return void 0;
   const jsonMediaType = content["application/json"];
-  if (isRecord4(jsonMediaType) && isRecord4(jsonMediaType.schema)) {
+  if (isRecord3(jsonMediaType) && isRecord3(jsonMediaType.schema)) {
     return jsonMediaType.schema;
   }
   for (const mediaType of Object.values(content)) {
-    if (isRecord4(mediaType) && isRecord4(mediaType.schema)) {
+    if (isRecord3(mediaType) && isRecord3(mediaType.schema)) {
       return mediaType.schema;
     }
   }
@@ -1592,7 +2060,7 @@ function extractRequestBodySchema(operationSchema) {
 function extractParameters(operationSchema) {
   const params = operationSchema.parameters;
   if (!Array.isArray(params)) return [];
-  return params.filter((value) => isRecord4(value));
+  return params.filter((value) => isRecord3(value));
 }
 function extractInputSchema(operationSchema) {
   const requestBody = extractRequestBodySchema(operationSchema);
@@ -1606,7 +2074,7 @@ function extractInputSchema(operationSchema) {
 }
 function parseOperationPrice(operation) {
   const paymentInfo = operation["x-payment-info"];
-  if (!isRecord4(paymentInfo)) return void 0;
+  if (!isRecord3(paymentInfo)) return void 0;
   const fixed = toFiniteNumber(paymentInfo.price);
   if (fixed != null) return `$${String(fixed)}`;
   const min = toFiniteNumber(paymentInfo.minPrice);
@@ -1616,23 +2084,12 @@ function parseOperationPrice(operation) {
 }
 function parseOperationProtocols(operation) {
   const paymentInfo = operation["x-payment-info"];
-  if (!isRecord4(paymentInfo) || !Array.isArray(paymentInfo.protocols)) return void 0;
+  if (!isRecord3(paymentInfo) || !Array.isArray(paymentInfo.protocols)) return void 0;
   const protocols = paymentInfo.protocols.filter(
     (protocol) => typeof protocol === "string" && protocol.length > 0
   );
   return protocols.length > 0 ? protocols : void 0;
 }
-function parseOperationAuthMode(operation) {
-  const authExtension = operation["x-agentcash-auth"];
-  if (isRecord4(authExtension)) {
-    const mode = authExtension.mode;
-    if (mode === "paid" || mode === "siwx" || mode === "apiKey" || mode === "unprotected") {
-      return mode;
-    }
-  }
-  if (isRecord4(operation["x-payment-info"])) return "paid";
-  return void 0;
-}
 function createResourceMap(result) {
   const map = /* @__PURE__ */ new Map();
   for (const resource of result.resources) {
@@ -1724,7 +2181,7 @@ async function inspectEndpointForMcp(options) {
     if (matched) {
       for (const candidate of OPENAPI_METHODS) {
         const operation = matched.pathItem[candidate.toLowerCase()];
-        if (!isRecord4(operation) || !isRecord4(document)) continue;
+        if (!isRecord3(operation) || !isRecord3(document)) continue;
         specMethods.push(candidate);
         const resolvedOperation = resolveRefs(document, operation, /* @__PURE__ */ new Set());
         const resource = resourceMap.get(toResourceKey(origin, candidate, matched.matchedPath));
@@ -1732,7 +2189,7 @@ async function inspectEndpointForMcp(options) {
         const operationSummary = typeof resolvedOperation.summary === "string" ? resolvedOperation.summary : typeof resolvedOperation.description === "string" ? resolvedOperation.description : void 0;
         const operationPrice = parseOperationPrice(resolvedOperation);
         const operationProtocols = parseOperationProtocols(resolvedOperation);
-        const operationAuthMode = parseOperationAuthMode(resolvedOperation);
+        const operationAuthMode = inferAuthMode(resolvedOperation) ?? "unprotected";
         const inputSchema = extractInputSchema(resolvedOperation);
         advisories[candidate] = {
           method: candidate,
@@ -2042,6 +2499,7 @@ export {
   LEGACY_SUNSET_DATE,
   STRICT_ESCALATION_CODES,
   UPGRADE_WARNING_CODES,
+  VALIDATION_CODES,
   auditContextHarness,
   buildContextHarnessReport,
   computeUpgradeSignal,
@@ -2049,7 +2507,9 @@ export {
   discover,
   discoverDetailed,
   discoverForMcp,
+  evaluateMetadataCompleteness,
   getHarnessClientProfile,
   inspectEndpointForMcp,
-  listHarnessClientProfiles
+  listHarnessClientProfiles,
+  validatePaymentRequiredDetailed
 };