@7h3/protocol 0.4.0 → 0.5.1

package/docs/BACKPRESSURE_TUNING.md

@@ -1,65 +0,0 @@
-# Backpressure and Saturation Tuning
-
-This guide documents practical tuning for GLUV transport behavior under contention.
-
-## Baseline methodology
-
-Run these commands before tuning changes:
-
-```bash
-npm run bench:openloop:quick
-npm run bench:openloop:adaptive:quick
-npm run bench:e2e:quick
-```
-
-Focus on:
-
-- `dropPct` under target load
-- `p99Ms` tail latency
-- `stageQueueMsPerOp` and `stageTransportMsPerOp`
-
-## Tuning priorities
-
-1. Prefer `ws` / `ws-batch` for high concurrency when tail latency dominates.
-2. Prefer `ws-binary-batch` when p99 latency is more important than single-message peak throughput.
-3. Reduce per-request payload size first; large payloads amplify queue and transport tails.
-4. Set `batchConcurrency` on receive paths when verification work starts starving the event loop.
-5. Use adaptive gate thresholds to cap unstable targets in CI.
-6. Keep replay and signature verification enabled; tune concurrency and batching instead.
-
-## Batch receive guidance
-
-- Start with `batchConcurrency = 8` for service-side receive loops.
-- Lower it when p99 grows faster than throughput.
-- Raise it only when `stageVerifyMsPerOp` dominates and drop rate remains stable.
-- Keep replay caches shared across the whole session so duplicate messages inside one batch are rejected.
-
-## Binary WebSocket guidance
-
-Use the open-loop benchmark modes below before changing runtime defaults:
-
-```bash
-npm run bench:openloop:adaptive:quick -- --modes ws,ws-batch,ws-binary,ws-binary-batch --payloads 256 --concurrency 10
-```
-
-Current policy: binary WebSocket modes are opt-in until full-profile benchmarks prove a stable throughput gain. Compact WebSocket remains the compatibility default.
-
-## CI gate defaults
-
-Use:
-
-```bash
-npm run bench:openloop:adaptive:ci
-```
-
-This gate enforces sustained operation bounds through adaptive search with p99 and drop-rate constraints.
-
-## Regression check
-
-Compare candidate against baseline:
-
-```bash
-npm run bench:diff -- --baseline <path/to/baseline.json> --candidate <path/to/candidate.json>
-```
-
-Block merges/releases when tail latency or drop-rate regresses beyond accepted limits.

package/docs/BENCHMARK_CLAIM_MATRIX.md

@@ -1,42 +0,0 @@
-# 7h3 Protocol AIP Benchmark Claim Matrix (v1.0)
-
-Use this matrix when making public performance claims.
-
-## Standard environment
-
-- OS: Linux (x86_64)
-- Node: 22.x
-- CPU: publish model and core count in benchmark report
-- Memory: publish total RAM in benchmark report
-- Command profile: `quick` for PR signal, `full` for release evidence
-
-## Required benchmark suites
-
-- `npm run bench:protocol`
-- `npm run bench:e2e:quick`
-- `npm run bench:e2e:full`
-- `npm run bench:openloop:quick`
-- `npm run bench:openloop:full`
-- `npm run bench:openloop:adaptive:ci`
-- `npm run bench:signatures:quick`
-- `npm run bench:signatures:full`
-
-## Mandatory dimensions
-
-- Payload sizes: `256`, `1024`, `4096`, `16384` bytes
-- Concurrency: `1`, `10`, `100`, `1000`
-- Transport modes: `inproc`, `http`, `ws`, `agent-loop` where applicable
-- Signature profiles: `HS256`, `ED25519`
-
-## Required metrics
-
-- Throughput: ops/s
-- Latency: p50, p95, p99
-- Drop rate percentage (open-loop)
-- Stage timings where available (build/canonicalize/mac/queue/transport/verify/decode)
-
-## Evidence requirements
-
-- Store JSON outputs under `bench-results/` (ignored by git, attached in CI/release notes)
-- Include baseline and candidate runs for release branch
-- Include `bench:diff` summary for release signoff

package/docs/BENCHMARK_REPORT_TEMPLATE.md

@@ -1,169 +0,0 @@
-# Benchmark Report Template (Release-Grade)
-
-Use this template for every candidate release benchmark report.
-
----
-
-## 1) Metadata
-
-- Report ID:
-- Date/Time (UTC):
-- Author:
-- Branch/Commit:
-- Environment:
-  - CPU:
-  - Memory:
-  - OS/Kernel:
-  - Node/npm versions:
-  - Network locality (loopback/LAN/WAN):
-
----
-
-## 2) Benchmark Scope
-
-- Profile: `quick` / `full`
-- Modes tested:
-- Payload sizes:
-- Concurrency levels:
-- Adaptive thresholds:
-  - p99 threshold:
-  - drop threshold:
-
----
-
-## 3) Security Configuration Matrix (Required)
-
-Mark each row as enabled/disabled and include exact settings.
-
-| Check | Transport-only Baseline | Full Secure Protocol |
-|---|---:|---:|
-| Signature verification |  |  |
-| Canonicalization |  |  |
-| Replay defense |  |  |
-| TTL/clock-skew enforcement |  |  |
-| Policy checks/guardrails |  |  |
-
-> Rule: Any public “protocol performance” claim must reference **Full Secure Protocol** results.
-
----
-
-## 4) Commands Executed
-
-Include exact commands and flags.
-
-```bash
-# adaptive sustainable runs
-npm run bench:openloop:quick
-npm run bench:openloop:full
-
-# explicit stress runs
-npm run bench:openloop:stress:quick
-npm run bench:openloop:stress:full
-
-# optional focused modes
-npx tsx scripts/bench-protocol-openloop.ts --profile quick --adaptive --modes http-binary-batch,ws-binary-batch --payload-sizes 256,1024
-```
-
----
-
-## 5) Results Summary (Required)
-
-### A) Full Secure Protocol (authoritative)
-
-| Mode | Payload | Concurrency | Ops/s | Drop % | p99 ms | Sustainable |
-|---|---:|---:|---:|---:|---:|---|
-|  |  |  |  |  |  |  |
-
-### B) Transport-only Baseline (optional reference)
-
-| Mode | Payload | Concurrency | Ops/s | Drop % | p99 ms | Sustainable |
-|---|---:|---:|---:|---:|---:|---|
-|  |  |  |  |  |  |  |
-
----
-
-## 6) SLO Gates (Pass/Fail)
-
-Define and evaluate lane-specific gates.
-
-| Lane | Gate | Result | Pass/Fail |
-|---|---|---|---|
-| Interactive (<=100 concurrency) | p99 <= 25ms, drop <= 0.1% |  |  |
-| High-throughput (1000 concurrency) | p99 <= 100ms, drop <= 0.5% |  |  |
-| Security invariants | all enforced |  |  |
-
-Overall decision:
-
-- [ ] PASS
-- [ ] FAIL
-
----
-
-## 7) Pressure Signals and Interpretation
-
-Document pressure points and likely causes.
-
-- Queueing/scheduling pressure observed at:
-- Session/stream pressure observed at:
-- Retry/backoff behavior:
-- Mode-level instability (if any):
-
-Interpretation:
-
-- Is degradation expected under stress, or present in adaptive sustainable lane?
-- Are drops due to overload policy or protocol correctness issues?
-
----
-
-## 8) Remediation / Tuning Actions
-
-List actions taken or recommended.
-
-- [ ] Lower inflight cap
-- [ ] Reduce batch size
-- [ ] Increase retry backoff
-- [ ] Move lane to `*-binary-batch`
-- [ ] Tighten queue bounds/backpressure
-- [ ] Adjust priority lanes
-
----
-
-## 9) Claim Language (Publish-safe)
-
-Use this format:
-
-> "In full secure mode (signature + canonicalization + replay + TTL + policy enabled), mode X achieved Y ops/s at payload Z and concurrency C with drop D% and p99 P ms under adaptive sustainable thresholds."
-
-Avoid:
-
-- mixing stress outputs into production SLO claims,
-- reporting transport-only baseline as secure protocol performance.
-
----
-
-## 10) Evidence Attachments
-
-- Raw JSON output paths:
-- Markdown output paths:
-- `bench:diff` output:
-- `release:dashboard` output:
-- Relevant logs (if anomalies):
-
----
-
-## 11) Security Review Checklist
-
-- [ ] Signature verification enabled
-- [ ] Replay defense enabled
-- [ ] TTL/clock-skew checks enabled
-- [ ] No bypass flags used in production benchmark lane
-- [ ] Policy file validated (`npm run policy:validate`)
-
----
-
-## 12) Release Recommendation
-
-- Recommendation: `GO` / `NO-GO`
-- Conditions for GO:
-- Conditions requiring re-test:
-- Risk notes:

package/docs/BINARY_CODEC_BENCH.md

@@ -1,23 +0,0 @@
-# Binary Codec Benchmark
-
-GLUV includes a binary wire codec prototype in `src/protocolBinary.ts`.
-
-## Run comparison
-
-```bash
-npm run bench:wire:quick
-npm run bench:wire:full
-```
-
-The benchmark compares `compact-json` vs `binary` for:
-
-- encoded size
-- encode/decode micro-latency
-- encode/decode ops/s
-
-Results are written to `bench-results/wire-codecs-*.json`.
-
-## Notes
-
-- Binary codec currently targets envelope transport efficiency and deterministic roundtrip.
-- Keep compact JSON path for compatibility while binary path is evaluated for broader rollout.

package/docs/CLEAN_CLONE_RUNBOOK.md

@@ -1,36 +0,0 @@
-# Clean Clone Runbook
-
-Use this to verify deterministic setup from a fresh checkout.
-
-## TypeScript path
-
-```bash
-git clone https://github.com/IceMasterT/GLUV-Protocol.git
-cd GLUV-Protocol
-npm install
-npm run lint
-npm run test
-npm run build
-```
-
-## Conformance path
-
-```bash
-npm run conformance:python
-npm run conformance:rust
-```
-
-## Quickstart path
-
-```bash
-npm run aip:quickstart
-npm run aip:framework:quickstart
-printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"planner"}}' | npm run aip:mcp:gateway
-```
-
-## Rust gateway path
-
-```bash
-cargo test --manifest-path sdk/rust/Cargo.toml
-printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"planner"}}' | cargo run --manifest-path sdk/rust/Cargo.toml --bin aip_mcp_gateway
-```

package/docs/CLOCK_SKEW_POLICY.md

@@ -1,30 +0,0 @@
-# Clock Skew Policy
-
-GLUV transport enforces a configurable future timestamp tolerance.
-
-## Default
-
-- `maxClockSkewMs`: `30000` (30s)
-
-Messages with `header.timestampMs > nowMs + maxClockSkewMs` are rejected with:
-
-- `Message timestamp exceeds allowed clock skew`
-
-## Usage
-
-```ts
-import { receiveEnvelope } from './src/protocolTransport'
-
-const result = await receiveEnvelope(rawEnvelope, {
-  nowMs: Date.now(),
-  maxClockSkewMs: 10_000,
-  replayCache,
-  secretResolver: async () => sharedSecret,
-})
-```
-
-## Operational guidance
-
-- Keep NTP enabled for all nodes.
-- Use tighter skew windows for low-latency trusted clusters.
-- Use slightly wider windows for geo-distributed deployments.

package/docs/DISTRIBUTED_REPLAY.md

@@ -1,142 +0,0 @@
-# Distributed Replay Defense
-
-7h3 Protocol AIP protects against replay through pluggable cache interfaces.
-
-## Interfaces
-
-- `InMemoryReplayCache`: single-process replay protection.
-- `DistributedReplayCache`: wraps a shared `DistributedReplayStore` for multi-node deployments.
-- `createRedisReplayStore`: a production `DistributedReplayStore` backed by Redis-style `SET NX PX`.
-
-Source: `src/protocolReplay.ts`, `src/replayStores.ts`.
-
-## Client-agnostic by design
-
-The library ships **no Redis dependency**. You inject any client matching the
-small `RedisLikeClient` surface (`set` with `nx`/`pxMs`, optional `get`/`del`,
-optional `pipeline`). `ioredis`, `node-redis`, Upstash, or a cluster proxy all
-adapt in a few lines. An `InMemoryRedisLikeClient` reference implementation is
-provided for tests and local development.
-
-## Usage
-
-```ts
-import { DistributedReplayCache, createRedisReplayStore, receiveEnvelope } from '@7h3/protocol'
-import Redis from 'ioredis'
-
-const redis = new Redis(process.env.REDIS_URL)
-
-const replayCache = new DistributedReplayCache(
-  createRedisReplayStore(
-    // adapt ioredis' set(key, val, 'PX', ms, 'NX') to the RedisLikeClient shape:
-    {
-      set: async (key, value, opts = {}) => {
-        const args = []
-        if (opts.pxMs !== undefined) args.push('PX', opts.pxMs)
-        if (opts.nx) args.push('NX')
-        return (await redis.set(key, value, ...args)) === 'OK' ? 'OK' : null
-      },
-    },
-    {
-      keyPrefix: 'aip:replay:',
-      errorBehavior: 'fallback', // degrade to local store on a Redis outage
-      onDegraded: (err) => metrics.increment('aip.replay.degraded'),
-    },
-  ),
-)
-
-await receiveEnvelope(rawEnvelope, { replayCache, secretResolver: async () => sharedSecret })
-```
-
-## Shared store contract
-
-`DistributedReplayStore.reserve(key, expiresAtMs, nowMs)` must be atomic:
-
-- Return `true` when the key is newly reserved.
-- Return `false` when the key is already reserved and still valid.
-
-`key` format is `sender|messageId|nonce`. The optional `reserveMany(entries, nowMs)`
-performs a batched reserve (one round-trip via a client pipeline) and is used
-automatically by `DistributedReplayCache.consumeMany` when present.
-
-## Behavior on Redis outage (`errorBehavior`)
-
-| Value | On client error | Use when |
-|---|---|---|
-| `fallback` (default) | Degrade to a local in-memory store — traffic flows, single-node replay protection stays in force, and TTL still bounds replays | Default; balances safety and uptime |
-| `reject` | Fail closed — deny the message | Strictest security posture |
-| `allow` | Fail open — accept the message | Uptime outweighs the narrow replay risk |
-
-Every degraded decision fires `onDegraded` so the condition is observable — degradation is never silent.
-
-## High-availability topologies
-
-### Redis Sentinel
-
-ioredis connects to Sentinel transparently. The adapter wrapper is identical to standalone Redis:
-
-```ts
-import Redis from 'ioredis'
-
-const redis = new Redis({
-  sentinels: [
-    { host: 'sentinel-1', port: 26379 },
-    { host: 'sentinel-2', port: 26379 },
-    { host: 'sentinel-3', port: 26379 },
-  ],
-  name: 'mymaster',
-})
-
-const aipRedis = {
-  set: async (key: string, value: string, opts: { nx?: boolean; pxMs?: number } = {}) => {
-    const args: (string | number)[] = []
-    if (opts.pxMs !== undefined) args.push('PX', opts.pxMs)
-    if (opts.nx) args.push('NX')
-    return (await redis.set(key, value, ...(args as [string, number, string]))) === 'OK'
-      ? ('OK' as const)
-      : null
-  },
-}
-
-const replayCache = new DistributedReplayCache(
-  createRedisReplayStore(aipRedis, { errorBehavior: 'fallback' }),
-)
-```
-
-Sentinel handles leader election automatically. During failover (typically < 30 s), `errorBehavior` controls whether requests are rejected or degrade to local replay protection.
-
-### Redis Cluster
-
-AIP replay keys (`aip:replay:{sender}:{messageId}:{nonce}`) and revocation keys (`aip:revoked:{keyId}`) are independent — no cross-slot transactions required. Cluster mode works without modification. Adapt a Cluster client the same way as standalone.
-
-```ts
-const cluster = new Redis.Cluster([
-  { host: 'node-1', port: 7000 },
-  { host: 'node-2', port: 7001 },
-  { host: 'node-3', port: 7002 },
-])
-// adapter wrapper identical to standalone
-```
-
-### Upstash (serverless / edge)
-
-Upstash's `@upstash/redis` client's `set` method matches `RedisLikeClient` directly:
-
-```ts
-import { Redis } from '@upstash/redis'
-
-const redis = new Redis({ url: process.env.UPSTASH_URL!, token: process.env.UPSTASH_TOKEN! })
-
-const aipRedis = {
-  set: async (key: string, value: string, opts: { nx?: boolean; pxMs?: number } = {}) =>
-    redis.set(key, value, { nx: opts.nx, px: opts.pxMs }),
-}
-```
-
-## Operational guidance
-
-- Use a distributed replay cache for any horizontally scaled gateway.
-- Keep clocks synchronized (NTP / PTP) — AIP TTL checks require clocks within the configured skew window (default ±30 s) across all nodes and Sentinel/Cluster members.
-- Monitor replay reject rate and `onDegraded` rate as security / health signals.
-- During Redis failover, `errorBehavior: 'fallback'` keeps traffic flowing under single-node replay protection. `errorBehavior: 'reject'` is safer but means failover = downtime for inbound envelopes. Choose the posture that matches your threat model.
-- The replay store is the only component AIP requires Redis for. The revocation store (`createRedisRevocationStore`) uses the same `RedisLikeClient` interface and the same HA patterns apply.

package/docs/FUZZ_CAMPAIGN.md

@@ -1,121 +0,0 @@
-# Fuzz Campaign
-
-AIP employs two complementary fuzzing strategies: mutation-based harnesses for TypeScript and coverage-guided libFuzzer targets for Rust.
-
----
-
-## TypeScript — mutation-based harnesses
-
-**Location:** `fuzz/ts/`
-
-**Run:**
-```bash
-npm run fuzz:ts          # both harnesses, default rounds
-FUZZ_ROUNDS=200000 npm run fuzz:ts   # heavier run
-npm run fuzz:ts:decode   # decoder only
-npm run fuzz:ts:verify   # verifier only
-```
-
-### Harness: `harness-decode.ts`
-
-**Target:** `decodeEnvelope`  
-**Invariant:** Must never throw on any input — garbage returns `{ok: false}`, not a crash.
-
-**Strategy:**
-1. Seed corpus: conformance vectors (JSON full form + compact form) + known-bad inputs (`{}`, `[]`, `null`, `"string"`, `{`, etc.)
-2. Each round: pick a mutator, apply it to the current input
-3. Reset to a fresh corpus item every 500 rounds
-
-**Mutators:**
-- Bit flip at a random byte position
-- Random byte insertion
-- Random byte deletion
-- Truncation to a random prefix length
-- JSON field mutation (null, type change)
-- Token substitution (e.g. `"aip/0.1"` → `"aip/0.2"`)
-
-**Initial run result (2026-06-05):**
-```
-[harness-decode] rounds=50000 ok=98 ok:false=49902 crashes=0
-```
-No crashes. Decoder tolerates all 50,000 mutated inputs.
-
----
-
-### Harness: `harness-verify.ts`
-
-**Target:** `verifyEnvelopeHmac`  
-**Invariants:**
-1. Must never throw on a tampered envelope.
-2. Any tampered envelope must verify as `false` (no false positives).
-
-**Strategy:**
-1. Sign a fresh baseline envelope
-2. Each round: deep-clone and randomly mutate one field in `header` or `body`
-3. Guard: if mutation produced no net change, force `body.content` to a sentinel value
-4. Every 200 rounds: test with a fully broken envelope (`{}` headers/body)
-
-**Mutation operators:**
-- String fields: bit flip a random byte, UTF-8 round-tripped (invalid sequences → replacement char)
-- Numeric fields: add a non-zero delta (−500 to −1 or +1 to +500)
-- Optional fields: set to `null`
-
-**Initial run result (2026-06-05):**
-```
-[harness-verify] rounds=20000 tamper-false-positives=0 crashes=0
-```
-No crashes, no false positives. No tampered envelope verified as valid.
-
----
-
-## Rust — cargo-fuzz (libFuzzer)
-
-**Location:** `sdk/rust/fuzz/`
-
-**Prerequisites:**
-```bash
-rustup toolchain install nightly
-cargo install cargo-fuzz
-```
-
-**Run:**
-```bash
-npm run fuzz:rust:decode         # 60-second decode fuzzing session
-npm run fuzz:rust:canonicalize   # 60-second canonicalize fuzzing session
-
-# Or run directly:
-cargo +nightly fuzz run fuzz_decode --manifest-path sdk/rust/fuzz/Cargo.toml
-cargo +nightly fuzz run fuzz_canonicalize --manifest-path sdk/rust/fuzz/Cargo.toml
-```
-
-### Target: `fuzz_decode`
-
-**Target:** `aip7h3::decode_envelope`  
-**Invariant:** Must never panic on any UTF-8-valid input — errors are `Err(...)`, not panics.
-
-Input: arbitrary byte sequences converted to UTF-8 via `std::str::from_utf8`.
-
-### Target: `fuzz_canonicalize`
-
-**Target:** `aip7h3::canonicalize_envelope`  
-**Invariant:** Calling it twice on the same envelope returns the same string (idempotence / purity).
-
-Input: fuzz bytes carved into envelope fields (`messageId`, `content`) to exercise the canonicalization path under arbitrary field content.
-
----
-
-## Coverage gaps and known limitations
-
-| Gap | Notes |
-|---|---|
-| TypeScript fuzzing is mutation-based, not coverage-guided | Coverage-guided fuzzing (e.g. jazzer.js) requires Java; out of scope for CI. The mutation harnesses provide meaningful parser boundary coverage without the dependency. |
-| Binary decoder (`decodeEnvelope` with `Uint8Array`) | The existing property-based tests (fast-check) cover this path (`src/protocolFuzz.advanced.test.ts`). A dedicated fuzz harness is a future addition. |
-| Ed25519 verification paths | These depend on WebCrypto internals; crash surface is on the envelope parsing/canonicalization layer (covered). |
-| No crash corpus retained | Extend the harnesses with a `fuzz/corpus/` directory to persist and replay interesting inputs. |
-| Python | No standalone fuzz harness — Python correctness is covered by conformance vectors and the property-based TS tests. |
-
----
-
-## Pre-release fuzz policy
-
-Per `docs/RELEASE_GATE.md`, at minimum the TypeScript harnesses run at default round counts as part of every release gate check. Rust fuzzing is optional for patch releases and required for minor/major bumps.