Module store 

store — walk, locate, and shard a db.md store.

A db.md store is one directory marked by an uppercase DB.md at its root. Store::open is the single gate every store-walking subcommand goes through; a missing DB.md is the NotAStore error (NOT_A_STORE). The toolkit never guesses a store root.

Scale discipline lives here: Store::walk and the layer/type-folder walks are SWEEP primitives used only by validate --all, index rebuild, and stats. The interactive loop instead uses Store::find_links_to / Store::find_links_to_any (a single presence-only content scan) and the index.jsonl sidecar readers (Store::find_by_type / Store::find_by_where / Store::read_type_index) — never a whole-store parse. The batch Store::find_links_to_any is what keeps the working-set validate’s incoming-linker discovery a single store scan rather than one scan per changed object.

Link edges are defined once, here, by the shared extract_edge_targets / canonical_link_target / link_edge_key helpers (fence-aware, whitespace-trimmed, case-folded to the filesystem), so the forward view (graph::forwardlinks), the backward view (Store::find_links_to_any), rename, and validate all agree on exactly which [[...]] is an edge. ensure_path_within_store is the within-store containment gate every caller-influenced path passes through before it is read or traversed.

Structs

NotAStore

Returned when a path is opened as a store but has no DB.md at its root. Surfaced as the structured code NOT_A_STORE with a non-zero exit.

Store

An opened db.md store: its root path plus the parsed DB.md Config.

Enums

Layer

The three canonical layers of a db.md store.

StoreError

Errors from store-level operations (walk, locate, shard, sidecar read).

Functions

canonical_link_target

Canonicalize a raw [[...]] inner target into the wiki-link key: forward slashes, no leading ./ or /, no trailing .md, inner whitespace trimmed. The single key forward and backward edges are compared on. Pairs with link_edge_key for the case-fold step.

ensure_path_within_store

Canonicalize candidate (resolving symlinks; for a not-yet-existing leaf, canonicalize its existing parent chain and re-append the leaf) and return it only if it resolves inside store_root; otherwise Err.

extract_edge_targets

Extract every wiki-link edge target from a markdown body, fence-aware and whitespace-trimmed, in document order (duplicates kept — callers dedup). Returns canonical targets (see canonical_link_target); the case-fold for comparison is applied separately via link_edge_key so the canonical form (used for rewrites/output) stays case-preserving.

fence_closes

True if line closes the currently open fence: same char, run at least as long, nothing but trailing whitespace after. Mirrors validate’s fence_closes / the parser’s is_closing_fence, so an inner fence of the other character (a ``` line inside a ~~~ block) does NOT close the outer fence.

fence_opens

If line opens a fenced code block, return (fence byte, run length). The single fence-open rule shared by extract_edge_targets and graph’s rewrite_links_to, mirroring validate’s fence_opens and the parser’s opening_fence so every link op tracks fences identically: a fence is ``` or ~~~ (run ≥ 3) at ≤ 3 spaces of indent, and a backtick fence’s info string may not itself contain a backtick.

infer_type_from_path

Infer a content file’s canonical type from its store-relative path — the inverse of [default_type_folder] and the single source of truth for path→type inference (the CLI’s fm init calls this, never re-derives it).

layer_for_type

The canonical Layer a type_ belongs to, derived from its default type-folder (email → Sources, contact → Records, wiki-page → Wiki, unrecognized → Records). The write path uses this to decide whether an agent-supplied folder is in the right layer for the type before honouring its sub-folder choice.

link_edge_key

The comparison key for a canonical link target: identity on a case-sensitive filesystem, ASCII-lowercased on a case-insensitive one (macOS/Windows), so the string-keyed edge comparison agrees with the filesystem’s case-folding is_file() resolution. Callers compare link_edge_key(a) == link_edge_key(b).