Skip to content

Commit a298191

Browse files
devlux76devlux76
committed
feat: Add runtime harness direction and verification details; retire legacy design notes and enhance execution plan
1 parent c003865 commit a298191

2 files changed

Lines changed: 85 additions & 11 deletions

File tree

‎CORTEX-DESIGN-PLAN-TODO.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,20 @@ Their durable content is preserved as canonical implementation/doc contracts:
5454
4. Model-derived numeric ownership is canonical in `core/ModelDefaults.ts`, `core/ModelProfileResolver.ts`, and `Policy.ts`.
5555
5. Naming convention is settled: use `Metroid` for project-domain graph terms; keep `medoid` only when referring to the underlying clustering statistic.
5656

57+
### 0.3 Runtime Harness Direction (2026-03-11)
58+
59+
Decision from runtime research and hotpath verification:
60+
1. Keep the test harness browser-first; do not fork into a large Electron-specific app shell.
61+
2. Use one renderer harness that can run unchanged in Chromium and Electron.
62+
3. Wrap it in a thin Electron launcher for Linux GPU/WebGPU realism, switch control, and GPU diagnostics.
63+
4. Keep Chromium as the web-parity lane and Electron as the primary runtime-realism lane.
64+
5. Serve the harness over localhost during development/testing so WebGPU secure-context requirements are satisfied.
65+
66+
Why this direction won:
67+
1. Electron retains Chromium's WebGPU path and limitations, so it is realistic instead of synthetic.
68+
2. Electron gives better observability than raw browser automation on Linux (`app.commandLine`, GPU feature status/info).
69+
3. The current missing confidence is browser-runtime execution, not WASM kernel validity; `Vectors.wat` and the dummy embedder hotpaths have already been executed successfully in ad hoc verification.
70+
5771
## 1. Design
5872

5973
### 1.1 Product contract

‎PROJECT-EXECUTION-PLAN.md‎

Lines changed: 71 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,33 @@ Completed in this pass:
3636
- `embeddings/EmbeddingRunner.ts`
3737
- tests: `tests/embeddings/ProviderResolver.test.ts`, `tests/embeddings/EmbeddingRunner.test.ts`
3838
- selection now supports capability filtering + benchmark-based winner choice
39+
11. Retired legacy design-note docs after full code/doc audit and preserved canonical pointers in current docs.
40+
12. Verified current hotpath elements compile/run in this workspace state:
41+
- `npm run build`
42+
- `npm run benchmark:dummy`
43+
- ad hoc `Vectors.wat` compile + instantiate + export smoke (`dot_many`, `project`, `hash_binary`, `hamming_scores`, `topk_i32`, `topk_f32`) via transient `wabt`
3944

4045
Open items carried to next pass:
4146
1. Wire resolved `ModelProfile` into first concrete ingest/query orchestrator path.
4247
2. Add real embedding providers (ONNX/Transformers/WebNN/WebGPU/WebGL/WASM) as candidates for the resolver.
4348
3. Add browser/electron runtime scripts and CI lanes for non-Node merge gating.
49+
4. Build the browser-first runtime harness described below and use it as the substrate for runtime-browser/runtime-electron lanes.
50+
51+
### Runtime Verification Snapshot (2026-03-11)
52+
53+
Verified directly in this workspace:
54+
1. TypeScript compile/typecheck passes.
55+
2. Dummy embedding hotpath benchmark executes successfully in Vitest bench mode.
56+
3. `Vectors.wat` is not just present as source text: it was compiled to wasm bytes and executed successfully through a one-off smoke harness.
57+
4. The current terminal-only Node runtime cannot execute browser GPU paths directly:
58+
- `document` is unavailable
59+
- `navigator.gpu` is unavailable
60+
- `navigator.ml` is unavailable
61+
62+
Interpretation:
63+
1. WASM and deterministic embedding hotpaths are validated.
64+
2. WebGPU/WebNN/WebGL paths still require a real browser/Electron runtime lane.
65+
3. The missing confidence is now runtime-environment realism, not core kernel syntax.
4466

4567
### External Capability Verification (2026-03-11)
4668

@@ -49,6 +71,13 @@ Verified during this pass (hard handoff facts):
4971
2. Transformers.js device mapping exposes `webnn`, `webnn-gpu`, `webnn-cpu`, `webnn-npu`, `webgpu`, and `wasm` for web environments.
5072
3. Transformers.js does not currently expose `webgl` as a direct `device` type; WebGL should remain an explicit ORT adapter path.
5173
4. Node-side ONNX providers (platform-dependent) include `cuda`, `dml`, and `coreml` in upstream mapping.
74+
5. Electron inherits Chromium GPU/WebGPU capability rather than bypassing it; it is still subject to host GPU drivers and Linux graphics stack limitations.
75+
6. Electron is still the preferred Linux realism harness because it gives explicit Chromium switch control via `app.commandLine.appendSwitch(...)` before `ready`, plus GPU diagnostics via `app.getGPUFeatureStatus()` / `app.getGPUInfo()` after `gpu-info-update`.
76+
7. Chrome WebGPU guidance confirms Linux support exists but can still require environment fixes when `navigator.gpu` is undefined or `requestAdapter()` returns `null`:
77+
- secure context is required (`http://localhost` is acceptable for local dev)
78+
- hardware acceleration must be enabled
79+
- Linux experimental cases may need unsafe WebGPU / Vulkan enablement
80+
- some hardware may require blocklist override for testing
5281

5382
Source anchors to re-check quickly in a new session:
5483
1. `huggingface/transformers.js` -> `packages/transformers/src/backends/onnx.js`:
@@ -58,21 +87,51 @@ Source anchors to re-check quickly in a new session:
5887
- `DEVICE_TYPES`
5988
3. Transformers.js docs (`v3.8.1` and `main`):
6089
- index + WebGPU guide + ONNX backend API pages
90+
4. Electron docs:
91+
- `app.commandLine.appendSwitch(...)`
92+
- `app.getGPUFeatureStatus()`
93+
- `app.getGPUInfo()`
94+
- `gpu-info-update`
95+
5. Chrome WebGPU troubleshooting docs:
96+
- secure-context requirement
97+
- Linux Vulkan / unsafe WebGPU notes
98+
- blocklist / hardware acceleration troubleshooting
99+
100+
### Runtime Harness Direction (2026-03-11)
101+
102+
Decision from this pass:
103+
1. Do not build a full Electron-first app shell just for testing.
104+
2. Build one browser-first harness page/app that can run unchanged in Chromium and Electron.
105+
3. Wrap that harness in a thin Electron launcher for Linux GPU realism and observability.
106+
4. Keep Chromium as the web-parity lane; use Electron as the primary GPU/runtime realism lane.
107+
5. Serve the harness over `http://127.0.0.1` / `http://localhost` during development and testing; do not rely on `file://` for WebGPU-sensitive execution.
61108

62109
## Next Session Highest Priority (P0)
63110

64-
Connect adaptive embedding selection to runtime orchestration and add real provider candidates.
111+
Stand up the browser-first runtime harness and thin Electron wrapper so real GPU/browser validation can begin, then connect adaptive embedding selection into that runtime path.
65112

66113
Instruction:
67-
1. Use `ModelProfileResolver` at runtime boundaries before any policy derivation or embedding execution.
68-
2. Register real embedding providers in `ProviderResolver` candidate lists.
69-
3. Keep strict TDD (Red -> Green -> Refactor).
70-
4. If a blocker appears, record it in this document under an error log entry and continue with the next actionable slice.
114+
1. Create a minimal harness renderer that reports:
115+
- `navigator.gpu` availability
116+
- adapter/device acquisition outcome
117+
- IndexedDB + OPFS availability
118+
- selected embedding backend/provider kind
119+
2. Add a thin Electron main-process wrapper that:
120+
- loads the same harness via localhost
121+
- appends required Chromium switches before `ready`
122+
- logs GPU feature status and GPU info after `gpu-info-update`
123+
3. Add Playwright coverage for two lanes:
124+
- Chromium web harness
125+
- Electron harness
126+
4. After the harness exists, register the first real embedding providers in `ProviderResolver` and test selection inside the real runtime lane.
127+
5. Keep strict TDD (Red -> Green -> Refactor).
128+
6. If a blocker appears, record it in this document under an error log entry and continue with the next actionable slice.
71129

72130
Definition of done for this pass:
73-
1. Runtime path resolves model metadata through `ModelProfileResolver` before use.
74-
2. At least one non-dummy real provider can be selected by capability + benchmark policy.
75-
3. Any unresolved blocker is documented with file/symptom/next action.
131+
1. A single renderer harness runs under both Chromium and Electron.
132+
2. Electron lane emits GPU capability diagnostics on Linux.
133+
3. At least one real provider candidate is wired into resolver selection from the runtime harness.
134+
4. Any unresolved blocker is documented with file/symptom/next action.
76135

77136
## Non-Negotiable Rules
78137

@@ -134,9 +193,10 @@ Available now:
134193

135194
Planned commands to add in later passes:
136195
1. `npm run test:unit -- tests/embeddings/OnnxEmbeddingRunner.test.ts`
137-
2. `npm run test:browser`
138-
3. `npm run test:electron`
139-
4. `npm run test:all`
196+
2. `npm run dev:harness`
197+
3. `npm run test:browser`
198+
4. `npm run test:electron`
199+
5. `npm run test:all`
140200

141201
## Known Hardcoded Hotspots To Clean First
142202

0 commit comments

Comments
 (0)