@7h3/protocol 0.1.2 → 0.4.0

package/docs/AI_RUNTIME_POLICY.json

@@ -0,0 +1,126 @@
+{
+  "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/AI_RUNTIME_POLICY.yaml

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

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

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

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

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

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

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