Skip to content

Commit e84d571

Browse files
author
Bruno Baumgartner
committed
Add evidence bundle export
1 parent a33368b commit e84d571

6 files changed

Lines changed: 884 additions & 1 deletion

File tree

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,6 @@ test-json-benchmark/
4949
# Benchmark output (already covered by output/ but listed explicitly)
5050
output/benchmark/
5151
output/json-benchmark/
52+
53+
# Evidence bundles (already covered by output/ but listed explicitly)
54+
output/bundles/

‎README.md‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# VSC — Versioned State Commit
22

3-
**v1.13 — JSON Event Benchmark**
3+
**v1.14 — Evidence Bundle Export**
44

55
Research prototype / proof-of-concept. Not production-ready.
66

@@ -180,6 +180,50 @@ npm run vsc -- benchmark:json large # 1000 states - extended test
180180

181181
---
182182

183+
## VSC v1.14 Evidence Bundle Export
184+
185+
VSC v1.14 adds **Evidence Bundle Export** — a CLI command that turns a verified VSC delta chain into a **portable evidence package** containing all proof artifacts.
186+
187+
```bash
188+
npm run vsc -- bundle output/vsc-chain-21A8390BFA3F-to-954BEB0FF3AA.json
189+
```
190+
191+
**What's included:**
192+
- Chain token (complete delta chain with all steps)
193+
- Base token (initial state snapshot)
194+
- Delta tokens (ordered state changes)
195+
- Chain report (human-readable summary)
196+
- SVG seals (visual proof representations)
197+
- Verification summary with expected hashes
198+
- Complete manifest
199+
- SHA-256 checksums for integrity
200+
201+
**Bundle structure:**
202+
```
203+
output/bundles/vsc-bundle-<BASE>-to-<LATEST>/
204+
├── README.md # Bundle guide
205+
├── manifest.json # Complete artifact inventory
206+
├── chain-token.json # The delta chain
207+
├── base-token.json # Base state
208+
├── verification-summary.json # Verification instructions
209+
├── checksums.sha256 # File integrity checksums
210+
├── delta-tokens/delta-*.json # Delta steps
211+
├── reports/chain-report.md # Human-readable report
212+
└── seals/*.svg # Visual seals
213+
```
214+
215+
**Use cases:**
216+
- **Partner sharing** — Send verifiable proof to collaborators
217+
- **Audit trail** — Create compliance evidence
218+
- **Research publication** — Package reproducible proof artifacts
219+
- **DigiEmu proof** — Export as proof artifact
220+
221+
**Note:** Bundles do not include heavy recovery chunk folders or restored state (these can be regenerated from the tokens).
222+
223+
→ [Full Evidence Bundle Export documentation](docs/vsc-v1-14-evidence-bundle-export.md)
224+
225+
---
226+
183227
## VSC v1.10 Static Showcase
184228

185229
VSC v1.10 adds a static showcase export. One command generates a portable `showcase/` folder with the SVG seals, demo metrics, verification summary, and gallery — no server required, opens in any browser.
@@ -263,6 +307,7 @@ npm run clean-manifest # remove stale manifest entries
263307
- [VSC v1.8 CLI](docs/vsc-v1-8-cli.md)
264308
- [VSC v1.9 One-command Demo](docs/vsc-v1-9-one-command-demo.md)
265309
- [VSC v1.10 Static Showcase](docs/vsc-v1-10-static-showcase.md)
310+
- [VSC v1.14 Evidence Bundle Export](docs/vsc-v1-14-evidence-bundle-export.md)
266311
- [VSC v1.13 JSON Event Benchmark](docs/vsc-v1-13-json-event-benchmark.md)
267312
- [VSC v1.12 Benchmark Mode](docs/vsc-v1-12-benchmark-mode.md)
268313
- [VSC v2 Architecture Notes](docs/vsc-v2-architecture-notes.md)

‎docs/vsc-v1-14-evidence-bundle-export.md‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
# VSC v1.14 — Evidence Bundle Export
2+
3+
**Version:** v1.14
4+
**Purpose:** Export complete, portable evidence packages for VSC delta chains
5+
**Status:** Research prototype / proof-of-concept
6+
7+
---
8+
9+
## Overview
10+
11+
VSC v1.14 adds **Evidence Bundle Export** — a CLI command that turns a verified VSC delta chain into a **portable evidence package** containing all proof artifacts:
12+
13+
- Chain token (complete delta chain)
14+
- Base token (initial state snapshot)
15+
- Delta tokens (ordered state changes)
16+
- Chain report (human-readable summary)
17+
- SVG seals (visual proof representations)
18+
- Verification summary
19+
- Complete manifest
20+
- SHA-256 checksums
21+
22+
These bundles can be **shared with partners, auditors, researchers**, or used as **DigiEmu proof artifacts**.
23+
24+
---
25+
26+
## Usage
27+
28+
### Basic Usage
29+
30+
```bash
31+
# Export bundle for a chain token
32+
npm run vsc -- bundle output/vsc-chain-21A8390BFA3F-to-954BEB0FF3AA.json
33+
34+
# Alternative: direct script
35+
npm run bundle output/vsc-chain-21A8390BFA3F-to-954BEB0FF3AA.json
36+
37+
# Or use Node directly
38+
node scripts/exportEvidenceBundle.js output/vsc-chain-21A8390BFA3F-to-954BEB0FF3AA.json
39+
```
40+
41+
### Output
42+
43+
Bundle is created in `output/bundles/vsc-bundle-<BASE>-to-<LATEST>/`:
44+
45+
```
46+
output/bundles/vsc-bundle-21A8390BFA3F-to-954BEB0FF3AA/
47+
├── README.md # Human-readable bundle guide
48+
├── manifest.json # Complete artifact inventory
49+
├── chain-token.json # The delta chain token
50+
├── base-token.json # Base state recovery token
51+
├── verification-summary.json # Verification status & instructions
52+
├── checksums.sha256 # SHA-256 checksums for all files
53+
├── delta-tokens/
54+
│ ├── delta-1.json # First delta step
55+
│ └── delta-2.json # Second delta step
56+
├── reports/
57+
│ └── chain-report.md # Human-readable chain report
58+
└── seals/
59+
├── base.svg # Base state seal
60+
├── delta-1.svg # First delta seal
61+
├── delta-2.svg # Second delta seal
62+
└── chain.svg # Chain seal
63+
```
64+
65+
---
66+
67+
## Bundle Structure
68+
69+
### Core Tokens
70+
71+
| File | Description |
72+
|------|-------------|
73+
| `chain-token.json` | Complete delta chain with all steps, proofs, and hashes |
74+
| `base-token.json` | Initial state snapshot (content hash, root hash, recovery manifest) |
75+
| `delta-tokens/delta-*.json` | Ordered delta steps (1.json, 2.json, etc.) |
76+
77+
### Documentation
78+
79+
| File | Description |
80+
|------|-------------|
81+
| `README.md` | Bundle guide: inspection, verification, reproduction steps |
82+
| `reports/chain-report.md` | Human-readable storage/timing report (if available) |
83+
| `manifest.json` | Machine-readable inventory of all artifacts |
84+
| `verification-summary.json` | Verification status, expected hashes, instructions |
85+
86+
### Verification
87+
88+
| File | Description |
89+
|------|-------------|
90+
| `checksums.sha256` | SHA-256 checksums for all included files |
91+
| `seals/*.svg` | Visual proof seals (base, deltas, chain) |
92+
93+
---
94+
95+
## Verification
96+
97+
### Automatic Checksums
98+
99+
Verify file integrity:
100+
101+
```bash
102+
cd output/bundles/vsc-bundle-21A8390BFA3F-to-954BEB0FF3AA
103+
sha256sum -c checksums.sha256
104+
```
105+
106+
### Manual Chain Verification
107+
108+
Restore and verify the chain:
109+
110+
```bash
111+
# 1. Restore latest state
112+
npm run vsc -- restore chain-token.json
113+
114+
# 2. Verify root hash match
115+
npm run vsc -- verify chain-token.json output/chain-21A8390BFA3F-to-954BEB0FF3AA/restored-test-wp
116+
```
117+
118+
Expected result: **Root hash match: YES**
119+
120+
---
121+
122+
## Manifest Format
123+
124+
The `manifest.json` provides machine-readable bundle metadata:
125+
126+
```json
127+
{
128+
"bundle_name": "vsc-bundle-21A8390BFA3F-to-954BEB0FF3AA",
129+
"bundle_version": "1.0",
130+
"created_at": "2026-06-16T00:00:00.000Z",
131+
"vsc_version": "v1.14",
132+
"chain": {
133+
"token_id": "vsc-chain-21A8390BFA3F-to-954BEB0FF3AA",
134+
"base_token_id": "21A8390BFA3F",
135+
"latest_token_id": "954BEB0FF3AA",
136+
"delta_count": 2,
137+
"chain_hash_prefix": "a1b2c3d4e5f6..."
138+
},
139+
"base": {
140+
"token_id": "21A8390BFA3F",
141+
"bundle_file": "base-token.json"
142+
},
143+
"deltas": [
144+
{ "index": 1, "token_id": "F3876A4BCFE1", "bundle_file": "delta-tokens/delta-1.json" }
145+
],
146+
"seals": [
147+
{ "type": "base", "token_id": "21A8390BFA3F", "bundle_file": "seals/base.svg" }
148+
],
149+
"warnings": [],
150+
"limitations": [
151+
"Recovery chunks not included (can be regenerated)",
152+
"Research prototype — not enterprise software"
153+
]
154+
}
155+
```
156+
157+
---
158+
159+
## What's Included vs Excluded
160+
161+
### Included
162+
163+
- ✅ Chain token (complete delta chain)
164+
- ✅ Base token (initial state)
165+
- ✅ Delta tokens (ordered steps)
166+
- ✅ Chain report (if available)
167+
- ✅ SVG seals (base, deltas, chain)
168+
- ✅ Verification summary
169+
- ✅ Complete manifest
170+
- ✅ SHA-256 checksums
171+
172+
### Excluded (by design)
173+
174+
- ❌ Recovery chunk folders (`output/recovery-*`) — can be regenerated from tokens
175+
- ❌ Restored state folders (`output/chain-*/restored-*`) — can be regenerated via restore
176+
- ❌ Benchmark fixture folders (`test-benchmark/`, `test-json-benchmark/`)
177+
- ❌ Heavy binary files (PDFs, unless explicitly lightweight)
178+
- ❌ `node_modules/`
179+
- ❌ Source code
180+
181+
---
182+
183+
## Safety & Limitations
184+
185+
### Research Prototype
186+
187+
This is **research prototype software**, not enterprise production infrastructure:
188+
189+
- No streaming ingestion (v2 roadmap)
190+
- No WAL (v2 roadmap)
191+
- No Go implementation (future)
192+
- No API server
193+
- No enterprise guarantees
194+
195+
### Bundle Limitations
196+
197+
| Aspect | Limitation |
198+
|--------|------------|
199+
| Recovery | Chunk folders must be regenerated from tokens |
200+
| Restore | State must be restored manually for verification |
201+
| Size | Very large chains may require significant disk space |
202+
| Verify | Manual verification required for full proof |
203+
204+
### Security Notes
205+
206+
- Checksums verify file integrity, not authenticity
207+
- Verify the source of the bundle independently
208+
- For high-stakes proof, run your own verification
209+
- Checksums can be recomputed: `sha256sum -c checksums.sha256`
210+
211+
---
212+
213+
## Use Cases
214+
215+
### Partner Sharing
216+
217+
Share a verified state change with a partner:
218+
219+
```bash
220+
npm run vsc -- bundle output/vsc-chain-ABC123-to-DEF456.json
221+
tar czf proof-bundle.tar.gz output/bundles/vsc-bundle-ABC123-to-DEF456/
222+
# Send proof-bundle.tar.gz to partner
223+
```
224+
225+
### Audit Trail
226+
227+
Create verifiable evidence for compliance:
228+
229+
```bash
230+
# After each significant state change
231+
npm run vsc -- bundle output/vsc-chain-$(date +%Y%m%d)-*.json
232+
# Store bundle in audit archive
233+
```
234+
235+
### Research & Publication
236+
237+
Package reproducible proof artifacts:
238+
239+
```bash
240+
npm run vsc -- bundle output/vsc-chain-EXPERIMENT-*.json
241+
cp -r output/bundles/vsc-bundle-EXPERIMENT-* ./paper/artifacts/
242+
```
243+
244+
---
245+
246+
## Reproduction
247+
248+
To reproduce a bundle from scratch:
249+
250+
```bash
251+
# 1. Create base snapshot
252+
npm run vsc -- backup test-wp
253+
254+
# 2. Create deltas
255+
npm run vsc -- delta output/vsc-21A8390BFA3F-folder-recovery.json test-wp-v2
256+
257+
# 3. Build chain
258+
npm run vsc -- chain output/vsc-21A8390BFA3F-folder-recovery.json output/vsc-21A8390BFA3F-to-*.json
259+
260+
# 4. Export bundle
261+
npm run vsc -- bundle output/vsc-chain-21A8390BFA3F-to-*.json
262+
```
263+
264+
---
265+
266+
## Related Documentation
267+
268+
- [VSC v1.13 JSON Event Benchmark](vsc-v1-13-json-event-benchmark.md) — Structured event log benchmark
269+
- [VSC v1.12 Benchmark Mode](vsc-v1-12-benchmark-mode.md) — Folder/file benchmark
270+
- [VSC v2 Architecture Notes](vsc-v2-architecture-notes.md) — Future design
271+
- [WordPress MVP Demo](wordpress-mvp-demo.md) — Stable public demo
272+
273+
---
274+
275+
*VSC v1.14 — Portable proof for verifiable state commitments*

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
"pages": "npm run vsc -- showcase",
3131
"benchmark": "node scripts/runBenchmark.js",
3232
"json-benchmark": "node scripts/runJsonEventBenchmark.js",
33+
"bundle": "node scripts/exportEvidenceBundle.js",
3334
"vsc": "node src/vscCli.js"
3435
}
3536
}

0 commit comments

Comments
 (0)