@7h3/protocol 0.1.2 → 0.5.0

package/docs/GATEWAY.md

@@ -0,0 +1,195 @@
+# 7h3 Protocol — Gateway Quick-Start
+
+The 7h3 gateway is a verifying HTTP reverse proxy.  It sits in front of your
+service, intercepts every request, checks that the AIP envelope header carries
+a valid Ed25519 (or HMAC) signature from a known sender, enforces per-route
+policies and rate limits, optionally signs upstream responses, then forwards
+clean HTTP to your application.
+
+---
+
+## 1. Install
+
+```bash
+npm install @7h3/protocol
+```
+
+`tsx` is required to run the CLI from source.  It is listed as a dev
+dependency and is also installed globally in the Docker image.
+
+```bash
+npm install -g tsx          # if running outside Docker
+```
+
+---
+
+## 2. In-Process Middleware
+
+Drop the gateway into an existing Express (or any Node.js `http`) server in
+three lines:
+
+```ts
+import express from 'express'
+import { createGateway } from '@7h3/protocol/gateway'
+import { createStaticKeyRegistry } from '@7h3/protocol/key-registry'
+
+const app = express()
+
+const registry = createStaticKeyRegistry({
+  'agent@example.com': process.env.AGENT_PUBLIC_KEY!,
+})
+
+const gateway = createGateway({
+  upstream: 'http://internal-api:3000',
+  keyRegistry: registry,
+  defaultPolicy: 'deny',
+})
+
+// Verify every request before it reaches your routes
+app.use(async (req, res, next) => {
+  const headers: Record<string, string> = {}
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (typeof v === 'string') headers[k] = v
+    else if (Array.isArray(v)) headers[k] = v[0]
+  }
+  const outcome = await gateway.verify({ method: req.method, path: req.path, headers })
+  if (!outcome.ok) return res.status(outcome.status).json({ error: outcome.reason })
+  res.locals.sender = outcome.sender
+  next()
+})
+```
+
+---
+
+## 3. Gateway Mode (CLI / Standalone Proxy)
+
+### 3a. Generate a keypair
+
+```bash
+7h3 keygen --output keys.json
+```
+
+This writes a JSON file with `publicKey` and `privateKey` (both base64url-encoded
+Ed25519 SPKI/PKCS8).  Store `privateKey` in a secret; share `publicKey` with
+the agents that will call your service.
+
+### 3b. Start the gateway
+
+```bash
+7h3 gateway \
+  --upstream http://localhost:3000 \
+  --public-key <base64url-SPKI> \
+  --port 8080 \
+  --require ed25519
+```
+
+Full options:
+
+| Flag | Default | Description |
+|---|---|---|
+| `--upstream <url>` | _(required)_ | Upstream service URL |
+| `--port <n>` | `8080` | Port to listen on |
+| `--require ed25519\|none` | `ed25519` if `--public-key` is set, else `none` | Signature mode |
+| `--public-key <key>` | — | Ed25519 SPKI public key (base64url) |
+| `--sign-responses` | `false` | Sign every proxied response |
+| `--private-key <key>` | — | Private key for response signing |
+| `--sender <id>` | — | Sender ID attached to signed responses |
+
+---
+
+## 4. Docker
+
+```bash
+# Bring up the gateway + example upstream
+docker compose up --build
+
+# Test with a health probe (no signature required)
+curl http://localhost:8080/health
+
+# Generate keys, then call a signed route
+7h3 keygen --output keys.json
+PRIV=$(jq -r .privateKey keys.json)
+PUB=$(jq -r .publicKey keys.json)
+
+ENVELOPE=$(7h3 sign --private-key "$PRIV" --sender agent@example.com --payload '{"q":"hello"}')
+curl -H "x-7h3-envelope: $ENVELOPE" http://localhost:8080/api/hello
+```
+
+To enable response signing, pass environment variables to the gateway service
+in `docker-compose.yaml`:
+
+```yaml
+environment:
+  GATEWAY_PRIVATE_KEY: <your-private-key>
+  GATEWAY_SENDER: gateway@my-service.example.com
+```
+
+---
+
+## 5. Config Reference (YAML)
+
+See `7h3.example.yaml` for a fully-annotated configuration file.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `upstream` | string | _(required)_ | Upstream base URL |
+| `port` | number | `8080` | Listening port |
+| `sender` | string | — | Gateway sender identity for signed responses |
+| `sign_responses` | boolean | `false` | Sign every proxied response |
+| `default_policy` | `allow` \| `deny` | `allow` | Behaviour when no route policy matches |
+| `keys.private_key` | string | — | Gateway Ed25519 private key (base64url PKCS8) |
+| `keys.registry` | map | `{}` | `senderID → publicKey` (base64url SPKI) |
+| `policies[].path` | glob string | _(required)_ | Route glob (`**` crosses slashes) |
+| `policies[].require` | `ed25519` \| `hmac` \| `any` \| `none` | _(required)_ | Signature algorithm |
+| `policies[].allowed_senders` | string[] | _(all)_ | Allowlist of sender IDs |
+| `policies[].rate_limit.requests` | number | — | Max requests in window |
+| `policies[].rate_limit.window_ms` | number | — | Sliding window in ms |
+| `policies[].sign_response` | boolean | — | Per-route response signing override |
+
+---
+
+## 6. Client-Side Signing
+
+Agents calling a 7h3-protected gateway must attach a signed AIP envelope to
+every request.  Use the TypeScript SDK:
+
+```ts
+import { createEnvelope, signEnvelopeEd25519 } from '@7h3/protocol'
+import { attachEnvelopeToHeaders } from '@7h3/protocol/http'
+
+async function signedFetch(url: string, body: string, privateKey: string) {
+  const envelope = createEnvelope({
+    sender: 'agent@example.com',
+    recipient: 'gateway@my-service.example.com',
+    intent: 'REQUEST',
+    content: body,
+    ttlMs: 60_000,
+  })
+
+  const signed = await signEnvelopeEd25519(envelope, privateKey)
+  const headers = attachEnvelopeToHeaders(signed, {})   // adds x-7h3-envelope
+
+  return fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...headers },
+    body,
+  })
+}
+```
+
+The gateway validates the envelope header, verifies the Ed25519 signature
+against the sender's registered public key, checks replay protection, and only
+then forwards the request to the upstream service.
+
+---
+
+## 7. Policy Examples
+
+| Use Case | `path` | `require` | `allowed_senders` | `rate_limit` |
+|---|---|---|---|---|
+| Public health probe | `/health` | `none` | — | — |
+| Open public API | `/public/**` | `none` | — | — |
+| Any authenticated agent | `/api/**` | `ed25519` | — | 1 000 req / 60 s |
+| Named admin agents only | `/api/admin/**` | `ed25519` | `admin-agent@…`, `orchestrator@…` | — |
+| Partner integration | `/api/partner/**` | `ed25519` | `partner-bot@partner.example.com` | 200 req / 60 s |
+| Webhook receiver | `/webhooks/**` | `hmac` | — | 500 req / 60 s |

package/docs/KEY_MANAGEMENT_POLICY.md

@@ -0,0 +1,53 @@
+# 7h3 Protocol AIP Key Management Policy (v1.0 draft)
+
+## Supported signature profiles
+
+- `HS256` (shared secret)
+- `ED25519` (asymmetric keypair)
+
+## Key ID rules
+
+- Every signing key must have a unique `keyId`.
+- Verifiers must resolve verification material by both `keyId` and `sender`.
+- Reusing the same `keyId` for different senders is prohibited.
+
+## Rotation policy
+
+- Rotation interval target:
+  - `HS256`: every 30 days
+  - `ED25519`: every 90 days
+- Rotation process:
+  1. Provision new key as active for signing.
+  2. Keep previous key in verify-only mode during overlap window.
+  3. End overlap and revoke old key.
+
+## Revocation policy
+
+- Immediate revocation triggers:
+  - suspected credential leak
+  - host compromise
+  - failed integrity investigation
+- Revoked keys must fail verification in resolver control plane within SLA.
+- For multi-node deployments, back revocation with a shared `RevocationStore`
+  (`createRedisRevocationStore`) and wrap the verification resolver with
+  `withRevocationCheck` so a revoke on one node is enforced fleet-wide. The
+  store fails **closed** by default: if the revocation list is unreachable, the
+  key is treated as revoked. See `KEY_REVOCATION.md`.
+
+## Storage requirements
+
+- Do not commit secrets/private keys to source control.
+- Store key material in managed secrets/KMS.
+- Restrict read access to signing services and verification control plane.
+
+## Runtime policy
+
+- Production endpoints require signatures by default.
+- `HS256` is recommended for tightly controlled private clusters.
+- `ED25519` is recommended for cross-domain or multi-tenant federation.
+- Use `RollingKeyring` (`src/keyRotation.ts`) for overlap windows, verify-only periods, and revocation enforcement.
+
+## Audit requirements
+
+- Log key activation, rotation, revocation, and failed verification events.
+- Retain audit logs for incident response and compliance windows.

package/docs/KEY_REVOCATION.md

@@ -0,0 +1,69 @@
+# Fleet-Wide Key Revocation
+
+`RollingKeyring` (`src/keyRotation.ts`) enforces revocation and `notBefore`/
+`notAfter` expiry **in-process**. For horizontally scaled deployments, a shared
+`RevocationStore` makes a revocation effective across every node: revoke a
+`(sender, keyId)` on one gateway and all gateways that consult the same store
+reject it.
+
+Source: `src/revocation.ts`.
+
+## Interfaces
+
+- `RevocationStore` — `isRevoked(sender, keyId, nowMs?)` and `revoke(sender, keyId, { untilMs? })`.
+- `InMemoryRevocationStore` — single-process implementation (tests, local dev, single node).
+- `createRedisRevocationStore` — Redis-backed shared store with cached reads.
+- `withRevocationCheck(resolver, store)` — wraps a signature resolver so a revoked key resolves to **no material**, which makes verification fail and the envelope is rejected.
+
+## Usage
+
+```ts
+import {
+  RollingKeyring,
+  createKeyringSignatureResolver,
+  createRedisRevocationStore,
+  withRevocationCheck,
+  receiveEnvelope,
+} from '@7h3/protocol'
+
+const keyring = new RollingKeyring(records)
+const revocations = createRedisRevocationStore(redisLikeClient, {
+  keyPrefix: 'aip:revoked:',
+  errorBehavior: 'reject', // fail closed (default)
+  cacheTtlMs: 5000,
+  onDegraded: (err, ctx) => metrics.increment('aip.revocation.degraded'),
+})
+
+const signatureResolver = withRevocationCheck(
+  createKeyringSignatureResolver(keyring),
+  revocations,
+)
+
+await receiveEnvelope(rawEnvelope, { signatureResolver })
+
+// Operationally, on a suspected compromise:
+await revocations.revoke('agent.worker', 'agent.worker-k1')           // permanent
+await revocations.revoke('agent.worker', 'agent.worker-k2', { untilMs: Date.now() + 86_400_000 }) // 24h
+```
+
+## Behavior on Redis outage (`errorBehavior`)
+
+| Value | On client error | Rationale |
+|---|---|---|
+| `reject` (default) | Treat the key as **revoked** (fail closed) | A revoked key is a compromised key — never accept on uncertainty |
+| `allow` | Treat the key as **not revoked** | Favor availability where the risk is acceptable |
+
+Reads are served from a short-lived local cache (`cacheTtlMs`), so:
+
+- the verify hot path does not hit Redis on every message (scalability), and
+- known revocations keep enforcing through a brief Redis outage (a stale cached
+  `revoked: true` is still honored).
+
+Every degraded decision fires `onDegraded` — degradation is never silent.
+
+## Operational guidance
+
+- Wire `withRevocationCheck` into every verifying node's `signatureResolver`.
+- Treat the `onDegraded` rate as a security signal; sustained degradation means
+  revocations may not be propagating.
+- Keep `cacheTtlMs` short enough that a revocation propagates within your SLA.

package/docs/MCP_WRAPPER.md

@@ -0,0 +1,159 @@
+# MCP Hardening Wrapper
+
+MCP messages are plain JSON-RPC 2.0 with no signature and no replay protection.
+This wrapper puts a signed AIP envelope around every MCP message on the wire —
+authenticating it, TTL-bounding it, and replay-checking it — **without changing
+your MCP handler**. Your handler still receives plain JSON-RPC `{ method, params }`
+and returns plain results; AIP lives entirely on the wire.
+
+Source: `src/mcpWrapper.ts`. Runnable demo: `npm run aip:mcp:wrap`.
+
+## Threat coverage
+
+| Threat | Covered by |
+|---|---|
+| Message tampering (params/method altered in flight) | Canonical signature over the envelope (HS256 / Ed25519) |
+| Replay / duplicate execution | `(sender, messageId, nonce)` replay cache + TTL; **on by default** (`InMemoryReplayCache` if none supplied) |
+| Cross-server relay (valid envelope for server A replayed to server B) | **Recipient binding** — the server runs the handler only when `recipient === selfAgentId` |
+| Response spoofing (another valid signer answers) | **Sender binding** — the client accepts a response only when `sender === peerAgentId` (peerAgentId is required) |
+| Response substitution (a valid response to request A returned for request B) | **Correlation binding** — the client requires `correlationId === the request's messageId` |
+| Compromised key still in use | Compose `withRevocationCheck` into `receive.signatureResolver` |
+
+`encodeRequest` returns `{ raw, messageId }`; pass `messageId` to `decodeResponse(raw, { expectCorrelationId })` to enforce the correlation binding (`wrapMcpClient` does this for you).
+
+## Server side — wrap an existing handler
+
+```ts
+import { wrapMcpServer, signEnvelopeHmac } from '@7h3/protocol'
+import { DistributedReplayCache, createRedisReplayStore } from '@7h3/protocol'
+
+// Your existing MCP handler — unchanged, AIP-unaware.
+async function myMcpServer(request) {
+  if (request.method === 'tools/call') return { jsonrpc: '2.0', id: request.id, result: runTool(request.params) }
+  return { jsonrpc: '2.0', id: request.id, error: { code: -32601, message: 'Method not found' } }
+}
+
+const secured = wrapMcpServer(myMcpServer, {
+  selfAgentId: 'agent.mcp-server',
+  sign: (e) => signEnvelopeHmac(e, process.env.AIP_SECRET!, 'server-k1'),
+  receive: {
+    secretResolver: async () => process.env.AIP_SECRET!,
+    replayCache: new DistributedReplayCache(createRedisReplayStore(redisLikeClient)), // fleet-wide replay
+  },
+})
+
+// `secured(rawWireEnvelope) => Promise<rawWireEnvelope>` — drop it into your stdio/HTTP transport read loop.
+```
+
+## HMAC vs Ed25519
+
+| | HMAC (HS256) | Ed25519 |
+|---|---|---|
+| Secret model | Shared secret — both sides can sign and verify | Keypair — only you can sign; peers verify with your public key |
+| Peer compromise | A compromised peer can forge messages | A compromised peer cannot forge your messages |
+| Key distribution | One secret distributed to all trusted peers | Public key is safe to publish; private key never leaves the signer |
+| When to use | Dev, testing, fully trusted internal infra | Production, multi-tenant, or any boundary where you do not control both sides |
+
+**Use HMAC when** you own both sides of the wire (same team, same trusted cluster) and want the simplest possible setup.
+
+**Use Ed25519 in production.** If a worker/peer node is compromised, the attacker gains verify capability only — they cannot impersonate the signer.
+
+Ed25519 server example (replace the HMAC `sign`/`receive` block above):
+
+```ts
+import { wrapMcpServer, signEnvelopeEd25519 } from '@7h3/protocol'
+
+// Generate keys once: npx @7h3/protocol-mcp → aip_generate_keypair
+// Set AIP_PRIVATE_KEY (server) and distribute AIP_CLIENT_PUBLIC_KEY (client's pubkey)
+
+const secured = wrapMcpServer(myMcpServer, {
+  selfAgentId: 'agent.mcp-server',
+  sign: (e) => signEnvelopeEd25519(e, process.env.AIP_PRIVATE_KEY!, 'k1'),
+  receive: {
+    signatureResolver: async (sig) =>
+      sig.alg === 'ED25519'
+        ? { alg: 'ED25519' as const, publicKey: process.env.AIP_CLIENT_PUBLIC_KEY! }
+        : undefined,
+  },
+})
+```
+
+## Client side — sign requests, verify responses
+
+```ts
+import { wrapMcpClient, signEnvelopeHmac } from '@7h3/protocol'
+
+const call = wrapMcpClient(transport.send /* (raw) => Promise<raw> */, {
+  selfAgentId: 'agent.mcp-client',
+  peerAgentId: 'agent.mcp-server',
+  sign: (e) => signEnvelopeHmac(e, process.env.AIP_SECRET!, 'client-k1'),
+  receive: { secretResolver: async () => process.env.AIP_SECRET! },
+})
+
+const result = await call({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'planner' } })
+// throws if the server response signature does not verify
+```
+
+`createMcpClientCodec(options)` exposes `encodeRequest` / `decodeResponse` directly
+when you manage the transport send yourself. `encodeRequest` returns
+`{ raw, messageId }`; pass that `messageId` as `decodeResponse(raw, { expectCorrelationId })`
+to bind each response to its request. `peerAgentId` is required so responses can be
+bound to the expected sender.
+
+## Composes with the rest of the stack
+
+The `receive` field is a full `ReceiveEnvelopeOptions`, so the wrapper inherits
+everything the transport pipeline offers:
+
+- **Fleet-wide replay** — pass a `DistributedReplayCache(createRedisReplayStore(...))`.
+- **Key revocation** — set `receive.signatureResolver = withRevocationCheck(resolver, revocationStore)`.
+- **Ed25519** — sign with `signEnvelopeEd25519` and resolve material via `signatureResolver`.
+- **Clock skew / TTL / telemetry** — `maxClockSkewMs`, `telemetry`, etc.
+
+## Transports
+
+The wrapper is transport-agnostic (it operates on wire envelopes). Two adapters
+connect it to real transports; both keep the handler on plain JSON-RPC.
+
+### stdio (newline-delimited)
+
+```ts
+import { wrapMcpServer, serveMcpOverStdio, createStdioMcpClient, wrapMcpClient } from '@7h3/protocol'
+
+// server process: read envelopes from stdin, write replies to stdout
+serveMcpOverStdio(wrapMcpServer(myMcpServer, serverOpts)) // defaults to process.stdin/stdout
+
+// client process: spawn the server and talk to it
+const stdio = createStdioMcpClient({ input: child.stdout, output: child.stdin })
+const call = wrapMcpClient(stdio.send, clientOpts)
+const result = await call({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'planner' } })
+```
+
+Stdio frames one envelope per line, so it supports the `json` and `compact` wire
+formats. For `binary`, use HTTP.
+
+### HTTP
+
+```ts
+import http from 'node:http'
+import { wrapMcpServer, createHttpMcpHandler, createHttpMcpClient, wrapMcpClient } from '@7h3/protocol'
+
+// server: any node:http-compatible host
+http.createServer(createHttpMcpHandler(wrapMcpServer(myMcpServer, serverOpts))).listen(8787)
+
+// client: POSTs each request envelope, returns the reply envelope (global fetch)
+const httpClient = createHttpMcpClient({ url: 'http://localhost:8787' })
+const call = wrapMcpClient(httpClient.send, clientOpts)
+const result = await call({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'planner' } })
+```
+
+Pass `{ binary: true }` to both `createHttpMcpHandler` and `createHttpMcpClient`
+to use the `binary` wire format over HTTP.
+
+## Notes
+
+- Both peers must be wrapped: the on-wire message is an AIP envelope, not plain
+  JSON-RPC. For interop with un-wrapped MCP peers, terminate AIP at a gateway.
+- `wireFormat` defaults to `compact`; use `binary` for the highest-throughput lanes.
+- Verification failures and replays come back as signed JSON-RPC errors
+  (`-32600`), so the client still gets an authenticated, well-formed response.

package/docs/MIGRATION_GUIDE.md

@@ -0,0 +1,40 @@
+# AIP Migration Guide
+
+## Import path migration (JS/TS)
+
+Use the stable package subpath export:
+
+```ts
+import { createAipAgentAdapter, receiveEnvelope } from '@7h3/protocol'
+```
+
+Avoid repo-relative imports in consumer apps.
+
+## Signature profile migration
+
+### HS256 to ED25519
+
+1. Generate/provision ED25519 key pairs.
+2. Keep HS256 verification active during overlap window.
+3. Start signing outbound envelopes with ED25519.
+4. Monitor verify failures by algorithm.
+5. Revoke/decommission HS256 keys after migration window.
+
+## Replay cache migration
+
+### Single-node to distributed
+
+1. Replace `InMemoryReplayCache` with `DistributedReplayCache`.
+2. Implement atomic reserve in shared store (for example Redis `SET NX PX`).
+3. Roll out gradually and monitor replay reject metrics.
+
+## Clock skew migration
+
+1. Start with default `maxClockSkewMs` (30s).
+2. Tighten to lower values in synchronized environments.
+3. Monitor `rejected_clock_skew` telemetry for false-positive tuning.
+
+## Rollback guidance
+
+- Keep prior verification profiles and key material during rollout.
+- Do not remove old verifiers until telemetry confirms stable traffic.

package/docs/OPERATORS.md

@@ -0,0 +1,184 @@
+# GLUV Operators Guide
+
+This guide is for SRE, platform, and performance teams operating GLUV-backed workloads in production.
+
+---
+
+## 1) Operational objectives
+
+Primary objectives:
+
+1. Maintain low drop-rate under declared load profiles
+2. Maintain p99 latency SLO
+3. Preserve signature/replay guarantees under stress
+4. Detect and stop regressions before release
+
+---
+
+## 2) SLO model
+
+Define SLOs per traffic class (example baseline):
+
+- **Availability:** protocol receive path success ≥ 99.9%
+- **Drop rate:** `dropPct <= 0.1%` (or 0% for critical lanes)
+- **Latency:** p99 <= 20ms (adjust by payload and transport class)
+- **Integrity:** 100% signature verification and replay checks on ingress
+
+Important: “no drop” means **within declared operating envelope**. Any system can be overloaded if offered load exceeds capacity.
+
+---
+
+## 3) Transport selection matrix
+
+Use this default selection policy:
+
+| Workload | Recommended Mode | Why |
+|---|---|---|
+| High-throughput lane | `http-binary-batch` or `ws-binary-batch` | best throughput and lowest overhead |
+| Balanced latency/compatibility | `ws-batch` | low framing overhead and stable p99 |
+| Low/medium compatibility lane | `http` | simplest interoperability |
+| Stress testing only | `http` + `--allow-unsafe-http` | intentional overload characterization |
+
+Guardrail behavior in benchmark harness blocks unsafe plain HTTP at high concurrency unless explicitly overridden.
+
+---
+
+## 4) Benchmark discipline
+
+### Sustainable benchmarks (default)
+
+Use adaptive benchmark commands for release confidence:
+
+```bash
+npm run bench:openloop:quick
+npm run bench:openloop:full
+```
+
+These discover sustainable operating rates using threshold gates.
+
+### Stress benchmarks (explicit overload)
+
+Use only for capacity ceiling exploration:
+
+```bash
+npm run bench:openloop:stress:quick
+npm run bench:openloop:stress:full
+```
+
+Do not use stress runs alone as production readiness criteria.
+
+---
+
+## 5) Core runbook commands
+
+### Quality and release gates
+
+```bash
+npm run lint
+npm run test
+npm run build
+npm run release:gate
+```
+
+### Conformance gates
+
+```bash
+npm run conformance:python
+npm run conformance:rust
+npm run conformance:binary
+```
+
+### Benchmark analysis
+
+```bash
+npm run bench:diff -- --baseline <baseline.json> --candidate <candidate.json>
+npm run release:dashboard
+```
+
+---
+
+## 6) Incident runbook
+
+### Symptom: high drop rate
+
+1. Confirm mode and benchmark class (adaptive vs stress)
+2. Check if plain HTTP is being used at high concurrency
+3. Switch to binary batch mode for hot lanes
+4. Inspect overload/retry behavior and queue pressure
+5. Reduce offered rate or widen worker capacity
+
+### Symptom: p99 latency spike
+
+1. Compare payload size distribution against baseline
+2. Check in-flight cap / batch-size adaptation behavior
+3. Verify no regression in signature profile or canonicalization path
+4. Re-run adaptive benchmark for sustainable envelope
+
+### Symptom: signature failures
+
+1. Validate key resolver outputs and key IDs
+2. Verify canonicalization parity across runtime boundaries
+3. Check clock skew / TTL policy window
+
+### Symptom: replay rejections
+
+1. Verify message uniqueness (`messageId`, `nonce`)
+2. Validate replay cache window sizing
+3. Confirm producer retry semantics are idempotent
+
+---
+
+## 7) Tuning matrix (starting points)
+
+| Setting | Low Traffic | Medium Traffic | High Traffic |
+|---|---:|---:|---:|
+| Batch size | 4–8 | 8–32 | 32–64 |
+| In-flight cap | 16–64 | 64–256 | 256–1024 |
+| Retry backoff | 1–2ms | 2–8ms | 4–16ms |
+| Preferred mode | `http`/`ws` | `ws-batch` | `http-binary-batch` / `ws-binary-batch` |
+
+Treat this as a starting policy; tune from measured p99/drop under adaptive runs.
+
+---
+
+## 8) Security and reliability invariants
+
+Never disable these in production:
+
+- signature verification
+- canonicalization checks
+- replay defense
+- TTL and clock-skew enforcement
+
+Any performance optimization must preserve these invariants.
+
+---
+
+## 9) Release acceptance checklist
+
+Release candidate is acceptable when:
+
+1. `release:gate` passes
+2. conformance suites pass (TS/Python/Rust/binary)
+3. adaptive benchmarks satisfy target SLO thresholds
+4. no critical regression in benchmark diff vs baseline
+5. rollback plan and threshold alerts are prepared
+
+---
+
+## 10) Recommended rollout strategy
+
+1. Canary 5%
+2. Observe drop/p99/signature/replay counters
+3. Expand 25% → 50% → 100%
+4. Auto-rollback if drop or p99 breaches thresholds for sustained window
+
+---
+
+## 11) Documentation map
+
+- Protocol technical guide: `README.md`
+- Executive brief: `README_EXECUTIVE.md`
+- Performance policy: `PERF_REGRESSION_POLICY.md`
+- Backpressure notes: `BACKPRESSURE_TUNING.md`
+- Release hardening: `RELEASE_GATE.md`