@7h3/protocol 0.1.2 → 0.4.0

package/conformance/7h3_v0_1.json

@@ -0,0 +1,77 @@
+{
+  "version": "7h3/0.1",
+  "vectors": [
+    {
+      "id": "task-with-capability-and-recipient",
+      "secret": "vector-secret-1",
+      "keyId": "vector-key-1",
+      "envelope": {
+        "header": {
+          "version": "7h3/0.1",
+          "messageId": "vec-1",
+          "timestampMs": 1712500000000,
+          "ttlMs": 60000,
+          "sender": "agent.alpha",
+          "recipient": "agent.beta",
+          "nonce": "nonce-vec-1"
+        },
+        "body": {
+          "intent": "TASK",
+          "content": "route:alpha->beta",
+          "capability": "task.plan",
+          "correlationId": "corr-1"
+        }
+      },
+      "canonical": "{\"body\":{\"capability\":\"task.plan\",\"content\":\"route:alpha->beta\",\"correlationId\":\"corr-1\",\"intent\":\"TASK\"},\"header\":{\"messageId\":\"vec-1\",\"nonce\":\"nonce-vec-1\",\"recipient\":\"agent.beta\",\"sender\":\"agent.alpha\",\"timestampMs\":1712500000000,\"ttlMs\":60000,\"version\":\"7h3/0.1\"}}",
+      "signature": "bZP1N1f4w4RGSKw6pfdcA6dQjvpv9nIHAQCttjNCZyI"
+    },
+    {
+      "id": "result-with-minimal-fields",
+      "secret": "vector-secret-2",
+      "keyId": "vector-key-2",
+      "envelope": {
+        "header": {
+          "version": "7h3/0.1",
+          "messageId": "vec-2",
+          "timestampMs": 1712500005000,
+          "ttlMs": 30000,
+          "sender": "memory.agent",
+          "nonce": "nonce-vec-2"
+        },
+        "body": {
+          "intent": "RESULT",
+          "content": "memory:ok"
+        }
+      },
+      "canonical": "{\"body\":{\"content\":\"memory:ok\",\"intent\":\"RESULT\"},\"header\":{\"messageId\":\"vec-2\",\"nonce\":\"nonce-vec-2\",\"sender\":\"memory.agent\",\"timestampMs\":1712500005000,\"ttlMs\":30000,\"version\":\"7h3/0.1\"}}",
+      "signature": "_soWM4GZS8qWZDWyXEeXPaQp7Diyp2SQua9mKy2q0BQ"
+    }
+  ],
+  "ed25519Vectors": [
+    {
+      "id": "task-ed25519-with-recipient",
+      "keyId": "ed-vector-key-1",
+      "publicKey": "MCowBQYDK2VwAyEA-mUFiTQtcKN4nnD19V_-Wyy4q19OivnAutRUPhOcC78",
+      "privateKey": "MC4CAQAwBQYDK2VwBCIEICheZbQGuDVb6hezIlcs0QnCHGxz6IhiLkC9M0qr8OOZ",
+      "envelope": {
+        "header": {
+          "version": "7h3/0.1",
+          "messageId": "vec-ed-1",
+          "timestampMs": 1712500010000,
+          "ttlMs": 45000,
+          "sender": "agent.ed",
+          "recipient": "agent.verify",
+          "nonce": "nonce-ed-1"
+        },
+        "body": {
+          "intent": "TASK",
+          "content": "route:ed25519",
+          "capability": "task.sign",
+          "correlationId": "corr-ed-1"
+        }
+      },
+      "canonical": "{\"body\":{\"capability\":\"task.sign\",\"content\":\"route:ed25519\",\"correlationId\":\"corr-ed-1\",\"intent\":\"TASK\"},\"header\":{\"messageId\":\"vec-ed-1\",\"nonce\":\"nonce-ed-1\",\"recipient\":\"agent.verify\",\"sender\":\"agent.ed\",\"timestampMs\":1712500010000,\"ttlMs\":45000,\"version\":\"7h3/0.1\"}}",
+      "signature": "AAWu-6pp7NQZ-NtWKrgREWlMBx-kMZZzZ5dIiBqOdT-zdr-u4HtS6upE79yX7UUNPYUfyKs7lfssi0EeOvIxAA"
+    }
+  ]
+}

package/conformance/7h3_v0_1_binary.json

@@ -0,0 +1,20 @@
+{
+  "generatedAt": "2026-06-28T00:56:52.383Z",
+  "vectors": [
+    {
+      "id": "task-with-capability-and-recipient",
+      "alg": "HS256",
+      "binaryHex": "41495042010f0000018eb8f445000000ea60000000073768332f302e31000000057665632d310000000b6167656e742e616c7068610000000b6e6f6e63652d7665632d31000000045441534b00000011726f7574653a616c7068612d3e626574610000000a6167656e742e62657461000000097461736b2e706c616e00000006636f72722d31010000000c766563746f722d6b65792d310000002b625a50314e31663477345247534b773670666463413664516a767076396e494841514374746a4e435a7949"
+    },
+    {
+      "id": "result-with-minimal-fields",
+      "alg": "HS256",
+      "binaryHex": "4149504201080000018eb8f4588800007530000000073768332f302e31000000057665632d320000000c6d656d6f72792e6167656e740000000b6e6f6e63652d7665632d3200000006524553554c54000000096d656d6f72793a6f6b010000000c766563746f722d6b65792d320000002b5f736f574d34475a533871575a445779584565585061517037446979703253517561396d4b793271304251"
+    },
+    {
+      "id": "task-ed25519-with-recipient",
+      "alg": "ED25519",
+      "binaryHex": "41495042010f0000018eb8f46c100000afc8000000073768332f302e31000000087665632d65642d31000000086167656e742e65640000000a6e6f6e63652d65642d31000000045441534b0000000d726f7574653a656432353531390000000c6167656e742e766572696679000000097461736b2e7369676e00000009636f72722d65642d31020000000f65642d766563746f722d6b65792d3100000056414157752d367070374e515a2d4e74574b72675245576c4d42782d6b4d5a5a7a5a3564496942714f64542d7a64722d753448745336757045373979583755554e50595566794b73376c667373693045654f7649784141"
+    }
+  ]
+}

package/conformance/aip_v0_1_binary.json

@@ -0,0 +1,20 @@
+{
+  "generatedAt": "2026-05-04T04:49:29.647Z",
+  "vectors": [
+    {
+      "id": "task-with-capability-and-recipient",
+      "alg": "HS256",
+      "binaryHex": "41495042010f0000018eb8f445000000ea60000000076169702f302e31000000057665632d310000000b6167656e742e616c7068610000000b6e6f6e63652d7665632d31000000045441534b00000011726f7574653a616c7068612d3e626574610000000a6167656e742e62657461000000097461736b2e706c616e00000006636f72722d31010000000c766563746f722d6b65792d310000002b4f6c376c516b5259336c52534961303576686b43795a32336f705973525139416250774670326378324430"
+    },
+    {
+      "id": "result-with-minimal-fields",
+      "alg": "HS256",
+      "binaryHex": "4149504201080000018eb8f4588800007530000000076169702f302e31000000057665632d320000000c6d656d6f72792e6167656e740000000b6e6f6e63652d7665632d3200000006524553554c54000000096d656d6f72793a6f6b010000000c766563746f722d6b65792d320000002b5a57775a5045787732646341416c354278507a33313337386d4351352d674768395566587536705a4b646f"
+    },
+    {
+      "id": "task-ed25519-with-recipient",
+      "alg": "ED25519",
+      "binaryHex": "41495042010f0000018eb8f46c100000afc8000000076169702f302e31000000087665632d65642d31000000086167656e742e65640000000a6e6f6e63652d65642d31000000045441534b0000000d726f7574653a656432353531390000000c6167656e742e766572696679000000097461736b2e7369676e00000009636f72722d65642d31020000000f65642d766563746f722d6b65792d310000005677787941674e494b6f66344d563478487757697a73623366366b326a574168325a7a7132703967684153456b5f464a4157346774366239317a76327a363344506b73416f485a365135334a64656a486f6150316f4251"
+    }
+  ]
+}

package/docker-compose.yaml

@@ -0,0 +1,77 @@
+# 7h3 Protocol — Docker Compose development stack
+# Brings up:
+#   gateway — verifying AIP proxy (port 8080)
+#   api     — minimal example upstream (port 3000, internal only)
+#
+# Quick start:
+#   docker compose up --build
+
+services:
+
+  # ---------------------------------------------------------------------------
+  # gateway — 7h3 Protocol verifying HTTP proxy
+  # ---------------------------------------------------------------------------
+  gateway:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8080:8080"
+    command:
+      - "--port"
+      - "8080"
+      - "--upstream"
+      - "http://api:3000"
+      - "--require"
+      - "ed25519"
+    environment:
+      # Override these at runtime to enable response signing:
+      #   GATEWAY_PRIVATE_KEY=<base64url private key>
+      #   GATEWAY_SENDER=gateway@my-service.example.com
+      NODE_ENV: production
+    depends_on:
+      api:
+        condition: service_started
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 5s
+      start_period: 10s
+      retries: 3
+
+  # ---------------------------------------------------------------------------
+  # api — minimal example upstream service
+  #
+  # This is a self-contained inline Node.js server that demonstrates the
+  # headers the gateway injects after successful envelope verification:
+  #   x-7h3-sender   — verified sender identity from the AIP envelope
+  #   x-7h3-verified — always "true" when the gateway passed the request
+  #
+  # Replace this service with your actual application in production.
+  # ---------------------------------------------------------------------------
+  api:
+    image: node:22-alpine
+    command: >
+      node -e "
+        const http = require('http');
+        const server = http.createServer((req, res) => {
+          const sender = req.headers['x-7h3-sender'] || null;
+          const verified = req.headers['x-7h3-verified'] === 'true';
+          const body = JSON.stringify({
+            ok: true,
+            path: req.url,
+            sender,
+            verified,
+            method: req.method,
+          });
+          res.writeHead(200, { 'content-type': 'application/json' });
+          res.end(body);
+        });
+        server.listen(3000, () => {
+          process.stderr.write('example api listening on port 3000\n');
+        });
+      "
+    expose:
+      - "3000"
+    restart: unless-stopped

package/docs/ADOPTION_PLAN.md

@@ -0,0 +1,120 @@
+# AIP Adoption Plan (Secure + Extremely Fast)
+
+This plan turns `aip/0.1` into a production-ready protocol for agentic AI systems, memory services, and multi-agent networks.
+
+## North-Star Targets
+
+- Default secure mode: signed envelopes, replay protection, strict TTL validation.
+- Transport speed: make `ws` the low-latency default and batch modes first-class for high-throughput workloads.
+- Interop: at least 3 language SDKs passing shared conformance vectors.
+- Operational maturity: CI performance gates on p99 latency, drop rate, and sustainable throughput.
+
+## Protocol Productization (Weeks 1-2)
+
+- Freeze protocol semantics from executable sources in `src/protocol.ts`, `src/protocolTransport.ts`, and `src/protocolReplay.ts`.
+- Publish `AIP RFC v0.1` with normative language (`MUST`, `SHOULD`, `MAY`) covering:
+  - canonicalization rules (field order + optional fields)
+  - signature requirements and key identifiers
+  - replay cache keying and eviction expectations
+  - error/diagnostic semantics and transport-level failure mapping
+- Include wire profiles:
+  - `json` profile (interop first)
+  - `compact` profile (performance first)
+
+## Security Hardening Track (Weeks 2-6)
+
+- Keep HS256 as baseline; add algorithm registry and pluggable signer/verifier interface for Ed25519 profile.
+- Define key rotation contract:
+  - key IDs
+  - overlap windows
+  - rotation cadence and emergency revocation behavior
+- Add hard limits and abuse controls:
+  - max payload size
+  - max batch size
+  - per-sender rate limits
+  - replay cache saturation behavior (fail-open/closed policy by profile)
+- Produce a threat model doc with explicit mitigations for replay flooding, clock skew abuse, and queue amplification.
+
+## Performance Engineering Track (Weeks 2-8)
+
+- Keep microbench (`npm run bench:protocol`) for function-level regressions.
+- Keep closed-loop E2E (`npm run bench:e2e:quick|full`) for latency/throughput under bounded concurrency.
+- Keep open-loop saturation (`npm run bench:openloop:quick|full`) for contention behavior and drop dynamics.
+- Use adaptive CI gate (`npm run bench:openloop:adaptive:ci`) as merge guard.
+- Adopt hard SLO gates per CI scenario:
+  - p99 <= 250ms
+  - dropPct <= 2%
+  - minimum sustainable ops/s threshold by mode/payload/concurrency tuple
+
+## SDK and Ecosystem Expansion (Weeks 3-10)
+
+- Build official SDKs:
+  - TypeScript (reference)
+  - Python (agent framework ecosystem)
+  - Go or Rust (infra/perf services)
+- Publish cross-language conformance vectors:
+  - canonical payload fixtures
+  - signature fixtures
+  - replay and TTL edge-case fixtures
+- Ship adapter packages:
+  - WebSocket session adapter
+  - HTTP batch adapter
+  - memory gateway adapter (AIP intents for memory read/write/search)
+
+## AI Memory System Integration (Weeks 4-10)
+
+- Add intent extensions for memory operations:
+  - `MEM_GET`, `MEM_PUT`, `MEM_APPEND`, `MEM_SEARCH`, `MEM_COMPACT`
+- Add capability namespace conventions:
+  - `mem.read`, `mem.write`, `mem.search`, `mem.admin`
+- Standardize idempotency and causality metadata:
+  - correlation IDs
+  - idempotency keys
+  - causal parent references for chain-of-thought-safe state updates
+
+## Agent Runtime Integration (Weeks 5-12)
+
+- Add a reference agent mesh demo:
+  - planner agent
+  - tool-executor agent
+  - memory agent
+  - policy/guardrail agent
+- Ensure all inter-agent traffic is AIP signed and replay-protected.
+- Instrument end-to-end agent loop latency:
+  - input -> planning -> tool call -> memory update -> response
+- Provide runbooks for degraded modes (queue pressure, key mismatch, stale clock).
+
+## CI, Governance, and Releases
+
+- CI stages:
+  - correctness: `npm run lint && npm run test && npm run build`
+  - perf gate: `npm run bench:openloop:adaptive:ci`
+  - regression diff: `npm run bench:diff -- --baseline <baseline> --candidate <candidate>`
+- Release cadence:
+  - protocol patch versions for non-breaking behavior
+  - minor versions for additive intents/capabilities
+  - major versions for breaking canonicalization/wire/security semantics
+- Governance:
+  - RFC process for protocol changes
+  - mandatory conformance vector updates for all normative changes
+
+## 30/60/90 Day Execution
+
+- Day 0-30:
+  - publish RFC v0.1
+  - lock CI adaptive gate
+  - ship SDK hardening notes and conformance vectors
+- Day 31-60:
+  - Python SDK beta
+  - memory intent extension draft
+  - key rotation + revocation reference implementation
+- Day 61-90:
+  - production profile v1 (`ws` + compact + adaptive perf SLOs)
+  - at least one multi-agent + memory reference deployment
+  - external adopter kit (quickstart + compatibility checklist)
+
+## Success Criteria
+
+- Security: no unsigned traffic in secure profiles; replay checks enforced in all reference transports.
+- Performance: CI gate remains green with stable p99 and sustainable throughput across selected scenarios.
+- Adoption: 3+ SDKs passing conformance tests and at least one external integration using AIP as primary inter-agent protocol.

package/docs/AGENTS.md

@@ -0,0 +1,77 @@
+# AGENTS
+
+## Commands (source of truth: package.json)
+- Install deps: `npm install`
+- Dev server: `npm run dev`
+- Lint: `npm run lint`
+- Full tests: `npm run test`
+- AI agent protocol quickstart demo: `npm run aip:quickstart`
+- Framework bridge quickstart demo: `npm run aip:framework:quickstart`
+- JSON-RPC gateway over AIP internals: `npm run aip:mcp:gateway`
+- Protocol microbench: `npm run bench:protocol`
+- E2E protocol quick benchmark: `npm run bench:e2e:quick`
+- E2E protocol full benchmark: `npm run bench:e2e:full`
+- Open-loop contention quick benchmark: `npm run bench:openloop:quick`
+- Open-loop contention full benchmark: `npm run bench:openloop:full`
+- Adaptive saturation benchmark gate: `npm run bench:openloop:adaptive:quick`
+- CI-friendly adaptive benchmark gate: `npm run bench:openloop:adaptive:ci`
+- Signature profile quick benchmark (`HS256` vs `ED25519`): `npm run bench:signatures:quick`
+- Signature profile full benchmark (`HS256` vs `ED25519`): `npm run bench:signatures:full`
+- Wire codec quick benchmark (`compact-json` vs `binary`): `npm run bench:wire:quick`
+- Wire codec full benchmark (`compact-json` vs `binary`): `npm run bench:wire:full`
+- Build release dashboard summary from latest bench runs: `npm run release:dashboard`
+- Compare two benchmark json runs: `npm run bench:diff -- --baseline <path> --candidate <path>`
+- CI uploads benchmark artifacts from `dist/bench/`, `dist/release-dashboard/`, `dist/npm-aip/`, and `bench-results/` for trend tracking and release evidence.
+- Python conformance suite: `npm run conformance:python`
+- Rust conformance suite: `npm run conformance:rust`
+- Single test file: `npm run test -- src/language.test.ts`
+- Single test name: `npm run test -- -t "signs and verifies with HMAC"`
+- Build + typecheck: `npm run build` (runs `tsc -b && vite build`)
+- Build library exports only: `npm run build:aip`
+- Prepare publishable package output (`@7h3/protocol`): `npm run package:aip`
+
+## Verification order
+- Use `npm run lint && npm run test && npm run build` before finishing.
+- `build` writes `dist/`; treat it as generated output, not hand-edited source.
+
+## Real entrypoints and module boundaries
+- `src/main.tsx` mounts the app; `src/App.tsx` is the single UI workbench.
+- `src/language.ts` is the core implementation (tokenize/compile/run/assemble/disassemble + stdlib preload + demos).
+- Protocol stack is split by responsibility:
+  - `src/protocol.ts`: envelope model, canonicalization, validation, HMAC sign/verify
+  - `src/protocolTransport.ts`: decode/encode (JSON + compact wire), inbound verification, replay checks, batch/session helpers
+  - `src/protocolAgent.ts`: session abstraction and auto-response loop
+  - `src/agentAdapter.ts`: drop-in raw-message adapter for AI framework integration
+  - `src/frameworkAdapters.ts`: framework bridge helpers (LangChain/LlamaIndex message mapping + JSON-RPC MCP-style bridge)
+  - `src/mcpGateway.ts`: line-based JSON-RPC gateway runtime over signed AIP internals
+  - `src/index.ts`: public protocol/adapter export surface for external integrations
+  - `src/protocolDemo.ts`: deterministic demo transcript used by UI/tests
+- Benchmark harnesses:
+  - `scripts/bench-protocol-e2e.ts` (closed-loop inproc/http/ws + agent-loop latency/throughput matrix, stage-level timing for build/canonicalize/mac/queue/transport/verify/decode)
+  - `scripts/bench-protocol-openloop.ts` (open-loop contention with http/ws + batch modes; supports adaptive search for max sustainable ops/s at p99/drop thresholds and `--ci` scenario preset)
+  - `scripts/bench-diff.ts` (baseline vs candidate regression check for ops/s and p99)
+- Shared cross-language vectors live in `conformance/aip_v0_1.json`; TypeScript and Python conformance tests should stay aligned to this fixture.
+- Shared cross-language vectors live in `conformance/aip_v0_1.json`; TypeScript, Python, and Rust conformance tests should stay aligned to this fixture.
+- Tests live in `src/*.test.ts` plus CLI process tests in `scripts/*.test.ts` (no custom Vitest config/setup file).
+
+## Non-obvious behavior to preserve
+- GLUV source accepts only four Unicode symbols (`╬ ┼ ╫ ╪`) plus whitespace.
+- `CALL` is encoded with two immediates: target index and arity (`arg2`).
+- If any `func` declarations exist, assembler enters function mode:
+  - requires `main` with arity `0`
+  - injects bootstrap instructions `CALL main` then `HALT`
+  - shifts jump/call targets by `+2`
+- `use <library>` directives are expanded before parsing; available libs are hardcoded in `STANDARD_LIBRARIES` inside `src/language.ts`.
+- Protocol verification defaults to signed envelopes (`requireSignature: true`) and needs a `secretResolver` for inbound signature checks.
+- For non-HS256 signatures (for example `ED25519`), use `signatureResolver` in transport/session options to provide algorithm-specific verification material.
+- Use `DistributedReplayCache` from `src/protocolReplay.ts` for multi-node replay defense (shared store reserve semantics).
+- Configure `maxClockSkewMs` in receive/session options when deployments need stricter/flexible time-skew tolerance.
+- Use `telemetry` (`receiveEnvelope`) and `onAuditEvent` (`createAipMcpGatewayRuntime`) to emit rejection and policy traces.
+- Stable JS consumer import path is `@7h3/protocol` (from `package.json` `exports`).
+- HMAC helpers depend on Web Crypto (`crypto.subtle`); runtimes without it will throw.
+- Protocol canonicalization is explicit and order-sensitive (`body` then `header`, each field in fixed key order); changing field order will break signature compatibility.
+- HMAC key import is cached (bounded map) in `src/protocol.ts`; preserve cache behavior for high-throughput signing/verification.
+- Compact wire format uses short keys in transport (`v, mid, ts, ttl, s, r, n, i, c, cap, cid, sig`) and must map losslessly to canonical envelope fields before verification; compact signatures can include `sig.a` for algorithm (`HS256` default if omitted).
+
+## Instruction files present
+- No repo-local agent instruction files were found besides this `AGENTS.md`.

package/docs/AIP_RFC_v0.1.md

@@ -0,0 +1,97 @@
+# AIP RFC v0.1 (Draft)
+
+This document defines the normative behavior for the GLUV AI communication protocol (`aip/0.1`).
+
+## 1. Scope
+
+- AIP defines signed, replay-resistant envelopes for agent-to-agent communication.
+- This RFC covers envelope structure, canonicalization, signing, validation, and transport expectations.
+
+## 2. Envelope Model
+
+An envelope has:
+
+- `header`
+  - `version` (MUST be `"aip/0.1"`)
+  - `messageId` (MUST be non-empty)
+  - `timestampMs` (Unix epoch milliseconds)
+  - `ttlMs` (MUST be > 0)
+  - `sender` (MUST be non-empty)
+  - `recipient` (OPTIONAL)
+  - `nonce` (MUST be non-empty)
+- `body`
+  - `intent` (MUST be one of `PING`, `PONG`, `CAPS`, `TASK`, `RESULT`, `ERROR`)
+  - `content` (MAY be empty but SHOULD be meaningful)
+  - `capability` (OPTIONAL)
+  - `correlationId` (OPTIONAL)
+- `signature` (OPTIONAL at format level, REQUIRED in secure profile)
+  - `alg` (`HS256` in v0.1)
+  - `keyId`
+  - `value` (base64url)
+
+## 3. Canonicalization (Normative)
+
+The canonical payload used for signing and verification MUST be a deterministic JSON string with fixed key ordering.
+
+- Top-level order MUST be: `body`, then `header`.
+- `body` key order MUST be:
+  - `capability` (if present)
+  - `content`
+  - `correlationId` (if present)
+  - `intent`
+- `header` key order MUST be:
+  - `messageId`
+  - `nonce`
+  - `recipient` (if present)
+  - `sender`
+  - `timestampMs`
+  - `ttlMs`
+  - `version`
+
+Receivers MUST verify signatures against this exact canonicalization behavior.
+
+## 4. Signature and Integrity
+
+- Secure profile senders MUST sign envelopes.
+- Secure profile receivers MUST reject missing signatures.
+- `HS256` signatures MUST be computed over canonical payload bytes (UTF-8).
+- `keyId` SHOULD identify the active secret material.
+
+## 5. Freshness and Replay
+
+- Receivers MUST enforce freshness: reject when `timestampMs + ttlMs < nowMs`.
+- Replay cache key MUST be `(sender, messageId, nonce)`.
+- Re-seeing an unexpired replay key MUST be rejected.
+
+## 6. Transport Expectations
+
+- JSON and compact wire forms are allowed; both MUST map losslessly to the same envelope model before validation.
+- Compact wire fields:
+  - `v, mid, ts, ttl, s, r, n, i, c, cap, cid, sig`
+- Validation and signature verification MUST occur after decoding to canonical envelope fields.
+
+## 7. Error Semantics
+
+Receivers SHOULD produce explicit diagnostics for:
+
+- invalid JSON / unrecognized shape
+- unsupported version
+- missing required fields
+- TTL expiry
+- missing or invalid signature
+- replay detection
+
+## 8. Security Profile Recommendations
+
+- Production deployments SHOULD require signatures (`requireSignature: true`).
+- Secrets SHOULD rotate; overlapping accept windows SHOULD be supported by `secretResolver`.
+- Deployments SHOULD apply payload size limits and rate limits per sender.
+
+## 9. Conformance
+
+Implementations are conformant to v0.1 if they:
+
+- produce/accept normative envelope model
+- match canonicalization behavior exactly
+- pass signature verification and replay/freshness requirements
+- interoperate across wire forms without semantic loss

package/docs/AI_DECISION_CARD.md

@@ -0,0 +1,122 @@
+# GLUV AI Decision Card (Runtime)
+
+Use this as a fast, deterministic runtime checklist for agent systems using GLUV.
+
+---
+
+## 1) Pick transport mode
+
+### If throughput is high or concurrency >= 100
+- Use: `http-binary-batch` or `ws-binary-batch`
+- Avoid: plain `http`
+
+### If moderate throughput with low complexity
+- Use: `ws-batch`
+
+### If low traffic / compatibility-first
+- Use: `http`
+
+---
+
+## 2) Pick batch size
+
+- Low traffic: `4–8`
+- Medium traffic: `8–32`
+- High traffic: `32–64`
+
+Rule: if p99 rises sharply, reduce batch size first.
+
+---
+
+## 3) Pick in-flight cap
+
+- Low traffic: `16–64`
+- Medium traffic: `64–256`
+- High traffic: `256–1024`
+
+Rule: if queueing grows and drop rises, lower cap and rely on backpressure.
+
+---
+
+## 4) Retry/backoff policy
+
+- Retry only on retriable overload/transient failures (e.g., 503)
+- Use jittered backoff:
+  - low: `1–2ms`
+  - medium: `2–8ms`
+  - high: `4–16ms`
+- Keep retries bounded (e.g., max 3 attempts)
+
+Never retry indefinitely.
+
+---
+
+## 5) Safety invariants (never disable)
+
+- Signature verification
+- Canonicalization
+- Replay defense
+- TTL / clock-skew checks
+
+If any are disabled, system is out of compliant mode.
+
+---
+
+## 6) Benchmark discipline
+
+Use **adaptive** for production readiness:
+
+```bash
+npm run bench:openloop:quick
+npm run bench:openloop:full
+```
+
+Use **stress** only for capacity ceiling exploration:
+
+```bash
+npm run bench:openloop:stress:quick
+npm run bench:openloop:stress:full
+```
+
+Do not use stress numbers as SLO pass/fail.
+
+---
+
+## 7) Fast decision tree
+
+1. Concurrency >= 100?
+   - Yes → choose `*-binary-batch`
+   - No → go to 2
+2. Need lowest latency and moderate throughput?
+   - Yes → `ws-batch`
+   - No → `http`
+3. Drop > threshold?
+   - Lower in-flight cap
+   - Reduce batch size
+   - Increase backoff
+   - Switch to binary batch mode
+
+---
+
+## 8) SLO gate template
+
+- `dropPct <= 0.1%` (or stricter by lane)
+- `p99 <= target_ms`
+- signatures/replay checks: 100% enforced
+- sustained for target duration under declared load profile
+
+If not met: do not promote release.
+
+---
+
+## 9) Operator handoff note
+
+When filing an incident/perf ticket include:
+
+- mode (`http`, `ws-batch`, `http-binary-batch`, etc.)
+- payload size(s)
+- concurrency
+- adaptive or stress run
+- p50/p95/p99
+- dropPct
+- retry counts and overload signals