VSC — Versioned State Commit

v1.17 — ZIP Bundle Export

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

License: VSC Core is licensed under the Apache License 2.0. The names DigiEmu and VSC, logos, and project branding are not granted as trademarks.

Core Concept

VSC is a base + delta + proof + recovery model for folder and file state:

T = (B, Δ, P, R)

B = base snapshot     — full state, chunked and root-hashed
Δ = ordered deltas    — only the files that changed
P = proof             — root hash / chain hash for verification
R = recovery          — rules for reconstructing state from base + deltas

Store a full state once. Store only what changes. Verify by root hash. Restore from base + ordered deltas.

WordPress MVP Demo

A WordPress-style folder was backed up once (1.58 MB base), then two later changes were captured as ordered deltas (641 B total). The latest state was reconstructed and verified.

Strategy	Storage
Traditional full-copy (3×)	4.75 MB
VSC (base + 2 deltas)	1.58 MB
Saved	3.17 MB (66.65%)

verify-all result: PASS: 3 / PROOF-ONLY: 12 / FAIL: 0

→ Full demo details

Visual Token Language

VSC tokens are rendered as SVG seals. Each token type has a distinct visual identity:

Token	Core symbol	Reading
FOLDER	`⊞ BASE SNAPSHOT`	Stable complete state
DELTA	`Δ CHANGED FILES`	Changed subset, BASE → TARGET
CHAIN	`N DELTA STEPS`	Ordered progression, latest verified
RECOVERY	`▣ RECOVERABLE`	Dense chunked payload
PROOF	`◌ SPARSE PROOF`	Lightweight deterministic proof

→ Full visual grammar

Current Status

What works:

Folder base snapshots, restore, verification
Folder deltas (file-level add / modify / delete)
Delta-on-delta and delta chains
Chain restore and chain verification
Chain storage report
Static token gallery with SVG seal previews
verify-all batch verification

Not yet built:

API layer
Distributed object storage
Authentication / tenant model
Production hardening

CLI Commands

# Encode folder base
npm run encode-folder <folder>

# Encode folder delta
npm run encode-folder-delta <base-token.json> <folder>

# Build delta chain
npm run create-chain <base.json> <delta1.json> [delta2.json ...]

# Restore latest state from chain
npm run restore-chain <chain.json>

# Verify restored state
npm run verify-chain <chain.json> <restored-folder>

# Storage report
npm run report-chain <chain.json>

# Verify all tokens
npm run verify-all

# Clean manifest
npm run clean-manifest

# Open gallery
start output\gallery.html

VSC v1.11 GitHub Pages Showcase

The static showcase is publicly deployed via GitHub Pages:

https://digiemu.github.io/vsc-core/

Only showcase/ is published. No recovery chunks, test fixtures, or heavy output folders are deployed. The deployment is triggered automatically on every push to main.

→ Publishing documentation

VSC v1.12 Benchmark Mode

VSC v1.12 adds Benchmark Mode — reproducible measurement of storage-load reduction and restore/verify performance.

npm run vsc -- benchmark        # default: medium profile (100 states)
npm run vsc -- benchmark small  # 10 states - fast smoke test
npm run vsc -- benchmark large  # 1000 states - extended test

What it measures:

Storage comparison: VSC base+delta vs traditional full-copy storage
Timing: Base snapshot, delta generation, chain creation, restore, verify
Verification: Restore integrity and root-hash verification pass/fail

Sample output:

Total chain reduction: 90-98% (profile-dependent)
Saved bytes: ~2-5 MB for medium fixture
Restore time: ~500-1500ms
Verify time: ~200-500ms

Benchmark Mode makes VSC's storage-load reduction claims measurable and reproducible without introducing unbenchmarked enterprise claims.

Note: Benchmark output is written to output/benchmark/ and is separate from the public showcase. The showcase (npm run vsc -- showcase) uses the stable WordPress-style demo, not benchmark artifacts.

→ Full benchmark documentation
→ VSC v2 Architecture Notes

VSC v1.13 JSON Event Benchmark

VSC v1.13 adds JSON Event Benchmark — extending storage-load reduction measurement to structured AI decision event logs represented as deterministic JSON.

npm run vsc -- benchmark:json        # default: medium profile (100 states)
npm run vsc -- benchmark:json small  # 10 states - fast smoke test
npm run vsc -- benchmark:json large  # 1000 states - extended test

Event Model:

Primary unit of proof: Individual Event (prompt/response, tool call, policy check, retrieval, final decision)
Deterministic JSON with canonical key ordering
Accumulating event log: each state contains all events from 0 to N
Events include: event_id, sequence, timestamp, event_type, actor, model, input_hash, output_hash, policy_result, tool_calls, metadata

What it measures:

Storage efficiency for growing AI event logs
VSC delta encoding performance on structured JSON
Restore and verify timing for event state chains

Note: This benchmark models AI-style events but uses synthetic deterministic data. It is a bridge toward future AI evidence logging, not a claim of enterprise-ready AI log infrastructure.

Separation: JSON Event Benchmark output is written to output/json-benchmark/ and is separate from both the public showcase and the v1.12 folder benchmark.

Gallery: The public showcase gallery uses an allowlist approach and does not include benchmark or JSON benchmark generated SVGs, keeping the GitHub Pages gallery deterministic and lightweight.

→ Full JSON Event Benchmark documentation

VSC v1.14 Evidence Bundle Export

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.

npm run vsc -- bundle output/vsc-chain-21A8390BFA3F-to-954BEB0FF3AA.json

What's included:

Chain token (complete delta chain with all steps)
Base token (initial state snapshot)
Delta tokens (ordered state changes)
Chain report (human-readable summary)
SVG seals (visual proof representations)
Verification summary with expected hashes
Complete manifest
SHA-256 checksums for integrity

Bundle structure:

output/bundles/vsc-bundle-<BASE>-to-<LATEST>/
├── README.md                    # Bundle guide
├── manifest.json                # Complete artifact inventory
├── chain-token.json             # The delta chain
├── base-token.json              # Base state
├── verification-summary.json    # Verification instructions
├── checksums.sha256            # File integrity checksums
├── delta-tokens/delta-*.json   # Delta steps
├── reports/chain-report.md     # Human-readable report
└── seals/*.svg                 # Visual seals

Use cases:

Partner sharing — Send verifiable proof to collaborators
Audit trail — Create compliance evidence
Research publication — Package reproducible proof artifacts
DigiEmu proof — Export as proof artifact

Note: Bundles do not include heavy recovery chunk folders or restored state (these can be regenerated from the tokens).

→ Full Evidence Bundle Export documentation

VSC v1.15 JSON Event Evidence Bundle

VSC v1.15 adds JSON Event Evidence Bundle Export — a specialized export mode that turns deterministic JSON AI event chains into portable evidence packages for audit, post-incident review, and DigiEmu verification workflows.

# Export bundle using latest JSON benchmark results
npm run vsc -- bundle:json

# Export with explicit chain token
npm run vsc -- bundle:json output/json-benchmark/vsc-chain-*.json

Prerequisites:

npm run vsc -- benchmark:json   # must run first to generate JSON benchmark data

What's included:

Event schema (event-schema.json) — Event structure definition
Event summary (event-summary.json) — Session statistics
JSON benchmark summary, report, and chart data
Chain token, base token, delta tokens
Verification summary with restore/verify status
Complete manifest and SHA-256 checksums

Bundle structure:

output/json-event-bundles/vsc-json-event-bundle-<BASE>-to-<LATEST>/
├── README.md                           # Bundle guide
├── manifest.json                       # Complete inventory
├── event-schema.json                   # Event structure
├── event-summary.json                  # Session statistics
├── json-benchmark-summary.json         # Benchmark metrics
├── json-benchmark-report.md            # Human report
├── json-benchmark-chart-data.json      # Chart data
├── chain-token.json                    # Delta chain
├── base-token.json                     # Base state
├── verification-summary.json           # Verification status
├── checksums.sha256                   # Checksums
└── delta-tokens/delta-*.json          # Delta steps

Event Model:

Primary unit of proof: Individual Event
Event types: prompt_response, tool_call, policy_check, retrieval, final_decision
Required fields: event_id, sequence, timestamp, event_type, actor, session_id, model, input_hash, output_hash, policy_result, tool_calls, metadata
Determinism: Synthetic deterministic data for reproducibility

Use cases:

Audit trail — AI decision event logging for compliance
Post-incident review — Capture decision timeline for investigation
Research publication — Reproducible AI event evidence
DigiEmu proof — Portable AI event proof artifact

Limitations:

Synthetic deterministic events — not real AI inference
Single-session model — not multi-session orchestration
Simulated tool calls — not actual execution
Research prototype — not enterprise production software

→ Full JSON Event Evidence Bundle documentation

VSC v1.16 Evidence Bundle Verification

VSC v1.16 adds Evidence Bundle Verification — a read-only verifier that checks whether an exported evidence bundle is complete, internally consistent, and unchanged according to its manifest and checksums.

# Verify a generic evidence bundle
npm run vsc -- verify-bundle output/bundles/vsc-bundle-<BASE>-to-<LATEST>

# Verify a JSON event evidence bundle
npm run vsc -- verify-bundle output/json-event-bundles/vsc-json-event-bundle-<BASE>-to-<LATEST>

What it verifies:

Required files — README.md, manifest.json, checksums.sha256, chain-token.json, base-token.json, verification-summary.json
Checksum integrity — Every file in checksums.sha256 exists and matches its hash
Manifest consistency — Manifest references match chain/base/delta token IDs
Chain token — Valid JSON, contains base/latest token IDs and steps
Base token — Exists and is valid JSON
Delta tokens — All deltas referenced by the chain exist in delta-tokens/
JSON event metadata — (for JSON event bundles) event-schema.json, event-summary.json, json-benchmark-summary.json are valid

Expected output:

VSC v1.16 — Evidence Bundle Verification
...
Manifest:        PASS
Checksums:       PASS (XX files verified)
Chain token:     PASS (BASE → LATEST)
Base token:      PASS
Delta tokens:    PASS (XX/XX found)
JSON event meta: PASS or N/A
Result:          PASS

Use cases:

Pre-sharing validation — Verify bundle integrity before sending to partners
Receipt verification — Confirm received bundle is unchanged
Audit compliance — Prove bundle completeness for compliance review
CI/CD integration — Automated bundle verification in pipelines

Note: This command is read-only. It never modifies the bundle (no manifest rewrite, no checksum update, no token mutation).

→ Full Evidence Bundle Verification documentation

VSC v1.17 ZIP Bundle Export

VSC v1.17 adds ZIP Bundle Export — a command to package an existing evidence bundle directory into a shareable ZIP archive.

npm run vsc -- zip-bundle output\json-event-bundles\vsc-json-event-bundle-408C8C13C4D4-to-ED9566562A13

What it does:

Creates a .zip file from the bundle folder
Outputs to output/zips/<bundle-name>.zip
Preserves the bundle directory structure inside the ZIP
Does not modify the source bundle

Expected output:

VSC v1.17 — ZIP Bundle Export
...
ZIP path:        output\zips\vsc-json-event-bundle-408C8C13C4D4-to-ED9566562A13.zip
Files included:  108
ZIP size:        245.6 KB
Result:          PASS

Use cases:

Email distribution — Share bundles as single-file attachments
Archive storage — Compress bundles for long-term storage
Distribution packaging — Prepare bundles for download/release

Note: The ZIP file is created in output/zips/ and is not committed to Git (see .gitignore).

→ Full ZIP Bundle Export documentation

VSC v1.10 Static Showcase

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.

npm run vsc -- demo:run   # run full proof flow first
npm run vsc -- showcase   # export showcase/

→ Full showcase documentation

VSC v1.9 One-command Demo

VSC v1.9 adds a complete reproducible demo command. One command runs the full WordPress-style base + delta + chain + restore + verify flow:

npm run vsc -- demo:run

No manual token ID replacement. No placeholder values. The runner discovers generated paths from the manifest and prints a final summary with DEMO RESULT: PASS.

→ Full demo documentation

VSC v1.8 CLI

VSC v1.8 introduces a simplified CLI wrapper. The old scripts remain available and unchanged.

npm run vsc -- help          # command overview
npm run vsc -- demo          # create demo fixture
npm run vsc -- backup test-wp
npm run vsc -- delta output\vsc-<BASE>-folder-recovery.json test-wp
npm run vsc -- chain <base> <delta1> <delta2>
npm run vsc -- restore output\vsc-chain-<BASE>-to-<D2>.json
npm run vsc -- verify  output\vsc-chain-<BASE>-to-<D2>.json output\chain-<BASE>-to-<D2>\restored-test-wp
npm run vsc -- report  output\vsc-chain-<BASE>-to-<D2>.json
npm run vsc -- verify-all
npm run vsc -- gallery

→ Full CLI documentation

Repository / Demo Notes

This repository is a research prototype / MVP. The following conventions apply:

Generated recovery chunk folders (output/recovery-*/) are excluded from git — they can be large and are always reproducible locally.
The test-wp/ fixture folder is excluded from git. Recreate it with npm run demo:fixture.
Token JSON and SVG files in output/ are lightweight and may be committed as reference artifacts.
See docs/demo-artifact-policy.md for the full artifact commit policy.
See docs/reproduce-wordpress-demo.md to reproduce the full demo from a clean clone.

npm run demo:fixture       # create or reset test-wp/ demo fixture
npm run encode-folder      # encode a folder as a base snapshot
npm run encode-folder-delta # encode a folder delta
npm run create-chain       # build a delta chain
npm run report-chain       # storage metrics report
npm run restore-chain      # restore latest state from chain
npm run verify-chain       # verify restored state
npm run verify-all         # verify all registered tokens
npm run clean-manifest     # remove stale manifest entries

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github/workflows		.github/workflows
docs		docs
examples/interop/tbn-vsc-bundle-001		examples/interop/tbn-vsc-bundle-001
scripts		scripts
showcase		showcase
src		src
.gitignore		.gitignore
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

VSC — Versioned State Commit

Core Concept

WordPress MVP Demo

Visual Token Language

Current Status

CLI Commands

VSC v1.11 GitHub Pages Showcase

VSC v1.12 Benchmark Mode

VSC v1.13 JSON Event Benchmark

VSC v1.14 Evidence Bundle Export

VSC v1.15 JSON Event Evidence Bundle

VSC v1.16 Evidence Bundle Verification

VSC v1.17 ZIP Bundle Export

VSC v1.10 Static Showcase

VSC v1.9 One-command Demo

VSC v1.8 CLI

Repository / Demo Notes

Documentation

About

Uh oh!

Releases 12

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

VSC — Versioned State Commit

Core Concept

WordPress MVP Demo

Visual Token Language

Current Status

CLI Commands

VSC v1.11 GitHub Pages Showcase

VSC v1.12 Benchmark Mode

VSC v1.13 JSON Event Benchmark

VSC v1.14 Evidence Bundle Export

VSC v1.15 JSON Event Evidence Bundle

VSC v1.16 Evidence Bundle Verification

VSC v1.17 ZIP Bundle Export

VSC v1.10 Static Showcase

VSC v1.9 One-command Demo

VSC v1.8 CLI

Repository / Demo Notes

Documentation

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages