P0-X: Update docs and mark naming drift tasks complete

Co-authored-by: devlux76 <86517969+devlux76@users.noreply.github.com>

Author: Copilot

ARCHITECTURE-REVIEW.md

@@ -4,6 +4,8 @@
 **Scope:** Full repository audit against corrected DESIGN.md (v1.2)
 **Status:** Documentation-only pass; no code changes made in this review
 
+**Update (P0-X resolved):** All P0-X naming drift items (D1–D9) have been corrected. `SemanticNeighbor`, `SemanticNeighborSubgraph`, `putSemanticNeighbors`, `getSemanticNeighbors`, `getInducedNeighborSubgraph`, `needsNeighborRecalc`, `flagVolumeForNeighborRecalc`, and `clearNeighborRecalcFlag` are now in place throughout `core/types.ts`, `storage/IndexedDbMetadataStore.ts`, `cortex/Query.ts`, and all test files. The IDB object store is `neighbor_graph` (DB_VERSION=3). The divergence entries below are preserved as historical record.
+
 ---
 
 ## Executive Summary

DESIGN.md

@@ -495,8 +495,6 @@ interface Edge {
 #### Semantic Neighbor (Proximity Edge)
 Sparse radius-graph edge connecting pages with high cosine similarity. Used for subgraph expansion during retrieval.
 
-> **Note:** The current codebase names this type `MetroidNeighbor` — this is an architectural naming error introduced by early conceptual drift. The correct term is `SemanticNeighbor` (or equivalent). A code-level rename is tracked in the TODO. The edge is a proximity concept, not a Metroid concept.
-
 **Critical distinction — two edge types, two roles:**
 
 | Edge type | Storage | Role |
@@ -525,8 +523,6 @@ interface SemanticNeighbor {
 #### Semantic Neighbor Subgraph
 Induced subgraph for BFS-based coherence path expansion.
 
-> **Note:** Currently named `MetroidSubgraph` in the codebase — same renaming correction applies.
-
 ```typescript
 interface SemanticNeighborSubgraph {
   nodes: Hash[];
@@ -587,7 +583,7 @@ Structured entity storage with automatic reverse indexes.
 **Object Stores:**
 - `pages`, `books`, `volumes`, `shelves`
 - `edges_hebbian` (Hebbian weights)
-- `neighbor_graph` (sparse semantic neighbor graph — currently named `metroid_neighbors` in code; rename tracked in TODO)
+- `neighbor_graph` (sparse semantic neighbor graph)
 - `flags` (dirty-volume recalc markers)
 - `page_to_book`, `book_to_volume`, `volume_to_shelf` (reverse indexes)
 - `hotpath_index` (periodic HOT-membership checkpoint, keyed by `entityId`; loaded on startup to reconstruct the RAM resident index; written by Daydreamer each maintenance cycle)
@@ -789,7 +785,7 @@ Matryoshka dimensional unwinding. Runs the thesis→freeze→antithesis→synthe
 search; m2 via cosine-opposite medoid; c computed once and frozen; subsequent candidates evaluated
 relative to frozen c. Planned module: `cortex/MetroidBuilder.ts`.
 
-**Semantic neighbor graph** (also: proximity graph, neighbor graph): The sparse radius-graph of cosine-similarity edges between pages, used for subgraph expansion during retrieval. This is **not** the same as a Metroid. The edges connect pages with high cosine similarity and are used for BFS expansion. Currently named `MetroidNeighbor` / `metroid_neighbors` in the codebase — this is a naming error that must be corrected (tracked in TODO as P0-X).
+**Semantic neighbor graph** (also: proximity graph, neighbor graph): The sparse radius-graph of cosine-similarity edges between pages, used for subgraph expansion during retrieval. This is **not** the same as a Metroid. The edges connect pages with high cosine similarity and are used for BFS expansion.
 
 **Hotpath**: The in-memory resident index of H(t) entries spanning all four hierarchy tiers. The hotpath is the first lookup target for every query; misses spill to WARM/COLD storage. HOT membership and salience are checkpointed to the `hotpath_index` IndexedDB store by Daydreamer each maintenance cycle, allowing the RAM index to be restored after a page reload or machine reboot without full corpus replay.
 

PLAN.md

@@ -98,7 +98,7 @@ This document tracks the implementation status of each major module in CORTEX. I
 | Dialectical Search Pipeline | ❌ Missing | `cortex/DialecticalSearch.ts` (planned) | Orchestrates thesis/antithesis/synthesis zone exploration using a Metroid; prevents confirmation bias |
 | Knowledge Gap Detector | ❌ Missing | `cortex/KnowledgeGapDetector.ts` (planned) | Determines when MetroidBuilder cannot find m2; emits curiosity probe |
 | Seed Selection | ❌ Missing | `cortex/SeedSelection.ts` (planned) | Threshold-based top-k page selection from ranking output |
-| Subgraph Expansion | 🟡 Partial | `storage/IndexedDbMetadataStore.ts` (`getInducedMetroidSubgraph` — to be renamed `getInducedNeighborSubgraph`) | BFS expansion implemented in storage layer; needs dynamic Williams bounds; needs orchestration wrapper |
+| Subgraph Expansion | 🟡 Partial | `storage/IndexedDbMetadataStore.ts` (`getInducedNeighborSubgraph`) | BFS expansion implemented in storage layer; needs dynamic Williams bounds; needs orchestration wrapper |
 | Open TSP Solver | ❌ Missing | `cortex/OpenTSPSolver.ts` (planned) | Dummy-node open-path heuristic for coherent ordering |
 | Query Orchestrator | 🟡 Needs Rework | `cortex/Query.ts` | Flat top-K scoring implemented (hotpath-first → warm/cold spill → PageActivity update → promotion sweep). **Must be substantially reworked** to implement the full dialectical pipeline: replace flat scoring with hierarchical resident-first ranking, add MetroidBuilder, dialectical zone scoring (thesis/antithesis/synthesis), subgraph expansion with dynamic Williams bounds, TSP coherence path, and query cost meter. The existing implementation does not use Hebbian edges or cosine-similarity-bounded subgraph expansion; it is a functional placeholder only. |
 | Result DTO | 🟡 Needs Rework | `cortex/QueryResult.ts` | Minimal DTO (`pages`, `scores`, `metadata`). **Must be reworked** to add `coherencePath: Hash[]`, `metroid?: { m1, m2, centroid }`, `knowledgeGap?: KnowledgeGap`, and `provenance: { subgraphSize, hopCount, edgeWeights, vectorOpCost, earlyStop }`. |
@@ -116,7 +116,7 @@ This document tracks the implementation status of each major module in CORTEX. I
 | Idle Scheduler | ❌ Missing | `daydreamer/IdleScheduler.ts` (planned) | Cooperative background loop; interruptible; respects CPU budget |
 | Hebbian Updates | ❌ Missing | `daydreamer/HebbianUpdater.ts` (planned) | LTP (strengthen), LTD (decay), prune below threshold; recompute σ(v) for changed nodes; run promotion/eviction sweep |
 | Prototype Recomputation | ❌ Missing | `daydreamer/PrototypeRecomputer.ts` (planned) | Recalculate volume/shelf medoids and centroids; recompute salience for affected entries; run tier-quota promotion/eviction |
-| Full Neighbor Graph Recalc | ❌ Missing | `daydreamer/FullNeighborRecalc.ts` (planned) | Rebuild bounded neighbor lists for dirty volumes; batch size bounded by O(√(t log t)) per idle cycle; recompute salience after recalc. **Note:** Currently planned as `FullMetroidRecalc` — this is a naming error; see TODO P0-X. |
+| Full Neighbor Graph Recalc | ❌ Missing | `daydreamer/FullNeighborRecalc.ts` (planned) | Rebuild bounded neighbor lists for dirty volumes; batch size bounded by O(√(t log t)) per idle cycle; recompute salience after recalc. |
 | Experience Replay | ❌ Missing | `daydreamer/ExperienceReplay.ts` (planned) | Simulate queries to reinforce connections |
 | Cluster Stability | ❌ Missing | `daydreamer/ClusterStability.ts` (planned) | Detect/trigger split/merge for unstable clusters; run lightweight label propagation for community detection; store community labels in PageActivity |
 
@@ -400,9 +400,9 @@ This document tracks the implementation status of each major module in CORTEX. I
 **Impact:** Core discovery-sharing value proposition is missing; knowledge gaps cannot be resolved via P2P.
 **Mitigation:** Phase 3 required track; implement eligibility classifier + curiosity broadcaster + signed subgraph exchange as v1 scope. CuriosityProbe must include `mimeType` and `modelUrn` to prevent incommensurable graph merges.
 
-### Blocker 4: Naming Drift (P0-X)
-**Impact:** The term "Metroid" is currently used for the proximity graph in all code. MetroidBuilder cannot be introduced without a rename collision.
-**Mitigation:** P0-X tasks (rename `MetroidNeighbor` → `SemanticNeighbor`, etc.) must be completed before MetroidBuilder is implemented.
+### Blocker 4: Naming Drift (P0-X) — RESOLVED
+**Impact:** The term "Metroid" was used for the proximity graph in all code. MetroidBuilder cannot be introduced without a rename collision.
+**Resolution:** P0-X rename completed. `SemanticNeighbor`, `SemanticNeighborSubgraph`, and all `*SemanticNeighbors`/`*NeighborRecalc` method names are now in place throughout `core/types.ts`, `storage/IndexedDbMetadataStore.ts`, `cortex/Query.ts`, and all test files. The IDB object store is `neighbor_graph` (DB_VERSION=3).
 
 ### Risk 1: TSP Complexity
 Open TSP is NP-hard; heuristic may be slow on large subgraphs.
@@ -485,7 +485,7 @@ After every implementation pass:
 
 ## Notes
 
-- **Metroid vs medoid vs semantic neighbor graph:** These are three distinct concepts. `Metroid` refers only to the dialectical search probe `{ m1, m2, c }` constructed by `MetroidBuilder` at query time. `medoid` refers to a cluster representative node. The sparse proximity/neighbor graph (used for BFS subgraph expansion) is the **semantic neighbor graph** — it is currently misnamed `MetroidNeighbor`/`MetroidSubgraph` in code (see TODO P0-X for the rename task).
+- **Metroid vs medoid vs semantic neighbor graph:** These are three distinct concepts. `Metroid` refers only to the dialectical search probe `{ m1, m2, c }` constructed by `MetroidBuilder` at query time. `medoid` refers to a cluster representative node. The sparse proximity/neighbor graph (used for BFS subgraph expansion) is the **semantic neighbor graph** — represented by `SemanticNeighbor` / `SemanticNeighborSubgraph` in `core/types.ts` and stored in the `neighbor_graph` IDB object store.
 - **Model-derived numerics:** Never hardcode; always source from `core/` model profile modules.
 - **Policy-derived constants:** Never hardcode; always source from `core/HotpathPolicy.ts`.
 - **Test philosophy:** TDD (Red → Green → Refactor) for all new slices.

TODO.md

@@ -208,17 +208,17 @@ These items **must** be completed to have a usable system. Without them, users c
 
 **Why:** The codebase uses the term "Metroid" to name the sparse proximity/neighbor graph (`MetroidNeighbor`, `MetroidSubgraph`, `metroid_neighbors`, `getInducedMetroidSubgraph`, `FastMetroidInsert`, `FullMetroidRecalc`). This is architecturally incorrect. In CORTEX, a **Metroid** is a structured dialectical search probe `{ m1, m2, c }` — a concept that does not yet exist in the codebase at all. The proximity graph has nothing to do with Metroids. This naming collision will cause permanent confusion and make the MetroidBuilder impossible to implement cleanly without a rename.
 
-- [ ] **P0-X1:** Rename `MetroidNeighbor` → `SemanticNeighbor` in `core/types.ts`
+- [x] **P0-X1:** Rename `MetroidNeighbor` → `SemanticNeighbor` in `core/types.ts`
   - Update all references in `storage/IndexedDbMetadataStore.ts`
   - Update all references in test files
   - Update JSDoc and inline comments
 
-- [ ] **P0-X2:** Rename `MetroidSubgraph` → `SemanticNeighborSubgraph` in `core/types.ts`
+- [x] **P0-X2:** Rename `MetroidSubgraph` → `SemanticNeighborSubgraph` in `core/types.ts`
   - Update all references in `storage/IndexedDbMetadataStore.ts`
   - Update all references in `cortex/Query.ts`
   - Update JSDoc and inline comments
 
-- [ ] **P0-X3:** Rename `MetadataStore` proximity graph methods:
+- [x] **P0-X3:** Rename `MetadataStore` proximity graph methods:
   - `putMetroidNeighbors` → `putSemanticNeighbors`
   - `getMetroidNeighbors` → `getSemanticNeighbors`
   - `getInducedMetroidSubgraph` → `getInducedNeighborSubgraph`
@@ -227,17 +227,17 @@ These items **must** be completed to have a usable system. Without them, users c
   - `clearMetroidRecalcFlag` → `clearNeighborRecalcFlag`
   - Update all callers in `storage/IndexedDbMetadataStore.ts`, `cortex/Query.ts`, and test files
 
-- [ ] **P0-X4:** Rename planned Hippocampus file `hippocampus/FastMetroidInsert.ts` → `hippocampus/FastNeighborInsert.ts`
+- [x] **P0-X4:** Rename planned Hippocampus file `hippocampus/FastMetroidInsert.ts` → `hippocampus/FastNeighborInsert.ts`
   - Rename class/function to `FastNeighborInsert`/`insertSemanticNeighbors`
 
-- [ ] **P0-X5:** Rename planned Daydreamer file `daydreamer/FullMetroidRecalc.ts` → `daydreamer/FullNeighborRecalc.ts`
+- [x] **P0-X5:** Rename planned Daydreamer file `daydreamer/FullMetroidRecalc.ts` → `daydreamer/FullNeighborRecalc.ts`
   - Rename class/function to `FullNeighborRecalc`/`runNeighborRecalc`
 
-- [ ] **P0-X6:** Rename IndexedDB object store from `metroid_neighbors` → `neighbor_graph`
+- [x] **P0-X6:** Rename IndexedDB object store from `metroid_neighbors` → `neighbor_graph`
   - Increment `DB_VERSION` in `storage/IndexedDbMetadataStore.ts`
   - Add migration in `applyUpgrade` to copy data from old store to new store
 
-- [ ] **P0-X7:** Update all documentation strings and JSDoc that use "Metroid neighbor" to use "semantic neighbor"
+- [x] **P0-X7:** Update all documentation strings and JSDoc that use "Metroid neighbor" to use "semantic neighbor"
 
 **Exit Criteria:** No source file uses "Metroid" to refer to the proximity graph. The term "Metroid" is reserved exclusively for the `{ m1, m2, c }` dialectical probe type implemented in `cortex/MetroidBuilder.ts`.
 
@@ -863,7 +863,7 @@ These items improve quality, performance, and developer experience. Not blockers
 If you're reading this and want to know "what do I work on right now?", here's the answer:
 
 **Immediate (unblock MetroidBuilder):**
-1. **P0-X1–X7:** Fix architectural naming drift (`MetroidNeighbor` → `SemanticNeighbor` and related renames)
+1. ~~**P0-X1–X7:** Fix architectural naming drift (`MetroidNeighbor` → `SemanticNeighbor` and related renames)~~ ✅ DONE
 
 **After P0-X (complete v0.1):**
 2. **P0-B1:** Implement `hippocampus/Chunker.ts`

docs/api.md

@@ -112,18 +112,18 @@ interface Edge {
 }
 ```
 
-#### `MetroidNeighbor`
+#### `SemanticNeighbor`
 
-A nearest-neighbour entry in the Metroid radius graph (a project-domain term for the medoid-inspired NN graph).
+A nearest-neighbour entry in the semantic neighbor radius graph — a sparse proximity graph connecting pages with high cosine similarity, used for BFS subgraph expansion during retrieval.
 
 ```typescript
-interface MetroidNeighbor {
+interface SemanticNeighbor {
   neighborPageId: Hash;
   cosineSimilarity: number;  // threshold defined by runtime policy
   distance: number;          // 1 – cosineSimilarity (TSP-ready)
 }
 
-interface MetroidSubgraph {
+interface SemanticNeighborSubgraph {
   nodes: Hash[];
   edges: { from: Hash; to: Hash; distance: number }[];
 }
@@ -180,20 +180,20 @@ interface MetadataStore {
   getVolumesByBook(bookId: Hash): Promise<Volume[]>;
   getShelvesByVolume(volumeId: Hash): Promise<Shelf[]>;
 
-  // Metroid NN radius index
-  putMetroidNeighbors(pageId: Hash, neighbors: MetroidNeighbor[]): Promise<void>;
-  getMetroidNeighbors(pageId: Hash, maxDegree?: number): Promise<MetroidNeighbor[]>;
+  // Semantic neighbor radius index
+  putSemanticNeighbors(pageId: Hash, neighbors: SemanticNeighbor[]): Promise<void>;
+  getSemanticNeighbors(pageId: Hash, maxDegree?: number): Promise<SemanticNeighbor[]>;
 
-  /** BFS expansion of the Metroid subgraph up to `maxHops` levels deep. */
-  getInducedMetroidSubgraph(
+  /** BFS expansion of the semantic neighbor subgraph up to `maxHops` levels deep. */
+  getInducedNeighborSubgraph(
     seedPageIds: Hash[],
     maxHops: number,
-  ): Promise<MetroidSubgraph>;
+  ): Promise<SemanticNeighborSubgraph>;
 
   // Dirty-volume recalculation flags
-  needsMetroidRecalc(volumeId: Hash): Promise<boolean>;
-  flagVolumeForMetroidRecalc(volumeId: Hash): Promise<void>;
-  clearMetroidRecalcFlag(volumeId: Hash): Promise<void>;
+  needsNeighborRecalc(volumeId: Hash): Promise<boolean>;
+  flagVolumeForNeighborRecalc(volumeId: Hash): Promise<void>;
+  clearNeighborRecalcFlag(volumeId: Hash): Promise<void>;
 }
 ```