Module index 

index — the hierarchical content catalog.

A uniform three-level tree: root + per-layer + per-type-folder. Two artifacts per type-folder: the human index.md (capped 500, recency browse) and the machine index.jsonl (complete, structured — one JSON object per file). Both read summary + key frontmatter fields + links directly from each file — there is no extraction logic here.

Maintained write-through by the write commands (Index::on_write / Index::on_rename / Index::on_remove — the loop path, O(changed), no store walk); Index::rebuild_all is the from-scratch SWEEP repair.

Key invariant: write-through must produce a byte-identical index.md and (post-compaction) index.jsonl to a full Index::rebuild_all over the same end state — the loop path can never drift from the repair path.

Implementation notes (deviations the reader should know)

• Self-contained, by design. This module does its own shard-aware folder walk, its own minimal frontmatter read, and its own atomic write, using only store.root (a public field) and the serde_yml / serde_json / chrono / walkdir crates rather than routing through the sibling store/parser helpers (Store::walk_type_folder, Store::recent_in_type_folder, [parser::read_file], …). The index has to stamp a deterministic updated: and emit a canonical, compacted index.jsonl (see the two notes below); keeping the read/walk/write local is what makes the byte-identity invariant a true byte comparison, free of any incidental formatting the shared readers might introduce. The public signatures in lib.rs are untouched.
• Deterministic updated: on the index files themselves. An index’s own updated frontmatter is derived as the max updated over the files it catalogs (max over children for root/layer) — NOT wall-clock-now. This is what makes the byte-identity invariant a true byte comparison: a write-through write and a rebuild_all over the same end state stamp the same value. (The SPEC’s rendered examples show a wall-clock-looking value; the conventions list only requires updated: <RFC3339>, and the property-tested invariant dominates.)
• index.jsonl is always compacted. Write-through rewrites the affected type-folder’s jsonl in canonical form (one current line per path, recency order) rather than appending superseded/tombstone lines, so the jsonl is byte-identical to rebuild_all immediately (a strictly stronger guarantee than the SPEC’s “post-compaction”). This keeps the loop cost at one sidecar read + one rewrite per touched type-folder — O(folder), the sanctioned loop primitive, never a whole-Store::walk.
• Root/layer entry styling follows plan §index ((N) numeric counts; layer headings in the root carry the layer’s total count) which is more specific than the SPEC’s illustrative (42 files) prose example. Type folders are listed alphabetically (a deterministic order a derived artifact needs); scope: type-folder follows the conventions list, not the one SPEC example that wrote scope: folder.

Structs

Index

A built (or being-built) catalog for one IndexLevel, with both rendered artifacts available. Pure data until written via Index::write_level.

IndexRecord

One record in a type-folder’s index.jsonl — the complete, structured twin of a single index.md browse entry.

Enums

IndexLevel

Which level of the catalog an Index represents.