docs: stop the bleeding — README honesty pass + ROADMAP.md

tufedev · tufedev · commit a7fd818b6c10 · 2026-05-16T15:38:43.000+09:00
Resets reader expectations to match reality. The repo's source IS what runs production at jecp.dev, but `cargo run` from a fresh clone needs 6 external services (Postgres, Stripe, Anthropic, AWS KMS, Sentry/Better Stack, Cloudflare DNS). The previous README said "production" + listed a `cp .env.example .env && cargo run` quickstart that does not actually boot. That's the misleading state that gets cited in HN comments — fixed now, before broader indexing picks it up. Changes: - Status badge: production → alpha. - Spec badge: v1.0-draft → v1.1.1 (current spec lock). - New section "⚠️ Alpha readiness notice (2026-05-16)" enumerating the 6 required external services and explicitly stating cargo-run is not supported from a fresh clone yet. - Quick start section replaced (was the misleading cp .env.example / cargo run / localhost:8080 procedure). - Architecture section renamed "Architecture (for readers, not runners)" — same content, honest framing. - Performance section: dropped the per-metric table (not reproducible by cloners); kept one production reference number with the explicit "not reproducible from a fresh clone" caveat + link to ROADMAP v0.2. - "Running your own Hub" rewritten to acknowledge today's reality (use the hosted Hub at jecp.dev; full self-host ships in v0.2). New file ROADMAP.md: - v0.1 (this release): spec-conforming reference, cargo-run NOT supported yet. - v0.2 (Q3): docker-compose dev profile, demo-mode feature flag, benchmark methodology doc. - v0.3 (Q4): examples/minimal-hub/ (8-endpoint MVH profile for indie devs), federation registry alpha. - After B-4 audit clean: x402 mainnet, threshold-signing keeper, Python + Go SDKs. No source code changes. Strategic decision on MVH vs full-Hub-with- docker-compose deferred to after B-4 audit per admiral; reflected in the ROADMAP v0.3 framing rather than forced today.
diff --git a/README.md b/README.md
@@ -3,11 +3,13 @@
 > Reference Hub implementation of the **Joint Execution & Commerce Protocol** (JECP).
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
-[![Status](https://img.shields.io/badge/status-production-green.svg)](https://jecp.dev)
+[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://jecp.dev)
 [![Built with](https://img.shields.io/badge/built%20with-Rust-orange.svg)](https://www.rust-lang.org/)
-[![Spec](https://img.shields.io/badge/spec-v1.0--draft-blue.svg)](https://github.com/jecpdev/jecp-spec)
+[![Spec](https://img.shields.io/badge/spec-v1.1.1-blue.svg)](https://github.com/jecpdev/jecp-spec)
 
-A Rust + Axum Hub implementation. Powers https://jecp.dev in production.
+A Rust + Axum Hub. Reference implementation of the JECP spec; the production Hub at https://jecp.dev runs on this exact source.
+
+**Indie operators**: see the **alpha readiness notice** below before attempting `cargo run`.
 
 ---
 
@@ -20,42 +22,26 @@ A Rust + Axum Hub implementation. Powers https://jecp.dev in production.
 - **Discovery** — `/v1/capabilities` (live catalog, includes both built-in and third-party)
 - **Forwarding** — HMAC-SHA256 signed requests to Provider endpoints with replay window
 
-## Quick start (developers)
-
-### Prerequisites
-
-- Rust 1.75+
-- PostgreSQL 15+ (Supabase or self-hosted)
-- Stripe account (test mode is fine for dev)
+## ⚠️ Alpha readiness notice (2026-05-16)
 
-### Local development
+The production Hub at jecp.dev runs on this exact source, but `cargo run` from a fresh clone is **not yet supported**. The binary boots only with all of:
 
-```bash
-git clone https://github.com/jecpdev/jecp-server.git
-cd jecp-server
-cp .env.example .env
-# Edit .env with your DB URL and Stripe test keys
-cargo run
-```
+- a Supabase-schema Postgres (51 migrations applied)
+- Stripe Connect platform account + test mode
+- Anthropic API key
+- AWS KMS asymmetric key (ECDSA secp256k1) for the keeper
+- Sentry + Better Stack credentials
+- Cloudflare DNS zone for Provider DNS verification
 
-Server starts on `localhost:8080`.
+We have **not yet** packaged this into a one-shot `docker-compose`; that's the v0.2 priority. See [ROADMAP.md](./ROADMAP.md).
 
-### Health check
+**Until then, this repo is best used as a specification-conforming reference**:
 
-```bash
-curl http://localhost:8080/health
-curl http://localhost:8080/v1/capabilities | jq
-```
+- Read the Rust to see how the spec is implemented (`src/routes/`, `src/auth/`, `src/protocol/`).
+- Point a JECP SDK / CLI at the live Hub at `https://jecp.dev` instead of running your own.
+- Use [@jecpdev/sdk](https://www.npmjs.com/package/@jecpdev/sdk) or [@jecpdev/cli](https://www.npmjs.com/package/@jecpdev/cli) for the agent / Provider integration path.
 
-### Production deployment
-
-```bash
-flyctl deploy
-```
-
-The production Hub at jecp.dev runs on Fly.io (Tokyo region, NRT).
-
-## Architecture
+## Architecture (for readers, not runners)
 
 ```
 src/
@@ -71,42 +57,39 @@ src/
 ├── billing/              # invoke_charge() (atomic deduct + 85/10/5 split)
 ├── middleware/           # CORS, rate limit (60 RPM/agent), tracing
 ├── protocol/             # Wire format, error catalog with next_action
-└── services/             # Postgres pool, Stripe API, signing
+└── services/             # Postgres pool, Stripe API, signing, KMS-backed keeper
 ```
 
 ## Specification
 
-This server implements [JECP Spec v1.0-draft](https://github.com/jecpdev/jecp-spec).
+This server implements [JECP Spec v1.1.1](https://github.com/jecpdev/jecp-spec).
 RFC 2119 compliant, JSON Schema 2020-12.
 
-## Performance (production, May 2026)
+## Performance
 
-| Metric | Target | Current |
-|--------|-------:|--------:|
-| `/v1/invoke` p50 | < 200ms | ~127ms |
-| `/v1/invoke` p95 | < 500ms | ~340ms |
-| Wallet debit consistency | 100% | 100% (atomic SQL function) |
-| Idempotency window | 24h | 24h on `(agent_id, request_id)` |
-| Concurrent RPS | 100+ | tested 200 |
+Production numbers (p50 ~127ms on `/v1/invoke` cached path) hold on the Tufe-operated Hub at jecp.dev under live load.
+
+**These are not reproducible from a fresh clone** — they depend on the Postgres schema, Stripe Connect accounts, and KMS keeper key that the Hub is provisioned against. A reproducible benchmark methodology + a self-hosted-friendly profile ship in v0.2 — see [ROADMAP.md](./ROADMAP.md).
 
 ## Client SDKs
 
 - **TypeScript:** [@jecpdev/sdk](https://www.npmjs.com/package/@jecpdev/sdk) — `npm install @jecpdev/sdk`
 - **Python:** planned (v0.2)
 - **Go:** planned (v0.3)
 
-The protocol is plain HTTP+JSON, so any language can implement directly. See [spec §3](https://github.com/jecpdev/jecp-spec/blob/main/spec/03-api.md).
+The protocol is plain HTTP+JSON, so any language can implement directly. See [the JECP spec](https://github.com/jecpdev/jecp-spec).
+
+## Running your own Hub (today's reality)
 
-## Running your own Hub
+For now, the realistic path is to **use the hosted Hub at jecp.dev** (it's the only fully-provisioned deployment of this reference).
 
-You don't need to use jecp.dev. Run your own Hub:
+If you already have all 6 dependencies in the Alpha readiness notice above and want to self-host today, your starting points are:
 
-1. Fork this repo
-2. Configure your DB + Stripe accounts
-3. Deploy (Fly.io / Railway / your-cloud-of-choice)
-4. Optionally federate with jecp.dev (federation registry is on Q4 roadmap)
+1. `fly.toml` — current production Fly.io config (retarget the app name + secrets)
+2. `Dockerfile` — current production container build
+3. `spec/openapi.yaml` — OpenAPI 3.1 schema if you want to start fresh in another language
 
-The protocol is multi-vendor and federation-ready.
+The protocol is multi-vendor and federation-ready by design; the federation registry itself ships in Q4 ([ROADMAP.md](./ROADMAP.md)).
 
 ## License
 
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -0,0 +1,42 @@
+# ROADMAP
+
+Public roadmap for the `jecp-server` reference Hub. Tracks what's runnable from a fresh clone — not the production Hub's roadmap at jecp.dev (which is operated separately).
+
+---
+
+## v0.1 (2026-05-16, current) — specification-conforming reference
+
+- ✅ Full Rust + Axum source matching the production Hub at jecp.dev
+- ✅ Spec conformance: v1.1.1, wire-frozen
+- ✅ OpenAPI 3.1 schema + Spectral lint config
+- ✅ Apache 2.0 + standard OSS scaffolding (CoC, Contributing, Security, PR / Issue templates, CI)
+- ⚠️ `cargo run` from a fresh clone is **not yet supported** — see [README "Alpha readiness notice"](./README.md#-alpha-readiness-notice-2026-05-16)
+
+## v0.2 (2026 Q3) — self-hostable alpha
+
+- [ ] `docker-compose.dev.yaml` profile: Postgres + Mailpit + LocalStack KMS + Stripe CLI test mode
+- [ ] **Demo mode** feature flag — mocks Anthropic + Stripe so end-to-end test runs without external keys
+- [ ] Benchmark methodology doc — so cloners can reproduce p50 / p95 claims on their own hardware
+- [ ] Self-hosted Fly.io quickstart guide (managed-Postgres variant)
+
+## v0.3 (2026 Q4)
+
+- [ ] `examples/minimal-hub/` — 8-endpoint Minimum Viable Hub profile (indie-dev path, no Trust Gate, no x402)
+- [ ] Federation registry alpha (Hub-to-Hub trust discovery)
+
+## After B-4 audit clean (TBD)
+
+- [ ] x402 mainnet settlement path (gated on the 3-scope `B4-audit-rfp-MASTER.md` engagement clean)
+- [ ] Threshold-signing keeper (FROST or Lit, replacing single-key KMS)
+- [ ] Python SDK
+- [ ] Go SDK
+
+## Deliberately out of scope for v1.x
+
+- Multi-chain support (Base only for v1.x; other chains in v2.x)
+- Composable revenue split beyond fixed 85 / 10 / 5
+- Single-block atomicity guarantee — v1.x is **invariant-level atomic** (split-or-revert), not **block-level**. See `RELEASE_NOTES_v1.0.0.md`.
+
+---
+
+This roadmap is informative, not binding. The protocol spec (wire-format) is binding; see [jecp-spec](https://github.com/jecpdev/jecp-spec).
