Skip to content

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

@github-actions

Description

@github-actions

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 MetroidNeighborSemanticNeighbor 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 MetroidSubgraphSemanticNeighborSubgraph 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:

    • putMetroidNeighborsputSemanticNeighbors
    • getMetroidNeighborsgetSemanticNeighbors
    • getInducedMetroidSubgraphgetInducedNeighborSubgraph
    • needsMetroidRecalcneedsNeighborRecalc
    • flagVolumeForMetroidRecalcflagVolumeForNeighborRecalc
    • clearMetroidRecalcFlagclearNeighborRecalcFlag
    • Update all callers in storage/IndexedDbMetadataStore.ts, cortex/Query.ts, and test files
  • P0-X4: Rename planned Hippocampus file hippocampus/FastMetroidInsert.tshippocampus/FastNeighborInsert.ts

    • Rename class/function to FastNeighborInsert/insertSemanticNeighbors
  • P0-X5: Rename planned Daydreamer file daydreamer/FullMetroidRecalc.tsdaydreamer/FullNeighborRecalc.ts

    • Rename class/function to FullNeighborRecalc/runNeighborRecalc
  • P0-X6: Rename IndexedDB object store from metroid_neighborsneighbor_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.

Metadata

Metadata

Labels

P0: criticalCritical path — blocks all dependent worklayer: cortexRetrieval orchestration (rank → expand → order)layer: daydreamerBackground consolidation (LTP/LTD, recalc)layer: documentationAPI docs, developer guide, architecture diagramslayer: hippocampusIngest orchestration (chunk → embed → persist)

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions