torchcell.provenance

Schema-dependency tracking, which decides when a built dataset must be rebuilt because the schema changed. schema_impact diffs the working-tree schema against a git ref, classifies each change as breaking or stale, and names the loaders that must rebuild (it runs as a pre-commit hook). build_manifest stores, next to each built LMDB, the contract fingerprints of the schema symbols its loader depends on, and its check reports which built datasets are stale. A fingerprint hashes a symbol’s contract (field shape and validators), not its source text, so a docstring edit flags nothing. schema_deps is the shared AST analysis.

Classes

ContractSpec	The contract-relevant surface of one schema class.
FieldSpec	A single pydantic field's contract-relevant shape.
SchemaSurface	All record-contract classes across the schema-surface modules, with their graph.
ChangeKind	Severity of a schema-symbol change for its dependent datasets.
ImpactReport	The full result of diffing a schema change: changed symbols and impacted loaders.
LoaderImpact	A dataset loader whose closure contains one or more changed symbols.
SymbolChange	A schema symbol that changed contract between two surfaces, with its severity.
BuildManifest	Records the schema contract a built LMDB was produced against.
DatasetCheck	Per-dataset outcome of a fleet-wide staleness scan.
StaleResult	Result of checking one manifest against the current schema surface.
SymbolDrift	One schema symbol whose contract fingerprint no longer matches the manifest.

Functions

contract_spec	Extract the contract-relevant surface of a schema class from its AST.
fingerprint	Contract fingerprint of a schema class AST node.
forward_closure	All symbols reachable from seeds (inclusive) along the reference graph.
load_default_surface	Load the default torchcell schema surface (schema.py + pydant.py).
load_surface	Parse the schema-surface modules on disk into a SchemaSurface.
load_surface_from_sources	Build a SchemaSurface from label -> source text pairs.
loader_closure	Transitive closure of a loader's schema imports -- the symbols it actually depends on.
loader_schema_deps	Surface symbols a loader imports directly from any torchcell.datamodels submodule.
build_impact_report	Diff the working-tree schema surface against base and map changes to loaders.
classify_change	Classify a fingerprint-changed symbol into breaking/stale with human-readable reasons.
diff_surfaces	Every symbol whose contract changed between two surfaces, classified.
check_all	Check every built dataset under DATA_ROOT for schema staleness.
check_manifest	Compare a manifest's stored fingerprints against the current local schema surface.
compute_manifest	Build a BuildManifest from a loader's transitive schema closure.
write_build_manifest	Compute and write build_manifest.json for a freshly built dataset instance.