taximeter 0.1.1 → 0.1.2

package/CONTRIBUTING.md

@@ -1,141 +0,0 @@
-# Contributing to Taximeter
-
-Taximeter observes agent payments, records them locally, and gates supported
-authorizations against budgets. Start with [SPEC.md](SPEC.md), then read
-[SPEC-NOTES.md](SPEC-NOTES.md) for the supported protocol and
-[DECISIONS.md](DECISIONS.md) for implementation choices.
-
-## Development
-
-Use Node.js 20 or 22 and npm. The package is TypeScript with ESM exports. CI is
-configured for both Node versions on Linux and Windows. Dependencies and tooling
-are pinned; keep `package-lock.json` consistent with `package.json`.
-
-From a checkout, run the same sequence as CI:
-
-```sh
-npm ci
-npm run typecheck
-npm run lint
-npm test
-npm run build
-npm pack
-npm run check:package
-npm run smoke:package
-git status --porcelain
-```
-
-The build creates the Node package in `dist/` and the prebuilt React dashboard in
-`dist/ui/`. A package consumer must not need to build the dashboard. On a clean
-checkout, the final command must print nothing. During development, it should
-show only your intentional changes. Do not commit generated bundles, coverage,
-tarballs, local configuration, or SQLite state.
-
-Use `npm run format` to apply Biome formatting. Keep LF line endings as specified
-in `.gitattributes`. Check the package contents and compressed size with
-`npm pack --dry-run`; the release tarball must stay below 2 MB.
-
-## Changes that preserve trust
-
-- Preserve unknown HTTP traffic byte for byte. Record a diagnostic when a format
-  cannot be parsed; do not guess the payment fields or rewrite its payload.
-- Store monetary amounts as integer strings. Use `BigInt` for arithmetic and
-  convert to a display string only at the rendering edge. Never combine assets
-  or networks, infer exchange rates, or use floating point for money.
-- Parse external inputs with Zod. Keep strict TypeScript types and
-  `noUncheckedIndexedAccess`; do not introduce `any` to silence a type error.
-- Keep policy and ledger derivations pure and synchronous. Evaluate policy and
-  reserve capacity within the same SQLite transaction before forwarding.
-- Keep events and outcomes append-only. Preserve uncertainty, retry identity,
-  concurrent attempt accounting, and original attribution.
-- Never add custody, private-key handling, payment signing, settlement,
-  telemetry, hosted accounts, or runtime metadata lookups. Runtime networking
-  is limited to forwarding the caller's traffic and the local dashboard.
-
-Read the primary x402 specification and published package types before changing
-a wire parser. Record changed assumptions and supported subsets in
-`SPEC-NOTES.md`. An internal model field is not necessarily a protocol field.
-
-## Tests and review
-
-For policy changes, write the failing behavioral test first. Add regressions for
-traffic corruption, arithmetic, replay, concurrency, and settlement failures when
-changing those paths. Keep policy and ledger coverage at least 90%; coverage is
-a floor, not a substitute for asserting observable behavior.
-
-Fixtures use synthetic authorizations and localhost servers. Tests must not
-require wallets, keys, funds, a facilitator, or an external API. Keep cleanup
-bounded to directories created by the test. Dashboard changes should be checked
-in light and dark themes at both desktop and narrow mobile widths.
-
-Golden CSV snapshots live in `test/__snapshots__/`. Regenerate a snapshot only
-for an intentional output change that is explained in the pull request and
-accepted in review. Never update a snapshot, remove a test, or relax an assertion
-simply to make a failure disappear.
-
-Open a focused pull request with the problem, resulting behavior, and actual
-validation results. Explain compatibility changes and known limitations. Use
-Conventional Commits, such as `fix(proxy): preserve response trailers`. Update
-the relevant docs when behavior or configuration changes. Report vulnerabilities
-privately as described in [SECURITY.md](SECURITY.md).
-
-## Versioning and releases
-
-For a user-visible change, run `npm run changeset` and commit the generated
-changeset with the change. Describe its effect on users and choose the appropriate
-version bump. Documentation-only changes may omit a changeset when they do not
-change package behavior.
-
-The release workflow uses Changesets on `main` to prepare version changes and
-publish after the release pull request is merged. With no pending changesets,
-the action also publishes the current version if npm does not yet contain it.
-A push to `main` with working npm credentials can therefore publish directly.
-Maintainers configure npm credentials separately.
-`npm run version-packages` updates package versions and
-the changelog; `npm run release` builds and runs Changesets publishing. Publishing
-requires maintainer authorization and credentials. The presence of that workflow
-does not mean any package version has already been published.
-
-### npm publishing credentials
-
-The current workflow uses token authentication. Create an npm **granular access
-token** with package **Read and write** permissions and **Bypass two-factor
-authentication** enabled for unattended publishing. Give it permission to publish
-the intended package and an appropriate expiration. Follow the
-[npm token setup instructions](https://docs.npmjs.com/creating-and-viewing-access-tokens/).
-
-For the first publication of a new unscoped package, it cannot yet be selected
-individually in npm's token settings. A temporary bootstrap token needs the
-**All Packages** selection to permit creating it. Replace it with a token limited
-to `taximeter` after the package exists, or use trusted publishing for later releases.
-
-In the repository's **Settings → Secrets and variables → Actions**, add a
-**repository secret** named exactly `NPM_TOKEN`. Use the token as its value.
-An Actions variable or a Dependabot secret will not populate `secrets.NPM_TOKEN`.
-An environment secret needs a matching job environment; this workflow does not
-select one. Organization secrets must grant this repository access. See
-[GitHub's Actions secret instructions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions).
-
-`changesets/action@v1` configures npm authentication from this secret. Its publish
-hook checks that the secret is present and that npm accepts the credentials
-before building or publishing. This identity check does not prove package write
-permission or 2FA bypass; npm validates those during publication. Version PRs
-can still be prepared without npm credentials. Do not commit a token to `.npmrc`
-or paste one into an issue or chat.
-
-After adding or correcting the secret, rerun the failed Release job. A local
-`npm login` does not authenticate a GitHub-hosted runner. `ENEEDAUTH` combined
-with `No NPM_TOKEN or OIDC available` means the runner received no usable
-authentication; the successful build and dependency-comment warnings do not
-resolve that missing configuration.
-
-Trusted publishing is a separate setup, not enabled by adding `GITHUB_TOKEN`.
-It requires npm-side trust, a supported npm CLI, and `id-token: write` on the
-workflow. The present hook deliberately requires `NPM_TOKEN`; migrate both the
-hook and workflow together when adopting
-[npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
-The package must already exist before trust can be configured; see the
-[npm trust prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust/).
-
-Contributions are provided under the project's [MIT license](LICENSE). Follow the
-[code of conduct](CODE_OF_CONDUCT.md) in issues, reviews, and other project spaces.

package/DECISIONS.md

@@ -1,54 +0,0 @@
-# Decisions
-
-- 2026-09-08 — The hosted release log passed the build but failed with npm `ENEEDAUTH`; Changesets explicitly reported neither `NPM_TOKEN` nor OIDC. Keep the existing token-based authentication route and add a publish-only presence/identity check, preserving credential-free version PR creation. Document the exact repository-secret setup. A local code change cannot supply the owner's npm credential, and an identity check cannot attest package write permissions.
-- 2026-09-08 — Replace the SPEC §6 demo placeholder with a 20-second Windows terminal recording. Native ConPTY capture and the standalone agg renderer work without WSL. Only the compact GIF ships in the package; capture tools and intermediate files remain local development artifacts.
-- Release packaging includes all relative README/SDK/contributor documentation targets and the example configuration. The package checker verifies these links and the explicit whitelist; source trees, tests, local state, and UI source maps stay excluded.
-- The release workflow can publish the first unpublished version on a credentialed `main` push when no changesets remain. Contributor instructions identify this initial-release behavior; no push or registry publication is performed during local verification.
-- The demo's unpaid v2 challenge branch is exercised before its signed synthetic replays, including the required `resource.url`, so demonstration code follows the same verified protocol contract.
-
-Recorded through the implementation audit on **2026-09-08**. The consolidated
-deviation inventory and detailed protocol evidence are in
-[SPEC-NOTES.md](SPEC-NOTES.md#implemented-deviations-and-release-limits).
-This log records the reasons for those choices and corrections made during the
-build; successful verification output belongs in [VERIFICATION.md](VERIFICATION.md).
-
-- 2026-09-08 — Work follows SPEC §8 on `feat/taximeter-v0.1.0`; each numbered step gets a full passing suite and a Conventional Commit.
-- Pin better-sqlite3 12.8.0: version 13 requires Node 22, while this release promises Node 20 support.
-- ESM only: a second CJS runtime adds packaging complexity without serving the primary CLI or modern fetch integrations.
-- Runtime requests are limited to forwarding traffic and the local dashboard API. Development dependency installation and protocol research are build activities.
-- Biome's automatic configuration migration emitted `preset: none`; corrected it to `recommended` immediately so lint remains a real quality gate.
-- Initial dependency audit found advisories in uuid 11.1.0 and tsup's esbuild 0.27.x. Pin uuid 11.1.1 and override tsup's esbuild to 0.28.1; validate with the full suite and build. Keep Changesets 2.x for Node 20 compatibility.
-- SQLite adds append-only `outcomes` and `diagnostics` tables beside `events`; this preserves original payment authorizations while recording settlement uncertainty and parser diagnostics. The migration is bundled as text from the tracked SQL source.
-- Idempotency binds the network/asset/payer/nonce identity to immutable authorization details; conflicting authorizations receive separate conservative reservations rather than bypassing policy through nonce reuse.
-- Zod 4 applies inner defaults even through `.partial()`. Configuration patch schemas therefore have no defaults; a regression test verifies later layers cannot reset earlier sibling options.
-- Independent ledger tests initially expected checksum-case output and `settlement_unknown: true` on blocked rows. Correct those expectations: EVM identities are canonical lowercase, and a replay blocked before forwarding has no uncertain settlement. Exact-value and deduplication assertions remain intact.
-- Track individual forwarding attempts in append-only outcomes. Any unresolved attempt retains capacity; confirmation anywhere wins. An unconfirmed retry outside a rolling window must reacquire capacity, with `attemptedAt` separate from the original immutable timestamp.
-- Runtime storage failures fail open and emit a visible local stderr warning: preserving the agent's traffic is the stated highest priority. Budget guarantees require working local storage. The original reservation survives a failed outcome write.
-- CLI precedence is flags > environment > explicit `--config` file > cwd file > home file > defaults. Relative database paths resolve against cwd; `~` expands locally. Explicit config files layer rather than replace lower-priority settings.
-- `reset --yes` archives the database under an atomic CLI lock. Stop all SDK writers first; the CLI lock coordinates CLI instances, while SQLite coordinates payment reservations. Reports, exports, and doctor use an in-memory empty ledger when the requested path does not yet exist, avoiding accidental file creation.
-- CSV includes every derived payment row. `amount` is its counted contribution (zero for blocked rows and authorizations whose known attempts all failed); `authorizedAmount` preserves the original proposal. Sum `amount` separately by network/asset to reproduce dashboard ledger totals. Formula-like text cells are escaped; monetary cells remain exact integer strings. Invoice export is a standalone printable HTML statement, with no PDF generation or claim of independent settlement verification.
-- SDK inspection clones only legacy 402 bodies, capped at 64 KiB and 100 ms, then returns the original response object. Slow/oversized unknown challenges are diagnosed and passed through. Request bodies are never consumed by the meter. Put `withMeter` inside the payment wrapper so signed retries are visible.
-- Dashboard reads share the ledger derivations and exact CSV accounting. The loopback API rejects foreign Host/Origin values, cross-site requests, mutations, ambiguous duplicate query options, and paths outside its bundled UI directory.
-- Dashboard typography uses system grotesque and monospace stacks: remote Google Fonts would violate the runtime network invariant. Financial chart coordinates and proportional widths use BigInt and become strings only when rendered.
-- The SDK cannot observe redirects or retries inside the supplied fetch transport. Preserve transport behavior, diagnose visible redirects, and avoid correlating redirected v1 challenges to the initial URL. Host-sensitive callers can request `redirect: "error"` or expose each hop to the wrapper.
-- Release review found truncated rejected-upgrade responses could leave clients hanging. Add a failing regression first, then mirror the ordinary response's abort/error cleanup.
-- Preserve the original HTTP request path and query while validating the routing authority separately. WHATWG URL normalization of encoded dot segments would otherwise change opaque or signature-sensitive traffic; HTTP and upgrade regressions cover both proxy modes.
-- The first dashboard shows the latest 30 events and a trailing 24-hour timeline. Rows remain readable and tables scroll on shorter or narrow screens; exact totals and clear settlement labels take priority over fitting every row into every viewport.
-
-## Scope and release audit
-
-- Support `exact` EVM EIP-3009 only: v1 `base` and `base-sepolia`, and v2 positive `eip155:<chain-id>` networks. Permit2, ERC-7710, and other transfer methods have different authorization semantics and stay transparent with diagnostics. Optional or variable-length signatures are structurally accepted according to the published 2.25.0 types; Taximeter never verifies them.
-- Bound v1 challenge context to URL, method, task, agent, Authorization, and Cookie, with a five-minute TTL and at most 1,000 contexts per intake instance. Require an unambiguous matching asset. This avoids inventing missing replay fields or sharing challenges across distinct request identities. The SDK does not cache redirected challenges under the original URL.
-- Limit inspected v1 bodies to 64 KiB and encoded payment header text to 65,536 characters. The SDK additionally stops challenge observation after 100 ms. The proxy streams its bounded body tap without holding the response; compressed legacy challenges pass through unmetered. These limits prioritize intact, responsive traffic over metering every possible challenge.
-- Keep local metadata only for Base and Base Sepolia USDC. Unknown assets use exact atomic strings with `decimalsKnown: false`; `decimals: 0` is an internal placeholder, never a token-metadata claim. Runtime metadata, RPC, and price calls would violate the network invariant.
-- Keep every budget separate by network and asset contract. `maxSingleAsset: "USDC"` makes the scalar per-payment cap's scope explicit, and optional budget `network` narrows a rule. Add nullable budgets/caps and fixed `1h`, `24h`, `7d`, and `30d` windows without introducing exchange rates or cross-chain combined balances.
-- Matching settlement evidence must use the event's network and, when provided, its payer and amount. A reported success with a nonempty transaction can confirm on any response status; an explicit failure on a 5xx remains uncertain. Missing evidence, disconnects, and malformed responses retain the reservation. Confirmation on any attempt wins over later contradictions; otherwise an unresolved attempt wins over a failed attempt.
-- Interpret explicit `upstream` as an origin: an incoming origin-form path replaces any configured path prefix. Preserve encoded path/query bytes while keeping leading `//` on that fixed origin. This rule is documented so callers do not silently route `/weather` to an assumed `/v1/weather`.
-- Forward HTTPS CONNECT as an unmetered encrypted tunnel, with no certificate installation or TLS interception. Gate recognized signed HTTP upgrade handshakes but do not claim to inspect subsequent stream frames. Payload-byte transparency excludes hop-by-hop headers and transfer framing that an HTTP proxy must reconstruct.
-- Keep the dashboard timeline to the current UTC hour plus the preceding 23 hourly buckets; do not invent a persistent process-session model. Show each asset's active global budget separately from the all-time ledger total. Show 30 recent events and 10 recent diagnostics; keep original payment JSON in JSON export rather than the live summary API.
-- Add `TAXIMETER_DB`, `TAXIMETER_PORT`, and `TAXIMETER_DASHBOARD_PORT` between explicit flags and configuration files. This follows the brief's environment-variable naming while making precedence explicit. Allow port `0` for local tests and ephemeral listeners. An injected SDK ledger uses supplied configuration plus defaults, avoiding hidden user-file dependencies for embedded callers.
-- `doctor` is deliberately local. With a nonexistent database it checks an empty in-memory SQLite ledger and configuration; it does not claim to test that future path's write permissions, wallet access, or upstream/facilitator readiness. Existing malformed config remains a visible error.
-- Protocol fixtures use deterministic synthetic authorizations and settlement results derived from documented envelopes. A structural parser test is not a real payment, wallet integration, or chain-settlement test. Record this boundary instead of presenting synthetic fixture success as live-network proof.
-- Rechecked the npm name on **2026-09-08**: `npm view taximeter` returned `E404`, so no fallback name was needed. The README keeps the required `npx taximeter start` command and labels registry publication as pending; source quickstart commands use `npm ci`, `npm run build`, and `node dist/cli/index.js start`. Validate the local `taximeter-0.1.0.tgz` in a fresh temporary directory before claiming packaged startup; record the actual result in `VERIFICATION.md`.
-- Generate the initial `CHANGELOG.md` with Changesets using a transient, uncommitted `0.0.0` version and an initial minor changeset, then restore the intended `0.1.0` through `npm run version-packages` and resynchronize the lockfile. This produces a generated changelog without changing the release version or rewriting commit history. The demo uses local synthetic payments: its recording script demonstrates 20 accepted payments and a blocked twenty-first payment without making a transfer. The initial GIF placeholder was subsequently replaced by the Windows recording documented above.
-- Repository visibility, description, and npm publication are maintainer-managed release settings. The intended repository description is **A taximeter for your AI agents.** A successful local build does not establish that registry publication or repository configuration has completed.

package/SPEC-NOTES.md

@@ -1,369 +0,0 @@
-# Protocol verification notes
-
-Research date: **2026-09-08**. These notes record the protocol baseline read before
-implementation, the supported subset, and corrections to [SPEC.md](SPEC.md).
-Amounts below are atomic integer strings. Taximeter does not sign, verify, or
-settle a payment.
-
-## Implemented deviations and release limits
-
-This is the release's consolidated deviation inventory. The detailed wire shapes
-and source evidence follow below; these limits apply to both the CLI and SDK
-unless a row names one intake specifically.
-
-| Area in the brief | Implemented behavior and reason |
-| --- | --- |
-| Demo placeholder (§6) | The original placeholder is replaced by a 20-second Windows ConPTY recording rendered by agg. The simulation runs locally; no payment is signed or settled. Only the GIF ships in the package; capture tools and intermediate files are local development artifacts. |
-| Broad x402 support (§2, §4) | Support HTTP v1/v2 `exact` EVM **EIP-3009** authorizations. v1 maps only `base` and `base-sepolia`; v2 accepts positive `eip155:<chain-id>` identifiers. Permit2, ERC-7710, other transfer methods, schemes, and networks are diagnosed and passed through. Their different authorization semantics cannot safely share this parser. |
-| Generic 402 JSON and complete replay context (§0, §2) | v1 reads the challenge body and `X-PAYMENT`; v2 reads `PAYMENT-REQUIRED` and `PAYMENT-SIGNATURE`. v1 replays omit asset context and need a previously observed, unambiguous challenge. v2 replays carry `accepted`. A status of 402 alone does not establish x402. |
-| Unbounded challenge observation (§4) | v1 correlation is local to each intake instance, with a five-minute TTL and at most 1,000 cached contexts. The key binds actual URL, method, task, agent, Authorization, and Cookie. Bodies are limited to 64 KiB; payment header text is limited to 65,536 characters. The proxy taps the streaming response without delaying delivery; the SDK additionally limits its cloned body observation to 100 ms. Missing, expired, oversized, slow, compressed proxy bodies, and ambiguous challenges cannot be metered reliably and pass through with a diagnostic. |
-| Token metadata in every event (§3) | Only Base and Base Sepolia USDC have trusted, static six-decimal metadata. Other assets retain exact amounts with `decimalsKnown: false` and an internal `decimals: 0` placeholder; displays say **atomic units**, not zero-decimal tokens. No RPC, token-list, or price lookup runs at runtime. |
-| One USDC balance and scalar maximum (§3) | Every total and budget is scoped separately by normalized network and contract. Symbol budgets match the local registry. `maxSingleAsset`, default `USDC`, scopes `maxSinglePayment`; unknown assets do not inherit a misleading one-USDC threshold. Optional budget `network` narrows a rule further. |
-| One `events` table and the original event fields (§3) | Keep immutable events and add append-only `outcomes` and `diagnostics` tables. Internal fields include `paymentKey`, `decimalsKnown`, `settlementStatus`, `settlement_unknown`, and derived `attemptedAt`; outcomes identify each forwarding attempt. These are Taximeter fields, not invented x402 wire fields. |
-| Deduplication by nonce/transaction/resource within a small window (§4) | A persistent key binds network, asset, payer, nonce, amount, recipient, and both authorization validity bounds. Signature, resource, and observation time are excluded. The same authorization counts once across retries and URLs; changed immutable authorization details retain a separate conservative reservation. |
-| Observed payments equal settled spend (§3, §4) | Reserve recognized authorizations synchronously in the same SQLite transaction as policy evaluation, before forwarding. Upstream-reported success is confirmation evidence, not independent settlement verification. Any confirmed attempt wins; otherwise any unresolved attempt retains capacity. Only an authorization whose known attempts all failed contributes zero. |
-| Retry timing and upstream failure (§4) | `attemptedAt` separates the latest unconfirmed forwarding attempt from immutable `ts`. An unconfirmed replay outside a rolling budget window must reacquire capacity. Missing settlement headers, disconnects, and unconfirmed 5xx responses remain unknown; an explicit matching success header can confirm even on a non-2xx response. |
-| Storage failure while preserving traffic (§4) | Runtime ledger/policy-intake storage failures fail open and emit a visible local warning plus a diagnostic when storage permits. A failed outcome write leaves its original reservation in place. Budget enforcement requires working storage; startup/configuration failures still fail visibly rather than claiming a working service. |
-| Universal zero-code proxy support (§2) | Clients must actually honor their proxy configuration. HTTPS CONNECT is an encrypted byte tunnel and is explicitly unmetered; Taximeter installs no certificate authority. An explicit localhost route with `--upstream`, or the SDK inside the payment wrapper, can inspect HTTP payment messages sent to HTTPS upstreams. |
-| Explicit base URL semantics (§2) | Origin-form requests require `upstream`. Its **origin** supplies the destination; the incoming path replaces any configured upstream path prefix. For example, upstream `https://api.example/v1` plus `/weather` forwards to `https://api.example/weather`. Leading `//` stays on the configured origin. Original encoded paths and query text are preserved separately from URL authority validation. |
-| Byte-identical forwarding and upgraded protocols (§4) | Preserve request/response payload bytes, duplicate end-to-end headers, and trailers, while rebuilding HTTP hop-by-hop headers and transfer framing as a proxy must. Recognized signed HTTP upgrade handshakes can be gated; subsequent upgraded stream frames are unmetered and diagnosed. CONNECT and upgrades do not imply inspection of payments hidden in their streams. |
-| Wrapping an arbitrary payment-enabled fetch (§2) | Compose `wrapFetchWithPayment(withMeter(fetch, options), client)` so each signed replay reaches the meter. The supplied transport's internal retries and redirects are invisible. A response marked `redirected` emits a visibility diagnostic and is never cached as a v1 challenge for the original URL. Host-sensitive callers can request `redirect: "error"` or expose each hop. The wrapper returns the original response and never consumes a request body. |
-| Configuration precedence (§3) | Extend precedence to flags > `TAXIMETER_*` environment > explicit `--config` file > cwd file > home file > defaults. The explicit file layers over automatic files. Environment support is exactly `TAXIMETER_DB`, `TAXIMETER_PORT`, and `TAXIMETER_DASHBOARD_PORT`. Relative database paths resolve from cwd; `~` expands locally. |
-| Additional configuration choices (§3) | `upstream` supports explicit routing; budget windows support `1h`, `24h`, `7d`, and `30d`; nullable budgets and `maxSinglePayment` disable their respective rules; port `0` requests an available port. Config and CLI options remain strict Zod inputs. Host/recipient allowlists are exact, case-insensitive matches, not wildcard patterns. |
-| Reset and local checks (§2) | `reset --yes` archives rather than deletes the ledger and acquires an atomic CLI lock. All SDK writers must be stopped separately; the lock coordinates CLI instances only. Read-only commands use an empty in-memory ledger when the path is absent. `doctor` checks local configuration and SQLite without requesting any upstream; it does not certify wallet/facilitator access or write permission for a nonexistent database path. |
-| Dashboard session and hero (§5) | Timeline shows the current UTC hour and preceding 23 hourly buckets, not an arbitrary process session. The Now hero shows the selected asset's active global budget window; all-time ledger totals are labeled separately. Assets and networks never share one monetary chart total. The latest 30 events and 10 diagnostics are shown; raw payment JSON remains available in JSON export. |
-| Thirty visible rows and Google Fonts (§5) | The event stream keeps 30 recent rows, with scrolling where screen height or width requires it. System grotesque and monospace stacks replace runtime Google Fonts requests to honor the network invariant. Complete light/dark tokens and exact BigInt-derived chart geometry are retained. |
-| Export and invoice format (§2, §5) | CSV includes all derived payment rows: `amount` is the counted contribution, while `authorizedAmount` preserves the original proposal. Blocked and wholly failed payments contribute zero. Sum each network/asset separately to reproduce the dashboard ledger totals. The invoice is standalone printable HTML, with no PDF renderer, exchange-rate conversion, tax calculation, or settlement attestation. |
-| Module and dependency choices (§7) | Ship ESM only, with no optional CommonJS build. Pin `better-sqlite3` 12.8.0 to preserve Node 20 support; version 13 requires Node 22. Exact pins and the audited esbuild override are recorded in `package.json` and the lockfile. |
-| Fixture realism and financial claims (§7) | Fixture envelopes follow primary protocol examples but all authorizations, signatures, and settlement responses are synthetic. Tests exercise parsing, transport, budget races, failures, and exact accounting; no real transfers, wallet signing, facilitator call, or independent chain verification is performed. |
-| Public installation and repository tagline (§1, §6) | The initial registry check returned `E404`; npm ownership was subsequently established with `0.1.0`. The release package uses `0.1.1`, and the README provides both `npx taximeter start` and source-build instructions. Fresh-directory startup from the local tarball is documented in `VERIFICATION.md`. Repository visibility is a maintainer-managed setting. The intended repository description is **A taximeter for your AI agents.** |
-
-These limitations make Taximeter a cooperative local meter. An agent that
-bypasses the intake, uses an unsupported payment method, or hides a replay
-inside a transport can bypass its budget checks. No supported flow holds funds,
-private keys, or payment-signing authority.
-
-## Primary sources and published packages
-
-The requested [Coinbase repository README](https://github.com/coinbase/x402/blob/main/README.md)
-now identifies Coinbase's repository as a development fork and points to the
-[x402 Foundation repository](https://github.com/x402-foundation/x402) as the project
-home. The requested files were read, together with the Foundation specifications,
-the HTTP transport specification, documentation, and actual npm tarballs:
-
-- [Protocol v1](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v1.md)
-  and [protocol v2](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md).
-- [Requested Coinbase v2 specification](https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md)
-  and [exact EVM scheme](https://github.com/coinbase/x402/blob/main/specs/schemes/exact/scheme_exact_evm.md).
-- [HTTP v2 transport](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md).
-- [x402 documentation](https://docs.x402.org/introduction),
-  [migration guide](https://docs.x402.org/guides/migration-v1-to-v2),
-  [network and token support](https://docs.x402.org/core-concepts/network-and-token-support),
-  [exact scheme](https://docs.x402.org/schemes/exact), and
-  [payment identifier extension](https://docs.x402.org/extensions/payment-identifier).
-
-All four published packages resolved to **2.25.0**. Their tarballs were downloaded
-with `npm pack`, extracted outside the repository, and their READMEs, package
-exports, and relevant exported declarations were inspected. These are research
-inputs, not runtime dependencies of Taximeter.
-
-| Package | Published API inspected | Relevant finding |
-| --- | --- | --- |
-| [@x402/core 2.25.0](https://www.npmjs.com/package/@x402/core/v/2.25.0) | `types`, `types/v1`, `schemas`, `client`, `http`, `server` | Both protocol versions; header helpers; optional fields differ between nominal types and runtime schemas. |
-| [@x402/evm 2.25.0](https://www.npmjs.com/package/@x402/evm/v/2.25.0) | Main types, `exact/client`, `exact/server`, `exact/facilitator`, `v1` | EIP-3009 and Permit2 payloads; legacy network map; local default-asset metadata. |
-| [@x402/fetch 2.25.0](https://www.npmjs.com/package/@x402/fetch/v/2.25.0) | `wrapFetchWithPayment`, `wrapFetchWithPaymentFromConfig` | The supplied fetch is called for the initial request and each signed replay. |
-| [@x402/express 2.25.0](https://www.npmjs.com/package/@x402/express/v/2.25.0) | `paymentMiddleware`, `paymentMiddlewareFromConfig`, `paymentMiddlewareFromHTTPServer`, `ExpressAdapter` | Middleware verifies and settles; Taximeter must not adopt that facilitator role. |
-
-The pinned package declarations can also be inspected at
-[@x402/core types](https://unpkg.com/@x402/core@2.25.0/dist/esm/types/index.d.mts),
-[@x402/core v1 types](https://unpkg.com/@x402/core@2.25.0/dist/esm/types/v1/index.d.mts),
-[@x402/evm types](https://unpkg.com/@x402/evm@2.25.0/dist/esm/index.d.mts),
-[@x402/fetch types](https://unpkg.com/@x402/fetch@2.25.0/dist/esm/index.d.mts), and
-[@x402/express types](https://unpkg.com/@x402/express@2.25.0/dist/esm/index.d.mts).
-
-## HTTP wire formats
-
-HTTP header names are case-insensitive. Payment headers contain Base64-encoded
-UTF-8 JSON, not the signature alone. A response is not necessarily x402 just
-because its status is 402.
-
-| Message | v1 | v2 |
-| --- | --- | --- |
-| Payment requirements | JSON response body with `x402Version: 1` | `PAYMENT-REQUIRED` response header with `x402Version: 2` |
-| Signed payment replay | `X-PAYMENT` request header | `PAYMENT-SIGNATURE` request header |
-| Settlement result | `X-PAYMENT-RESPONSE` response header | `PAYMENT-RESPONSE` response header |
-
-In v2, the response body is application content. It may be empty, JSON, HTML, or
-another media type. It is not the authoritative location of payment requirements.
-The published HTTP client checks `PAYMENT-REQUIRED` first and uses a v1 body only
-as the compatibility fallback. It recognizes both settlement header names.
-[HTTP transport source](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md)
-
-### v1 envelopes
-
-The following notation uses `?` for optional fields and describes the wire shape,
-not a TypeScript import from a payment SDK:
-
-```text
-PaymentRequiredV1 {
-  x402Version: 1,
-  error?: string,
-  accepts: PaymentRequirementsV1[]
-}
-
-PaymentRequirementsV1 {
-  scheme: string,
-  network: string,
-  maxAmountRequired: string,
-  resource: string,
-  description: string,
-  mimeType?: string,
-  outputSchema?: object | null,
-  payTo: string,
-  maxTimeoutSeconds: number,
-  asset: string,
-  extra?: object | null
-}
-
-PaymentPayloadV1 {
-  x402Version: 1,
-  scheme: string,
-  network: string,
-  payload: object
-}
-```
-
-The v1 specification's field table requires `error`; the published 2.25.0 Zod
-schema makes it optional. Its `mimeType`, `outputSchema`, and `extra` are also
-optional even though the nominal declaration is stricter. Taximeter follows the
-compatible runtime shape for these fields. `accepts` must contain at least one
-option; `maxTimeoutSeconds` is a positive number.
-
-Legacy networks use names such as `base` and `base-sepolia`. A v1 signed replay
-does **not** carry `asset`, `resource`, `accepted`, or `maxAmountRequired` at its
-top level. The preceding challenge supplies that missing context.
-[v1 source](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v1.md)
-
-### v2 envelopes
-
-```text
-ResourceInfo {
-  url: string,
-  description?: string,
-  mimeType?: string
-}
-
-PaymentRequirementsV2 {
-  scheme: string,
-  network: string,
-  amount: string,
-  asset: string,
-  payTo: string,
-  maxTimeoutSeconds: number,
-  extra?: object | null
-}
-
-PaymentRequiredV2 {
-  x402Version: 2,
-  error?: string,
-  resource: ResourceInfo,
-  accepts: PaymentRequirementsV2[],
-  extensions?: object | null
-}
-
-PaymentPayloadV2 {
-  x402Version: 2,
-  resource?: ResourceInfo,
-  accepted: PaymentRequirementsV2,
-  payload: object,
-  extensions?: object | null
-}
-```
-
-The v2 amount field is `amount`, not v1's `maxAmountRequired`. The selected option
-is `accepted`, not `accepts`. The required-response resource is a separate object;
-the replay's resource is optional. Networks use CAIP-2 identifiers such as
-`eip155:8453` and `eip155:84532`.
-
-Published schemas accept `null` for optional v2 resource/error metadata and
-normalize it to absence. They also permit resource metadata `serviceName`, `tags`,
-and `iconUrl`. These optional fields and unknown extensions do not determine
-spend. The original parsed JSON is retained for auditing, and forwarding does
-not reserialize or rewrite the payment payload.
-[v2 source](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md)
-
-### Exact EVM EIP-3009 payload, both versions
-
-```text
-payload {
-  signature: hex-string,
-  authorization: {
-    from: EVM-address,
-    to: EVM-address,
-    value: unsigned-decimal-integer-string,
-    validAfter: unsigned-decimal-integer-string,
-    validBefore: unsigned-decimal-integer-string,
-    nonce: 32-byte-hex-string
-  }
-}
-```
-
-`value` is the signed token amount. `validAfter` and `validBefore` are Unix seconds
-represented as strings; they are not the observation timestamp. `from` is the
-payer and `to` is the recipient. An exact payment's signed `value` must match the
-selected requirement's amount; its recipient must match `payTo`. Comparisons of
-EVM addresses are case-insensitive. Parsing these relationships is not signature
-verification.
-
-The scheme document describes a 65-byte EOA signature, while published
-`ExactEIP3009Payload` declares `signature?` and the implementation supports smart
-account signature paths. A monitor must not assume every supported signature is
-exactly 65 bytes. Unsupported or structurally unrecognized payloads remain
-transparent traffic, with a diagnostic.
-[Exact EVM source](https://github.com/coinbase/x402/blob/main/specs/schemes/exact/scheme_exact_evm.md)
-
-The same exact-scheme source also describes Permit2
-(`payload.permit2Authorization` with `permitted.token`, `permitted.amount`, `from`,
-`spender`, decimal `nonce`, `deadline`, and `witness.to`/`witness.validAfter`) and
-ERC-7710 (`delegationManager`, `permissionContext`, `delegator`). Published EVM
-2.25.0 types include EIP-3009 and Permit2. These are distinct payload formats, not
-aliases for `authorization`. Taximeter's initial adapter does not meter them.
-
-### Settlement responses
-
-Both header generations decode to an object with the following fields. There is
-no required `x402Version` in this object:
-
-```text
-SettleResponse {
-  success: boolean,
-  transaction: string,
-  network: string,
-  payer?: string,
-  errorReason?: string,
-  errorMessage?: string,
-  amount?: unsigned-decimal-integer-string,
-  extensions?: object,
-  extensionResponses?: object,
-  extra?: object
-}
-```
-
-`transaction` is the wire field. Taximeter maps it to internal `txHash`; it does
-not search for an invented wire `txHash`. Failed settlement may use an empty
-transaction string. v1 uses legacy network names; v2 uses CAIP-2. Optional
-`amount` appears in current v2 types for schemes whose settlement differs from
-their authorization; it is not permission to treat `upto` as `exact`. Published
-types make `payer` optional in both versions, despite the older v1 table.
-[Settlement source](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md)
-
-The monitor considers settlement headers on all response statuses. A signed
-replay, HTTP 200, or transaction-looking string alone is not independently
-verified settlement. A recognized success is described as **reported settled**.
-Malformed, missing, or inconsistent settlement evidence remains unknown.
-
-## Supported subset and accounting decisions
-
-1. **Versions and networks.** Meter v1 and v2 HTTP `exact` EVM EIP-3009 payments.
-   Normalize v1 `base` to `eip155:8453` and `base-sepolia` to `eip155:84532`.
-   Other legacy names are outside the first implementation's mapping. v2 accepts
-   EVM CAIP-2 networks. Other schemes, transfer methods, networks, and versions
-   pass through with a diagnostic. This bounded subset supports the common USDC
-   flow without pretending to understand different authorization semantics.
-2. **Challenge correlation.** v1 requires an observed compatible challenge.
-   Correlation uses actual URL, method, task, agent, Authorization, and Cookie,
-   with a five-minute TTL and 1,000-context capacity. It then matches scheme,
-   network, recipient, and atomic amount.
-   Ambiguous asset choices must not be guessed. A v2 replay can supply its own
-   selected requirements, so the initial 402 exchange need not have been seen.
-   Host policy uses the actual upstream URL, not an untrusted advertised URL.
-   The SDK does not cache a response marked `redirected` under the original URL.
-3. **Asset identity.** Totals and budget windows are separate for every normalized
-   network and asset contract. An asset symbol is a label, not an identity.
-   Case-normalized EVM addresses avoid duplicate groups for checksum variants.
-4. **Decimals.** Neither protocol envelope provides reliable decimals or ticker
-   metadata. `extra.name` and `extra.version` are EIP-712 domain fields, not a
-   verified symbol/decimals pair. Use a local registry for Base and Base Sepolia
-   USDC only. Unknown assets retain exact atomic units, `decimalsKnown: false`,
-   and an internal `decimals: 0` placeholder; the UI labels them as atomic units.
-   It must not claim that the token has zero decimals. There are no runtime RPC
-   or metadata lookups.
-5. **Local USDC registry.** The six-decimal entries are Base
-   `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` and Base Sepolia
-   `0x036CbD53842c5426634e7929541eC2318f3dCF7e`, as documented in the
-   [official asset table](https://docs.x402.org/core-concepts/network-and-token-support).
-   An arbitrary contract advertising `name: "USDC"` does not join these groups.
-6. **Budget asset scope.** The brief's scalar `maxSinglePayment` defaults to
-   verified USDC, made explicit through `maxSingleAsset` with default `USDC`.
-   Symbol budgets match trusted local registry entries and are evaluated
-   separately for each network/asset pair. There is no cross-chain combined
-   dollar balance and no exchange-rate conversion.
-7. **Authorization and outcomes.** A challenge is an offer, not spend. A forwarded
-   recognized authorization consumes conservative budget capacity before the
-   asynchronous upstream request completes. Append-only outcome observations
-   distinguish reported settlement, known failure, and unknown settlement.
-   Outcomes retain separate attempt identities. Confirmation on any attempt
-   wins; otherwise any unresolved attempt retains capacity. Only wholly failed
-   attempts release a payment's contribution. Missing settlement evidence, a
-   disconnect, or an unconfirmed upstream 5xx after forwarding does not silently
-   release that capacity. `attemptedAt` permits an unconfirmed retry outside a
-   rolling window to reacquire capacity without rewriting the original event.
-8. **Idempotency.** The principal EIP-3009 identity includes network, asset,
-   payer, and nonce, bound to amount, recipient, `validAfter`, and `validBefore`.
-   Repeated observations of that authorization count once,
-   including observations under a different resource. Nonce alone would collide
-   across payers/contracts; transaction hash alone can collapse different
-   transfers in one transaction. Resource and wall-clock time alone are not a
-   reliable payment identity. The optional protocol payment-identifier extension
-   is preserved but is not trusted to override an EIP-3009 authorization identity.
-   Signature bytes are not part of the key. Conflicting immutable authorization
-   details receive separate conservative reservations rather than a free replay.
-9. **Concurrency.** Policy evaluation and reservation must be one synchronous
-   operation before forwarding. Otherwise concurrent requests can all observe
-   the same old total. Totals derive from the event log; settlement observations
-   do not mutate earlier rows.
-10. **Transparency boundary.** Unsupported or malformed traffic is forwarded
-    with its payload unchanged and `parse_failed` diagnostics. Storage failures
-    also fail open, with a visible local warning; enforcement needs working
-    storage. Therefore this is a cooperative
-    local meter, not a security boundary against an agent deliberately bypassing
-    the proxy or using an unsupported payment form. Raw audit payloads are
-    payment authorizations, not private keys; the ledger is local state.
-
-## Additional protocol corrections relative to the brief
-
-The comprehensive implementation inventory is at the top of this file. These
-additional corrections concern the research premise itself:
-
-| Brief assumption or omission | Resolution |
-| --- | --- |
-| Coinbase repository is the primary project home. | Read the requested files and follow the README's Foundation pointer; preserve source links and research date above. |
-| Nominal TypeScript declarations are the only accepted wire shape. | Published 2.25.0 runtime schemas permit optional/nullish descriptive fields and optional EIP-3009 signatures. Follow compatible schemas without weakening the authorization relationships that determine spend. |
-| The payment rails have no budget support. | Published core 2.25.0 already has client `spendControls`, including a default per-payment cap. Taximeter's distinct contribution is the persistent local ledger, attribution, rolling budgets, and exports. |
-
-The HTTPS limitation follows from the transport design: a CONNECT tunnel gives
-the proxy an encrypted stream, while the payment protocol lives inside HTTP
-headers. Taximeter does not install a certificate authority or intercept TLS.
-The package README documents which connection modes are metered.
-
-For SDK composition, the intended pattern is
-`wrapFetchWithPayment(withMeter(fetch, options), client)`. The official fetch
-implementation invokes the supplied transport again for the replay, so this
-placement allows the meter to observe the challenge and gate the authorization
-before it reaches the upstream.
-[@x402/fetch source](https://unpkg.com/@x402/fetch@2.25.0/dist/esm/index.mjs)
-
-## Fixture provenance and verification limits
-
-Fixture field names, example Base Sepolia token address, and envelope layout
-come from the linked v1/v2 and exact EVM specification examples. Test values,
-nonces, signatures, resource URLs, and transaction identifiers may be adapted
-deterministically for localhost tests. They are **synthetic protocol examples**,
-not captures of real paid requests and not evidence of cryptographic validity.
-The fixture server accepts the documented replay shape without moving money.
-
-Parser tests establish structural compatibility and exact accounting;
-integration tests establish forwarding, blocking, idempotency, and failure
-handling. Neither test category establishes on-chain settlement, facilitator
-availability, wallet compatibility, or universal x402 support. Those claims are
-outside the initial implementation and its non-custodial scope.