Module maintenance 

Maintenance for the on-disk knowledge stores.

A store at <data_dir>/knowledge/<hash>/ is keyed to a project_root. When that root is deleted (a removed git worktree, a thrown-away temp project) the store can never be written again — its per-store eviction cap can therefore never self-heal (the memory lifecycle only runs on write) and the directory is pure accumulated bloat. This module finds and prunes those orphaned stores.

Pruning is only ever invoked from the explicit lean-ctx doctor --fix path; the background lifecycle must never delete a store, since a missing root can also mean a temporarily-unmounted drive rather than a deleted project.

Structs

GcPlan

What lean-ctx knowledge gc found under the knowledge directory.

OrphanedStore

A knowledge store whose recorded project_root no longer exists on disk.

PruneReport

Outcome of a prune pass.

Functions

apply_gc_in

Remove the directories plan names as removable under data_dir. Each one is removed under its store lock (the lock every knowledge write takes), after it was classified again under that lock: one that gained data or a file since the plan, or whose lock is held, is kept. Returns how many were removed.

find_orphaned_stores

Scan every knowledge store under the real data dir and return the orphaned ones. See find_orphaned_stores_in for the detection rules.

find_orphaned_stores_in

Detect orphaned stores under an explicit data_dir (the testable core).

plan_gc_in

Plan a gc pass under an explicit data_dir; reads only.

prune_orphaned_stores

Remove every orphaned store under the real data dir. Best-effort.

prune_orphaned_stores_in

Prune orphaned stores under an explicit data_dir (the testable core). Removes each orphaned knowledge/<hash>/ directory plus the matching episodic-memory file (memory/episodes/<hash>.json). A failure on one store never aborts the rest.