feat(p2): bug fixes, unit tests, P2 productization docs

Bug fixes:
  - K9Contract.enforce_pre_proxy/2 now enforces the rate_limit field that
    was previously declared and validated but never checked. Implements a
    per-route token bucket scoped to the contract (capacity = rate_limit).
    Gateway responds with 429 + Retry-After on contract rate-limit breach.
  - K9Contract.list_all/0 and count/0 now filter ETS entries by {:contract,
    _, _} key pattern so they ignore :breach_count counters and the new
    :contract_bucket rate-limit state. Previously they returned counter
    integers in place of contract structs (latent bug).
  - K9Contract.find_wildcard_match/2 uses :ets.match_object to iterate only
    contract entries. Previously a FunctionClauseError would be raised when
    a wildcard lookup occurred with any non-contract entry in the table.
  - gateway.ex extract_cert_subject/1 now uses Record.extract-based
    OTPCertificate / OTPTBSCertificate accessors. Replaces the documented
    TODO approximation that matched on a speculative {:Certificate, ...}
    tuple shape which did not match what :public_key.pkix_decode_cert
    actually returns in :otp mode.

Unit tests:
  - test/k9_contract_test.exs: registration, tiered lookup (exact, :ANY,
    wildcard), trust threshold, rate limit enforcement, post-proxy SLA,
    all four breach policies, parse_breach_policy safety, count/list_all
    filtering, wildcard-with-mixed-entries safety.
  - test/circuit_breaker_test.exs: full FSM — closed → open → half_open →
    closed (recovery) and half_open → open (failed probe). Manual trip,
    reset (including timer cancellation), all_states snapshot, and
    defensive edge cases (non-string backends, unregistered backends).

P2 productization docs:
  - docs/RELEASE-CRITERIA.md: replaces percentage-based release gating
    with concrete test-suite gates. Each MVP claim maps to a passing
    test file. Explicit non-gates (topology %, LOC, module count) to
    prevent reintroduction of the "97% production-ready" overclaim.
  - docs/SCOPED-DEPLOYMENT.md: recommends deploying the gateway in front
    of selected API routes first, not the whole application surface.
    Includes nginx example, rollback plan, and migration path.
  - TOPOLOGY.md: removed percentage bars, replaced with test-file-backed
    status table; added banner explaining the correction (mTLS was
    previously 100% but demonstrably broken).
  - ROADMAP-v2.md: marked as HISTORICAL/ASPIRATIONAL — features it lists
    (web UI, plugins, AI suggestions) are explicitly out of v0.1.0 MVP.
  - docs/SUPPORTED-FEATURES.md: mTLS row upgraded from "Not recommended"
    to "Supported with caveats" now that Record.extract is in place.
  - ROADMAP.adoc: P1 and P2 sections marked complete with references.
  - TEST-NEEDS.md: updated coverage summary (9 unit test files + security
    + E2E + concurrency + fuzz + benchmarks).

https://claude.ai/code/session_01TzU2xW8y2uBCaCm2mE4NUV

Author: claude

ROADMAP-v2.md

@@ -1,7 +1,17 @@
-# http-capability-gateway v2.0 Roadmap
-# Making It Irresistible
-
-## Vision: The Gateway Everyone Wants
+# http-capability-gateway v2.0 Roadmap — HISTORICAL / ASPIRATIONAL
+
+> **⚠️ HISTORICAL DOCUMENT (2026-04-16):** This is an aspirational v2.0 vision
+> written when the project was still in design phase. It is NOT on the current
+> release path for v0.1.0 — the features listed here (web UI, plugins, multi-protocol
+> full support, AI policy suggestions, etc.) are explicitly **out of MVP scope**.
+>
+> See `ROADMAP.adoc` and `docs/SUPPORTED-FEATURES.md` for the current scope and
+> what is actually supported today.
+>
+> Do not treat any item in this document as a commitment or an imminent feature.
+> It is preserved for reference and long-term direction only.
+
+# Original Vision: The Gateway Everyone Wants
 
 Transform http-capability-gateway from "good production gateway" to **"the obvious choice for API governance"** by making it:
 

ROADMAP.adoc

@@ -75,16 +75,16 @@ Each claim above must have at least one passing test:
 
 == P1 Gateway Hardening
 
-* [ ] Benchmark routing, policy evaluation, and rate limiting.
-* [ ] Add concurrency and failure-mode tests for rate limiter, circuit breaker, and reload paths.
-* [ ] Tighten operator documentation around what protocols and trust sources are actually supported.
-* [ ] Keep the runtime role constrained to prefiltering before origin-side enforcement.
+* [x] Benchmark routing, policy evaluation, and rate limiting. `test/benchmark_test.exs`.
+* [x] Add concurrency and failure-mode tests for rate limiter, circuit breaker, and reload paths. `test/concurrency_test.exs`.
+* [x] Tighten operator documentation around what protocols and trust sources are actually supported. `docs/SUPPORTED-FEATURES.md`.
+* [x] Keep the runtime role constrained to prefiltering before origin-side enforcement. `docs/SCOPED-DEPLOYMENT.md`.
 
 == P2 Productization
 
-* [ ] Use the gateway in front of selected API routes first, not the whole application surface.
-* [ ] Add release criteria that require executed tests rather than topology percentages.
-* [ ] Mark older design-only documents as historical where they no longer reflect the codebase.
+* [x] Use the gateway in front of selected API routes first, not the whole application surface. See `docs/SCOPED-DEPLOYMENT.md`.
+* [x] Add release criteria that require executed tests rather than topology percentages. See `docs/RELEASE-CRITERIA.md`.
+* [x] Mark older design-only documents as historical where they no longer reflect the codebase. `ROADMAP-v2.md`, `IMPLEMENTATION-ROADMAP.md`, `TOPOLOGY.md` updated.
 
 == Milestones
 

TEST-NEEDS.md

@@ -2,59 +2,63 @@
 
 ## CRG Grade: C — ACHIEVED 2026-04-04
 
-> Generated 2026-03-29 by punishing audit.
+> Generated 2026-03-29 by punishing audit. Superseded 2026-04-16 by the
+> P0/P1/P2 test work documented below.
 
 ## Current State (updated 2026-04-16)
 
 | Category     | Count | Notes |
 |-------------|-------|-------|
-| Unit tests   | 7     | gateway, policy_compiler, policy_loader, policy_validator, policy_property, performance, http_capability_gateway |
+| Unit tests   | 9     | gateway, policy_compiler, policy_loader, policy_validator, policy_property, performance, http_capability_gateway, **circuit_breaker**, **k9_contract** |
 | Security     | 1     | security_test.exs: sanitization, headers, SSRF, capability tokens (30+ tests) |
 | E2E          | 1     | e2e_test.exs: full lifecycle, policy hot-reload, upstream proxy, health probes (20+ tests) |
+| Concurrency  | 1     | concurrency_test.exs: rate limiter contention, circuit breaker serialization, atomic reload under load |
 | Fuzz         | 1     | fuzz_test.exs: property-based fuzzing with StreamData (6 properties) |
-| Benchmarks   | 0     | None |
-
-**Source modules:** ~19 Elixir modules (gateway, circuit_breaker, proxy, rate_limiter, safe_trust, graphql_handler, grpc_handler, policy_*, minikaran, logging, etc.) + 2 Idris2 ABI + 4 Zig FFI.
-
-## What's Missing
-
-### P2P (Property-Based) Tests
-- [ ] Policy compilation: fuzz arbitrary YAML policies through compiler
-- [ ] Rate limiter: property tests for token bucket invariants
-- [ ] Circuit breaker: state machine property tests (closed->open->half-open)
-- [ ] GraphQL/gRPC handler: arbitrary request shape handling
-
-### E2E Tests
-- [ ] Full request lifecycle: client -> gateway -> upstream -> response
-- [ ] Multi-protocol routing (HTTP, GraphQL, gRPC through single gateway)
-- [ ] Policy hot-reload under load
-- [ ] Health check / readiness probe validation
-
-### Aspect Tests
-- **Security:** Request sanitization, header injection, SSRF prevention, capability token validation — covered in `test/security_test.exs`
-- **Performance:** No load tests, no latency benchmarks, no throughput measurement
-- **Concurrency:** No tests for concurrent connections, race conditions in rate limiter, circuit breaker under contention
-- **Error handling:** No tests for upstream timeout, malformed requests, policy parse failures
-
-### Build & Execution
-- [ ] `mix test` runner verification
-- [ ] Zig FFI integration test execution
-- [ ] Container build + smoke test
-
-### Benchmarks Needed
-- [ ] Request routing latency (per-protocol)
-- [ ] Policy evaluation overhead
-- [ ] Rate limiter throughput
-- [ ] Circuit breaker state transition cost
-
-### Self-Tests
-- [ ] Configuration validation on startup
-- [ ] Policy schema self-check
-- [ ] Capability token format verification
+| Benchmarks   | 2     | performance_test.exs (existing) + benchmark_test.exs (rate limiter / circuit breaker / route lookup) |
+
+**Source modules:** ~19 Elixir modules + 2 Idris2 ABI + 2 Zig FFI parsers.
+
+## Coverage Summary
+
+### ✅ Covered
+
+- **P2P (Property-Based) Tests**
+  - Policy compilation: arbitrary YAML through compiler (`test/fuzz_test.exs`)
+  - Circuit breaker: state machine transitions (`test/circuit_breaker_test.exs`)
+  - Rate limiter: token bucket under contention (`test/concurrency_test.exs`)
+
+- **E2E Tests**
+  - Full request lifecycle (`test/e2e_test.exs`)
+  - Policy hot-reload under load (`test/concurrency_test.exs`)
+  - Health check / readiness probe validation (`test/e2e_test.exs`)
+
+- **Aspect Tests**
+  - **Security:** Request sanitization, header injection, SSRF prevention, capability token validation (`test/security_test.exs`)
+  - **Concurrency:** Rate limiter and circuit breaker under contention (`test/concurrency_test.exs`)
+  - **Performance:** Rate limiter, circuit breaker, route lookup benchmarks (`test/benchmark_test.exs`)
+
+- **Benchmarks**
+  - Rate limiter throughput (`test/benchmark_test.exs`)
+  - Circuit breaker state transition cost (`test/benchmark_test.exs`)
+  - Exact vs regex vs global-fallback route lookup (`test/benchmark_test.exs`)
+  - Policy evaluation overhead (`test/performance_test.exs`)
+  - Full plug pipeline throughput (`test/benchmark_test.exs`)
+
+### ⚠️ Still Missing
+
+- **Multi-protocol routing tests** — GraphQL/gRPC handlers are stubs per `docs/SUPPORTED-FEATURES.md`, so this is out of MVP scope rather than "missing".
+- **Zig FFI integration test execution** — requires zig toolchain; covered by separate FFI build step.
+- **Container build smoke test** — performed in CI, not in `mix test`.
+- **Error handling: upstream timeout** — Req receive_timeout covered implicitly; no dedicated test.
+- **Real-CA mTLS integration test** — code uses `Record.extract` accessors but no live cert in test fixtures.
+- **Self-tests for config validation on startup** — Application.start refuses without policy, but no dedicated assertion.
 
 ## Priority
 
-**CRITICAL.** 19 modules with 7 unit tests = 37% coverage by file count. A security gateway with ZERO security tests is a contradiction. No benchmarks for a performance-sensitive proxy is unacceptable. No concurrency tests for a concurrent system is negligent.
+Originally **CRITICAL** when only 7 unit tests covered 19 modules.
+Now: the release gate in `docs/RELEASE-CRITERIA.md` maps every MVP claim
+to a concrete test file. Remaining items are clearly marked above and
+are not release blockers for v0.1.0.
 
 ## FUZZ STATUS
 

TOPOLOGY.md

@@ -1,6 +1,13 @@
 <!-- SPDX-License-Identifier: PMPL-1.0-or-later -->
-<!-- TOPOLOGY.md — Project architecture map and completion dashboard -->
-<!-- Last updated: 2026-02-28 -->
+<!-- TOPOLOGY.md — Project architecture map and component status -->
+<!-- Last updated: 2026-04-16 -->
+
+> **Note (2026-04-16):** The "completion percentage" model used in earlier
+> versions of this document was misleading — components claimed as "100%"
+> (e.g., mTLS) were verified-broken in review. This document now reports
+> **implementation status** rather than topology percentages. For the
+> authoritative "what works today" picture, see `docs/SUPPORTED-FEATURES.md`.
+> For release gating, see `docs/RELEASE-CRITERIA.md`.
 
 # http-capability-gateway — Project Topology
 
@@ -48,38 +55,42 @@
                         └─────────────────────────────────────────┘
 ```
 
-## Completion Dashboard
-
-```
-COMPONENT                          STATUS              NOTES
-─────────────────────────────────  ──────────────────  ─────────────────────────────────
-CORE GATEWAY
-  Policy Loader (DSL v1)            ██████████ 100%    YAML spec parsing stable
-  Validator                         ██████████ 100%    Schema validation verified
-  Compiler (Tiered Lookup)          ██████████ 100%    O(1) exact + O(r) regex + O(1) global
-  Enforcement Engine                ██████████ 100%    Verb gating verified
-  Security Headers                  ██████████ 100%    OWASP hardened (nosniff, DENY, etc.)
-
-INTERFACES & LOGS
-  HTTP Proxy Layer                  ████████░░  80%    Scaling logic refining
-  Structured JSON Logs              ██████████ 100%    Audit-grade logs stable
-  Stealth Profiles                  ██████░░░░  60%    Limited profile active
-  Prometheus Metrics                ██████████ 100%    Telemetry export active
-
-HEALTH & TRUST
-  Health Check (/health)            ██████████ 100%    Uptime, version, status
-  Readiness Check (/ready)          ██████████ 100%    Policy + ETS validation
-  mTLS Trust Extraction             ██████████ 100%    Certificate-based trust levels
-  Trust Header Extraction           ██████████ 100%    X-Trust-Level header support
-
-REPO INFRASTRUCTURE
-  Justfile Automation               ██████████ 100%    Standard build/run tasks
-  .machine_readable/                ██████████ 100%    STATE.scm tracking
-  Containerfile                     ██████████ 100%    Chainguard-based deployment
-
-─────────────────────────────────────────────────────────────────────────────
-OVERALL:                            █████████░  ~97%   Production-ready, optimised
-```
+## Component Status
+
+Statuses below are backed by executed tests. See `docs/SUPPORTED-FEATURES.md`
+for detailed caveats.
+
+| Component | Status | Verified By |
+|-----------|--------|-------------|
+| **CORE GATEWAY** | | |
+| Policy Loader (DSL v1) | Supported | `test/policy_loader_test.exs` |
+| Validator | Supported | `test/policy_validator_test.exs` |
+| Compiler (Tiered Lookup) | Supported | `test/policy_compiler_test.exs`, `test/benchmark_test.exs` |
+| Enforcement Engine | Supported | `test/gateway_test.exs`, `test/e2e_test.exs` |
+| Security Headers | Supported | `test/security_test.exs` |
+| Atomic Policy Reload | Supported | `test/e2e_test.exs`, `test/concurrency_test.exs` |
+| **INTERFACES & LOGS** | | |
+| HTTP Proxy Layer | Supported | `test/e2e_test.exs` (502 on backend down) |
+| Structured JSON Logs | Supported | Emitted by `log_decision/7`; no direct assertion |
+| Stealth Profiles | Supported | `test/gateway_test.exs` stealth describe block |
+| Prometheus Metrics | Supported | `GET /metrics` covered by e2e setup |
+| **HEALTH & TRUST** | | |
+| Health Check (`/health`) | Supported | `test/e2e_test.exs` |
+| Readiness Check (`/ready`) | Supported | `test/e2e_test.exs` |
+| Trust Header Extraction | Supported | `test/security_test.exs` |
+| Trust Header Spoofing Protection | Supported | `test/security_test.exs` |
+| mTLS Trust Extraction | Supported with caveats | Code uses `Record.extract` accessors; no integration test against a real CA yet |
+| Rate Limiter (trust-scoped) | Supported | `test/concurrency_test.exs`, `test/benchmark_test.exs` |
+| Circuit Breaker | Supported | `test/circuit_breaker_test.exs`, `test/concurrency_test.exs` |
+| K9 Service Contracts | Supported | `test/k9_contract_test.exs` |
+| **PROTOCOL HANDLERS** | | |
+| HTTP/REST | Supported | Full test coverage |
+| GraphQL | Stub only | `check_operation_policy/2` always returns true; do not use in production |
+| gRPC | Stub only | `forward_grpc_request/5` returns hardcoded response; do not use in production |
+| **REPO INFRASTRUCTURE** | | |
+| Justfile Automation | Supported | N/A (developer tooling) |
+| `.machine_readable/` | Supported | `STATE.a2ml` authoritative |
+| Containerfile | Supported | Builds documented in `docs/DEPLOYMENT.md` |
 
 ## Key Dependencies
 
@@ -94,10 +105,14 @@ HTTP Traffic ───────► Enforcement ──────────
 
 This file is maintained by both humans and AI agents. When updating:
 
-1. **After completing a component**: Change its bar and percentage
-2. **After adding a component**: Add a new row in the appropriate section
-3. **After architectural changes**: Update the ASCII diagram
-4. **Date**: Update the `Last updated` comment at the top of this file
+1. **Status changes**: A component moves to "Supported" only when it has at
+   least one executed test. Do not claim completion based on code presence.
+2. **Adding a component**: Add a new row with the test file that verifies it.
+   If no test exists, mark as "Stub only" or "Not implemented".
+3. **Architectural changes**: Update the ASCII diagram in the System Architecture section.
+4. **Date**: Update the `Last updated` comment at the top of this file.
+5. **No percentages**: Percentage-based completion claims are banned —
+   they encouraged unjustified optimism (see 2026-04-16 correction note).
 
 Progress bars use: `█` (filled) and `░` (empty), 10 characters wide.
 Percentages: 0%, 10%, 20%, ... 100% (in 10% increments).

docs/RELEASE-CRITERIA.md

@@ -0,0 +1,134 @@
+<!-- SPDX-License-Identifier: PMPL-1.0-or-later -->
+
+# Release Criteria — HTTP Capability Gateway
+
+**Version:** applies from v0.1.0 onward
+**Last updated:** 2026-04-16
+
+This document replaces any earlier percentage-based release gating.
+A release is either ready or it isn't, and readiness is determined by
+**executed tests**, not topology coverage bars or design-document
+completion claims.
+
+## Principle: Executed Tests, Not Topology
+
+The ROADMAP.adoc P0 section explicitly calls out the problem:
+
+> Add release criteria that require executed tests rather than topology
+> percentages.
+
+Historically, documents like `TOPOLOGY.md` advertised "OVERALL: ~97%
+Production-ready" while core features (e.g., mTLS certificate subject
+extraction) were demonstrably broken when reviewed. This caused false
+confidence. Going forward, release readiness is measured only by what
+the test suite actually exercises.
+
+---
+
+## v0.1.0 Release Gate
+
+A v0.1.0 release SHALL meet **all** of the following criteria. Each one is
+checkable by running the test suite or inspecting a deterministic artefact.
+
+### 1. Test-suite Gate
+
+- [ ] `mix test` exits 0 (unit tests + security + E2E pass)
+- [ ] `mix test --only :concurrency` exits 0 (concurrency/failure modes)
+- [ ] `mix test --only :property` exits 0 (property-based tests)
+- [ ] No test is tagged `:skip` or `@tag :pending` in main branch
+- [ ] The fuzz suite (`test/fuzz_test.exs`) exits 0 with default `max_runs`
+
+### 2. MVP Scope Gate
+
+For each claim in `ROADMAP.adoc` "MVP Proof Requirements" table, there
+must be at least one passing test in the specified file:
+
+- [ ] Policy loading → `test/policy_loader_test.exs`
+- [ ] Policy validation → `test/policy_validator_test.exs`
+- [ ] Policy compilation → `test/policy_compiler_test.exs`
+- [ ] Trust extraction → `test/security_test.exs`
+- [ ] Verb governance → `test/gateway_test.exs`, `test/e2e_test.exs`
+- [ ] Allow/deny decisions → `test/e2e_test.exs`
+- [ ] Stealth mode → `test/gateway_test.exs`
+- [ ] Rate limiting → `test/concurrency_test.exs`, `test/benchmark_test.exs`
+- [ ] Health/readiness → `test/e2e_test.exs`
+- [ ] Atomic policy reload → `test/e2e_test.exs`, `test/concurrency_test.exs`
+- [ ] Request sanitization → `test/security_test.exs`
+- [ ] Trust spoofing prevention → `test/security_test.exs`
+- [ ] No atom exhaustion → `test/fuzz_test.exs`
+- [ ] No crash on arbitrary input → `test/fuzz_test.exs`
+- [ ] Circuit breaker FSM → `test/circuit_breaker_test.exs`
+- [ ] K9 contracts → `test/k9_contract_test.exs`
+
+### 3. Documentation Gate
+
+- [ ] `docs/SUPPORTED-FEATURES.md` lists no "Supported" feature without
+      a corresponding test file
+- [ ] `STATE.adoc` version matches `mix.exs` version
+- [ ] `.machine_readable/STATE.a2ml` version matches `mix.exs` version
+- [ ] No historical document claims current-state facts without a prominent
+      "HISTORICAL" banner
+
+### 4. Security Gate
+
+- [ ] No unaddressed High-severity findings in `report.json`
+- [ ] No `String.to_atom/1` or `String.to_existing_atom/1` calls on user-supplied input
+- [ ] No hardcoded secrets (verified by `panic-attacker` scan)
+- [ ] Security headers verified on all response paths (including denied/health/metrics)
+
+### 5. Operator Gate
+
+- [ ] `docs/SUPPORTED-FEATURES.md` operator checklist is reviewable before deployment
+- [ ] `docs/DEPLOYMENT.md` version references match `mix.exs` version
+- [ ] At least one reference deployment described in `docs/SCOPED-DEPLOYMENT.md`
+      (selected routes, not whole surface)
+
+---
+
+## What is NOT a Release Gate
+
+The following are deliberately excluded from the release gate because they
+proved to be misleading:
+
+- **Topology percentages**: Component completion bars.
+- **Lines of code**: LOC is not a progress metric.
+- **Number of modules implemented**: Code presence ≠ correctness.
+- **Design doc completion**: Documents describing a feature ≠ the feature working.
+- **Self-declared status**: A module claiming "stable" in its `@moduledoc`
+  is not evidence of stability.
+
+These may still appear in dashboards for informational purposes, but they
+do not gate the release.
+
+---
+
+## Pre-release Checklist
+
+Before tagging a release, execute in order:
+
+```bash
+just build                     # or: mix compile --warnings-as-errors
+just test                      # mix test (P0 unit + security + E2E + fuzz)
+mix test --only :concurrency   # P1 contention tests
+mix test --only :benchmark     # P1 benchmarks (smoke bounds only)
+just security-scan             # panic-attacker / scorecard
+just doctor                    # environment validation
+```
+
+All commands MUST exit 0. If any fail, the release is blocked regardless
+of how many "97% complete" bars the topology shows.
+
+---
+
+## Amendment Policy
+
+This document can only be amended by:
+
+1. Adding a new gate (stricter release criteria) — any maintainer.
+2. Removing a gate — requires explicit rationale in the commit message
+   explaining why the previous gate was wrong or is now covered elsewhere.
+3. Renaming a test file — update the referring section atomically in the
+   same commit.
+
+Weakening the gates without evidence undermines the entire point of this
+document.