# Source Code Map {#sec-source-code-map}
This appendix provides a complete directory-level index of the panproto repository. Use it to find the file responsible for a given concept.
## Workspace root
| Path | Description |
|---|---|
| `Cargo.toml` | Workspace definition, shared dependencies, lint config, profiles |
| `Cargo.lock` | Pinned dependency versions |
| `LICENSE` | MIT license |
| `README.md` | Project overview and quick-start |
| `dev-guide/` | This developer guide (Quarto book) |
| `sdk/` | Language SDKs |
| `tests/` | Integration tests and fixtures |
| `.github/` | CI/CD workflows and Dependabot config |
## crates/panproto-gat --- GAT engine
The algebraic core. Defines theories, morphisms, and colimits.
| File | Description |
|---|---|
| `src/lib.rs` | Public API re-exports |
| `src/theory.rs` | `Theory` struct: `new()`, `extending()`, `find_sort()`, `find_op()` |
| `src/sort.rs` | `Sort`, `SortParam` structs |
| `src/op.rs` | `Operation` struct: name, input sorts, output sort |
| `src/eq.rs` | `Equation`, `Term` types for stating algebraic laws |
| `src/morphism.rs` | `TheoryMorphism`, `check_morphism()` validation |
| `src/colimit.rs` | `colimit()` pushout computation over theory morphisms |
| `src/model.rs` | `Model`, `ModelValue`, `migrate_model()` |
| `src/schema_functor.rs` | `TheoryEndofunctor`, `TheoryTransform`, `TheoryConstraint`: theory endofunctors and subcategory predicates |
| `src/factorize.rs` | `factorize()`, `Factorization`, `validate_factorization()`: morphism decomposition into elementary steps |
| `src/error.rs` | `GatError` enum |
| `benches/gat_bench.rs` | divan benchmarks for colimit, morphism checking |
## crates/panproto-schema --- Schema representation
Typed hypergraph schemas and protocol definitions.
| File | Description |
|---|---|
| `src/lib.rs` | Public API re-exports |
| `src/schema.rs` | `Schema`, `Vertex`, `Edge`, `HyperEdge`, `Constraint` structs |
| `src/builder.rs` | `SchemaBuilder` for fluent schema construction |
| `src/protocol.rs` | `Protocol` trait, `EdgeRule` struct |
| `src/validate.rs` | `validate()` — check a schema against protocol rules |
| `src/normalize.rs` | `normalize()` — collapse reference chains and canonicalize |
| `src/error.rs` | `SchemaError` enum |
## crates/panproto-inst --- Instances (W-type and functor)
The data layer: instance representation, parsing, and validation.
| File | Description |
|---|---|
| `src/lib.rs` | Public API re-exports |
| `src/wtype.rs` | W-type instance: `anchor_surviving()`, `reachable_from_root()`, `ancestor_contraction()`, `resolve_edge()`, `reconstruct_fans()` |
| `src/fan.rs` | `Fan` struct |
| `src/functor.rs` | Functor instance representation and conversion |
| `src/value.rs` | `Value` enum (the leaf data carried by nodes) |
| `src/metadata.rs` | Instance metadata: timestamps, provenance |
| `src/parse.rs` | Parse raw data (JSON, MessagePack) into W-type instances |
| `src/validate.rs` | Validate an instance against its schema |
| `src/tree_edit.rs` | `TreeEdit` monoid: identity, compose, apply for W-type instances |
| `src/table_edit.rs` | `TableEdit` monoid: identity, compose, apply for functor instances |
| `src/edit_error.rs` | `EditError` enum for edit application failures |
| `src/reachability.rs` | `ReachabilityIndex`: incremental reachability tracking from root |
| `src/contraction.rs` | `ContractionTracker`, `ContractionRecord`: incremental ancestor contraction |
| `src/error.rs` | `InstError` enum |
| `tests/integration.rs` | Per-crate integration tests |
| `benches/inst_bench.rs` | divan benchmarks for W-type construction and restrict |
## crates/panproto-mig --- Migration engine
Compiles, executes, composes, and inverts migrations.
| File | Description |
|---|---|
| `src/lib.rs` | Public API re-exports |
| `src/migration.rs` | `Migration`, `CompiledMigration` structs |
| `src/compile.rs` | `compile()` — produce a compiled migration from a theory morphism diff |
| `src/existence.rs` | `existence_check()` — verify a migration can be applied to an instance |
| `src/lift.rs` | `lift()` — backward migration (target to source) |
| `src/compose.rs` | `compose()` — chain two migrations into one |
| `src/invert.rs` | `invert()` — reverse a migration (requires lens complement) |
| `src/error.rs` | `MigError` enum |
| `benches/mig_bench.rs` | divan benchmarks for compile, lift, compose |
## crates/panproto-lens --- Bidirectional lenses
Symmetric and asymmetric lenses with law checking.
| File | Description |
|---|---|
| `src/lib.rs` | Public API re-exports |
| `src/symmetric.rs` | Symmetric lens: `get`, `put`, complement storage |
| `src/asymmetric.rs` | Asymmetric lens: one-directional with state |
| `src/combinators.rs` | `compose()`, `product()`, `sum()`, `identity()` combinators |
| `src/compose.rs` | Lens composition internals |
| `src/protolens.rs` | `Protolens`, `ProtolensChain`, `ComplementConstructor`, `elementary::*`: schema-parameterized lens families |
| `src/complement_type.rs` | `ComplementSpec`, `DefaultRequirement`, `CapturedField`: dependent complement type evaluation |
| `src/auto_lens.rs` | `auto_generate()`, `AutoLensConfig`, `AutoLensResult`: automatic protolens generation pipeline |
| `src/diff_to_protolens.rs` | `diff_to_protolens()`, `diff_to_lens()`, `DiffSpec`: schema diff to protolens conversion |
| `src/laws.rs` | `check_get_put()`, `check_put_get()` law verification |
| `src/edit_lens.rs` | `EditLens`: incremental edit translation with stateful complement |
| `src/edit_error.rs` | `EditLensError` enum for edit lens failures |
| `src/edit_laws.rs` | `check_edit_consistency()`, `check_complement_coherence()` law verification |
| `src/edit_pipeline.rs` | `EditPipeline`: five-step incremental translation pipeline |
| `src/edit_provenance.rs` | `EditProvenance`: translation lineage tracking |
| `src/error.rs` | `LensError` enum |
## crates/panproto-lens-dsl --- Declarative lens DSL
Compiles Nickel, JSON, and YAML lens specifications to `ProtolensChain` + `FieldTransform`.
| File | Description |
|---|---|
| `contracts/lens.ncl` | Nickel contract library: `Lens`, `Step`, `Rule` contracts + combinator functions (bundled via `include_str!`) |
| `src/lib.rs` | Public API: `load()`, `load_dir()`, `compile()`, `load_and_compile()`, `LoadDirResult` |
| `src/document.rs` | Serde types: `LensDocument`, `Step` (19 variants), `Rule`, `ComposeSpec`, `AutoSpec`, coercion/passthrough enums |
| `src/eval.rs` | Nickel evaluation via `nickel-lang` 2.0 (`eval_deep_for_export` + `to_serde`), JSON/YAML pass-through |
| `src/steps.rs` | `compile_steps()`: maps steps to `combinators::*`, `elementary::*`, `FieldTransform`; includes `parse_term()` for equation terms |
| `src/rules.rs` | `compile_rules()`: rule expansion, `passthrough` via `KeepFields`, `map_attr_value` via `attr_value_op_to_expr` |
| `src/compose.rs` | `compile_compose()`: vertical (pipeline) and horizontal (fuse + `protolens_horizontal`) composition |
| `src/compile.rs` | `CompiledLens` output type, unified `compile()` dispatcher |
| `src/error.rs` | `LensDslError` with miette diagnostics |
## crates/panproto-check --- Breaking-change detection
Diff, classify, and report schema changes.
| File | Description |
|---|---|
| `src/lib.rs` | Public API re-exports |
| `src/diff.rs` | `diff()` — compute structural diff between two schemas |
| `src/classify.rs` | `classify()` — label each diff entry as breaking, compatible, or informational |
| `src/report.rs` | `Report` struct, human-readable and machine-readable output |
| `src/error.rs` | `CheckError` enum |
## crates/panproto-protocols --- Built-in protocols (schema-level presentations)
Protocol definitions and schema-level parse/emit for supported schema languages.
| File | Description |
|---|---|
| `src/lib.rs` | Public API, protocol registry |
| `src/theories.rs` | Shared base theories (e.g., the "typed graph" sub-theory) |
| `src/emit.rs` | Shared schema emission helpers |
| `src/annotation/` | Linguistic annotation formats (19 protocols) |
| `src/api/` | API specification formats (5 protocols) |
| `src/config/` | Configuration formats (4 protocols) |
| `src/data_schema/` | Data schema formats (7 protocols) |
| `src/data_science/` | Data science formats (3 protocols) |
| `src/database/` | Database schema formats (6 protocols) |
| `src/domain/` | Domain-specific formats (6 protocols) |
| `src/serialization/` | Serialization/IDL formats (8 protocols) |
| `src/type_system/` | Programming language type systems (8 protocols) |
| `src/web_document/` | Web and document formats (10 protocols) |
| `src/error.rs` | `ProtocolError` enum |
## crates/panproto-io --- Instance-level presentations
Format-specific parse/emit for all 76 protocols, producing `WInstance`/`FInstance`.
| File | Description |
|---|---|
| `src/lib.rs` | Public API, `default_registry()`, re-exports |
| `src/traits.rs` | `InstanceParser`, `InstanceEmitter`, `NativeRepr` trait definitions |
| `src/error.rs` | `ParseInstanceError`, `EmitInstanceError` enums |
| `src/registry.rs` | `ProtocolRegistry` runtime dispatch by protocol name |
| `src/json_pathway.rs` | SIMD-accelerated JSON pathway via `simd-json` |
| `src/json_codec.rs` | Generic `JsonCodec` reused by ~30 JSON-based protocols |
| `src/xml_pathway.rs` | Zero-copy XML pathway via `quick-xml` |
| `src/xml_codec.rs` | Generic `XmlCodec` reused by ~14 XML-based protocols |
| `src/tabular_pathway.rs` | SIMD tabular pathway via `memchr` (CoNLL-U, CSV, etc.) |
| `src/tabular_codec.rs` | Generic `TabularCodec` for delimited text protocols |
| `src/arena.rs` | Arena allocation helpers for zero-copy hot paths |
| `src/web_document/html.rs` | SIMD HTML codec via `tl` |
| `src/web_document/markdown.rs` | Markdown codec via `pulldown-cmark` |
| `src/annotation/conllu.rs` | CoNLL-U codec with custom SIMD field splitting |
| `src/annotation/` | Annotation protocol codecs (19) |
| `src/api/` | API protocol codecs (5) |
| `src/config/` | Config protocol codecs (4) |
| `src/data_schema/` | Data schema codecs (7) |
| `src/data_science/` | Data science codecs (3) |
| `src/database/` | Database codecs (6) |
| `src/domain/` | Domain codecs (6) |
| `src/serialization/` | Serialization codecs (8) |
| `src/type_system/` | Type system codecs (8) |
| `src/web_document/` | Web/document codecs (10) |
| `benches/io_bench.rs` | divan throughput benchmarks |
## crates/panproto-core --- Shared re-exports
| File | Description |
|---|---|
| `src/lib.rs` | Re-exports from `panproto-gat`, `panproto-schema`, `panproto-inst`, `panproto-mig`, `panproto-lens`, `panproto-check`, `panproto-io` |
## crates/panproto-wasm --- WASM boundary
JavaScript-facing API with slab allocation and MessagePack serialization.
| File | Description |
|---|---|
| `src/lib.rs` | `wasm-bindgen` entry point, initialization |
| `src/api.rs` | Exported JS functions: `create_schema`, `compile_migration`, `restrict`, `lift`, etc. |
| `src/slab.rs` | `Slab<T>` allocator: `alloc()`, `get()`, `free()`, `slab_stats()` |
| `src/error.rs` | `WasmError`, JavaScript-friendly error conversion |
## crates/panproto-vcs --- Schematic version control
See @sec-vcs-engine for the full module layout. Selected files relevant to edit lenses:
| File | Description |
|---|---|
| `src/edit_mig.rs` | `incremental_migrate`, `encode_edit_log`, `decode_edit_log`: VCS-level incremental migration |
| `src/object.rs` | `EditLogObject`, `CommitObject` (with `edit_log_ids` field) |
## crates/panproto-cli --- Command-line interface
| File | Description |
|---|---|
| `src/main.rs` | CLI binary: `clap`-based argument parsing, subcommands for migrate, check, validate, etc. |
| `src/cmd/data.rs` | `schema data sync` and `schema data status` CLI commands |
## sdk/typescript --- TypeScript SDK
| File | Description |
|---|---|
| `src/index.ts` | Package entry point, public exports |
| `src/panproto.ts` | `Panproto` class: high-level API wrapping WASM calls |
| `src/schema.ts` | `Schema` class: schema construction and manipulation |
| `src/protocol.ts` | `Protocol` class: protocol loading and configuration |
| `src/migration.ts` | `Migration` class: compile, restrict, lift |
| `src/lens.ts` | `Lens` class: bidirectional transformation API |
| `src/wasm.ts` | WASM module loader and initialization |
| `src/msgpack.ts` | MessagePack encode/decode helpers |
| `src/types.ts` | TypeScript type definitions mirroring Rust structs |
| `tests/panproto.test.ts` | End-to-end SDK tests |
| `tests/schema.test.ts` | Schema construction tests |
| `tests/migration.test.ts` | Migration pipeline tests |
| `tests/wasm.test.ts` | WASM boundary tests |
## tests/integration --- Cross-crate integration tests
| File | Description |
|---|---|
| `src/lib.rs` | Shared test utilities |
| `tests/atproto_roundtrip.rs` | AT Protocol schema, instance, migrate, round-trip |
| `tests/atproto_recursive.rs` | Recursive AT Protocol schemas |
| `tests/cross_protocol.rs` | Migration across different protocols |
| `tests/sql_migration.rs` | SQL-specific migration scenarios |
| `tests/breaking_change.rs` | Breaking-change detection on real diffs |
| `tests/lens_laws.rs` | GetPut / PutGet law verification |
| `tests/wasm_boundary.rs` | WASM serialization fidelity |
| `tests/hypergraph_fan.rs` | Hyper-edge and fan operations |
| `tests/theory_composition.rs` | Theory morphism and colimit composition |
| `tests/cambria_subsumption.rs` | Comparison with Cambria-style lenses |
| `tests/cql_subsumption.rs` | Comparison with CQL-style functorial migration |
| `tests/custom_protocol.rs` | User-defined protocol tests |
| `tests/self_description.rs` | Self-describing schema tests |
| `tests/performance.rs` | Performance regression tests |
| `fixtures/atproto/` | AT Protocol test fixture data |
| `fixtures/sql/` | SQL test fixture data |
## .github --- CI/CD
| File | Description |
|---|---|
| `workflows/ci.yml` | Main CI: lint, test, WASM build, TS build/test |
| `workflows/bench.yml` | Benchmark comparison on PRs |
| `workflows/release.yml` | Crate publishing and npm release |
| `workflows/publish-tutorial.yml` | Tutorial site deployment |
| `dependabot.yml` | Automated dependency update configuration |
## dev-guide --- This developer guide
| Path | Description |
|---|---|
| `_quarto.yml` | Quarto book configuration: chapters, parts, format settings |
| `index.qmd` | Preface / landing page |
| `chapters/` | Numbered chapter files (`01-welcome.qmd` through `19-release.qmd`) |
| `appendices/` | Appendix files (`A-glossary.qmd`, `B-source-code-map.qmd`, `C-troubleshooting.qmd`) |
| `references.bib` | Bibliography |
| `styles.css` | Custom CSS overrides |