@7h3/protocol 0.5.0 → 0.5.1

package/docs/AI_RUNTIME_POLICY.yaml

@@ -1,110 +0,0 @@
-version: "1.0"
-name: "gluv-runtime-policy"
-status: "active"
-owner: "platform-ai-ops"
-updated_at: "2026-05-10"
-
-purpose:
-  summary: "Deterministic runtime policy for selecting GLUV transport, batching, retries, and safety controls."
-  intent: "Maximize sustainable throughput while preserving protocol integrity and low drop rates."
-
-hard_invariants:
-  require_signature_verification: true
-  require_canonicalization: true
-  require_replay_defense: true
-  require_ttl_clock_skew_enforcement: true
-  disallow_invariant_bypass: true
-
-slo_defaults:
-  drop_pct_max: 0.1
-  p99_ms_max: 20
-  enforce_over_window: "5m"
-  fail_release_on_breach: true
-
-mode_selection:
-  rules:
-    - when:
-        concurrency_gte: 100
-      use: "http-binary-batch"
-      fallback: "ws-binary-batch"
-      rationale: "High-concurrency lanes require binary+batch to avoid plain-http collapse."
-    - when:
-        latency_sensitive: true
-        concurrency_lt: 100
-      use: "ws-batch"
-      rationale: "Balanced p99 and throughput."
-    - when:
-        compatibility_first: true
-        concurrency_lt: 100
-      use: "http"
-      rationale: "Lowest integration friction for low/medium load."
-
-guardrails:
-  block_plain_http_high_concurrency: true
-  plain_http_block_threshold_concurrency: 100
-  allow_override_flag: "--allow-unsafe-http"
-  override_allowed_only_for: "stress-benchmarks"
-
-tuning:
-  batch_size:
-    low_traffic: [4, 8]
-    medium_traffic: [8, 32]
-    high_traffic: [32, 64]
-  inflight_cap:
-    low_traffic: [16, 64]
-    medium_traffic: [64, 256]
-    high_traffic: [256, 1024]
-  retry_backoff_ms:
-    low_traffic: [1, 2]
-    medium_traffic: [2, 8]
-    high_traffic: [4, 16]
-  max_retry_attempts: 3
-  retriable_status_codes: [503]
-
-adaptive_flow:
-  enabled: true
-  ewma_latency_alpha: 0.15
-  degrade_if_latency_ms_gt: 25
-  recover_if_latency_ms_lt: 8
-  reduce_inflight_factor_on_error: 0.85
-  reduce_batch_factor_on_error: 0.8
-
-benchmark_policy:
-  production_readiness:
-    require_adaptive_mode: true
-    commands:
-      - "npm run bench:openloop:quick"
-      - "npm run bench:openloop:full"
-  stress_characterization:
-    allowed: true
-    commands:
-      - "npm run bench:openloop:stress:quick"
-      - "npm run bench:openloop:stress:full"
-    note: "Stress outputs must not be used as direct SLO acceptance."
-
-runtime_decision_tree:
-  - if: "concurrency >= 100"
-    then: "use http-binary-batch"
-  - if: "drop_pct > drop_pct_max"
-    then:
-      - "reduce inflight cap"
-      - "reduce batch size"
-      - "increase retry backoff"
-      - "switch to binary-batch mode"
-  - if: "p99_ms > p99_ms_max"
-    then:
-      - "reduce batch size"
-      - "reduce inflight cap"
-      - "re-run adaptive benchmark"
-
-operator_handoff_required_fields:
-  - mode
-  - payload_bytes
-  - concurrency
-  - benchmark_type
-  - p50_ms
-  - p95_ms
-  - p99_ms
-  - drop_pct
-  - retry_count
-  - overload_signals

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.