Skip to content

Commit 1bed6c0

Browse files
RiverbraidRiverbraid
committed
docs: add evidence packet generator design
1 parent bcae1a6 commit 1bed6c0

1 file changed

Lines changed: 140 additions & 0 deletions

File tree

‎docs/EVIDENCE_PACKET_GENERATOR.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Evidence Packet Generator Design
2+
3+
**Status**: DRAFT / DESIGN ONLY
4+
**Scope**: standardized Riverbraid evidence packet generation
5+
**Implementation status**: NOT_IMPLEMENTED
6+
**Cryptographic signing status**: DESIGN_ONLY / NOT_CLAIMED
7+
8+
## Executive summary
9+
10+
The Evidence Packet Generator is a proposed Riverbraid component for standardizing the output of verification processes.
11+
12+
Evidence packets are intended to become portable, machine-readable records of:
13+
14+
- repository state
15+
- commit under test
16+
- verifier command
17+
- verification result
18+
- limitations
19+
- non-claims
20+
- optional cryptographic proof material
21+
22+
This document describes a target design. It does not claim the generator exists today.
23+
24+
## Core principles
25+
26+
- **Standardization**: evidence packets should follow a versioned schema.
27+
- **Verifiability**: packets should contain enough information to inspect and reproduce the verification path.
28+
- **Completeness**: packets should record command, commit, result, environment, and non-claims.
29+
- **Extensibility**: schema should allow future evidence types.
30+
- **Machine-readability**: packets should be parseable by CLI, dashboards, and auditors.
31+
- **Claim-boundedness**: packets must not imply certification, external audit, production readiness, or registry inclusion unless separately evidenced.
32+
33+
## Packet structure
34+
35+
Each evidence packet should be a JSON document.
36+
37+
Required top-level fields:
38+
39+
| Field | Type | Description |
40+
|---|---|---|
41+
| `schema_version` | string | Evidence packet schema version. |
42+
| `timestamp` | string | UTC timestamp when the packet was generated. |
43+
| `repository_id` | string | Repository identifier. |
44+
| `commit_sha` | string | Exact commit verified. |
45+
| `ring` | integer or null | Riverbraid ring level if applicable. |
46+
| `petal` | string or null | Petal name if applicable. |
47+
| `invariant` | string | Invariant or boundary under test. |
48+
| `status` | string | `VERIFIED`, `FAILED`, `PARTIAL`, or `ERROR`. |
49+
| `verification_details` | object | Tool, version, command, and individual results. |
50+
| `non_claims` | array | Explicit non-claims for this packet. |
51+
| `known_limitations` | array | Current limitations of the evidence. |
52+
53+
Optional top-level fields:
54+
55+
| Field | Type | Description |
56+
|---|---|---|
57+
| `cryptographic_proofs` | object | Hashes, Merkle root, or signature material if implemented. |
58+
| `metadata` | object | Environment, actor, workflow run, or other context. |
59+
| `source_artifacts` | array | Files, workflow runs, or logs used to generate packet. |
60+
61+
## Example packet skeleton
62+
63+
```json
64+
{
65+
"schema_version": "riverbraid.evidence.v1.0.0",
66+
"timestamp": "2026-06-14T12:34:56Z",
67+
"repository_id": "Riverbraid__Riverbraid-Core",
68+
"commit_sha": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4",
69+
"ring": 0,
70+
"petal": "Core",
71+
"invariant": "CLUSTER_STATIONARY",
72+
"status": "VERIFIED",
73+
"verification_details": {
74+
"tool": "cluster-verify.mjs",
75+
"version": "1.0.0",
76+
"command": "npm test",
77+
"results": [
78+
{
79+
"check": "local_remote_aligned",
80+
"pass": true,
81+
"message": "Local and remote main branches are aligned."
82+
}
83+
]
84+
},
85+
"cryptographic_proofs": {
86+
"status": "NOT_IMPLEMENTED_IN_THIS_DESIGN_DOC"
87+
},
88+
"non_claims": [
89+
"not a certification",
90+
"not an external audit",
91+
"not a production readiness claim"
92+
],
93+
"known_limitations": [],
94+
"metadata": {}
95+
}
96+
```
97+
98+
## Generation process
99+
100+
Target process:
101+
102+
1. Collect repository path, commit SHA, verifier command, and config.
103+
2. Ensure the verifier runs against the declared commit.
104+
3. Execute verifier or ingest already-preserved verifier output.
105+
4. Aggregate stdout, stderr, exit code, and result status.
106+
5. Record non-claims and known limitations.
107+
6. Optionally hash relevant files and outputs.
108+
7. Optionally sign the packet if a key procedure exists.
109+
8. Write the final JSON packet to a deterministic output path.
110+
111+
## Integration with RB-CLI
112+
113+
Target command:
114+
115+
```text
116+
rb evidence generate
117+
```
118+
119+
Additional commands:
120+
121+
```text
122+
rb evidence validate <path>
123+
rb evidence publish <path>
124+
```
125+
126+
## Cryptographic proof boundary
127+
128+
Merkle roots and digital signatures are future design targets.
129+
130+
They must not be claimed until:
131+
132+
- the signing process exists
133+
- keys are managed under a defined procedure
134+
- unsigned fields are clearly excluded from signature calculation
135+
- verification command is documented
136+
- negative verification examples exist
137+
138+
## Non-claim
139+
140+
This document does not create an evidence packet generator, a signing procedure, or cryptographic evidence. It defines a target packet shape and generation process.

0 commit comments

Comments
 (0)