notarius

The clerk that records and authenticates a tree. Create immutable, machine-verifiable manifests of any repository or directory, with an optional Zenodo reviewer bundle.

Generates:

• Per-file SHA-256 hashes
• File sizes
• Deterministic tree hash over the entire set
• Git commit + dirty flag (if inside a git repo)
• UTC timestamp (embedded in both the filename and the manifest body)
• Structured JSON (schema vdm.provenance.manifest.v1)

With --zenodo, also emits a five-file reviewer-facing bundle suitable for dropping straight into a Zenodo deposit.

---

Installation (one-time, global CLI)

This tool is designed to be installed once and used from anywhere on your system.

# Clone anywhere stable
git clone https://github.com/Neuroca-Inc/notarius.git
cd notarius

# Install globally via pipx (recommended — isolated, no system pollution)
pipx install -e .

# Add to PATH (run once)
pipx ensurepath

Important: Close and reopen your terminal (or run exec bash -l / source ~/.bashrc) so the new notarius command is visible.

build_provenance is kept as a second alias for the same entry point, so older scripts and habits keep working.

---

Usage

From any directory on your machine:

# Generate manifest only, in the current directory
notarius --target .

# Or point at any absolute/relative path
notarius --target /path/to/your/project
notarius --target ~/Downloads/my-dataset

# Generate manifest + full Zenodo reviewer bundle
notarius --target . --zenodo

# Manifest + bundle with a custom prefix applied to the manifest filename
# and referenced inside technical_info.txt
notarius --target . --zenodo --zenodo-prefix CF19

# Verbose progress
notarius --target . --verbose

# Full help
notarius --help

---

Manifest filename

Each run writes a timestamped manifest so successive runs never overwrite each other and so every deposit has a unique, sortable name.

• Plain: PROVENANCE_manifest_{YYYYMMDDHHMMSS}.json
• Prefixed: {PREFIX}_PROVENANCE_manifest_{YYYYMMDDHHMMSS}.json

The timestamp is UTC and is identical to the generated_utc field inside the manifest body — filename and content cannot drift. Any prior manifest matching either pattern is automatically excluded from future scans.

---

Output

After execution you will see a summary on stdout:

{
  "manifest": "/path/to/CF19_PROVENANCE_manifest_20260416151530.json",
  "files": 1427,
  "bytes": 8743921
}

When --zenodo is passed, the summary also includes a "zenodo" map listing every reviewer file written.

The manifest is created inside the target folder (never elsewhere).

When --zenodo is passed, the following reviewer-facing files are also written next to the manifest (and excluded from the hash set, so re-runs stay idempotent):

• technical_info.txt — points reviewers at the companion {prefix}_FULL_PACKAGE.zip
• review_notes.txt — falsification invitation and reviewer observability note
• table_of_contents.txt — tree-formatted listing of the target directory
• how_to_contribute.txt — links and ways to contribute or push back
• LICENSE.md — the Neuroca Proprietary Dual License (v2.1)

---

Command-line Options

Flag	Description	Default
--target ROOT	Directory to scan	.
--exclude PATH	Extra path prefix to exclude (repeatable)	(none)
--zenodo	Also emit the 5-file Zenodo reviewer bundle	off
--zenodo-prefix STR	Prefix applied to the manifest filename and referenced in technical_info.txt (e.g. CF19 → CF19_FULL_PACKAGE.zip)	(plain filename; bundle uses target dir name)
--verbose	Show progress on stderr	false

---

Features & Guarantees

• Deterministic content: Same input directory → identical tree hash (canonical ordering).
• Unique filenames: UTC timestamp embedded in the filename prevents accidental overwrites.
• Filename ↔ content locked: The timestamp in the filename is the same instant as generated_utc in the JSON.
• Git-aware: Uses git ls-files when possible (respects .gitignore automatically).
• Self-healing re-runs: Prior manifests matching either naming shape are auto-excluded.
• No external services: Pure stdlib; no network calls.
• Independent timestamping: After generation, submit the manifest to a TSA (RFC3161) or OpenTimestamps for independent time receipts.

---

For Developers / Contributors

1. Clone the repo.
2. Make changes in src/notarius/cli.py or src/notarius/zenodo.py.
3. Test with pipx install -e . (changes take effect immediately).
4. Bump version in pyproject.toml before releasing.

Pull requests welcome for bug fixes, additional excludes, or platform improvements.

---

License Neuroca Proprietary Dual License (Academic + Commercial) v2.1 — see LICENSE.md.

Copyright © 2025 Justin K. Lietz, Neuroca, Inc.