@agentcash/discovery 0.1.0

package/.claude/CLAUDE.md

@@ -0,0 +1,24 @@
+# CLAUDE.md
+
+This package is the canonical discovery runtime for agentcash.
+
+## Core decisions
+
+- OpenAPI is canonical machine discovery source.
+- Discovery order: override -> OpenAPI -> `/.well-known/x402` -> DNS `_x402` -> probe.
+- `discover` is progressive and token-light.
+- `discoverDetailed` is full-waterfall with trace.
+- Compatibility adapters are isolated and removable.
+- `llms.txt` is unstructured guidance only; OpenAPI carries machine metadata.
+
+## Important defaults
+
+- `compatMode = on` (until legacy sunset window ends).
+- `verified = false` in advisory output.
+- `trustTier` values: `unverified | origin_hosted | ownership_verified | runtime_verified`.
+
+## Do not do
+
+- Do not leak legacy branches into canonical parser logic.
+- Do not introduce hidden fallback passes.
+- Do not change warning codes without a breaking version decision.

package/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+## Purpose
+
+This repo implements canonical discovery logic for the agentcash ecosystem.
+
+## Hard Constraints
+
+1. Keep canonical core and compatibility modules physically separate.
+2. Avoid legacy conditionals in `src/core/*`.
+3. Preserve stable warning codes.
+4. Keep `discover` token-light and deterministic.
+5. Keep compatibility removable via a single top-level mode.
+
+## Module Boundaries
+
+- `src/core/*`: canonical OpenAPI-first discovery.
+- `src/compat/legacy-x402scan/*`: `/.well-known/x402` + DNS `_x402` compatibility.
+- `src/compat/interop-mpp/*`: optional registry interop adapter.
+
+## Result Contract
+
+Resource identity is always `origin + method + path`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Merit Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @agentcash/discovery
+
+Canonical discovery library for the agentcash ecosystem.
+
+## What It Solves
+
+- One deterministic discovery contract across `agentcash`, `agentcash-router`, `the-stables`, and scanners.
+- OpenAPI-first discovery with explicit compatibility fallbacks.
+- Progressive runtime output (`discover`) and full debug/indexer output (`discoverDetailed`).
+
+## Discovery Order
+
+Default order is:
+
+1. explicit override URLs (if provided)
+2. OpenAPI (`/openapi.json`, then `/.well-known/openapi.json`)
+3. `/.well-known/x402` (compat path)
+4. DNS TXT `_x402` pointers (compat path)
+5. live probe fallback (only when probe candidates are provided)
+
+`discover` stops on the first valid non-empty stage.
+
+`discoverDetailed` runs the full waterfall and merges deterministically.
+
+## Install
+
+```bash
+pnpm add @agentcash/discovery
+```
+
+CLI audit:
+
+```bash
+npx @agentcash/discovery stabletravel.dev
+npx @agentcash/discovery stabletravel.dev -v
+npx @agentcash/discovery stabletravel.dev --json
+```
+
+## Usage
+
+```ts
+import { discover, discoverDetailed } from '@agentcash/discovery';
+
+const result = await discover({
+  target: 'https://api.example.com',
+  compatMode: 'on',
+});
+
+const detailed = await discoverDetailed({
+  target: 'api.example.com',
+  compatMode: 'strict',
+  rawView: 'full',
+  includeInteropMpp: true,
+  txtResolver: async (fqdn) => {
+    // Provide DNS TXT lookup in your runtime.
+    return [];
+  },
+});
+```
+
+## Key API
+
+- `discover(options)`: token-light, progressive, first-valid-non-empty.
+- `discoverDetailed(options)`: full trace/details, merge across stages, optional raw artifacts.
+- Both results include:
+- `upgradeSuggested` (`boolean`)
+- `upgradeReasons` (`string[]` warning-code reasons such as legacy-path usage)
+
+## Compatibility Controls
+
+- `compatMode: 'on'` (default): enable legacy adapters.
+- `compatMode: 'off'`: disable all legacy adapters.
+- `compatMode: 'strict'`: enable legacy adapters and escalate legacy warnings to errors.
+
+## Internal Registry Audit Harness
+
+Use this to benchmark compatibility against the x402scan registry dataset.
+
+```bash
+SCAN_DATABASE_URL='postgresql://...' pnpm audit:registry
+```
+
+Quick sample mode:
+
+```bash
+SCAN_DATABASE_URL='postgresql://...' pnpm audit:registry:quick
+```
+
+Outputs are written to:
+
+- `audit/registry-audit-<timestamp>.json`
+- `audit/registry-audit-latest.json`
+
+## Canonical Contract
+
+Each normalized resource key is:
+
+```text
+${origin} ${method} ${path}
+```
+
+Required per-resource fields:
+
+- `resourceKey`
+- `origin`
+- `method`
+- `path`
+- `source`
+- `verified` (defaults to `false`)
+
+## Philosophy Boundary
+
+- Machine-parsable discovery metadata lives in OpenAPI.
+- `llms.txt` is unstructured, optional domain guidance.
+- Discovery is advisory. Runtime challenge/probe is authoritative.

package/bin/discovery.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { main } from '../dist/cli.js';
+
+const exitCode = await main(process.argv.slice(2));
+process.exit(exitCode);