P0-X: Fix architectural naming drift — complete doc/tracking cleanup

[Copilot]

The term "Metroid" was incorrectly used throughout code and docs to name the sparse proximity/neighbor graph (MetroidNeighbor, MetroidSubgraph, metroid_neighbors). In CORTEX, "Metroid" is reserved for the { m1, m2, c } dialectical search probe — a distinct concept that must not collide with proximity graph naming.

The TypeScript sources (core/types.ts, storage/IndexedDbMetadataStore.ts, cortex/Query.ts, tests) were already renamed in a prior pass. This PR closes out the remaining documentation and tracking debt.

docs/api.md

• MetroidNeighbor → SemanticNeighbor, MetroidSubgraph → SemanticNeighborSubgraph
• All six MetadataStore proximity graph methods updated to correct names (putSemanticNeighbors, getSemanticNeighbors, getInducedNeighborSubgraph, needsNeighborRecalc, flagVolumeForNeighborRecalc, clearNeighborRecalcFlag)
• Section heading updated from "Metroid NN radius index" → "Semantic neighbor radius index"
• Fixed British "nearest-neighbour" → American "nearest-neighbor" spelling

core/types.ts

• Fixed British "nearest-neighbour" → American "nearest-neighbor" in section comment

README.md

• Fixed two instances of British "nearest-neighbour" / "nearest neighbours" → American "nearest-neighbor" / "nearest neighbors"
• Removed stale ARCHITECTURE-REVIEW.md entry from the key documents table

DESIGN.md

• Removed three stale callout blocks that said the rename was "tracked in TODO" — it is done
• Terminology section definition of "semantic neighbor graph" no longer references the resolved naming error

PLAN.md

• Dropped "to be renamed" annotation from Subgraph Expansion row
• Removed naming-error note from FullNeighborRecalc row
• Blocker 4 updated from open risk to RESOLVED
• Notes section updated to reference the correct live type names

TODO.md

• P0-X1 through P0-X7 marked complete (- [x])
• P0-X6 stale migration sub-bullets removed (no migration needed — fresh code)
• Quick Reference entry struck through and marked ✅ DONE

ARCHITECTURE-REVIEW.md

• Deleted entirely — the document was an outdated information hazard cataloguing naming drift that has since been fully resolved

Original prompt

---

This section details on the original issue you should resolve

<issue_title>P0-X: Fix Architectural Naming Drift (BLOCKS: correct design implementation)</issue_title>
<issue_description>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

  • 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

  • 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:

  • putMetroidNeighbors → putSemanticNeighbors
  • getMetroidNeighbors → getSemanticNeighbors
  • getInducedMetroidSubgraph → getInducedNeighborSubgraph
  • needsMetroidRecalc → needsNeighborRecalc
  • flagVolumeForMetroidRecalc → flagVolumeForNeighborRecalc
  • 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

  • Rename class/function to FastNeighborInsert/insertSemanticNeighbors

• 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

  • 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"

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.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes P0-X: Fix Architectural Naming Drift (BLOCKS: correct design implementation) #56

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[devlux76]

@copilot This may already be done and just failed to be referenced. Check the current code base and issues status. Mark as complete anything completed and just limit your work to review and cleanup.

[Copilot]

@copilot This may already be done and just failed to be referenced. Check the current code base and issues status. Mark as complete anything completed and just limit your work to review and cleanup.

Confirmed — all P0-X rename work was already complete in the TypeScript sources (core/types.ts, storage/IndexedDbMetadataStore.ts, cortex/Query.ts, and all test files). This PR closes out the remaining documentation and tracking gaps:

• docs/api.md — updated to SemanticNeighbor, SemanticNeighborSubgraph, and correct method names
• DESIGN.md — removed stale "tracked in TODO" callout blocks
• TODO.md — P0-X1 through P0-X7 marked [x] complete
• PLAN.md — Blocker 4 updated to RESOLVED; stale "to be renamed" annotations removed
• ARCHITECTURE-REVIEW.md — resolution status added to header

All 211 unit tests pass and lint is clean. The CI action_required status is a GitHub Actions environment approval gate, not a code failure (the run shows 0 jobs — it never started). Commit: 627f38f.

[Copilot]

Pull request overview

Closes out the remaining documentation/tracking updates for the completed “Metroid (proximity graph) → SemanticNeighbor (proximity graph)” rename, ensuring “Metroid” remains reserved for the { m1, m2, c } dialectical probe concept.

Changes:

• Updates API docs to use SemanticNeighbor / SemanticNeighborSubgraph and the renamed MetadataStore neighbor-graph method names.
• Removes/updates stale “rename pending” notes in DESIGN.md and resolves the naming-drift blocker status in PLAN.md.
• Marks P0-X items complete in TODO.md and adds a “resolved” update in ARCHITECTURE-REVIEW.md.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/api.md	Renames proximity-graph types/methods in the published API documentation.
DESIGN.md	Removes stale callouts implying the rename is still pending.
PLAN.md	Updates plan rows and marks the naming-drift blocker as resolved.
TODO.md	Checks off P0-X tasks and updates the quick-reference section.
ARCHITECTURE-REVIEW.md	Adds a resolution status update while retaining the historical divergence catalog.

[devlux76]

@copilot no migration is needed. This is fresh code. Just remove the references to it.

[Copilot]

Removed the migration sub-bullets from P0-X6. The entry now simply reads - [x] **P0-X6:** Rename IndexedDB object store from 'metroid_neighbors' → 'neighbor_graph' with no migration notes. Commit: 97d445b.

[devlux76]

@copilot Good catch and critical at P0 level. I'd recommend you scour the code base and fix any and all inconsistencies like that. I'm American so we may as well settle on American rather than English ☕️

[Copilot]

Scoured the full codebase — found and fixed all three occurrences of "neighbour" in docs/api.md, core/types.ts, and README.md. No British spellings remain. Commit: 6582cbe.

[devlux76]

@copilot This document is now outdated and presents an information hazard. Just delete it. It was missed in a previous pass over the docs and popped up here.

[Copilot]

Deleted ARCHITECTURE-REVIEW.md and removed its entry from the README key documents table. No references to it remain. Commit: e0601d6.