You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-**`capsule://` URI scheme** — content-addressable references to Capsule records via their SHA3-256 hash. Spec at `spec/uri-scheme.md`. Supports hash references (`capsule://sha3_<hash>`), chain references (`capsule://chain/42`), ID references, and fragment syntax into the 6 sections.
25
-
-**TypeScript reference implementation** — full CPS-conformant implementation at `reference/typescript/`: Capsule model with factories, canonical JSON serializer (CPS Section 2 with float-path handling), SHA3-256 hashing, Ed25519 seal/verify, and chain verification. Passes all 15 golden fixtures. 101 tests, 100% coverage (v8). Uses `@noble/hashes` ^2.0.1, `@noble/ed25519` ^3.0.0, vitest ^4.0.0, TypeScript ^5.9.0. Node.js >= 20.19.0.
30
+
-**`capsule://` URI scheme (Active)** — content-addressable references to Capsule records via their SHA3-256 hash. Spec at `spec/uri-scheme.md`, finalized from Draft to Active. Supports hash references (`capsule://sha3_<hash>`), chain references (`capsule://chain/42`), ID references, and fragment syntax into the 6 sections. Includes URI conformance vectors at `conformance/uri-fixtures.json`.
31
+
-**TypeScript reference implementation** — full CPS-conformant implementation at `reference/typescript/`: Capsule model with factories, canonical JSON serializer (CPS Section 2 with float-path handling), SHA3-256 hashing, Ed25519 seal/verify, and chain verification. Passes all 16 golden fixtures. 101 tests, 100% coverage (v8). Uses `@noble/hashes` ^2.0.1, `@noble/ed25519` ^3.0.0, vitest ^4.0.0, TypeScript ^5.9.0. Node.js >= 20.19.0.
26
32
-**Implementor's Guide** (`docs/implementors-guide.md`) — step-by-step instructions for building a conformant CPS implementation in any language, with language-specific pitfalls for TypeScript, Go, and Rust.
27
33
-**Why Capsules** (`docs/why-capsules.md`) — the case for cryptographic AI memory, aimed at decision-makers and architects.
28
-
-**URI scheme security considerations** — `spec/uri-scheme.md` now includes: URI injection validation, resolution trust model, denial-of-service mitigations, fragment path traversal safety, no ambient authority principle.
34
+
-**URI scheme security considerations** — `spec/uri-scheme.md` includes: URI injection validation, resolution trust model, denial-of-service mitigations, fragment path traversal safety, no ambient authority principle.
35
+
-**URI conformance vectors** (`conformance/uri-fixtures.json`) — 10 valid and 11 invalid URI parsing test vectors for cross-language URI parser verification.
36
+
-**`vault` golden fixture** — conformance suite now covers all 8 CapsuleTypes (16 total fixtures, up from 15). The `vault_secret` fixture tests secret rotation with policy-based authority.
29
37
-**Protocol structure tests** (`reference/python/tests/test_protocol_structure.py`) — guards the protocol-first layout, spec completeness, conformance suite integrity, TypeScript type alignment with spec, markdown link resolution, CI configuration, and root-level file requirements.
30
38
-**Dependabot for TypeScript** — npm dependency updates for `reference/typescript/`.
31
39
@@ -92,5 +100,6 @@ Initial public release of the Capsule Protocol Specification (CPS) v1.0 referenc
@@ -58,7 +58,7 @@ Section 3 (Reasoning) records the AI's analysis, the options it considered, the
58
58
Every Capsule is hashed and signed at the moment of creation. If anyone modifies the content after the fact, the hash changes, the signature fails, and the chain breaks. This is a property of every individual record, not the storage layer.
59
59
60
60
**3. Cross-language interoperability.**
61
-
The Capsule Protocol Specification defines byte-level serialization rules. A Capsule sealed in Python can be verified in TypeScript, Go, or Rust. All implementations produce identical canonical JSON for the same input, validated by 15 golden test vectors.
61
+
The Capsule Protocol Specification defines byte-level serialization rules. A Capsule sealed in Python can be verified in TypeScript, Go, or Rust. All implementations produce identical canonical JSON for the same input, validated by 16 golden test vectors.
62
62
63
63
---
64
64
@@ -121,7 +121,7 @@ The **Capsule Protocol Specification (CPS)** defines the complete protocol:
Copy file name to clipboardExpand all lines: conformance/README.md
+38-3Lines changed: 38 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
1
# Conformance Test Suite
2
2
3
-
**15 golden test vectors for cross-language interoperability.**
3
+
**16 golden test vectors for cross-language interoperability.**
4
4
5
-
Any implementation of the Capsule Protocol Specification (CPS) must produce byte-identical output for these test vectors. If your implementation passes all 15 fixtures, it can seal and verify Capsules interchangeably with every other conformant implementation.
5
+
Any implementation of the Capsule Protocol Specification (CPS) must produce byte-identical output for these test vectors. If your implementation passes all 16 fixtures, it can seal and verify Capsules interchangeably with every other conformant implementation.
6
6
7
7
---
8
8
@@ -25,7 +25,7 @@ For every fixture:
25
25
3. Compute SHA3-256 of the canonical JSON bytes (UTF-8 encoded)
26
26
4. Compare the hash against `sha3_256_hash`
27
27
28
-
If all 15 pass, your implementation is conformant.
28
+
If all 16 pass, your implementation is conformant.
29
29
30
30
---
31
31
@@ -48,6 +48,7 @@ If all 15 pass, your implementation is conformant.
48
48
|**chain_linked**| Second Capsule with previous_hash set |
49
49
|**failure_with_error**| Failed tool call with error details |
50
50
|**auth_escalated**| Auth-type with MFA escalation chain |
51
+
|**vault_secret**| Vault-type with secret rotation and policy authority |
51
52
52
53
---
53
54
@@ -64,6 +65,40 @@ This regenerates `fixtures.json` from the reference implementation. The generato
64
65
65
66
---
66
67
68
+
## URI Conformance Vectors
69
+
70
+
The `uri-fixtures.json` file provides test vectors for `capsule://` URI parsing. Implementations that include a URI parser should validate against these vectors.
71
+
72
+
Each entry in the `valid` array contains:
73
+
74
+
| Field | Type | Description |
75
+
|---|---|---|
76
+
|`uri`| string | The `capsule://` URI to parse |
77
+
|`expected`| object | The expected parse result with `scheme`, `chain`, `reference_type`, `hash_algorithm`, `hash_value`, `sequence`, `id`, and `fragment`|
78
+
79
+
Each entry in the `invalid` array contains:
80
+
81
+
| Field | Type | Description |
82
+
|---|---|---|
83
+
|`uri`| string | A malformed or invalid URI |
84
+
|`reason`| string | Why this URI must be rejected |
85
+
86
+
### URI conformance check
87
+
88
+
For every valid fixture:
89
+
90
+
1. Parse the URI
91
+
2. Compare every field in the parse result against `expected`
92
+
93
+
For every invalid fixture:
94
+
95
+
1. Attempt to parse the URI
96
+
2. Confirm the parser rejects it (returns an error or null)
97
+
98
+
The URI spec is at [`spec/uri-scheme.md`](../spec/uri-scheme.md).
99
+
100
+
---
101
+
67
102
## Adding New Fixtures
68
103
69
104
New fixtures must be added through the [protocol change proposal](https://github.com/quantumpipes/capsule/issues/new?template=spec-change.md) process. Every new fixture must:
"description": "Golden test vectors for cross-language Capsule verification. Each fixture contains a capsule_dict, the expected canonical_json, and the expected sha3_256_hash. A conformant implementation must produce byte-identical canonical_json and matching hash for each fixture.",
"description": "Vault-type capsule for secret storage/rotation. Tests CapsuleType.VAULT with tool call for secret rotation and policy-based authority.",
1091
+
"capsule_dict": {
1092
+
"id": "d6e7f8a9-b0c1-2345-defa-456789abcdef",
1093
+
"type": "vault",
1094
+
"domain": "secrets",
1095
+
"parent_id": null,
1096
+
"sequence": 0,
1097
+
"previous_hash": null,
1098
+
"trigger": {
1099
+
"type": "scheduled",
1100
+
"source": "secret_rotator",
1101
+
"timestamp": "2026-01-15T12:00:00+00:00",
1102
+
"request": "Rotate database credentials for production",
1103
+
"correlation_id": null,
1104
+
"user_id": null
1105
+
},
1106
+
"context": {
1107
+
"agent_id": "vault-agent",
1108
+
"session_id": null,
1109
+
"environment": {
1110
+
"vault_backend": "hashicorp",
1111
+
"region": "us-east-1"
1112
+
}
1113
+
},
1114
+
"reasoning": {
1115
+
"analysis": "",
1116
+
"options": [],
1117
+
"options_considered": [],
1118
+
"selected_option": "",
1119
+
"reasoning": "",
1120
+
"confidence": 0.0,
1121
+
"model": null,
1122
+
"prompt_hash": null
1123
+
},
1124
+
"authority": {
1125
+
"type": "policy",
1126
+
"approver": null,
1127
+
"policy_reference": "POLICY-SECRET-ROTATION-90D",
1128
+
"chain": [],
1129
+
"escalation_reason": null
1130
+
},
1131
+
"execution": {
1132
+
"tool_calls": [
1133
+
{
1134
+
"tool": "vault_rotate",
1135
+
"arguments": {
1136
+
"secret": "db/prod/credentials",
1137
+
"ttl": "90d"
1138
+
},
1139
+
"result": {
1140
+
"rotated": true,
1141
+
"version": 7
1142
+
},
1143
+
"success": true,
1144
+
"duration_ms": 320,
1145
+
"error": null
1146
+
}
1147
+
],
1148
+
"duration_ms": 320,
1149
+
"resources_used": {
1150
+
"api_calls": 2
1151
+
}
1152
+
},
1153
+
"outcome": {
1154
+
"status": "success",
1155
+
"result": {
1156
+
"secret_path": "db/prod/credentials",
1157
+
"new_version": 7
1158
+
},
1159
+
"summary": "Rotated database credentials, version 7",
1160
+
"error": null,
1161
+
"side_effects": [
1162
+
"Old credentials revoked after 5m grace period"
1163
+
],
1164
+
"metrics": {}
1165
+
}
1166
+
},
1167
+
"canonical_json": "{\"authority\":{\"approver\":null,\"chain\":[],\"escalation_reason\":null,\"policy_reference\":\"POLICY-SECRET-ROTATION-90D\",\"type\":\"policy\"},\"context\":{\"agent_id\":\"vault-agent\",\"environment\":{\"region\":\"us-east-1\",\"vault_backend\":\"hashicorp\"},\"session_id\":null},\"domain\":\"secrets\",\"execution\":{\"duration_ms\":320,\"resources_used\":{\"api_calls\":2},\"tool_calls\":[{\"arguments\":{\"secret\":\"db/prod/credentials\",\"ttl\":\"90d\"},\"duration_ms\":320,\"error\":null,\"result\":{\"rotated\":true,\"version\":7},\"success\":true,\"tool\":\"vault_rotate\"}]},\"id\":\"d6e7f8a9-b0c1-2345-defa-456789abcdef\",\"outcome\":{\"error\":null,\"metrics\":{},\"result\":{\"new_version\":7,\"secret_path\":\"db/prod/credentials\"},\"side_effects\":[\"Old credentials revoked after 5m grace period\"],\"status\":\"success\",\"summary\":\"Rotated database credentials, version 7\"},\"parent_id\":null,\"previous_hash\":null,\"reasoning\":{\"analysis\":\"\",\"confidence\":0.0,\"model\":null,\"options\":[],\"options_considered\":[],\"prompt_hash\":null,\"reasoning\":\"\",\"selected_option\":\"\"},\"sequence\":0,\"trigger\":{\"correlation_id\":null,\"request\":\"Rotate database credentials for production\",\"source\":\"secret_rotator\",\"timestamp\":\"2026-01-15T12:00:00+00:00\",\"type\":\"scheduled\",\"user_id\":null},\"type\":\"vault\"}",
0 commit comments