Skip to content

Commit ca1cb00

Browse files
Copilotdevlux76
Copilot
and
devlux76
committed
docs: restore CORTEX architecture alignment — fix Metroid/medoid/centroid conflation
- Rewrite DESIGN.md v1.2: add MetroidBuilder, dialectical search, knowledge gap detection, P2P curiosity, fix all 'Metroid neighbor graph' naming drift - Update PLAN.md v1.2: add MetroidBuilder/KnowledgeGapDetector/DialecticalSearch modules, fix naming errors, correct Phase 2 description - Rewrite TODO.md: add P0-X (naming fix tasks), P1-M (MetroidBuilder), P1-N (knowledge gap), update P1-C/E/F/P2-C/G with correct terminology - Create ARCHITECTURE-REVIEW.md: 15-divergence catalog with file/component/ current/intended/correction/todo-task for each issue - Update README.md and copilot-instructions.md with correct Cortex description No code changes in this pass. Co-authored-by: devlux76 <86517969+devlux76@users.noreply.github.com>
1 parent 823163a commit ca1cb00

6 files changed

Lines changed: 668 additions & 106 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ CORTEX (**C**lustered **O**ntic **R**outing **T**hrough **E**ntangled e**X**chan
66

77
The engine models three biological brain regions:
88
- **Hippocampus** — Fast associative encoding (WebGPU multi-prototype lookups, Matryoshka embeddings, Hebbian edge creation, OPFS-backed vector storage)
9-
- **Cortex** — Intelligent routing & coherence (parallel WebGPU scoops, IndexedDB sub-graph retrieval, closed-loop Hebbian path tracing)
9+
- **Cortex** — Intelligent routing & coherence (Metroid construction `{ m1, m2, c }`, dialectical search, Matryoshka dimensional unwinding, knowledge gap detection, P2P curiosity broadcasting, parallel WebGPU scoops, IndexedDB sub-graph retrieval, closed-loop Hebbian path tracing)
1010
- **Daydreamer** — Background consolidation Web Worker (LTP/LTD, pruning, medoid recomputation, experience replay)
1111

1212
## Key Documentation Files

‎ARCHITECTURE-REVIEW.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
# CORTEX Architecture Review — Naming Drift Report
2+
3+
**Date:** 2026-03-13
4+
**Scope:** Full repository audit against corrected DESIGN.md (v1.2)
5+
**Status:** Documentation-only pass; no code changes made in this review
6+
7+
---
8+
9+
## Executive Summary
10+
11+
The repository has drifted from the intended CORTEX architecture due to an early conceptual collapse between **medoids** and **Metroids**. This caused the term "Metroid" to be applied throughout the codebase and documentation to describe the sparse proximity/neighbor graph connecting pages — a fundamentally different concept.
12+
13+
The correct meaning of each term is:
14+
15+
| Term | Correct Meaning |
16+
|------|----------------|
17+
| **Medoid** | An existing memory node selected as a cluster representative via the medoid statistic |
18+
| **Centroid** | A mathematical average of vectors — a computed point, never a stored node |
19+
| **Metroid** | A structured dialectical search probe: `{ m1, m2, c }` — ephemeral, constructed at query time |
20+
21+
The sparse proximity graph connecting pages with high cosine similarity is **not** a Metroid. It is the **semantic neighbor graph**. The entire MetroidBuilder component — the heart of CORTEX's epistemic search capability — does not yet exist in the codebase.
22+
23+
This report catalogs every divergence found and maps each to a correction task in TODO.md.
24+
25+
---
26+
27+
## Divergence Catalog
28+
29+
### D1 — `core/types.ts`: `MetroidNeighbor` interface
30+
31+
| Field | Value |
32+
|-------|-------|
33+
| **File** | `core/types.ts` |
34+
| **Line** | ~70 |
35+
| **Component** | `MetroidNeighbor` interface |
36+
| **Current behavior** | Defines a sparse proximity graph edge with `neighborPageId`, `cosineSimilarity`, and `distance`. Named as if it represents a "Metroid" concept. |
37+
| **Intended behavior** | This is a proximity edge in the semantic neighbor graph. It has nothing to do with the `Metroid = { m1, m2, c }` dialectical probe. Should be named `SemanticNeighbor`. |
38+
| **Required correction** | Rename `MetroidNeighbor` → `SemanticNeighbor`. Update all references. |
39+
| **TODO task** | P0-X1 |
40+
41+
---
42+
43+
### D2 — `core/types.ts`: `MetroidSubgraph` interface
44+
45+
| Field | Value |
46+
|-------|-------|
47+
| **File** | `core/types.ts` |
48+
| **Line** | ~76 |
49+
| **Component** | `MetroidSubgraph` interface |
50+
| **Current behavior** | Defines the induced subgraph used for BFS expansion during retrieval. Named "MetroidSubgraph". |
51+
| **Intended behavior** | This is a semantic neighbor subgraph, not a Metroid. Should be named `SemanticNeighborSubgraph`. |
52+
| **Required correction** | Rename `MetroidSubgraph` → `SemanticNeighborSubgraph`. |
53+
| **TODO task** | P0-X2 |
54+
55+
---
56+
57+
### D3 — `core/types.ts`: `MetadataStore` proximity graph methods
58+
59+
| Field | Value |
60+
|-------|-------|
61+
| **File** | `core/types.ts` |
62+
| **Lines** | ~178–191 |
63+
| **Component** | `MetadataStore` interface — methods section "Metroid NN radius index" |
64+
| **Current behavior** | Six methods use "Metroid" naming: `putMetroidNeighbors`, `getMetroidNeighbors`, `getInducedMetroidSubgraph`, `needsMetroidRecalc`, `flagVolumeForMetroidRecalc`, `clearMetroidRecalcFlag`. |
65+
| **Intended behavior** | These methods operate on the semantic neighbor graph (a proximity graph). "Metroid" in method names implies a connection to the dialectical probe construct, which is incorrect. |
66+
| **Required correction** | Rename all six methods: `putSemanticNeighbors`, `getSemanticNeighbors`, `getInducedNeighborSubgraph`, `needsNeighborRecalc`, `flagVolumeForNeighborRecalc`, `clearNeighborRecalcFlag`. |
67+
| **TODO task** | P0-X3 |
68+
69+
---
70+
71+
### D4 — `storage/IndexedDbMetadataStore.ts`: `metroid_neighbors` IDB store
72+
73+
| Field | Value |
74+
|-------|-------|
75+
| **File** | `storage/IndexedDbMetadataStore.ts` |
76+
| **Lines** | ~32–35 (DB store declarations) |
77+
| **Component** | IndexedDB object store named `metroid_neighbors` |
78+
| **Current behavior** | Persists proximity graph edges between pages in a store named `metroid_neighbors`. |
79+
| **Intended behavior** | The store name should reflect that it holds semantic proximity edges, not Metroid probes. Should be `neighbor_graph`. |
80+
| **Required correction** | Rename IDB store from `metroid_neighbors` → `neighbor_graph`. Increment `DB_VERSION`. Add migration in `applyUpgrade` to copy existing data. |
81+
| **TODO task** | P0-X6 |
82+
83+
---
84+
85+
### D5 — `storage/IndexedDbMetadataStore.ts`: proximity graph method implementations
86+
87+
| Field | Value |
88+
|-------|-------|
89+
| **File** | `storage/IndexedDbMetadataStore.ts` |
90+
| **Lines** | All methods implementing `MetadataStore` proximity graph interface |
91+
| **Component** | `putMetroidNeighbors`, `getMetroidNeighbors`, `getInducedMetroidSubgraph`, `needsMetroidRecalc`, `flagVolumeForMetroidRecalc`, `clearMetroidRecalcFlag` implementations |
92+
| **Current behavior** | Implements the six methods using `MetroidNeighbor` types and `metroid_neighbors` IDB store. |
93+
| **Intended behavior** | Should use renamed types and store. |
94+
| **Required correction** | After interface rename (D1–D4), update all implementations to use new names. |
95+
| **TODO task** | P0-X1–X6 |
96+
97+
---
98+
99+
### D6 — `cortex/Query.ts`: Absent MetroidBuilder
100+
101+
| Field | Value |
102+
|-------|-------|
103+
| **File** | `cortex/Query.ts` |
104+
| **Lines** | Entire file |
105+
| **Component** | `query()` function |
106+
| **Current behavior** | Embeds query, scores hotpath pages, falls back to full scan, updates PageActivity, runs promotion sweep. Returns a ranked list of pages. **No Metroid is ever constructed. No dialectical search is performed. No knowledge gap is ever detected.** |
107+
| **Intended behavior** | The query path should: (1) select m1 (topic medoid), (2) call MetroidBuilder to construct `{ m1, m2, c }`, (3) use centroid `c` as the balanced search anchor, (4) explore thesis/antithesis/synthesis zones, (5) detect and surface knowledge gaps. |
108+
| **Required correction** | After MetroidBuilder is implemented (P1-M), upgrade `cortex/Query.ts` to include the full dialectical pipeline (P1-E). |
109+
| **TODO task** | P1-E1 |
110+
111+
---
112+
113+
### D7 — `cortex/Query.ts`: `getInducedMetroidSubgraph` call
114+
115+
| Field | Value |
116+
|-------|-------|
117+
| **File** | `cortex/Query.ts` |
118+
| **Lines** | The subgraph expansion step (BFS, if present) |
119+
| **Component** | Subgraph expansion via `MetadataStore` |
120+
| **Current behavior** | If subgraph BFS is called, it uses `getInducedMetroidSubgraph`, propagating the incorrect naming. |
121+
| **Intended behavior** | Should call `getInducedNeighborSubgraph` (after rename). |
122+
| **Required correction** | Rename the method call after P0-X3 is complete. |
123+
| **TODO task** | P0-X3 |
124+
125+
---
126+
127+
### D8 — DESIGN.md (pre-correction): Incorrect Terminology
128+
129+
| Field | Value |
130+
|-------|-------|
131+
| **File** | `DESIGN.md` (pre-v1.2) |
132+
| **Component** | Terminology section |
133+
| **Current behavior** | Defined "Metroid (canonical domain term): Sparse nearest-neighbor graph structure inspired by medoid-based clustering." This is architecturally incorrect. |
134+
| **Intended behavior** | Metroid = dialectical probe `{ m1, m2, c }`. The sparse NN graph is the semantic neighbor graph. |
135+
| **Required correction** | **Already corrected in DESIGN.md v1.2.** |
136+
| **TODO task** | Resolved |
137+
138+
---
139+
140+
### D9 — DESIGN.md (pre-correction): Missing MetroidBuilder, Dialectical Search, Knowledge Gap
141+
142+
| Field | Value |
143+
|-------|-------|
144+
| **File** | `DESIGN.md` (pre-v1.2) |
145+
| **Component** | Entire document |
146+
| **Current behavior** | No section describing MetroidBuilder, Matryoshka dimensional unwinding, antithesis discovery, dialectical search, or knowledge gap detection. |
147+
| **Intended behavior** | These are core architectural concepts that must be described for any engineer to implement CORTEX correctly. |
148+
| **Required correction** | **Already corrected in DESIGN.md v1.2** — new section "Conceptual Constructs: Medoid, Centroid, and Metroid" added. |
149+
| **TODO task** | Resolved |
150+
151+
---
152+
153+
### D10 — PLAN.md (pre-correction): "Metroid vs medoid" note
154+
155+
| Field | Value |
156+
|-------|-------|
157+
| **File** | `PLAN.md` (pre-v1.2) |
158+
| **Component** | Notes section |
159+
| **Current behavior** | Note read: "Metroid vs medoid: Use Metroid in all API surfaces and docs; medoid only in algorithmic comments." This instructs developers to use the wrong term everywhere, making MetroidBuilder impossible to introduce without collision. |
160+
| **Intended behavior** | The note must distinguish three concepts: Metroid (dialectical probe), medoid (cluster representative), and semantic neighbor graph (proximity graph for BFS). |
161+
| **Required correction** | **Already corrected in PLAN.md v1.2.** |
162+
| **TODO task** | Resolved |
163+
164+
---
165+
166+
### D11 — `PLAN.md` (pre-correction): Missing MetroidBuilder in CORTEX module table
167+
168+
| Field | Value |
169+
|-------|-------|
170+
| **File** | `PLAN.md` (pre-v1.2) |
171+
| **Component** | CORTEX module table |
172+
| **Current behavior** | No MetroidBuilder, KnowledgeGapDetector, or DialecticalSearch pipeline listed as planned modules. |
173+
| **Intended behavior** | These are critical CORTEX components without which the system is merely a vector search engine. |
174+
| **Required correction** | **Already corrected in PLAN.md v1.2** — new rows added. |
175+
| **TODO task** | Resolved |
176+
177+
---
178+
179+
### D12 — `hippocampus/Ingest.ts`: Semantic neighbor insertion absent
180+
181+
| Field | Value |
182+
|-------|-------|
183+
| **File** | `hippocampus/Ingest.ts` |
184+
| **Lines** | Entire file |
185+
| **Component** | `ingestText()` function |
186+
| **Current behavior** | Chunks, embeds, persists pages, builds a book, runs promotion sweep. Does **not** insert semantic neighbor edges. |
187+
| **Intended behavior** | After persisting pages, should call `FastNeighborInsert` to maintain the semantic neighbor graph with Williams-bounded degree. |
188+
| **Required correction** | After `FastNeighborInsert` is implemented (P1-C), upgrade `ingestText` to call it (P1-C2). |
189+
| **TODO task** | P1-C2 |
190+
191+
---
192+
193+
### D13 — `core/types.ts`: No Metroid type defined
194+
195+
| Field | Value |
196+
|-------|-------|
197+
| **File** | `core/types.ts` |
198+
| **Component** | Type definitions |
199+
| **Current behavior** | The word "Metroid" appears only as part of `MetroidNeighbor`, `MetroidSubgraph`, and `MetadataStore` method names — all of which are proximity-graph concepts. The **actual Metroid type** `{ m1, m2, c }` does not exist. |
200+
| **Intended behavior** | `core/types.ts` should define: `interface Metroid { m1: Hash; m2: Hash | null; centroid: Float32Array | null; knowledgeGap: boolean }` and `interface KnowledgeGap { topicMedoidId: Hash; queryEmbedding: Float32Array; dimensionalBoundary: number; timestamp: string }`. |
201+
| **Required correction** | Add these types to `core/types.ts` as part of MetroidBuilder implementation (P1-M). |
202+
| **TODO task** | P1-M1 |
203+
204+
---
205+
206+
### D14 — `core/types.ts`: No `matryoshkaProtectedDim` in `ModelProfile`
207+
208+
| Field | Value |
209+
|-------|-------|
210+
| **File** | `core/ModelProfile.ts` |
211+
| **Component** | `ModelProfile` interface |
212+
| **Current behavior** | No field for the protected Matryoshka dimension boundary. |
213+
| **Intended behavior** | MetroidBuilder needs to know which lower dimensions to freeze during antithesis search. `ModelProfile` should include `matryoshkaProtectedDim: number` — the number of lower dimensions that encode invariant semantic context. |
214+
| **Required correction** | Add `matryoshkaProtectedDim` to `ModelProfile` interface; add default value to `ModelDefaults.ts`; add per-model value to `BuiltInModelProfiles.ts`. |
215+
| **TODO task** | P1-M1 (prerequisite) |
216+
217+
---
218+
219+
### D15 — `cortex/QueryResult.ts`: No Metroid or knowledge gap fields
220+
221+
| Field | Value |
222+
|-------|-------|
223+
| **File** | `cortex/QueryResult.ts` |
224+
| **Component** | `QueryResult` interface |
225+
| **Current behavior** | Contains only `pages`, `scores`, and `metadata`. No field for Metroid probe used, no knowledge gap field. |
226+
| **Intended behavior** | Should include `metroid`, `knowledgeGap`, `coherencePath`, and `provenance` fields (see P1-E2). |
227+
| **Required correction** | Upgrade `QueryResult` as part of P1-E2. |
228+
| **TODO task** | P1-E2 |
229+
230+
---
231+
232+
## Summary by Severity
233+
234+
| Severity | Count | Description |
235+
|----------|-------|-------------|
236+
| **Critical (blocks MetroidBuilder)** | 3 | D1, D2, D3 — type/interface naming collision |
237+
| **High (architectural gap)** | 4 | D4, D6, D13, D14 — missing types and IDB store |
238+
| **Medium (propagated naming error)** | 4 | D5, D7, D12, D15 — implementations following wrong names |
239+
| **Resolved by this PR** | 4 | D8, D9, D10, D11 — corrected in DESIGN.md v1.2 and PLAN.md v1.2 |
240+
241+
**Total: 15 divergences** (3 + 4 + 4 + 4)
242+
243+
---
244+
245+
## Components with Zero Drift
246+
247+
The following components correctly implement their intended architecture and require no changes related to this review:
248+
249+
- `core/HotpathPolicy.ts` — Williams Bound policy implementation; correct
250+
- `core/SalienceEngine.ts` — Promotion/eviction lifecycle; correct
251+
- `core/crypto/` — Hash, sign, verify; correct
252+
- `storage/OPFSVectorStore.ts` — Append-only vector file; correct
253+
- `storage/MemoryVectorStore.ts` — In-memory testing backend; correct
254+
- `embeddings/` — All embedding providers; correct
255+
- `hippocampus/Chunker.ts` — Text chunking; correct
256+
- `hippocampus/PageBuilder.ts` — Page entity construction; correct
257+
- All `VectorBackend` implementations — correct
258+
259+
---
260+
261+
## Recommended Fix Order
262+
263+
1. **P0-X1–X7** — Fix naming drift in `core/types.ts`, `storage/IndexedDbMetadataStore.ts`, `cortex/Query.ts`, and planned file names. This unblocks MetroidBuilder without risking collision.
264+
2. **P1-M1–M3** — Add `Metroid` and `KnowledgeGap` types; implement `MetroidBuilder`.
265+
3. **P1-N1–N4** — Implement `KnowledgeGapDetector`.
266+
4. **P1-E1–E3** — Upgrade `cortex/Query.ts` to full dialectical orchestrator.
267+
5. **P1-C1–C3** — Implement `FastNeighborInsert` (correctly named after P0-X).

0 commit comments

Comments
 (0)