DAN-855: the front door — a demo you can run, and four claims that were not true

[Danny-Devs]

Why

s402 is the repo a grant reviewer opens first. The engineering behind it was already sound and already verified — what failed was the front door. Until this PR, the entire runnable surface of a 389-line README was npm install and two ls commands.

This came out of the first grant-ready §7 pass ever run against this repo, measured on an unauthenticated HTTPS clone of main rather than a local checkout.

The demo

git clone https://github.com/s402-protocol/core.git && cd core
pnpm install
pnpm demo

Sixty seconds. No wallet, no keys, no network, no faucet. It encodes a 402 into one HTTP header, decodes it from the client side, absorbs an x402 V1 body through the compat layer, and runs the 167 published conformance vectors against the code in your clone.

It reports how many malformed headers were refused and how many leaked through. The second number is the one that means anything: a suite that only ever watches things pass cannot distinguish a working validator from one that returns true unconditionally.

That counter was verified the only way a gate can be — by poisoning a vector (a valid header falsely marked shouldReject) and confirming the run names it, counts it, and exits non-zero.

Four claims that were not true

s402/compat is not an exported subpath	The README used it four times. Copying the compat example produced ERR_PACKAGE_PATH_NOT_EXPORTED. The real path is s402/compat/x402, which exports all five documented functions. The sub-path table was also missing six real entries.
@sweefi/sui described as "coming soon"	It is published on npm. The same README described that implementation in the present tense two paragraphs earlier — one fact, two tenses. This is DAN-588's shape: a hedge nobody re-read after its condition lifted. An under-claim is not the safe direction.
GET /api/catalog reported version "0.3"	S402_VERSION is "1". Anyone curling the catalog to see what the protocol advertises got a number contradicting every payload the same server emits.
Gas figures stated without conditions	The table presented modelled estimates as flat facts and dropped the case the whitepaper is careful to name: x402 on Solana ($0.25/1K) is cheaper than s402 Exact on Sui ($7.00) for one-shot calls. The whitepaper was more honest than the front page, which is backwards.

Two sections that did not exist

What Is True Today — shipped / published / partial / not-runnable, per component, in the honest tense.
Receipts — a command for every claim the README makes about itself.

These were missing structurally, which is why the four false claims had nowhere to be correct.

demo-api/ is reachable again

It was absent from pnpm-workspace.yaml, had no README, and pinned a published s402@^0.6.0 while this repo ships 0.9.0 — neither wired to the workspace nor documented anywhere. Now a workspace package on workspace:*, typechecking against current source, with a README documenting the verified route: /api/joke, not /api/data, which is what its first draft claimed until curl said 404.

Verification — observed, not assumed

• pnpm typecheck — clean
• pnpm vitest run — 1108 passed, 29 files
• pnpm build — 23 files, 268 kB
• pnpm demo — exit 0; negative control proven by deliberate poisoning
• demo-api — documented curl pipeline run against a freshly started process (the first attempt read a stale one still holding the port; that reading was discarded)
• every relative link in the README resolves

Not in scope

Merging #3 or #4. The Unlock/SEAL work. mcp-demo's gRPC migration — it still cannot reach the network, its README says so first, and this PR does not pretend otherwise.

🤖 Generated with Claude Code

https://claude.ai/code/session_01N7ufynvh6FC65iyC9YHNzb

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
s402-docs	Ready	Preview	Aug 22, 2026 6:29am