overview implementation

Sources: index of the per-file design notes

Every source file in the repository has a markdown sibling of the same name describing what it is for. Because the vault root is the repository root, those siblings are ordinary vault notes and link into the rest of the design. This note is the index of them.

All code files are comments only. Nothing is implemented, nothing is meant to run. See Repository Layout for the tree and the Rust/Julia split, and Roadmap for the order in which these would actually be written.

Rust — crates/ (implemented, 2026-10-20)

CrateFileNoteRole
sophia-hashsophia_hash.rssophia_hashidentity: framing, digests, components; language-agnostic
sophialang-coredebug.rsdebugDebug in derive’s layout without recursion (SP-015)
sophialang-syntaxtests/deep.rsparserevery pass at depth 100 000 on a 256 KiB stack
canonical.rscanonicalthe tag-length-value framing shared with Moonkale
component.rscomponentSCCs and the canonical order of recursive groups
merkle.rsmerklecomponent, member and nominal digests; Record
digest.rsdigestthe 256-bit digest type
sophialang-coresophialang_core.rssophialang_coresophialang’s core calculus and normaliser
term.rstermcore terms
definition.rsdefinitiondefinition kinds and bodies
encode.rsencodecanonical encoding, decoding, display data
normalise.rsnormalisebatches of drafts → records
samples.rssamplesthe 16-definition sample program
sophia-storesophia_store.rssophia_storethe store over interchangeable backends
sophia-storefolder.rsfolderfolder stores (SPEC-009): replace_files, file manifests, the derived mode, text_source
sophia-storetests/folder.rsfolderreplace_files on four backends
sophia-storeexamples/folder_garbage.rsfolder_garbagehow much of a folder store no current file reaches (before garbage collection)
backend.rsbackendthe backend traits
logic.rslogicthe store’s rules
types.rstypesnames, log, nominal entities, lineages, annotations, facts
codec.rs, query.rs, error.rscodec, query, errorvalue encoding, query results, errors
sqlite.rssqliteSQLite backend with the read-only guard
redb_store.rs, lmdb_store.rs, kv.rsredb_store, lmdb_store, kvkey-value backends and their shared logic
duckdb_store.rsduckdb_storeDuckDB backend (analytics)
sophialang-syntaxsophialang_syntax.rssophialang_syntaxprofiles, printer, parser; the round-trip guarantee
lexer.rs, parser.rs, ast.rslexer, parser, asttext → surface tree
elab.rs, resolve.rselab, resolvesurface tree → core; shared name resolution
print.rs, profile.rs, diagnostic.rsprint, profile, diagnosticcore → text; profiles; diagnostics
sophia-interfacesophia_interface.rssophia_interfacewhat Moonkale’s adapter wraps (SPEC-004)
edit.rs, profiles.rsedit, profilesedits through text; profiles in the database
propose.rsproposean outside edit of an exported sophialang file as a proposal (SPEC-010 §5)
tests/propose_text.rsproposepropose_text against the specification, compared with real edits (Mistral’s review probes)
sophia-querysophia_query.rssophia_querySophia’s own query language (SPEC-007): prepare, run, SQL, cache, store
sophia-querybounded.rsboundeda hard memory bound for untrusted queries: a worker process under RLIMIT_DATA (B-017)
sophia-querybin/sophia-query-worker.rssophia-query-workerthe worker binary of bounded
ir.rs, syntax.rs, canon.rsir, syntax, canonthe IR; Julia-flavoured syntax and printers; canonical form and ids
check.rs, plan.rs, magic.rscheck, plan, magicsorts, safety, strata; literal ordering; the magic-set rewrite
eval.rs, sql.rseval, sqlthe native executor; the SQL translation
tests/set_oriented.rsevalthe prefix path and anti-joins against tuple at a time (every backend) and SQL (B-014)
sophia-ingestsophia_ingest.rs, metamath.rs, code.rs, module.rssophia_ingest, metamath, code, modulefrontends for real code (B-16): Metamath into statements, proofs and library collections; Julia, Rust and Python through Moonkale’s shared WP-66 normal form; generic functions keyed by (module, name)
source.rssourcesource files as records and the ingest manifest; reconstruct rebuilds and compares every record
examples/lean_export_stats.rslean_export_statsmeasures a lean4export file (statements, programs, proofs)
examples/julia_conformance.rs, tests/julia-semantics/methods.jljulia_conformance, methodsSophia’s generic-function grouping against Julia’s own method table (Julia Conformance)
sophia-interfaceexamples/edit_timing.rsedit_timingB-15’s steps on Interface directly, to separate Sophia’s share
sophia-interfaceexamples/listing_timing.rslisting_timingchildren and all on a large store (Moonkale’s Explorer calls)
sophia-interfacetests/wasm_read.rssophia_interfacethe read path on wasm32 under Node, from a store’s bytes (SPEC-009 §4)
sophia-interfacetests/wasm_deep.rssophia_interfaceevery pass at depth 100 000 in wasm (Node, Firefox)
sophia-interfacetests/wasm_fixture.rs, tests/fixtures/web.sophiasophia_interfacethe fixture store, and from_bytes natively
experiments/b15-edit-looprun.shrunB-15: Moonkale’s edit_loop on synthetic stores of 10³–10⁵ definitions
sophia-benchsophia_bench.rs, bin/sophia-bench-report.rssophia_bench, sophia-bench-reportthe benchmark suite
bin/sophia-mm-check.rssophia-mm-checkMetamath dependency answers against metamath.exe
experiments/ad-materializationad_costs.jlad_costsE-AD-0: cost of producing vs running a derivative (Julia)
reactant_persist.jlreactant_persistE-AD-1: split the first call; restore a compiled derivative in a fresh process
pkgimage_reuse.jl, pkgimage_control.jl, ADCache/pkgimage_reuse, pkgimage_control, ADCacheE-AD-1: the same through Julia’s package image (fails)
sophia-climain.rsmainthe sophia command

The comment-only crates of the first vault (sophia-core, sophia-equiv, sophia-emit, sophia-frontend-metamath) are kept as ideas in attic/: sophia_core, elaborate, effects, sophia_equiv, egraph, witness, sophia_emit, metamath.

Julia

The comment-only Julia skeleton (src/*.jl, Project.toml) was deleted on 2026-10-20 (S-ADR-0004: Rust only). Julia may come back much later, for analytics on the code graph (SR-24).

Reading order for someone new

  1. Status and SPEC-001 Sophia Store v0: what the system is now
  2. sophia_hash → canonical → component → merkle: how identity works, and what can go wrong with it
  3. sophialang_core → term → encode → normalise: the first language
  4. sophia_store → backend → logic → sqlite / redb_store: how it is stored, and the measurements (Benchmark Results)

Where the risk is concentrated

Three files, for three different reasons: