@7h3/protocol 0.5.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -1317
- package/agentAdapter.d.ts +26 -0
- package/auditLog.d.ts +54 -0
- package/capability.d.ts +67 -0
- package/cborCodec.d.ts +34 -0
- package/conformanceVectors.d.ts +20 -0
- package/encryption.d.ts +85 -0
- package/envelopeCbor.d.ts +33 -0
- package/frameworkAdapters.d.ts +72 -0
- package/gateway.d.ts +53 -0
- package/grpcBinding.d.ts +29 -0
- package/httpBinding.d.ts +50 -0
- package/index.d.ts +39 -0
- package/index.js +3662 -0
- package/keyInfra.d.ts +64 -0
- package/keyRegistry.d.ts +9 -0
- package/keyRotation.d.ts +20 -0
- package/mcpGateway.d.ts +37 -0
- package/mcpTransports.d.ts +62 -0
- package/mcpWrapper.d.ts +83 -0
- package/otel.d.ts +65 -0
- package/package.json +13 -121
- package/policyEnforcer.d.ts +50 -0
- package/policyTelemetryFeedback.d.ts +11 -0
- package/{src/protocol.d.ts → protocol.d.ts} +1 -2
- package/protocolAgent.d.ts +58 -0
- package/protocolBinary.d.ts +8 -0
- package/protocolCapabilities.d.ts +24 -0
- package/protocolReplay.d.ts +35 -0
- package/protocolTransport.d.ts +73 -0
- package/queueBinding.d.ts +43 -0
- package/rateLimiter.d.ts +18 -0
- package/{src/redisClient.ts → redisClient.d.ts} +25 -75
- package/replayStores.d.ts +98 -0
- package/revocation.d.ts +71 -0
- package/routePolicy.d.ts +30 -0
- package/runtimePolicy.d.ts +24 -0
- package/runtimePolicyManager.d.ts +15 -0
- package/runtimePolicyPresets.d.ts +11 -0
- package/signedResponse.d.ts +21 -0
- package/stream.d.ts +59 -0
- package/telemetry.d.ts +79 -0
- package/webhookBinding.d.ts +30 -0
- package/wsBinding.d.ts +52 -0
- package/.dockerignore +0 -19
- package/.github/dependabot.yml +0 -32
- package/.github/workflows/ci.yml +0 -31
- package/.github/workflows/publish.yml +0 -59
- package/.github/workflows/scorecard.yml +0 -37
- package/7h3.example.yaml +0 -125
- package/CHANGELOG.md +0 -152
- package/CONTRIBUTING.md +0 -82
- package/Dockerfile +0 -73
- package/GOVERNANCE.md +0 -62
- package/SECURITY.md +0 -70
- package/bench-results/replay-cache-full-1777891033256.json +0 -10
- package/bench-results/replay-cache-full-1777896317488.json +0 -10
- package/bench-results/replay-cache-full-1777900993184.json +0 -10
- package/bench-results/replay-cache-full-1777901019285.json +0 -10
- package/bench-results/replay-cache-quick-1777870170126.json +0 -10
- package/bench-results/signature-profiles-quick-1775875160079.json +0 -85
- package/bench-results/signature-profiles-quick-1775983539716.json +0 -85
- package/bench-results/signature-profiles-quick-1776237913190.json +0 -85
- package/bench-results/wire-codecs-full-1777891019803.json +0 -93
- package/bench-results/wire-codecs-full-1777896260964.json +0 -93
- package/bench-results/wire-codecs-full-1777901004247.json +0 -93
- package/bench-results/wire-codecs-quick-1775972879056.json +0 -93
- package/bench-results/wire-codecs-quick-1775983541111.json +0 -93
- package/bench-results/wire-codecs-quick-1776237914299.json +0 -93
- package/bench-results/wire-codecs-quick-1777841285236.json +0 -93
- package/bench-results/wire-codecs-quick-1777841321772.json +0 -93
- package/bench-results/wire-codecs-quick-1777841330408.json +0 -93
- package/bench-results/wire-codecs-quick-1777852886082.json +0 -93
- package/bench-results/wire-codecs-quick-1777852988773.json +0 -93
- package/bench-results/wire-codecs-quick-1777870188095.json +0 -93
- package/bench-results/wire-codecs-quick-1777870263918.json +0 -93
- package/bench-results/wire-codecs-quick-1777870455034.json +0 -93
- package/bench-results/wire-codecs-quick-1778816163081.json +0 -93
- package/bench-results/wire-codecs-quick-1778843936130.json +0 -93
- package/bin/7h3.ts +0 -406
- package/conformance/7h3_v0_1.json +0 -77
- package/conformance/7h3_v0_1_binary.json +0 -20
- package/conformance/aip_v0_1_binary.json +0 -20
- package/docker-compose.yaml +0 -77
- package/docs/ADOPTION_PLAN.md +0 -120
- package/docs/AGENTS.md +0 -77
- package/docs/AIP_RFC_v0.1.md +0 -97
- package/docs/AI_DECISION_CARD.md +0 -122
- package/docs/AI_RUNTIME_POLICY.json +0 -126
- package/docs/AI_RUNTIME_POLICY.yaml +0 -110
- package/docs/BACKPRESSURE_TUNING.md +0 -65
- package/docs/BENCHMARK_CLAIM_MATRIX.md +0 -42
- package/docs/BENCHMARK_REPORT_TEMPLATE.md +0 -169
- package/docs/BINARY_CODEC_BENCH.md +0 -23
- package/docs/CLEAN_CLONE_RUNBOOK.md +0 -36
- package/docs/CLOCK_SKEW_POLICY.md +0 -30
- package/docs/DISTRIBUTED_REPLAY.md +0 -142
- package/docs/FUZZ_CAMPAIGN.md +0 -121
- package/docs/GATEWAY.md +0 -195
- package/docs/KEY_MANAGEMENT_POLICY.md +0 -53
- package/docs/KEY_REVOCATION.md +0 -69
- package/docs/MCP_WRAPPER.md +0 -159
- package/docs/MIGRATION_GUIDE.md +0 -40
- package/docs/OPERATORS.md +0 -184
- package/docs/PERF_REGRESSION_POLICY.md +0 -34
- package/docs/PROJECT_EXAMINATION_2026-05-31.md +0 -219
- package/docs/RELEASE_BENCHMARK_REPORT_2026-05-15.md +0 -135
- package/docs/RELEASE_GATE.md +0 -25
- package/docs/RELEASE_NOTES_v0.1.0.md +0 -54
- package/docs/SECURITY_REVIEW_2026-06-05.md +0 -165
- package/docs/TELEMETRY.md +0 -41
- package/docs/THREAT_MODEL.md +0 -89
- package/docs/VERSIONING_POLICY.md +0 -30
- package/docs/assets/banner-github.png +0 -0
- package/docs/assets/banner.png +0 -0
- package/docs/assets/banner.svg +0 -123
- package/eslint.config.js +0 -15
- package/fuzz/ts/harness-decode.ts +0 -136
- package/fuzz/ts/harness-verify.ts +0 -121
- package/fuzz/ts/run.ts +0 -35
- package/mcp-server/README.md +0 -38
- package/mcp-server/package-lock.json +0 -1187
- package/mcp-server/package.json +0 -35
- package/mcp-server/src/index.ts +0 -236
- package/mcp-server/tsconfig.json +0 -14
- package/scripts/aip-framework-quickstart.ts +0 -110
- package/scripts/aip-mcp-gateway.ts +0 -38
- package/scripts/aip-mcp-wrap-demo.ts +0 -72
- package/scripts/aip-quickstart.ts +0 -60
- package/scripts/bench-diff.ts +0 -118
- package/scripts/bench-protocol-e2e.ts +0 -937
- package/scripts/bench-protocol-openloop.ts +0 -1397
- package/scripts/bench-replay-cache.ts +0 -76
- package/scripts/bench-signature-profiles.ts +0 -180
- package/scripts/bench-wire-codecs.ts +0 -161
- package/scripts/build-binary-conformance.ts +0 -36
- package/scripts/build-release-dashboard.ts +0 -175
- package/scripts/canary-rollout.ts +0 -38
- package/scripts/mcpGatewayCli.test.ts +0 -116
- package/scripts/prepare-aip-package.ts +0 -88
- package/scripts/regen-conformance-sigs.ts +0 -18
- package/scripts/release-gate.ts +0 -19
- package/scripts/validate-runtime-policy.ts +0 -18
- package/sdk/browser/index.test.ts +0 -162
- package/sdk/browser/index.ts +0 -257
- package/sdk/browser/package.json +0 -13
- package/sdk/go/cbor.go +0 -551
- package/sdk/go/cbor_test.go +0 -232
- package/sdk/go/encryption.go +0 -280
- package/sdk/go/encryption_test.go +0 -318
- package/sdk/go/go.mod +0 -7
- package/sdk/go/go.sum +0 -4
- package/sdk/go/http.go +0 -135
- package/sdk/go/protocol.go +0 -324
- package/sdk/go/protocol_test.go +0 -334
- package/sdk/go/replay.go +0 -121
- package/sdk/go/replay_test.go +0 -149
- package/sdk/go/webhook.go +0 -136
- package/sdk/pq/package-lock.json +0 -1358
- package/sdk/pq/package.json +0 -42
- package/sdk/pq/src/index.test.ts +0 -143
- package/sdk/pq/src/index.ts +0 -166
- package/sdk/pq/tsconfig.json +0 -14
- package/sdk/pq/vitest.config.ts +0 -7
- package/sdk/python/README.md +0 -18
- package/sdk/python/protocol_7h3/__init__.py +0 -46
- package/sdk/python/protocol_7h3/encryption.py +0 -252
- package/sdk/python/protocol_7h3/http.py +0 -212
- package/sdk/python/protocol_7h3/keys.py +0 -149
- package/sdk/python/protocol_7h3/pq.py +0 -244
- package/sdk/python/protocol_7h3/protocol.py +0 -525
- package/sdk/python/protocol_7h3/queue.py +0 -118
- package/sdk/python/protocol_7h3/replay.py +0 -98
- package/sdk/python/protocol_7h3/webhook.py +0 -116
- package/sdk/python/pyproject.toml +0 -40
- package/sdk/python/tests/test_conformance.py +0 -110
- package/sdk/python/tests/test_encryption.py +0 -206
- package/sdk/python/tests/test_http.py +0 -305
- package/sdk/python/tests/test_keys.py +0 -417
- package/sdk/python/tests/test_queue.py +0 -120
- package/sdk/python/tests/test_webhook.py +0 -345
- package/sdk/rust/Cargo.lock +0 -371
- package/sdk/rust/Cargo.toml +0 -25
- package/sdk/rust/README.md +0 -31
- package/sdk/rust/fuzz/Cargo.toml +0 -29
- package/sdk/rust/fuzz/fuzz_targets/fuzz_canonicalize.rs +0 -46
- package/sdk/rust/fuzz/fuzz_targets/fuzz_decode.rs +0 -11
- package/sdk/rust/src/bin/aip_mcp_gateway.rs +0 -59
- package/sdk/rust/src/http.rs +0 -145
- package/sdk/rust/src/keys.rs +0 -161
- package/sdk/rust/src/lib.rs +0 -688
- package/sdk/rust/src/queue.rs +0 -79
- package/sdk/rust/src/webhook.rs +0 -86
- package/sdk/rust/tests/conformance.rs +0 -148
- package/sdk/rust/tests/gateway.rs +0 -130
- package/sdk/rust/tests/http_webhook_queue.rs +0 -201
- package/sdk/rust/tests/keys.rs +0 -189
- package/sdk/threshold/index.d.ts +0 -68
- package/sdk/threshold/index.d.ts.map +0 -1
- package/sdk/threshold/index.js +0 -254
- package/sdk/threshold/package-lock.json +0 -1361
- package/sdk/threshold/package.json +0 -39
- package/sdk/threshold/src/index.d.ts +0 -68
- package/sdk/threshold/src/index.d.ts.map +0 -1
- package/sdk/threshold/src/index.js +0 -254
- package/sdk/threshold/src/index.test.ts +0 -238
- package/sdk/threshold/src/index.ts +0 -355
- package/sdk/threshold/tsconfig.json +0 -19
- package/sdk/threshold/vitest.config.ts +0 -12
- package/src/agentAdapter.test.ts +0 -48
- package/src/agentAdapter.ts +0 -56
- package/src/auditLog.test.ts +0 -145
- package/src/auditLog.ts +0 -147
- package/src/capability.test.ts +0 -504
- package/src/capability.ts +0 -380
- package/src/cborCodec.test.ts +0 -263
- package/src/cborCodec.ts +0 -339
- package/src/conformance.test.ts +0 -136
- package/src/conformanceVectors.ts +0 -99
- package/src/encryption.test.ts +0 -206
- package/src/encryption.ts +0 -245
- package/src/envelopeCbor.ts +0 -140
- package/src/frameworkAdapters.test.ts +0 -290
- package/src/frameworkAdapters.ts +0 -261
- package/src/gateway.test.ts +0 -343
- package/src/gateway.ts +0 -246
- package/src/grpcBinding.test.ts +0 -211
- package/src/grpcBinding.ts +0 -103
- package/src/httpBinding.test.ts +0 -376
- package/src/httpBinding.ts +0 -189
- package/src/index.ts +0 -39
- package/src/keyInfra.test.ts +0 -278
- package/src/keyInfra.ts +0 -228
- package/src/keyRegistry.ts +0 -59
- package/src/keyRotation.test.ts +0 -78
- package/src/keyRotation.ts +0 -72
- package/src/mcpGateway.test.ts +0 -129
- package/src/mcpGateway.ts +0 -250
- package/src/mcpTransports.test.ts +0 -92
- package/src/mcpTransports.ts +0 -169
- package/src/mcpWrapper.test.ts +0 -179
- package/src/mcpWrapper.ts +0 -206
- package/src/otel.ts +0 -136
- package/src/policyEnforcer.test.ts +0 -99
- package/src/policyEnforcer.ts +0 -169
- package/src/policyTelemetryFeedback.test.ts +0 -25
- package/src/policyTelemetryFeedback.ts +0 -38
- package/src/protocol.bench.ts +0 -37
- package/src/protocol.d.ts.map +0 -1
- package/src/protocol.js +0 -294
- package/src/protocol.test.ts +0 -155
- package/src/protocol.ts +0 -414
- package/src/protocolAgent.test.ts +0 -105
- package/src/protocolAgent.ts +0 -169
- package/src/protocolBinary.test.ts +0 -165
- package/src/protocolBinary.ts +0 -312
- package/src/protocolCapabilities.ts +0 -70
- package/src/protocolFuzz.advanced.test.ts +0 -235
- package/src/protocolFuzz.test.ts +0 -111
- package/src/protocolNegative.test.ts +0 -97
- package/src/protocolReplay.test.ts +0 -71
- package/src/protocolReplay.ts +0 -194
- package/src/protocolTransport.test.ts +0 -556
- package/src/protocolTransport.ts +0 -483
- package/src/queueBinding.test.ts +0 -130
- package/src/queueBinding.ts +0 -102
- package/src/rateLimiter.test.ts +0 -96
- package/src/rateLimiter.ts +0 -46
- package/src/redisIntegration.test.ts +0 -134
- package/src/replayStores.test.ts +0 -273
- package/src/replayStores.ts +0 -215
- package/src/revocation.test.ts +0 -98
- package/src/revocation.ts +0 -0
- package/src/routePolicy.test.ts +0 -87
- package/src/routePolicy.ts +0 -72
- package/src/runtimePolicy.test.ts +0 -49
- package/src/runtimePolicy.ts +0 -81
- package/src/runtimePolicyManager.test.ts +0 -29
- package/src/runtimePolicyManager.ts +0 -50
- package/src/runtimePolicyPresets.ts +0 -43
- package/src/signedResponse.test.ts +0 -111
- package/src/signedResponse.ts +0 -83
- package/src/stream.test.ts +0 -254
- package/src/stream.ts +0 -417
- package/src/telemetry.test.ts +0 -251
- package/src/telemetry.ts +0 -299
- package/src/webhookBinding.test.ts +0 -144
- package/src/webhookBinding.ts +0 -115
- package/src/wsBinding.test.ts +0 -221
- package/src/wsBinding.ts +0 -200
- package/tsconfig.json +0 -15
- package/tsconfig.lib.json +0 -23
- package/vite.lib.config.ts +0 -16
- package/vitest.config.ts +0 -11
|
@@ -1,20 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"generatedAt": "2026-05-04T04:49:29.647Z",
|
|
3
|
-
"vectors": [
|
|
4
|
-
{
|
|
5
|
-
"id": "task-with-capability-and-recipient",
|
|
6
|
-
"alg": "HS256",
|
|
7
|
-
"binaryHex": "41495042010f0000018eb8f445000000ea60000000076169702f302e31000000057665632d310000000b6167656e742e616c7068610000000b6e6f6e63652d7665632d31000000045441534b00000011726f7574653a616c7068612d3e626574610000000a6167656e742e62657461000000097461736b2e706c616e00000006636f72722d31010000000c766563746f722d6b65792d310000002b4f6c376c516b5259336c52534961303576686b43795a32336f705973525139416250774670326378324430"
|
|
8
|
-
},
|
|
9
|
-
{
|
|
10
|
-
"id": "result-with-minimal-fields",
|
|
11
|
-
"alg": "HS256",
|
|
12
|
-
"binaryHex": "4149504201080000018eb8f4588800007530000000076169702f302e31000000057665632d320000000c6d656d6f72792e6167656e740000000b6e6f6e63652d7665632d3200000006524553554c54000000096d656d6f72793a6f6b010000000c766563746f722d6b65792d320000002b5a57775a5045787732646341416c354278507a33313337386d4351352d674768395566587536705a4b646f"
|
|
13
|
-
},
|
|
14
|
-
{
|
|
15
|
-
"id": "task-ed25519-with-recipient",
|
|
16
|
-
"alg": "ED25519",
|
|
17
|
-
"binaryHex": "41495042010f0000018eb8f46c100000afc8000000076169702f302e31000000087665632d65642d31000000086167656e742e65640000000a6e6f6e63652d65642d31000000045441534b0000000d726f7574653a656432353531390000000c6167656e742e766572696679000000097461736b2e7369676e00000009636f72722d65642d31020000000f65642d766563746f722d6b65792d310000005677787941674e494b6f66344d563478487757697a73623366366b326a574168325a7a7132703967684153456b5f464a4157346774366239317a76327a363344506b73416f485a365135334a64656a486f6150316f4251"
|
|
18
|
-
}
|
|
19
|
-
]
|
|
20
|
-
}
|
package/docker-compose.yaml
DELETED
|
@@ -1,77 +0,0 @@
|
|
|
1
|
-
# 7h3 Protocol — Docker Compose development stack
|
|
2
|
-
# Brings up:
|
|
3
|
-
# gateway — verifying AIP proxy (port 8080)
|
|
4
|
-
# api — minimal example upstream (port 3000, internal only)
|
|
5
|
-
#
|
|
6
|
-
# Quick start:
|
|
7
|
-
# docker compose up --build
|
|
8
|
-
|
|
9
|
-
services:
|
|
10
|
-
|
|
11
|
-
# ---------------------------------------------------------------------------
|
|
12
|
-
# gateway — 7h3 Protocol verifying HTTP proxy
|
|
13
|
-
# ---------------------------------------------------------------------------
|
|
14
|
-
gateway:
|
|
15
|
-
build:
|
|
16
|
-
context: .
|
|
17
|
-
dockerfile: Dockerfile
|
|
18
|
-
ports:
|
|
19
|
-
- "8080:8080"
|
|
20
|
-
command:
|
|
21
|
-
- "--port"
|
|
22
|
-
- "8080"
|
|
23
|
-
- "--upstream"
|
|
24
|
-
- "http://api:3000"
|
|
25
|
-
- "--require"
|
|
26
|
-
- "ed25519"
|
|
27
|
-
environment:
|
|
28
|
-
# Override these at runtime to enable response signing:
|
|
29
|
-
# GATEWAY_PRIVATE_KEY=<base64url private key>
|
|
30
|
-
# GATEWAY_SENDER=gateway@my-service.example.com
|
|
31
|
-
NODE_ENV: production
|
|
32
|
-
depends_on:
|
|
33
|
-
api:
|
|
34
|
-
condition: service_started
|
|
35
|
-
restart: unless-stopped
|
|
36
|
-
healthcheck:
|
|
37
|
-
test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
|
|
38
|
-
interval: 30s
|
|
39
|
-
timeout: 5s
|
|
40
|
-
start_period: 10s
|
|
41
|
-
retries: 3
|
|
42
|
-
|
|
43
|
-
# ---------------------------------------------------------------------------
|
|
44
|
-
# api — minimal example upstream service
|
|
45
|
-
#
|
|
46
|
-
# This is a self-contained inline Node.js server that demonstrates the
|
|
47
|
-
# headers the gateway injects after successful envelope verification:
|
|
48
|
-
# x-7h3-sender — verified sender identity from the AIP envelope
|
|
49
|
-
# x-7h3-verified — always "true" when the gateway passed the request
|
|
50
|
-
#
|
|
51
|
-
# Replace this service with your actual application in production.
|
|
52
|
-
# ---------------------------------------------------------------------------
|
|
53
|
-
api:
|
|
54
|
-
image: node:22-alpine
|
|
55
|
-
command: >
|
|
56
|
-
node -e "
|
|
57
|
-
const http = require('http');
|
|
58
|
-
const server = http.createServer((req, res) => {
|
|
59
|
-
const sender = req.headers['x-7h3-sender'] || null;
|
|
60
|
-
const verified = req.headers['x-7h3-verified'] === 'true';
|
|
61
|
-
const body = JSON.stringify({
|
|
62
|
-
ok: true,
|
|
63
|
-
path: req.url,
|
|
64
|
-
sender,
|
|
65
|
-
verified,
|
|
66
|
-
method: req.method,
|
|
67
|
-
});
|
|
68
|
-
res.writeHead(200, { 'content-type': 'application/json' });
|
|
69
|
-
res.end(body);
|
|
70
|
-
});
|
|
71
|
-
server.listen(3000, () => {
|
|
72
|
-
process.stderr.write('example api listening on port 3000\n');
|
|
73
|
-
});
|
|
74
|
-
"
|
|
75
|
-
expose:
|
|
76
|
-
- "3000"
|
|
77
|
-
restart: unless-stopped
|
package/docs/ADOPTION_PLAN.md
DELETED
|
@@ -1,120 +0,0 @@
|
|
|
1
|
-
# AIP Adoption Plan (Secure + Extremely Fast)
|
|
2
|
-
|
|
3
|
-
This plan turns `aip/0.1` into a production-ready protocol for agentic AI systems, memory services, and multi-agent networks.
|
|
4
|
-
|
|
5
|
-
## North-Star Targets
|
|
6
|
-
|
|
7
|
-
- Default secure mode: signed envelopes, replay protection, strict TTL validation.
|
|
8
|
-
- Transport speed: make `ws` the low-latency default and batch modes first-class for high-throughput workloads.
|
|
9
|
-
- Interop: at least 3 language SDKs passing shared conformance vectors.
|
|
10
|
-
- Operational maturity: CI performance gates on p99 latency, drop rate, and sustainable throughput.
|
|
11
|
-
|
|
12
|
-
## Protocol Productization (Weeks 1-2)
|
|
13
|
-
|
|
14
|
-
- Freeze protocol semantics from executable sources in `src/protocol.ts`, `src/protocolTransport.ts`, and `src/protocolReplay.ts`.
|
|
15
|
-
- Publish `AIP RFC v0.1` with normative language (`MUST`, `SHOULD`, `MAY`) covering:
|
|
16
|
-
- canonicalization rules (field order + optional fields)
|
|
17
|
-
- signature requirements and key identifiers
|
|
18
|
-
- replay cache keying and eviction expectations
|
|
19
|
-
- error/diagnostic semantics and transport-level failure mapping
|
|
20
|
-
- Include wire profiles:
|
|
21
|
-
- `json` profile (interop first)
|
|
22
|
-
- `compact` profile (performance first)
|
|
23
|
-
|
|
24
|
-
## Security Hardening Track (Weeks 2-6)
|
|
25
|
-
|
|
26
|
-
- Keep HS256 as baseline; add algorithm registry and pluggable signer/verifier interface for Ed25519 profile.
|
|
27
|
-
- Define key rotation contract:
|
|
28
|
-
- key IDs
|
|
29
|
-
- overlap windows
|
|
30
|
-
- rotation cadence and emergency revocation behavior
|
|
31
|
-
- Add hard limits and abuse controls:
|
|
32
|
-
- max payload size
|
|
33
|
-
- max batch size
|
|
34
|
-
- per-sender rate limits
|
|
35
|
-
- replay cache saturation behavior (fail-open/closed policy by profile)
|
|
36
|
-
- Produce a threat model doc with explicit mitigations for replay flooding, clock skew abuse, and queue amplification.
|
|
37
|
-
|
|
38
|
-
## Performance Engineering Track (Weeks 2-8)
|
|
39
|
-
|
|
40
|
-
- Keep microbench (`npm run bench:protocol`) for function-level regressions.
|
|
41
|
-
- Keep closed-loop E2E (`npm run bench:e2e:quick|full`) for latency/throughput under bounded concurrency.
|
|
42
|
-
- Keep open-loop saturation (`npm run bench:openloop:quick|full`) for contention behavior and drop dynamics.
|
|
43
|
-
- Use adaptive CI gate (`npm run bench:openloop:adaptive:ci`) as merge guard.
|
|
44
|
-
- Adopt hard SLO gates per CI scenario:
|
|
45
|
-
- p99 <= 250ms
|
|
46
|
-
- dropPct <= 2%
|
|
47
|
-
- minimum sustainable ops/s threshold by mode/payload/concurrency tuple
|
|
48
|
-
|
|
49
|
-
## SDK and Ecosystem Expansion (Weeks 3-10)
|
|
50
|
-
|
|
51
|
-
- Build official SDKs:
|
|
52
|
-
- TypeScript (reference)
|
|
53
|
-
- Python (agent framework ecosystem)
|
|
54
|
-
- Go or Rust (infra/perf services)
|
|
55
|
-
- Publish cross-language conformance vectors:
|
|
56
|
-
- canonical payload fixtures
|
|
57
|
-
- signature fixtures
|
|
58
|
-
- replay and TTL edge-case fixtures
|
|
59
|
-
- Ship adapter packages:
|
|
60
|
-
- WebSocket session adapter
|
|
61
|
-
- HTTP batch adapter
|
|
62
|
-
- memory gateway adapter (AIP intents for memory read/write/search)
|
|
63
|
-
|
|
64
|
-
## AI Memory System Integration (Weeks 4-10)
|
|
65
|
-
|
|
66
|
-
- Add intent extensions for memory operations:
|
|
67
|
-
- `MEM_GET`, `MEM_PUT`, `MEM_APPEND`, `MEM_SEARCH`, `MEM_COMPACT`
|
|
68
|
-
- Add capability namespace conventions:
|
|
69
|
-
- `mem.read`, `mem.write`, `mem.search`, `mem.admin`
|
|
70
|
-
- Standardize idempotency and causality metadata:
|
|
71
|
-
- correlation IDs
|
|
72
|
-
- idempotency keys
|
|
73
|
-
- causal parent references for chain-of-thought-safe state updates
|
|
74
|
-
|
|
75
|
-
## Agent Runtime Integration (Weeks 5-12)
|
|
76
|
-
|
|
77
|
-
- Add a reference agent mesh demo:
|
|
78
|
-
- planner agent
|
|
79
|
-
- tool-executor agent
|
|
80
|
-
- memory agent
|
|
81
|
-
- policy/guardrail agent
|
|
82
|
-
- Ensure all inter-agent traffic is AIP signed and replay-protected.
|
|
83
|
-
- Instrument end-to-end agent loop latency:
|
|
84
|
-
- input -> planning -> tool call -> memory update -> response
|
|
85
|
-
- Provide runbooks for degraded modes (queue pressure, key mismatch, stale clock).
|
|
86
|
-
|
|
87
|
-
## CI, Governance, and Releases
|
|
88
|
-
|
|
89
|
-
- CI stages:
|
|
90
|
-
- correctness: `npm run lint && npm run test && npm run build`
|
|
91
|
-
- perf gate: `npm run bench:openloop:adaptive:ci`
|
|
92
|
-
- regression diff: `npm run bench:diff -- --baseline <baseline> --candidate <candidate>`
|
|
93
|
-
- Release cadence:
|
|
94
|
-
- protocol patch versions for non-breaking behavior
|
|
95
|
-
- minor versions for additive intents/capabilities
|
|
96
|
-
- major versions for breaking canonicalization/wire/security semantics
|
|
97
|
-
- Governance:
|
|
98
|
-
- RFC process for protocol changes
|
|
99
|
-
- mandatory conformance vector updates for all normative changes
|
|
100
|
-
|
|
101
|
-
## 30/60/90 Day Execution
|
|
102
|
-
|
|
103
|
-
- Day 0-30:
|
|
104
|
-
- publish RFC v0.1
|
|
105
|
-
- lock CI adaptive gate
|
|
106
|
-
- ship SDK hardening notes and conformance vectors
|
|
107
|
-
- Day 31-60:
|
|
108
|
-
- Python SDK beta
|
|
109
|
-
- memory intent extension draft
|
|
110
|
-
- key rotation + revocation reference implementation
|
|
111
|
-
- Day 61-90:
|
|
112
|
-
- production profile v1 (`ws` + compact + adaptive perf SLOs)
|
|
113
|
-
- at least one multi-agent + memory reference deployment
|
|
114
|
-
- external adopter kit (quickstart + compatibility checklist)
|
|
115
|
-
|
|
116
|
-
## Success Criteria
|
|
117
|
-
|
|
118
|
-
- Security: no unsigned traffic in secure profiles; replay checks enforced in all reference transports.
|
|
119
|
-
- Performance: CI gate remains green with stable p99 and sustainable throughput across selected scenarios.
|
|
120
|
-
- Adoption: 3+ SDKs passing conformance tests and at least one external integration using AIP as primary inter-agent protocol.
|
package/docs/AGENTS.md
DELETED
|
@@ -1,77 +0,0 @@
|
|
|
1
|
-
# AGENTS
|
|
2
|
-
|
|
3
|
-
## Commands (source of truth: package.json)
|
|
4
|
-
- Install deps: `npm install`
|
|
5
|
-
- Dev server: `npm run dev`
|
|
6
|
-
- Lint: `npm run lint`
|
|
7
|
-
- Full tests: `npm run test`
|
|
8
|
-
- AI agent protocol quickstart demo: `npm run aip:quickstart`
|
|
9
|
-
- Framework bridge quickstart demo: `npm run aip:framework:quickstart`
|
|
10
|
-
- JSON-RPC gateway over AIP internals: `npm run aip:mcp:gateway`
|
|
11
|
-
- Protocol microbench: `npm run bench:protocol`
|
|
12
|
-
- E2E protocol quick benchmark: `npm run bench:e2e:quick`
|
|
13
|
-
- E2E protocol full benchmark: `npm run bench:e2e:full`
|
|
14
|
-
- Open-loop contention quick benchmark: `npm run bench:openloop:quick`
|
|
15
|
-
- Open-loop contention full benchmark: `npm run bench:openloop:full`
|
|
16
|
-
- Adaptive saturation benchmark gate: `npm run bench:openloop:adaptive:quick`
|
|
17
|
-
- CI-friendly adaptive benchmark gate: `npm run bench:openloop:adaptive:ci`
|
|
18
|
-
- Signature profile quick benchmark (`HS256` vs `ED25519`): `npm run bench:signatures:quick`
|
|
19
|
-
- Signature profile full benchmark (`HS256` vs `ED25519`): `npm run bench:signatures:full`
|
|
20
|
-
- Wire codec quick benchmark (`compact-json` vs `binary`): `npm run bench:wire:quick`
|
|
21
|
-
- Wire codec full benchmark (`compact-json` vs `binary`): `npm run bench:wire:full`
|
|
22
|
-
- Build release dashboard summary from latest bench runs: `npm run release:dashboard`
|
|
23
|
-
- Compare two benchmark json runs: `npm run bench:diff -- --baseline <path> --candidate <path>`
|
|
24
|
-
- CI uploads benchmark artifacts from `dist/bench/`, `dist/release-dashboard/`, `dist/npm-aip/`, and `bench-results/` for trend tracking and release evidence.
|
|
25
|
-
- Python conformance suite: `npm run conformance:python`
|
|
26
|
-
- Rust conformance suite: `npm run conformance:rust`
|
|
27
|
-
- Single test file: `npm run test -- src/language.test.ts`
|
|
28
|
-
- Single test name: `npm run test -- -t "signs and verifies with HMAC"`
|
|
29
|
-
- Build + typecheck: `npm run build` (runs `tsc -b && vite build`)
|
|
30
|
-
- Build library exports only: `npm run build:aip`
|
|
31
|
-
- Prepare publishable package output (`@7h3/protocol`): `npm run package:aip`
|
|
32
|
-
|
|
33
|
-
## Verification order
|
|
34
|
-
- Use `npm run lint && npm run test && npm run build` before finishing.
|
|
35
|
-
- `build` writes `dist/`; treat it as generated output, not hand-edited source.
|
|
36
|
-
|
|
37
|
-
## Real entrypoints and module boundaries
|
|
38
|
-
- `src/main.tsx` mounts the app; `src/App.tsx` is the single UI workbench.
|
|
39
|
-
- `src/language.ts` is the core implementation (tokenize/compile/run/assemble/disassemble + stdlib preload + demos).
|
|
40
|
-
- Protocol stack is split by responsibility:
|
|
41
|
-
- `src/protocol.ts`: envelope model, canonicalization, validation, HMAC sign/verify
|
|
42
|
-
- `src/protocolTransport.ts`: decode/encode (JSON + compact wire), inbound verification, replay checks, batch/session helpers
|
|
43
|
-
- `src/protocolAgent.ts`: session abstraction and auto-response loop
|
|
44
|
-
- `src/agentAdapter.ts`: drop-in raw-message adapter for AI framework integration
|
|
45
|
-
- `src/frameworkAdapters.ts`: framework bridge helpers (LangChain/LlamaIndex message mapping + JSON-RPC MCP-style bridge)
|
|
46
|
-
- `src/mcpGateway.ts`: line-based JSON-RPC gateway runtime over signed AIP internals
|
|
47
|
-
- `src/index.ts`: public protocol/adapter export surface for external integrations
|
|
48
|
-
- `src/protocolDemo.ts`: deterministic demo transcript used by UI/tests
|
|
49
|
-
- Benchmark harnesses:
|
|
50
|
-
- `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)
|
|
51
|
-
- `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)
|
|
52
|
-
- `scripts/bench-diff.ts` (baseline vs candidate regression check for ops/s and p99)
|
|
53
|
-
- Shared cross-language vectors live in `conformance/aip_v0_1.json`; TypeScript and Python conformance tests should stay aligned to this fixture.
|
|
54
|
-
- Shared cross-language vectors live in `conformance/aip_v0_1.json`; TypeScript, Python, and Rust conformance tests should stay aligned to this fixture.
|
|
55
|
-
- Tests live in `src/*.test.ts` plus CLI process tests in `scripts/*.test.ts` (no custom Vitest config/setup file).
|
|
56
|
-
|
|
57
|
-
## Non-obvious behavior to preserve
|
|
58
|
-
- GLUV source accepts only four Unicode symbols (`╬ ┼ ╫ ╪`) plus whitespace.
|
|
59
|
-
- `CALL` is encoded with two immediates: target index and arity (`arg2`).
|
|
60
|
-
- If any `func` declarations exist, assembler enters function mode:
|
|
61
|
-
- requires `main` with arity `0`
|
|
62
|
-
- injects bootstrap instructions `CALL main` then `HALT`
|
|
63
|
-
- shifts jump/call targets by `+2`
|
|
64
|
-
- `use <library>` directives are expanded before parsing; available libs are hardcoded in `STANDARD_LIBRARIES` inside `src/language.ts`.
|
|
65
|
-
- Protocol verification defaults to signed envelopes (`requireSignature: true`) and needs a `secretResolver` for inbound signature checks.
|
|
66
|
-
- For non-HS256 signatures (for example `ED25519`), use `signatureResolver` in transport/session options to provide algorithm-specific verification material.
|
|
67
|
-
- Use `DistributedReplayCache` from `src/protocolReplay.ts` for multi-node replay defense (shared store reserve semantics).
|
|
68
|
-
- Configure `maxClockSkewMs` in receive/session options when deployments need stricter/flexible time-skew tolerance.
|
|
69
|
-
- Use `telemetry` (`receiveEnvelope`) and `onAuditEvent` (`createAipMcpGatewayRuntime`) to emit rejection and policy traces.
|
|
70
|
-
- Stable JS consumer import path is `@7h3/protocol` (from `package.json` `exports`).
|
|
71
|
-
- HMAC helpers depend on Web Crypto (`crypto.subtle`); runtimes without it will throw.
|
|
72
|
-
- Protocol canonicalization is explicit and order-sensitive (`body` then `header`, each field in fixed key order); changing field order will break signature compatibility.
|
|
73
|
-
- HMAC key import is cached (bounded map) in `src/protocol.ts`; preserve cache behavior for high-throughput signing/verification.
|
|
74
|
-
- 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).
|
|
75
|
-
|
|
76
|
-
## Instruction files present
|
|
77
|
-
- No repo-local agent instruction files were found besides this `AGENTS.md`.
|
package/docs/AIP_RFC_v0.1.md
DELETED
|
@@ -1,97 +0,0 @@
|
|
|
1
|
-
# AIP RFC v0.1 (Draft)
|
|
2
|
-
|
|
3
|
-
This document defines the normative behavior for the GLUV AI communication protocol (`aip/0.1`).
|
|
4
|
-
|
|
5
|
-
## 1. Scope
|
|
6
|
-
|
|
7
|
-
- AIP defines signed, replay-resistant envelopes for agent-to-agent communication.
|
|
8
|
-
- This RFC covers envelope structure, canonicalization, signing, validation, and transport expectations.
|
|
9
|
-
|
|
10
|
-
## 2. Envelope Model
|
|
11
|
-
|
|
12
|
-
An envelope has:
|
|
13
|
-
|
|
14
|
-
- `header`
|
|
15
|
-
- `version` (MUST be `"aip/0.1"`)
|
|
16
|
-
- `messageId` (MUST be non-empty)
|
|
17
|
-
- `timestampMs` (Unix epoch milliseconds)
|
|
18
|
-
- `ttlMs` (MUST be > 0)
|
|
19
|
-
- `sender` (MUST be non-empty)
|
|
20
|
-
- `recipient` (OPTIONAL)
|
|
21
|
-
- `nonce` (MUST be non-empty)
|
|
22
|
-
- `body`
|
|
23
|
-
- `intent` (MUST be one of `PING`, `PONG`, `CAPS`, `TASK`, `RESULT`, `ERROR`)
|
|
24
|
-
- `content` (MAY be empty but SHOULD be meaningful)
|
|
25
|
-
- `capability` (OPTIONAL)
|
|
26
|
-
- `correlationId` (OPTIONAL)
|
|
27
|
-
- `signature` (OPTIONAL at format level, REQUIRED in secure profile)
|
|
28
|
-
- `alg` (`HS256` in v0.1)
|
|
29
|
-
- `keyId`
|
|
30
|
-
- `value` (base64url)
|
|
31
|
-
|
|
32
|
-
## 3. Canonicalization (Normative)
|
|
33
|
-
|
|
34
|
-
The canonical payload used for signing and verification MUST be a deterministic JSON string with fixed key ordering.
|
|
35
|
-
|
|
36
|
-
- Top-level order MUST be: `body`, then `header`.
|
|
37
|
-
- `body` key order MUST be:
|
|
38
|
-
- `capability` (if present)
|
|
39
|
-
- `content`
|
|
40
|
-
- `correlationId` (if present)
|
|
41
|
-
- `intent`
|
|
42
|
-
- `header` key order MUST be:
|
|
43
|
-
- `messageId`
|
|
44
|
-
- `nonce`
|
|
45
|
-
- `recipient` (if present)
|
|
46
|
-
- `sender`
|
|
47
|
-
- `timestampMs`
|
|
48
|
-
- `ttlMs`
|
|
49
|
-
- `version`
|
|
50
|
-
|
|
51
|
-
Receivers MUST verify signatures against this exact canonicalization behavior.
|
|
52
|
-
|
|
53
|
-
## 4. Signature and Integrity
|
|
54
|
-
|
|
55
|
-
- Secure profile senders MUST sign envelopes.
|
|
56
|
-
- Secure profile receivers MUST reject missing signatures.
|
|
57
|
-
- `HS256` signatures MUST be computed over canonical payload bytes (UTF-8).
|
|
58
|
-
- `keyId` SHOULD identify the active secret material.
|
|
59
|
-
|
|
60
|
-
## 5. Freshness and Replay
|
|
61
|
-
|
|
62
|
-
- Receivers MUST enforce freshness: reject when `timestampMs + ttlMs < nowMs`.
|
|
63
|
-
- Replay cache key MUST be `(sender, messageId, nonce)`.
|
|
64
|
-
- Re-seeing an unexpired replay key MUST be rejected.
|
|
65
|
-
|
|
66
|
-
## 6. Transport Expectations
|
|
67
|
-
|
|
68
|
-
- JSON and compact wire forms are allowed; both MUST map losslessly to the same envelope model before validation.
|
|
69
|
-
- Compact wire fields:
|
|
70
|
-
- `v, mid, ts, ttl, s, r, n, i, c, cap, cid, sig`
|
|
71
|
-
- Validation and signature verification MUST occur after decoding to canonical envelope fields.
|
|
72
|
-
|
|
73
|
-
## 7. Error Semantics
|
|
74
|
-
|
|
75
|
-
Receivers SHOULD produce explicit diagnostics for:
|
|
76
|
-
|
|
77
|
-
- invalid JSON / unrecognized shape
|
|
78
|
-
- unsupported version
|
|
79
|
-
- missing required fields
|
|
80
|
-
- TTL expiry
|
|
81
|
-
- missing or invalid signature
|
|
82
|
-
- replay detection
|
|
83
|
-
|
|
84
|
-
## 8. Security Profile Recommendations
|
|
85
|
-
|
|
86
|
-
- Production deployments SHOULD require signatures (`requireSignature: true`).
|
|
87
|
-
- Secrets SHOULD rotate; overlapping accept windows SHOULD be supported by `secretResolver`.
|
|
88
|
-
- Deployments SHOULD apply payload size limits and rate limits per sender.
|
|
89
|
-
|
|
90
|
-
## 9. Conformance
|
|
91
|
-
|
|
92
|
-
Implementations are conformant to v0.1 if they:
|
|
93
|
-
|
|
94
|
-
- produce/accept normative envelope model
|
|
95
|
-
- match canonicalization behavior exactly
|
|
96
|
-
- pass signature verification and replay/freshness requirements
|
|
97
|
-
- interoperate across wire forms without semantic loss
|
package/docs/AI_DECISION_CARD.md
DELETED
|
@@ -1,122 +0,0 @@
|
|
|
1
|
-
# GLUV AI Decision Card (Runtime)
|
|
2
|
-
|
|
3
|
-
Use this as a fast, deterministic runtime checklist for agent systems using GLUV.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## 1) Pick transport mode
|
|
8
|
-
|
|
9
|
-
### If throughput is high or concurrency >= 100
|
|
10
|
-
- Use: `http-binary-batch` or `ws-binary-batch`
|
|
11
|
-
- Avoid: plain `http`
|
|
12
|
-
|
|
13
|
-
### If moderate throughput with low complexity
|
|
14
|
-
- Use: `ws-batch`
|
|
15
|
-
|
|
16
|
-
### If low traffic / compatibility-first
|
|
17
|
-
- Use: `http`
|
|
18
|
-
|
|
19
|
-
---
|
|
20
|
-
|
|
21
|
-
## 2) Pick batch size
|
|
22
|
-
|
|
23
|
-
- Low traffic: `4–8`
|
|
24
|
-
- Medium traffic: `8–32`
|
|
25
|
-
- High traffic: `32–64`
|
|
26
|
-
|
|
27
|
-
Rule: if p99 rises sharply, reduce batch size first.
|
|
28
|
-
|
|
29
|
-
---
|
|
30
|
-
|
|
31
|
-
## 3) Pick in-flight cap
|
|
32
|
-
|
|
33
|
-
- Low traffic: `16–64`
|
|
34
|
-
- Medium traffic: `64–256`
|
|
35
|
-
- High traffic: `256–1024`
|
|
36
|
-
|
|
37
|
-
Rule: if queueing grows and drop rises, lower cap and rely on backpressure.
|
|
38
|
-
|
|
39
|
-
---
|
|
40
|
-
|
|
41
|
-
## 4) Retry/backoff policy
|
|
42
|
-
|
|
43
|
-
- Retry only on retriable overload/transient failures (e.g., 503)
|
|
44
|
-
- Use jittered backoff:
|
|
45
|
-
- low: `1–2ms`
|
|
46
|
-
- medium: `2–8ms`
|
|
47
|
-
- high: `4–16ms`
|
|
48
|
-
- Keep retries bounded (e.g., max 3 attempts)
|
|
49
|
-
|
|
50
|
-
Never retry indefinitely.
|
|
51
|
-
|
|
52
|
-
---
|
|
53
|
-
|
|
54
|
-
## 5) Safety invariants (never disable)
|
|
55
|
-
|
|
56
|
-
- Signature verification
|
|
57
|
-
- Canonicalization
|
|
58
|
-
- Replay defense
|
|
59
|
-
- TTL / clock-skew checks
|
|
60
|
-
|
|
61
|
-
If any are disabled, system is out of compliant mode.
|
|
62
|
-
|
|
63
|
-
---
|
|
64
|
-
|
|
65
|
-
## 6) Benchmark discipline
|
|
66
|
-
|
|
67
|
-
Use **adaptive** for production readiness:
|
|
68
|
-
|
|
69
|
-
```bash
|
|
70
|
-
npm run bench:openloop:quick
|
|
71
|
-
npm run bench:openloop:full
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
Use **stress** only for capacity ceiling exploration:
|
|
75
|
-
|
|
76
|
-
```bash
|
|
77
|
-
npm run bench:openloop:stress:quick
|
|
78
|
-
npm run bench:openloop:stress:full
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
Do not use stress numbers as SLO pass/fail.
|
|
82
|
-
|
|
83
|
-
---
|
|
84
|
-
|
|
85
|
-
## 7) Fast decision tree
|
|
86
|
-
|
|
87
|
-
1. Concurrency >= 100?
|
|
88
|
-
- Yes → choose `*-binary-batch`
|
|
89
|
-
- No → go to 2
|
|
90
|
-
2. Need lowest latency and moderate throughput?
|
|
91
|
-
- Yes → `ws-batch`
|
|
92
|
-
- No → `http`
|
|
93
|
-
3. Drop > threshold?
|
|
94
|
-
- Lower in-flight cap
|
|
95
|
-
- Reduce batch size
|
|
96
|
-
- Increase backoff
|
|
97
|
-
- Switch to binary batch mode
|
|
98
|
-
|
|
99
|
-
---
|
|
100
|
-
|
|
101
|
-
## 8) SLO gate template
|
|
102
|
-
|
|
103
|
-
- `dropPct <= 0.1%` (or stricter by lane)
|
|
104
|
-
- `p99 <= target_ms`
|
|
105
|
-
- signatures/replay checks: 100% enforced
|
|
106
|
-
- sustained for target duration under declared load profile
|
|
107
|
-
|
|
108
|
-
If not met: do not promote release.
|
|
109
|
-
|
|
110
|
-
---
|
|
111
|
-
|
|
112
|
-
## 9) Operator handoff note
|
|
113
|
-
|
|
114
|
-
When filing an incident/perf ticket include:
|
|
115
|
-
|
|
116
|
-
- mode (`http`, `ws-batch`, `http-binary-batch`, etc.)
|
|
117
|
-
- payload size(s)
|
|
118
|
-
- concurrency
|
|
119
|
-
- adaptive or stress run
|
|
120
|
-
- p50/p95/p99
|
|
121
|
-
- dropPct
|
|
122
|
-
- retry counts and overload signals
|
|
@@ -1,126 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"version": "1.0",
|
|
3
|
-
"name": "gluv-runtime-policy",
|
|
4
|
-
"status": "active",
|
|
5
|
-
"owner": "platform-ai-ops",
|
|
6
|
-
"updated_at": "2026-05-10",
|
|
7
|
-
"purpose": {
|
|
8
|
-
"summary": "Deterministic runtime policy for selecting GLUV transport, batching, retries, and safety controls.",
|
|
9
|
-
"intent": "Maximize sustainable throughput while preserving protocol integrity and low drop rates."
|
|
10
|
-
},
|
|
11
|
-
"hard_invariants": {
|
|
12
|
-
"require_signature_verification": true,
|
|
13
|
-
"require_canonicalization": true,
|
|
14
|
-
"require_replay_defense": true,
|
|
15
|
-
"require_ttl_clock_skew_enforcement": true,
|
|
16
|
-
"disallow_invariant_bypass": true
|
|
17
|
-
},
|
|
18
|
-
"slo_defaults": {
|
|
19
|
-
"drop_pct_max": 0.1,
|
|
20
|
-
"p99_ms_max": 20,
|
|
21
|
-
"enforce_over_window": "5m",
|
|
22
|
-
"fail_release_on_breach": true
|
|
23
|
-
},
|
|
24
|
-
"mode_selection": {
|
|
25
|
-
"rules": [
|
|
26
|
-
{
|
|
27
|
-
"when": { "concurrency_gte": 100 },
|
|
28
|
-
"use": "http-binary-batch",
|
|
29
|
-
"fallback": "ws-binary-batch",
|
|
30
|
-
"rationale": "High-concurrency lanes require binary+batch to avoid plain-http collapse."
|
|
31
|
-
},
|
|
32
|
-
{
|
|
33
|
-
"when": { "latency_sensitive": true, "concurrency_lt": 100 },
|
|
34
|
-
"use": "ws-batch",
|
|
35
|
-
"rationale": "Balanced p99 and throughput."
|
|
36
|
-
},
|
|
37
|
-
{
|
|
38
|
-
"when": { "compatibility_first": true, "concurrency_lt": 100 },
|
|
39
|
-
"use": "http",
|
|
40
|
-
"rationale": "Lowest integration friction for low/medium load."
|
|
41
|
-
}
|
|
42
|
-
]
|
|
43
|
-
},
|
|
44
|
-
"guardrails": {
|
|
45
|
-
"block_plain_http_high_concurrency": true,
|
|
46
|
-
"plain_http_block_threshold_concurrency": 100,
|
|
47
|
-
"allow_override_flag": "--allow-unsafe-http",
|
|
48
|
-
"override_allowed_only_for": "stress-benchmarks"
|
|
49
|
-
},
|
|
50
|
-
"tuning": {
|
|
51
|
-
"batch_size": {
|
|
52
|
-
"low_traffic": [4, 8],
|
|
53
|
-
"medium_traffic": [8, 32],
|
|
54
|
-
"high_traffic": [32, 64]
|
|
55
|
-
},
|
|
56
|
-
"inflight_cap": {
|
|
57
|
-
"low_traffic": [16, 64],
|
|
58
|
-
"medium_traffic": [64, 256],
|
|
59
|
-
"high_traffic": [256, 1024]
|
|
60
|
-
},
|
|
61
|
-
"retry_backoff_ms": {
|
|
62
|
-
"low_traffic": [1, 2],
|
|
63
|
-
"medium_traffic": [2, 8],
|
|
64
|
-
"high_traffic": [4, 16]
|
|
65
|
-
},
|
|
66
|
-
"max_retry_attempts": 3,
|
|
67
|
-
"retriable_status_codes": [503]
|
|
68
|
-
},
|
|
69
|
-
"adaptive_flow": {
|
|
70
|
-
"enabled": true,
|
|
71
|
-
"ewma_latency_alpha": 0.15,
|
|
72
|
-
"degrade_if_latency_ms_gt": 25,
|
|
73
|
-
"recover_if_latency_ms_lt": 8,
|
|
74
|
-
"reduce_inflight_factor_on_error": 0.85,
|
|
75
|
-
"reduce_batch_factor_on_error": 0.8
|
|
76
|
-
},
|
|
77
|
-
"benchmark_policy": {
|
|
78
|
-
"production_readiness": {
|
|
79
|
-
"require_adaptive_mode": true,
|
|
80
|
-
"commands": [
|
|
81
|
-
"npm run bench:openloop:quick",
|
|
82
|
-
"npm run bench:openloop:full"
|
|
83
|
-
]
|
|
84
|
-
},
|
|
85
|
-
"stress_characterization": {
|
|
86
|
-
"allowed": true,
|
|
87
|
-
"commands": [
|
|
88
|
-
"npm run bench:openloop:stress:quick",
|
|
89
|
-
"npm run bench:openloop:stress:full"
|
|
90
|
-
],
|
|
91
|
-
"note": "Stress outputs must not be used as direct SLO acceptance."
|
|
92
|
-
}
|
|
93
|
-
},
|
|
94
|
-
"runtime_decision_tree": [
|
|
95
|
-
{ "if": "concurrency >= 100", "then": "use http-binary-batch" },
|
|
96
|
-
{
|
|
97
|
-
"if": "drop_pct > drop_pct_max",
|
|
98
|
-
"then": [
|
|
99
|
-
"reduce inflight cap",
|
|
100
|
-
"reduce batch size",
|
|
101
|
-
"increase retry backoff",
|
|
102
|
-
"switch to binary-batch mode"
|
|
103
|
-
]
|
|
104
|
-
},
|
|
105
|
-
{
|
|
106
|
-
"if": "p99_ms > p99_ms_max",
|
|
107
|
-
"then": [
|
|
108
|
-
"reduce batch size",
|
|
109
|
-
"reduce inflight cap",
|
|
110
|
-
"re-run adaptive benchmark"
|
|
111
|
-
]
|
|
112
|
-
}
|
|
113
|
-
],
|
|
114
|
-
"operator_handoff_required_fields": [
|
|
115
|
-
"mode",
|
|
116
|
-
"payload_bytes",
|
|
117
|
-
"concurrency",
|
|
118
|
-
"benchmark_type",
|
|
119
|
-
"p50_ms",
|
|
120
|
-
"p95_ms",
|
|
121
|
-
"p99_ms",
|
|
122
|
-
"drop_pct",
|
|
123
|
-
"retry_count",
|
|
124
|
-
"overload_signals"
|
|
125
|
-
]
|
|
126
|
-
}
|