# Prikk
[](LICENSE)
[](https://crates.io/crates/prikk)
[](https://docs.rs/prikk)
[](https://deps.rs/crate/prikk)
[](https://crates.io/crates/prikk-crypto)
[](https://docs.rs/prikk-crypto)
[](https://deps.rs/crate/prikk-crypto)
[](https://crates.io/crates/prikk-error)
[](https://docs.rs/prikk-error)
[](https://deps.rs/crate/prikk-error)
[](https://crates.io/crates/prikk-hash)
[](https://docs.rs/prikk-hash)
[](https://deps.rs/crate/prikk-hash)
[](https://crates.io/crates/prikk-object)
[](https://docs.rs/prikk-object)
[](https://deps.rs/crate/prikk-object)
[](https://crates.io/crates/prikk-store)
[](https://docs.rs/prikk-store)
[](https://deps.rs/crate/prikk-store)
**A next-generation VCS built around block-oriented patch theory.**
## Overview
Prikk is an experimental distributed version control system focused on ease of use, safety,
resilience, flexibility, and long-term performance. The implementation follows the approved FDD
sequence: object identity and storage first, then WAL/ref durability, patch algebra, plugins, and
sync.
## Why / When
Use Prikk development builds when evaluating the architecture or contributing to the implementation.
Do not use Prikk for real project history yet.
## Quick Start
```sh
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo run -p prikk -- init ./sample-repo
# Author and publish a first commit (genesis) on a fresh repository:
export PRIKK_AUTHOR_KEY_ID="dev-author"
export PRIKK_AUTHOR_SEED="00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff"
echo "hello prikk" > ./sample-repo/readme.txt
(cd ./sample-repo && ../target/debug/prikk commit -m "genesis")
(cd ./sample-repo && ../target/debug/prikk seal --allow-no-audit)
cargo run -p prikk -- log ./sample-repo
cargo run -p prikk -- worktree-status ./sample-repo
cargo run -p prikk -- verify ./sample-repo
cargo run -p prikk -- doctor ./sample-repo
# If doctor reports only incomplete trailing WAL bytes:
# cargo run -p prikk -- doctor ./sample-repo --repair-wal-tail
# If doctor reports only a missing heads/main pointer recoverable from the ref log:
# cargo run -p prikk -- doctor ./sample-repo --repair-main-ref
```
`prikk commit` authors node-addressed worktree patches signed with a real role-bound Ed25519 AUTHOR
signature; key material is supplied via `PRIKK_AUTHOR_KEY_ID` / `PRIKK_AUTHOR_SEED` (a minimal key-input
mechanism, not a trust store). On a fresh repository the first commit is a **genesis** commit (all files
authored as `CreateFile`); the first `seal` publishes a Root block on `heads/main`.
## Design Notes
Current implementation drop: **0.3.0** (DC-10 — rollback-draft identity and AUTHOR signing).
Implemented:
- Rust workspace scaffold.
- Deterministic canonical object identity seed.
- Object envelopes with signatures outside identity.
- Persistent `.prikk/` layout and object store.
- Active-session WAL append/replay for signed patch envelopes.
- Read-only repository verification for objects, block references, sealed rollback Patch classification, ref pointers, ref logs, and active WAL.
- `doctor` diagnostics layered on top of verification, with opt-in safe WAL tail and missing-ref-pointer repair.
- Read-only sealed-history inspection from the current RefState chain, including rollback block labels.
- Snapshot-manifest validation, path-safety checks, opt-in snapshot materialization, and read-only worktree status.
- Initial RefState publication primitives with flat hashed ref pointer paths.
- Node-addressed worktree patch authoring (`prikk commit`): against a published `heads/main` baseline reconstructed from authoritative replay — or, on a fresh repository, a **genesis** first commit against an empty baseline (all files authored as `CreateFile`) — worktree changes are authored as node-addressed §9.3 operations (`CreateFile`, `DeleteNode`, `EditText`, `ReplaceBinary`, `ChangePerm`) with CSPRNG-minted node identities in canonical order, normalized file modes, and shared text-span identity. Existing-node kind is authoritative; rename inference, symlink authoring, and text↔binary transitions are out of scope.
- **Role-bound Ed25519 AUTHOR signing** for production Patch authoring paths: worktree commits and rollback drafts sign through an injected `AuthorSigner`; the production `Ed25519AuthorSigner` produces a real Ed25519 signature over the role-bound preimage (`Ed25519, Patch, unsigned-patch-id, Author, key_id`). Key material is supplied via `PRIKK_AUTHOR_KEY_ID` / `PRIKK_AUTHOR_SEED` (a minimal key-input mechanism, not a trust store).
- Local no-audit seal scaffold that persists WAL patches, creates a Block, and advances `heads/main`.
- Supported patch replay planning/materialization for `CreateFile`/`DeleteNode`, with full-file `EditText` and node-addressed record reconciliation for the remaining §9.3 kinds.
- Explicit deletion planning and opt-in deletion of patch-removed files whose bytes still match the old blob.
- Read-only inverse planning, non-mutating rollback preview, rollback-draft append/verification, and sealed rollback block classification for the supported subset. Rollback-draft identity is recorded as `PatchPurpose::RollbackDraft`, not as a reserved AUTHOR key id.
Signing scope (interim): AUTHOR-role Patch signatures produced by production commands are real role-bound Ed25519 signatures. This does **not** yet imply trust-store enforcement, key management, MAINTAINER publication signing, or publication-grade repository trust.
Minimal CLI commands: `init`, `commit [--from-worktree] [--text-edits] -m`, `seal --allow-no-audit`, `status`, `log`, `checkout --plan-only`, `checkout --snapshot-plan`, `checkout --snapshot-materialize`, `checkout --patch-plan`, `checkout --patch-materialize`, `checkout --patch-delete-plan`, `checkout --patch-materialize-delete`, `inverse-plan`, `rollback-preview`, `rollback-draft --append-inverse`, `rollback-draft-verify`, `worktree-status`, `verify`, `doctor`, `doctor --repair-wal-tail`, `doctor --repair-main-ref`, and `--version`.
Not implemented yet:
- Rename detection, arbitrary text-span discovery/generation, rollback refs, rollback authorization, commutation, full patch algebra, and general destructive checkout pruning.
- Genesis first-commit onto non-default refs (this drop supports genesis on the default `heads/main` only).
- Publication-grade MAINTAINER signing, trust store, key management/rotation, and signature policy.
- Policy-aware audit/attestation publication through seal; plugin/audit execution.
- Remote sync.
## More Detail
Full documentation is kept under `docs/src` and is structured for mdBook.