panproto: Developer Guide
Architecture, Internals, and Contributor Handbook
Preface
This guide is nearly fully LLM-generated. Proceed with caution. We appreciate bug reports.
This is the panproto developer guide. It documents crate architecture, algebraic internals, and contributor workflow for the panproto schematic version control system. We assume familiarity with Rust (ownership, traits, generics, Result-based error handling; Edition 2024) and basic algebraic thinking (sorts, operations, equations). If the algebraic vocabulary is new to you, the tutorial’s formal foundations appendix provides the necessary background.
Crate map
| Level | Crates | Role |
|---|---|---|
| 0 | panproto-gat |
The GAT engine: theories, structure-preserving maps, theory merges |
| 1 | panproto-schema, panproto-inst |
Schema graphs and instance trees |
| 2 | panproto-mig, panproto-lens, panproto-check |
Migration compilation, lenses, breaking-change analysis |
| 3 | panproto-protocols |
Protocol definitions and schema-level presentation |
| 3.5 | panproto-io |
Instance-level presentation: format-specific parse/emit |
| 4 | panproto-core, panproto-wasm, panproto-cli |
Re-export facade, WASM boundary, CLI |
Each level depends only on the levels below it. panproto-gat has no panproto dependencies. panproto-core re-exports everything.
Reading paths
Contributors landing a fix or feature: start with Chapters 1 and 2, then Chapter 3 (building the project), then Chapters 16 through 18 (the PR workflow).
Protocol authors adding a new schema language: read Chapter 5 (architecture overview), Chapter 6 (the GAT engine), then Chapter 12 (protocols).
Researchers exploring the internals: read Chapters 5 and 6 sequentially, then 18 Advanced Internals: Building Blocks, Naming, Auto-Morphisms, and Type Checking, then 19 Protolens Engine and 20 Automated Lens Generation Pipeline.
Links
- Tutorial: https://panproto.dev/tutorial/
- Repository: https://github.com/panproto/panproto
- Rustdoc: generated from
cargo doc --workspace --no-deps
Conventions
Inline code like panproto-gat refers to a crate name. File paths like crates/panproto-gat/src/theory.rs are relative to the repository root. Shell commands assume a Unix-like environment (macOS or Linux).
Aaron Steven White