@7h3/protocol 0.4.0 → 0.5.1

package/docs/GATEWAY.md

@@ -1,195 +0,0 @@
-# 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

@@ -1,53 +0,0 @@
-# 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

@@ -1,69 +0,0 @@
-# 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

@@ -1,159 +0,0 @@
-# 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

@@ -1,40 +0,0 @@
-# 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

@@ -1,184 +0,0 @@
-# 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`