twzrd-x402-gate 0.9.1 → 0.9.3

package/QUICKSTART.md

@@ -1,15 +1,17 @@
 # twzrd-x402-gate — Quickstart (15 minutes, 0 USDC)
 
-**Product:** replace naked `createX402Client({ wallet })` with a client that
-**refuses wash before sign**. Free `merchant_card`, no API key. Intel down →
-**fail-open** (never invents wash). No Path A in the default path.
+Refuses payment to a wash-flagged merchant **before your wallet signs**. Free intel, no
+API key, no signup, no config — every `TWZRD_*` env var is an optional override. If intel
+is unreachable the gate never *invents* a wash flag (the wash check fails open); a failed
+preflight blocks the payment by default (`TWZRD_FAIL_OPEN=true` to allow).
 
-**Pin:** `twzrd-x402-gate@0.9.0` + `x402-solana@3.0.0`.
+**Pin:** `twzrd-x402-gate@0.9.3` + stock PayAI client `x402-solana@3.0.0` (official
+`beforePayment` seat). `@x402/core` Path E remains supported; refuse script is fallback.
 
 ## 1. Stock PayAI client (default seat — copy-paste)
 
 ```bash
-npm install twzrd-x402-gate@0.9.0 x402-solana@3.0.0
+npm install twzrd-x402-gate@0.9.3 x402-solana@3.0.0
 ```
 
 > **ESM-only.** The package ships `import` conditions only — a CommonJS
@@ -17,16 +19,6 @@ npm install twzrd-x402-gate@0.9.0 x402-solana@3.0.0
 > fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`. Set `"type": "module"` in your
 > package.json, use `.mjs`, or bundle ESM.
 
-```typescript
-import { createX402Client } from "x402-solana";
-import { createTwzrdPayingClient } from "twzrd-x402-gate";
-
-// was: createX402Client({ wallet })
-const client = createX402Client(createTwzrdPayingClient({ wallet }));
-```
-
-Or hook-only:
-
 ```typescript
 import { createX402Client } from "x402-solana";
 import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
@@ -34,18 +26,17 @@ import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
 const client = createX402Client({
   wallet,
   network: "solana",
-  beforePayment: createTwzrdBeforePaymentHook(),
+  beforePayment: createTwzrdBeforePaymentHook({ refuseWashFlagged: true }),
 });
 ```
 
-Default engine = wash only. Full 0.8 preflight/Path A: `{ engine: "full" }`.
-
+Equivalent: `beforePayment: installTwzrdAutoGate("x402-solana", { refuseWashFlagged: true })`.
 Then: `await client.fetch("https://merchant.example/paid");`
 
 ## 1b. Official `@x402/core` client (Path E)
 
 ```bash
-npm install twzrd-x402-gate@0.9.0 @x402/core @x402/fetch @x402/svm
+npm install twzrd-x402-gate@0.9.3 @x402/core @x402/fetch @x402/svm
 ```
 
 ```typescript

package/README.md

@@ -1,72 +1,40 @@
 # twzrd-x402-gate
 
-**Product: the paying client that already has the brake.**
+**TWZRD is the spend-control SDK for agents paying over x402** — and the default
+`onBeforePaymentCreation` policy engine for official x402 clients.
 
-Agents pay other machines unsupervised. Most 402s are junk or wash. Something has
-to say **no** before the signature. TWZRD is that no — inside `beforePayment` /
-fetch+sign, not inside PayAI’s SDK defaults, not as a shop at intel.twzrd.xyz.
+### One call (named export `twzrd`)
 
-The other reason the no must live at the signature: **attaching a funded wallet
-to an agent that reads untrusted web content is a drain vector** — indirect
-prompt injection can spend anything the agent can sign. The gate closes it by
-attaching the wallet to a policy runtime the injected content cannot
-renegotiate: per-request cap, rolling daily ceiling, wash brake, endpoint
-mandates, and a tamper-evident spend ledger that survives restarts. A fully
-compromised agent spends at most what policy allows, to whom it allows, with
-every decision signed.
+```js
+import { twzrd } from "twzrd-x402-gate";
 
-### Replace naked `createX402Client({ wallet })` (5 lines)
-
-```bash
-npm install twzrd-x402-gate@0.9.0 x402-solana@3.0.0
-```
-
-```typescript
-import { createX402Client } from "x402-solana";
-import { createTwzrdPayingClient } from "twzrd-x402-gate";
-
-// was: createX402Client({ wallet })
-const client = createX402Client(createTwzrdPayingClient({ wallet }));
-```
-
-Equivalent one-hook form:
-
-```typescript
-import { createX402Client } from "x402-solana";
-import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
-
-const client = createX402Client({
-  wallet,
-  network: "solana",
-  beforePayment: createTwzrdBeforePaymentHook(), // wash default
+const result = await twzrd.safeFetch(url, {
+  maxSpend: "0.10",              // per-call cap AND cumulative budget
+  allowNetworks: ["solana", "base"],
+  requireOfferBinding: true,     // requires the prepare/submit split below
 });
+// result.verdict: "allow" | "warn" | "block" — blocks have signerInvocations === 0
+// result.receipt: { strength: "hard"|"soft"|"refuse", leaf_hash, fact_type: "resource_bound" }
 ```
 
-**Default path (engine `"wash"`):**  
-`GET /v1/intel/merchant_card/{payTo}` → abort **iff** `wash_flagged === true` →  
-**fail-open** on timeout / non-2xx / throw (never invent wash).  
-No Path A, no requireReceipt, no second 402, no payment-control tokens.
-
-**Full 0.8.x engine (named opt-in):** preflight + optional Path A / escalate /
-paymentControl:
-
-```typescript
-createTwzrdBeforePaymentHook({ engine: "full", /* … */ })
-// or createTwzrdFullBeforePaymentHook({ … })
-```
+`requireOfferBinding` is deliberately fail-closed: an opaque `pay()` callback
+can sign before this library can inspect the transaction, so it is rejected for
+bound payments. Use `prepareBoundPayment` to build an unsigned transaction with
+the supplied `memo`, then `submitBoundPayment` to sign and submit the exact
+validated `transactionBase64`. This SDK never holds keys.
 
-Customer = whoever ships `createX402Client({ wallet })` with no hook (Eliza, MCP
-hosts, agent wallets). Crawlers will never `npm install`.
+Full walkthrough: [QUICKSTART.md](https://github.com/twzrd-sol/twzrd-trust/blob/main/QUICKSTART.md) ·
+verify receipts yourself: [REVIEW.md](https://github.com/twzrd-sol/twzrd-trust/blob/main/REVIEW.md)
 
-> **ESM-only:** CommonJS `require()` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`
-> — set `"type": "module"` (or use `.mjs` / an ESM bundler).
+**Core product (buyer gate):** after the client selects the exact payment requirement and
+**before** payment payload creation / wallet signing — free preflight + merchant_card wash
+refuse. Protects the **payer** from a risky **merchant** (`payTo`). Chain-neutral envelope;
+**Solana-deep** reputation only (Base/EVM = explicit `unknown`).
 
-### Default-on AutoGate (alternate seats)
+### Default-on AutoGate (5 lines)
 
 ```bash
-npm install twzrd-x402-gate@0.9.0 x402-solana@3.0.0
-# official @x402/* path (alternate seat):
-# npm install twzrd-x402-gate@0.9.0 @x402/core @x402/fetch @x402/svm
+npm install twzrd-x402-gate @x402/core @x402/fetch @x402/svm
 ```
 
 ```typescript
@@ -74,28 +42,26 @@ import { x402Client } from "@x402/core/client";
 import { installTwzrdAutoGate } from "twzrd-x402-gate";
 
 const client = new x402Client();
-// stock solana seat still defaults to wash via createTwzrdBeforePaymentHook()
+// refuseWashFlagged defaults true; gateOnCanSpend stays false unless you opt in
 installTwzrdAutoGate(client, { refuseWashFlagged: true });
 // then register schemes + wrapFetchWithPayment as usual
 ```
 
-**Intercept proof (0 USDC, bad seller never reaches signer):**
+**Intercept proof (0 USDC, wash seller never reaches signer):**
 
 ```bash
 cd packages/twzrd-x402-gate && npm run autogate-block-proof
 # writes block-proof-<run_id>.json  (schema twzrd.autogate_block_proof.v1)
-# public reason: "TWZRD_TRUST_GATE_BLOCK: wash_flagged"    (wash basis)
-#            or  "TWZRD_TRUST_GATE_BLOCK: decision_block"  (readiness block basis)
-# fixture resolves live: wash_flagged seller if available, else decision=block
+# public reason: TWZRD_TRUST_GATE_BLOCK: wash_flagged
 ```
 
-`gateOnCanSpend` remains **opt-in** (`false` by default; set `true` or `TWZRD_GATE_ON_CAN_SPEND=1` only when you want hard cap enforcement). Full-engine preflight outage default stays fail-closed unless `failOpen: true` / `TWZRD_FAIL_OPEN=1`. The **product wash path always fail-opens** on intel outage.
+`gateOnCanSpend` remains **opt-in** (`false` by default; set `true` or `TWZRD_GATE_ON_CAN_SPEND=1` only when you want hard cap enforcement).
 
-**Optional:** a resource-server settle hook so merchants can apply **customer policy**
+**Optional (0.8.1):** a resource-server settle hook so merchants can apply **customer policy**
 before they settle and serve (abuse, sanctions, bots, “don’t serve this payer”). Not an equal
 mirror of the buyer problem — settled USDC is final; wash resistance is mainly TWZRD scoring.
 
-## Seller settle guard (`onBeforeSettle`) — optional
+## Seller settle guard (`onBeforeSettle`) — optional 0.8.1
 
 Resource servers can screen the **payer** before *they* settle an inbound payment and serve
 the resource. Use for merchant policy (abuse / sanctions / bots / customer selection). TWZRD is
@@ -107,7 +73,7 @@ transfer on-chain. Wash/sybil edges are primarily discounted in TWZRD scoring, n
 revenue refusal.
 
 ```bash
-npm install twzrd-x402-gate@0.9.0
+npm install twzrd-x402-gate@0.9.3
 ```
 
 ```typescript
@@ -139,23 +105,7 @@ Offline demo: `npx tsx examples/seller-settle-guard.ts`
 Fixture-backed SVM extract tests live in `test/seller-hook.test.ts` +
 `test/fixtures/exact-svm-transfer-checked.ts`.
 
-**PayAI x402-solana@2.1.0+** (stock client - primary Solana seat via `beforePayment`).
-Both 2.1.0 and 3.0.0 are supported and produce an identical refuse transcript; 3.0.0
-is the current release and what the install lines pin. The hook absorbs the one
-breaking change between them (`declaredResource` is a string on 2.1.0, `{ url }` on
-3.0.0) - see `src/x402-client-hook.ts` and `test/x402-solana-before-payment.test.ts`.
-
-```typescript
-import { createX402Client } from "x402-solana";
-import { createTwzrdPayingClient } from "twzrd-x402-gate";
-
-const client = createX402Client(createTwzrdPayingClient({ wallet }));
-```
-
-Also: `installTwzrdAutoGate("x402-solana", opts)` returns the same wash-default hook.
-Prove refuse-before-sign: `npm run x402-solana-before-payment-proof`.
-
-**PayAI agentic-payments** (alternate PayAI surface; prefer x402-solana@3.0.0 when available):
+**PayAI agentic-payments** (the active PayAI SDK, not the dormant x402-solana):
 `npx tsx examples/payai-agentic-onPaymentVerified.ts` — wire `onPaymentVerified`
 → `toPayaiVerifyResult` to screen payers before serving. Fail-open by default.
 
@@ -167,7 +117,7 @@ Prove refuse-before-sign: `npm run x402-solana-before-payment-proof`.
 Install the published gate and run against wash fixtures:
 
 ```bash
-npm install twzrd-x402-gate@0.9.0
+npm install twzrd-x402-gate@0.9.3
 # from package root after install, or from a checkout:
 npm run wash-dogfood
 ```
@@ -187,7 +137,7 @@ Gate dogfood: `approved=false` `reason=twzrd_decision_block`, **USDC spent = 0**
 
 **Accurate paste line:**
 
-> Preflight returned decision=block on wash seller 7G73PL… / HuSiSpc… (preflight_id 378468 / 378469, wash_flagged=true). Gate approved=false reason=twzrd_decision_block. No USDC spent. No tx broadcast. Repro: `npm i twzrd-x402-gate@0.9.0 && npm run wash-dogfood` or gist above.
+> Preflight returned decision=block on wash seller 7G73PL… / HuSiSpc… (preflight_id 378468 / 378469, wash_flagged=true). Gate approved=false reason=twzrd_decision_block. No USDC spent. No tx broadcast. Repro: `npm i twzrd-x402-gate@0.8.5 && npm run wash-dogfood` or gist above.
 
 This is a **reproducible demonstration** that the free gate blocks known wash sellers with stamped `preflight_id`s and zero spend. It is **not** proof that external agents already default to this path at scale.
 
@@ -265,61 +215,11 @@ No AgentCash. No marketplace. No second probe. No TWZRD custody.
 Wire `twzrdOnPaymentRequested` / prefer `onPaymentRequired` + `onBeforePayment` per
 [lifecycle hooks](https://docs.x402.org/advanced-concepts/lifecycle-hooks). Same policy core.
 
-### Cloudflare Agents x402 (Base)
-
-Cloudflare's `withX402Client` takes an `onPaymentRequired` callback before its
-automatic payment retry. Use the adapter below at that boundary:
-
-```ts
-import { createTwzrdCloudflareX402Approval } from "twzrd-x402-gate";
-
-const approvePayment = createTwzrdCloudflareX402Approval({
-  // Base/EVM has no TWZRD behavioral reputation yet. Refuse it rather than
-  // presenting a policy allow as a trust verdict.
-  unsupportedNetworkMode: "strict",
-});
-
-await this.x402Client.callTool(approvePayment, {
-  name: "paid_tool",
-  arguments: {},
-});
-```
-
-`observe` is available for an agent that intentionally permits unscored Base
-payments, but it returns policy allow with `decision=unknown`; it is never a
-TWZRD reputation approval. This adapter protects the Cloudflare x402 path only.
-MPP is a separate protocol and belongs on its own `onChallenge` /
-`onPaymentRequired` control path.
-
-### Cloudflare Worker / Base x402 (edge-safe preflight)
-
-For a Worker, import the dedicated subpath rather than the package root. It has
-no Node-native imports and sends the exact Base `payTo` plus `chain_id: 8453` to
-`/v1/intel/preflight` before a Viem account signs:
-
-```ts
-import { withTwzrdBasePreflight } from "twzrd-x402-gate/cloudflare-base";
-
-const signature = await withTwzrdBasePreflight(
-  paymentRequirements, // accepts: [{ network: "eip155:8453", payTo: "0x..." }]
-  { intelBase: "https://intel.twzrd.xyz" },
-  () => account.signTypedData(eip3009Authorization),
-);
-```
-
-`block` throws `TwzrdBasePaymentBlockedError` and never invokes the signing
-callback. `allow` and `warn` both proceed; enforce any additional amount or
-mandate policy in the caller. Base is not presented as reputation-scored.
-Checksummed and lowercase EVM addresses are accepted unchanged. The fixture in
-[`test/cloudflare-base-edge.test.ts`](./test/cloudflare-base-edge.test.ts) proves
-`block → zero signTypedData calls` and the compiled subpath is checked for Node
-runtime leaks.
-
 ### Raw-fetch composition (injectible pay client only)
 
 ```typescript
 import { installTwzrdAutoGate } from "twzrd-x402-gate";
-import { wrapFetchWithPayment } from "@x402/fetch"; // or @x402/svm helper
+import { wrapFetchWithPayment } from "@x402/fetch";
 
 // Guard RAW fetch, then hand to a client that still surfaces 402 to the guard layer
 // — OR installTwzrdAutoGate(x402Client) (canonical) / installTwzrdX402ClientHook alias.
@@ -362,13 +262,11 @@ Dogfood (one public live proof path):
 ## Install
 
 ```bash
-npm install twzrd-x402-gate@0.9.0 x402-solana@3.0.0
+npm install twzrd-x402-gate@0.9.3
 ```
 
-Install pin is the published version (`GATE_PACKAGE_PIN` in
-`packages/twzrd-agent-intel/src/twzrd_agent_intel/pins.py`). Repo `package.json`
-may be one patch ahead until that release is on npm. Confirm with
-`npm view twzrd-x402-gate version`.
+Do not hardcode a version in this doc — every past pin here (**0.5.4**, **0.7.1**, **0.8.5**,
+**0.8.6**) has gone stale. Check `npm view twzrd-x402-gate version` if in doubt.
 
 Optional settle guard (resource-server **payer** policy): see **Seller settle guard
 (`onBeforeSettle`) — optional 0.8.1** above. Do not confuse with facilitator
@@ -462,16 +360,15 @@ installTwzrdX402ClientHook(client, {
 - Hook binding test:
   [`test/intent-binding.test.ts`](./test/intent-binding.test.ts).
 
-### On MPP (Machine Payments Protocol) — Solana and narrow Base EVM charge
+### On MPP (Machine Payments Protocol) — Solana charge only
 
-`createTwzrdMppOnChallenge` guards `Mppx.create({ onChallenge })`. It supports
-`solana/charge` and the published native MPP `evm/charge` shape only for
-Base-mainnet native USDC (EIP-3009 authorization). `onChallenge` is the last
-deterministic checkpoint before `createCredential()` makes the credential, so a
-TWZRD block is an exception that means **`createCredential()` never runs and
-nothing signs**. On allow, the guard creates the credential for the exact
-challenge it evaluated; other methods/intents fail closed
-(`allowUnevaluated: true` is an explicit ungated opt-out).
+`createTwzrdMppOnChallenge` guards `Mppx.create({ onChallenge })`. The mppx
+Solana method signs AND broadcasts the transaction inside `createCredential()`,
+so `onChallenge` is the last deterministic checkpoint before money moves - and
+mppx re-throws `onChallenge` errors, so a TWZRD block is an exception that means
+**`createCredential()` never runs and nothing signs**. On allow, the guard
+creates the credential for the exact challenge it evaluated; non-`solana/charge`
+challenges fail closed (`allowUnevaluated: true` to opt out).
 
 ```typescript
 import { Mppx } from "mppx/client";
@@ -487,30 +384,6 @@ const mppx = Mppx.create({
 });
 ```
 
-For Base, use mppx's EVM client with explicit local spend policy:
-
-```typescript
-import { Mppx } from "mppx/client";
-import { evm } from "mppx/evm/client";
-import { createTwzrdMppOnChallenge, createLocalDecisionSigner } from "twzrd-x402-gate";
-
-const mppx = Mppx.create({
-  methods: [evm({ account: wallet })],
-  onChallenge: createTwzrdMppOnChallenge({
-    signer: createLocalDecisionSigner(),
-    policy: {
-      allowedNetworks: ["eip155:8453"],
-      allowedAssets: ["0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913"],
-      maxAmountUsd: "1.00",
-    },
-  }),
-});
-```
-
-Base is **not reputation-scored**. The EVM path provides an actual pre-credential
-local control point for Base USDC; it does not call a Solana-derived score or
-present a local policy allow as a TWZRD trust verdict.
-
 **Scope limit (honest):** the guard is authoritative only when no
 `onChallengeReceived` event handler supplies a credential. mppx resolves
 `eventCredential ?? onChallenge(...)`, so an event handler returning a credential
@@ -526,8 +399,6 @@ fails closed rather than approve a payment it cannot bind:
 | Non-USD-pegged asset | `UNPRICED_ASSET` | Policy ceilings are USD; the wire amount is base-unit tokens. Pricing SOL would store `asset: solana:native` beside a **dollar** `amount` and lose the token quantity actually transferred. (A 1.5 SOL charge of `1500000000` at 9 decimals would otherwise evaluate as "$1.50" and sail under a $5 ceiling while moving ~$270.) USDC/USDT only until an intent version carries token amount + quote. |
 | Unknown cluster | `UNKNOWN_CLUSTER` | mppx-solana's `resolveEndpoint` returns an unrecognized `cluster` **verbatim as the RPC endpoint URL**, and a network string containing "solana" is otherwise scored as mainnet - so `solana:https://seller-rpc.example` would inherit mainnet reputation for a chain never observed. Known cluster names only. |
 | Misdeclared decimals | `MALFORMED_CHALLENGE` | A known stablecoin declaring the wrong decimals is a discount attempt, not a rounding error. |
-| Non-Base EVM chain | `UNSUPPORTED_EVM_NETWORK` | EVM MPP is narrow: Base mainnet only. A testnet or another EVM network cannot inherit a Base USDC valuation. |
-| EVM split recipients | `MULTI_LEG_CHARGE` | mppx EVM permits `splits`; each is an additional recipient. PaymentIntent v1 binds one amount to one payTo, so the guard refuses rather than approve transfers it cannot represent. |
 
 The intent binds a **digest of the entire normalized challenge**, not just
 `realm:id` - swapping `recipient` or `amount` under the same challenge id changes
@@ -580,10 +451,8 @@ Canonical entry point (design: `docs/strategy/install-autogate-design.md`). One
 | Call | Adapter |
 |------|---------|
 | `installTwzrdAutoGate(payWrap, opts?)` | Fetch: guard raw fetch → pay client |
-| `installTwzrdAutoGate(x402Client, opts?)` | Official `@x402/core` `onBeforePaymentCreation` |
-| `installTwzrdAutoGate("x402-solana", opts?)` | PayAI stock client `beforePayment` (2.1.0+) |
+| `installTwzrdAutoGate(x402Client, opts?)` | Official x402 `onBeforePaymentCreation` |
 | `installTwzrdAutoGate("mpp", opts)` | MPP `onChallenge` (returns handler) |
-| `createTwzrdBeforePaymentHook(opts?)` | Same as `"x402-solana"` — pass to `createX402Client` |
 
 Aliases: `installTwzrdX402ClientHook`, `createTwzrdMppOnChallenge` remain; docs prefer AutoGate.
 Kill switch: `TWZRD_GATE_ENABLED=false` or `TWZRD_AUTO_GATE=0`. Uninstall x402 installs with `uninstallTwzrdAutoGate(client)`.
@@ -596,7 +465,7 @@ ever gets a chance to sign.
 
 ```typescript
 import { installTwzrdAutoGate } from "twzrd-x402-gate";
-import { wrapFetchWithPayment } from "@x402/svm";
+import { wrapFetchWithPayment } from "@x402/fetch";
 
 const payingFetch = installTwzrdAutoGate((guarded) => wrapFetchWithPayment(guarded, buyerWallet));
 
@@ -647,7 +516,7 @@ manage the raw/paying composition yourself:
 
 ```typescript
 import { withTwzrdGuard } from "twzrd-x402-gate";
-import { wrapFetchWithPayment } from "@x402/svm";
+import { wrapFetchWithPayment } from "@x402/fetch";
 
 const raw = globalThis.fetch;               // MUST still surface HTTP 402
 const guarded = withTwzrdGuard(raw);        // guard sits upstream
@@ -682,49 +551,15 @@ const safeFetch = withTwzrdGuard(x402Fetch, {
 });
 ```
 
-### Path A — default on the buyer seat when a paying fetch is wired
-
-Free preflight still decides `allow|warn|block`. **Facilitator `onBeforeSettle`
-stays free** (abort on `block` only — we do not tax their rail).
-
-On the **buyer** install, if you pass `x402Fetch` (or use
-`installTwzrdAutoGate(payWrap)`, which auto-wires `payWrap(raw)`), Path A
-defaults on:
-
-| Free decision | Resource price | What fires |
-|---------------|----------------|------------|
-| `block` | any | free refuse |
-| `warn` | ≥ $2.50 | $0.05 V6 (`requireReceipt`) |
-| `warn` | < $2.50 | $0.001 quick re-decide (`escalateOnWarn`) |
-| `allow` | > $2.50 | $0.05 V6 |
-| `allow` | ≤ $2.50 | free proceed |
-
-```typescript
-import { wrapFetchWithPayment } from "@x402/svm";
-import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
-
-const x402Fetch = wrapFetchWithPayment(fetch, buyerWallet);
-const client = createX402Client({
-  wallet: buyerWallet,
-  network: "solana",
-  beforePayment: createTwzrdBeforePaymentHook({
-    refuseWashFlagged: true,
-    x402Fetch, // turns Path A defaults on
-  }),
-});
-```
-
-Opt out: `requireReceipt: false` and/or `escalateOnWarn: false`.
-Refuse-only seats (no `x402Fetch`) stay free.
-
-`evaluate_x402_resource` itself stays opt-in. `autoReceipt: true` still buys
-$0.05 on every non-block (broader than the default ladder).
+`autoReceipt` is **off by default** — it spends the **buyer's** USDC, so you opt in. When on,
+every warn/allow verdict settles $0.05 USDC to TWZRD and returns a signed V6 trust credential
+for the counterparty before you pay the resource.
 
 **`x402Fetch` is yours to supply** (this package is dependency-free). Wire the proven
 `@x402/svm` sponsored-feePayer client — the same one `twzrd-mcp-server` uses:
 
 ```typescript
-import { wrapFetchWithPayment } from "@x402/svm";
+import { wrapFetchWithPayment } from "@x402/fetch";
 const x402Fetch = wrapFetchWithPayment(fetch, buyerWallet); // settles 402 challenges
 ```
 
@@ -916,31 +751,17 @@ const gatedFetch = wrapFetchWithTwzrdGate(fetch, resolveConfig());
 
 A payment is **blocked** when:
 1. `decision ∈ blockDecisions` (default: `["block"]`)
-2. `trust_score < preflightMinScore` (default: `40`) — note a card with **no**
-   `trust_score` is scored `0` (`policy.ts`: `card.trust_score ?? 0`), so a
-   missing score blocks under the default floor
+2. `trust_score < preflightMinScore` (default: `40`)
 3. `can_spend === false` — **only** when `gateOnCanSpend: true` (default `false`, opt-in)
-4. `merchant_card.wash_flagged === true` — **on by default**
-   (`refuseWashFlagged`, `TWZRD_REFUSE_WASH_FLAGGED`); forces `verdict: "block"`
-   with `reason: twzrd_wash_flagged`. Only tightens, and fails **open** when the
-   card is unreachable or `wash_flagged` is `null` (never evaluated ≠ clean).
-   Soft-cap instead of hard refuse with `washMaxUsdc` / `TWZRD_WASH_MAX_USDC`.
 
 `warn` is allowed unless overridden. Preflight network failure **fails closed** by default (a preflight outage blocks the payment, so an intel hiccup never silently approves a spend); set `failOpen: true` / `TWZRD_FAIL_OPEN=true` to opt into legacy allow-on-outage.
 
 A 402 whose payment requirements yield **no identifiable seller wallet** (missing/empty `payTo`, or an unparseable `accepts[]`) is a different case from "unknown seller" — it always **blocks** with `reason: twzrd_unidentifiable_payment_recipient`, without ever calling the preflight network. This is unconditional (not affected by `failOpen`): `failOpen` governs what happens when the TWZRD *service* is unreachable, not what happens when the caller can't say who they're paying.
 
 > **`can_spend` note:** the free preflight returns `can_spend=false` for most sellers
-> not yet in the TWZRD corpus, including legitimate ones. That **`can_spend` leg
-> alone** is opt-in — it is ignored unless you set `gateOnCanSpend: true` — so an
-> unknown seller on a platform like Agentic.Market is not blocked *on that basis*.
->
-> This is **not** a blanket "unknown sellers are allowed by default". Conditions 1,
-> 2 and 4 above are all active by default, and condition 2 is the one that catches
-> unknown sellers: a card carrying no `trust_score` evaluates as `0` and blocks
-> under the default `preflightMinScore: 40` with `twzrd_score_0_below_40`. To
-> actually let unscored sellers through, lower or disable `preflightMinScore` —
-> setting `gateOnCanSpend` does not govern it.
+> not yet in the TWZRD corpus, including legitimate ones. The default is decision-only
+> gating so unknown sellers on platforms like Agentic.Market are not blocked by default.
+> Set `gateOnCanSpend: true` for strict mode.
 
 ## Config
 
@@ -951,24 +772,11 @@ A 402 whose payment requirements yield **no identifiable seller wallet** (missin
 | `blockDecisions` | `TWZRD_BLOCK_DECISIONS` | `block` | Decisions that throw |
 | `failOpen` | `TWZRD_FAIL_OPEN` | `false` | `true` opts into legacy allow-on-outage; default blocks (fail-closed) |
 | `gateOnCanSpend` | `TWZRD_GATE_ON_CAN_SPEND` | `false` | Also block when `can_spend=false` |
-| `refuseWashFlagged` | `TWZRD_REFUSE_WASH_FLAGGED` | **`true`** | Refuse when `merchant_card.wash_flagged === true` (Policy 4). Set `false` / `0` to opt out |
-| `washMaxUsdc` | `TWZRD_WASH_MAX_USDC` | — | Soft cap instead of hard refuse on wash: allow up to this USDC amount |
-| `unsupportedNetworkMode` | `TWZRD_UNSUPPORTED_NETWORK_MODE` | `observe` | Behavior on a non-Solana / unrecognized network |
-| `fetch` | — | global `fetch` | Injected fetch used for preflight + merchant card (testing / custom agents) |
-| `onWarnUpsell` | — | — | Callback fired on a `warn` verdict (Path A upsell hook) |
-| `attribution` | `TWZRD_ATTRIBUTION_INTEGRATION` + `TWZRD_ATTRIBUTION_RUN_ID` | — | Opt-in run attribution (see below) |
-
-The four options below are **not** `TwzrdGateConfig` fields — they belong to
-`TwzrdGuardOptions` / `InstallAutoGateOptions` (`withTwzrdGuard` /
-`installTwzrdAutoGate`). Passing them to `createTwzrdGate({...})` is a type error
-and is silently dropped at runtime:
-
-| Option | Env | Default | Description |
-|---|---|---|---|
 | `autoReceipt` | — | `false` | Auto-buy $0.05 TWZRD receipt on warn/allow |
 | `x402Fetch` | — | — | x402-capable fetch for `autoReceipt` |
 | `onReceipt` | — | — | Callback after receipt is captured |
 | `disabled` (`installTwzrdAutoGate` only) | `TWZRD_AUTO_GATE=0`/`false` | `false` | Bypass the guard entirely — `payWrap` gets the raw, unguarded fetch |
+| `attribution` | `TWZRD_ATTRIBUTION_INTEGRATION` + `TWZRD_ATTRIBUTION_RUN_ID` | — | Opt-in run attribution (see below) |
 
 ## Gate adoption proof (no-spend harness)
 

package/dist/decision-ledger-file.d.ts

@@ -0,0 +1,49 @@
+export declare const DECISION_LEDGER_SCHEMA_VERSION = 1;
+export type DecisionLedgerRow = {
+    schema_version: typeof DECISION_LEDGER_SCHEMA_VERSION;
+    decision_id: string;
+    at_unix_ms: number;
+    outcome: "allow" | "warn" | "block" | "error";
+    reason_codes: string[];
+    policy_version: string;
+    input: {
+        /** Public chain address, retained for settlement and counterparty joins. */
+        pay_to?: string;
+        resource_origin?: string;
+        network?: string;
+        /** Exact value retained for mandate/cap reconciliation. */
+        amount_micro?: string;
+    };
+    signer_invocations: number;
+    latency_ms?: number;
+    error?: {
+        code: string;
+        message?: string;
+    };
+    settlement?: {
+        status: "pending" | "settled" | "failed";
+        tx?: string;
+    };
+};
+export type RecordDecisionInput = Omit<DecisionLedgerRow, "schema_version" | "decision_id" | "at_unix_ms" | "input"> & {
+    decision_id?: string;
+    at_unix_ms?: number;
+    input: {
+        pay_to?: string;
+        resource?: string;
+        network?: string;
+        amount_micro?: string;
+    };
+};
+export type FileDecisionLedgerOptions = {
+    maxBufferedRows?: number;
+    rotateBytes?: number;
+    /** Opt in only when this library owns the host process lifecycle. Default: false. */
+    flushOnSignals?: boolean;
+};
+/** `record` never blocks the payment path. `flush` fsyncs an async batch. */
+export declare function createFileDecisionLedger(filePath: string, options?: FileDecisionLedgerOptions): {
+    record(input: RecordDecisionInput): DecisionLedgerRow;
+    flush: () => Promise<void>;
+};
+//# sourceMappingURL=decision-ledger-file.d.ts.map

package/dist/decision-ledger-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-ledger-file.d.ts","sourceRoot":"","sources":["../src/decision-ledger-file.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,cAAc,EAAE,OAAO,8BAA8B,CAAC;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IAC9C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE;QACL,4EAA4E;QAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,2DAA2D;QAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,UAAU,CAAC,EAAE;QAAE,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,iBAAiB,EAAE,gBAAgB,GAAG,aAAa,GAAG,YAAY,GAAG,OAAO,CAAC,GAAG;IACrH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxF,CAAC;AAaF,MAAM,MAAM,yBAAyB,GAAG;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,yBAA8B;kBAqChF,mBAAmB,GAAG,iBAAiB;iBA9B/B,OAAO,CAAC,IAAI,CAAC;EA4CtC"}