panproto-vcs 0.6.0

Schematic version control for panproto — git-like VCS for schema evolution
Documentation

panproto-vcs

crates.io docs.rs

Schematic version control for panproto.

Schemas are content-addressed objects (blake3) stored in a commit DAG, with branches, three-way structural merge via categorical pushout, rename detection, and data lifting through history. The CLI binary is schema.

API

Item Description
Repository High-level porcelain: init, add, commit, merge, rebase, cherry-pick, reset, gc
FsStore Filesystem-backed object store (.panproto/ directory)
MemStore In-memory store for tests and WASM
Store Trait abstracting over storage backends
ObjectId Blake3 content-address (32 bytes)
Object Enum: Schema, Migration, Commit
CommitObject A point in the schema evolution DAG
HeadState Branch or detached HEAD
ReflogEntry Audit trail entry for ref mutations
Index Staging area for the next commit
MergeResult Three-way merge output with typed conflict detection
BisectState / BisectStep Binary search for breaking commits
BlameEntry Which commit introduced a schema element
GcReport Garbage collection results
GatDiagnostics Type errors, equation violations, and migration warnings from GAT validation
CommitOptions Commit configuration including skip_verify to bypass GAT equation checks

Modules

Module Description
hash Canonical serialization + blake3 content addressing
dag Merge base, path finding, log walk, compose path, compose_path_with_coherence
merge Three-way schema merge + conflict detection
refs Branches, tags, resolve_ref
auto_mig Derive Migration from SchemaDiff
rename_detect Structural similarity scoring for vertex/edge renames
rebase Replay commits onto a new base
cherry_pick Apply a single commit's migration
reset Soft/mixed/hard HEAD reset
stash Save/restore working state
bisect Binary search for breaking commit
blame Schema element attribution
gc Mark-sweep garbage collection
gat_validate GAT-level validation: type-checked migrations, theory equation verification, schema model checking
repo Repository orchestration (porcelain)

Safety

The VCS pipeline integrates GAT-level validation at two points:

  • On commit: auto-derived migrations are validated as well-formed theory morphisms via gat_validate::validate_migration. The protocol theory's equations are type-checked via gat_validate::validate_theory_equations, and the schema model is verified against those equations via gat_validate::validate_schema_equations. Pass skip_verify in CommitOptions to bypass these checks.
  • On merge: pullback-enhanced overlap detection uses panproto_gat::pullback to identify structural overlap between the two branch heads and the merge base. This produces fewer false conflicts than name-based matching alone, because two sorts or operations that share a common image under their protocol morphisms are recognized as the same element regardless of local naming.

The compose_path_with_coherence function composes a chain of migrations along a commit path and verifies that intermediate morphisms are coherent, returning both the composed migration and any coherence warnings.

Example

use panproto_vcs::Repository;

let mut repo = Repository::init(".").unwrap();

// Stage and commit a schema
repo.add(&schema).unwrap();
let id = repo.commit("initial schema", "alice").unwrap();

// Branch, evolve, merge
panproto_vcs::refs::create_branch(repo.store_mut(), "feature", id).unwrap();

License

MIT