Module adjacency

Expand description

On-disk format for the derived adjacency index (indexes/adjacency/, ADR 0005).

The adjacency index is a derived, rebuildable CSR (compressed sparse row) representation of the topology. Canonical Parquet under topology/ remains the sole source of truth: every file in indexes/adjacency/ can be reconstructed from the typed edge tables alone, and an absent index means “build in memory on demand”, never an error.

indexes/adjacency/
├── index_manifest.parquet    ADJACENCY_MANIFEST_SCHEMA (Parquet)
├── WORKS_AT.out.csr          ADJACENCY_CSR_SCHEMA (Arrow IPC)
├── WORKS_AT.in.csr
└── _all.out.csr              union across relation types

§Build ordering convention

Builders MUST write all CSR files first and index_manifest.parquet last. A crash mid-build then leaves the manifest absent or carrying the old topology_generation, so the index reads as stale and the provider falls back to scan-and-build — a torn build can cost a rebuild, never correctness.

§CSR encoding

A .csr file is a single-batch Arrow IPC file with one column, adjacency: LargeList<Struct{edge_id, neighbor_id}> and one row per surrogate node_id in 0..node_count. The list offsets buffer is the CSR offsets array; the struct child is the targets array. See ADJACENCY_CSR_SCHEMA and docs/book/architecture/storage.md §Derived Indexes. The in-memory CsrIndex exposes the logical offsets/targets model directly, so consumers never deal with the list encoding.

Structs§

AdjacencyInspection: Rust-owned identity and freshness inspection for the adjacency artifact.
AdjacencyManifestRow: One row of index_manifest.parquet — the build record for a single CSR file. See ADJACENCY_MANIFEST_SCHEMA.
CsrIndex: In-memory CSR adjacency structure, surrogate-keyed.

Enums§

AdjacencyFreshnessReason: Bounded reason accompanying a non-current adjacency state.
AdjacencyFreshnessState: Bounded freshness state for the derived adjacency artifact.
AdjacencyValidationIssue: One problem found by validate_adjacency_index.
Direction: Edge direction a CSR file is keyed by.

Constants§

ALL_RELATIONS_STEM: Reserved relation-type stem for the union-across-relation-types index (_all.out.csr). Underscore-prefixed names cannot collide with declared relation types (matching the _exploratory.parquet convention).
MANIFEST_FILE: File name of the adjacency index manifest within indexes/adjacency/.

Functions§

adjacency_dir: indexes/adjacency/ within project_dir.
build_adjacency_index: Build the full adjacency index for the project under indexes/adjacency/: one {out, in} CSR pair per relation type found in topology/edges/, plus the ALL_RELATIONS_STEM union pair, then index_manifest.parquet last (the build-ordering convention in the module docs).
build_adjacency_index_into: Build from canonical topology in source_project_dir into a separate private artifact project root. The caller publishes the completed directory.
build_adjacency_index_with_checkpoint: Cancellation-aware variant of build_adjacency_index.
csr_path: Path of the CSR file for (relation_type, direction): indexes/adjacency/<REL_TYPE>.<dir>.csr.
inspect_adjacency_index: Inspect adjacency identity and freshness using the same complete-delta-chain rule as validation and execution.
manifest_path: Path of index_manifest.parquet within project_dir.
read_csr: Read a CSR file written by write_csr back into a CsrIndex.
read_manifest: Read index_manifest.parquet. An absent manifest (or absent indexes/adjacency/ directory) returns Ok(vec![]) — the index simply has not been built, mirroring the absent-file semantics of the catalog readers.
validate_adjacency_index: Verify a persisted adjacency index against a fresh in-memory rebuild from topology/ (ADR 0005 maintenance op): for every manifest row, the CSR file must exist, parse, and equal the expected CSR byte-for-byte (same deterministic sort the builder uses). An absent index (no manifest) is clean — there is nothing to validate, not an error.
validate_adjacency_index_against: Validate a privately staged artifact against canonical source topology.
write_csr: Write csr to path as a single-batch Arrow IPC file (ADJACENCY_CSR_SCHEMA), atomically (sibling temp + rename, the same pattern as RewriteBatch; IPC files cannot reuse it directly because it encodes Parquet).
write_manifest: Replace index_manifest.parquet with rows, atomically.