# Provenance ledger — design & schema

Published in the project's GitHub repository — [`maneuver-calculus/maneuvercalculus.org`](https://github.com/maneuver-calculus/maneuvercalculus.org/tree/master/web/site/provenance) under `web/site/provenance/` — and mirrored on the live site at [`/provenance/`](https://maneuvercalculus.org/provenance/). This directory implements a commit–reveal scheme: work is hashed and anchored to third-party timestamps now; specific content is revealed later, selectively. Nothing here is a release commitment.

## Two layers

**Public layer** (in this repository, mirrored on the site):

```
provenance/ledger.csv                one row per snapshot entry
provenance/anchors/L####.root        hex root hash of the entry's manifest
provenance/anchors/L####.root.ots    OpenTimestamps proof for the root
```

**Private layer** (kept in a separate, private repository — never published):

```
private/L####/manifest.json           per-file path + sha256 + bytes
private/L####/records/NNNN.sha256      one "hash  relpath" record per file
private/L####/records/NNNN.sha256.ots  per-file OpenTimestamps proof
```

Why both: the **public root** is the visible commitment — anyone can verify that substantial work in an area was anchored as of a given date. The **private per-file records** are the selective-reveal mechanism — revealing one file requires publishing only that file, its record, and its `.ots`, without disclosing sibling filenames.

## Ledger schema (`ledger.csv`)

| column | meaning |
|---|---|
| `entry_id` | `L0001`, monotonic |
| `snapshot_utc` | ISO 8601 UTC of hashing |
| `area_ids` | roadmap area(s) the entry covers |
| `label_public` | sanitized thematic label (matches the roadmap) |
| `root_sha256` | sha256 of the entry's `manifest.json` |
| `file_count`, `total_bytes` | scale signal, no content leak |
| `anchor_type` | `ots` \| `pending` \| `none` |
| `anchor_ref` | path to the public `.ots` |
| `status` | area state: exploring / active / parked / published. Free metadata — not part of the hashed manifest. |
| `revealed_utc` | blank until revealed |
| `notes_public` | optional, public-safe |

## What this proves — and what it doesn't

- **Proves:** the exact bytes existed no later than the anchored time, independent of anyone's word.
- **Doesn't prove:** authorship — a hash carries no name — and, because nothing is disclosed, it creates no prior art or defensive publication.

## Verifying an anchor

```
# recompute a root from a revealed manifest and compare to the published L####.root
sha256sum private/L####/manifest.json

# verify the OpenTimestamps proof (calendar attestation now; Bitcoin confirmation accrues over time)
ots verify provenance/anchors/L####.root.ots
```

Durability is backed by closed-access Zenodo deposits under the project's concept DOI, so the record survives independent of any single machine.