diff --git a/.factory/library/environment.md b/.factory/library/environment.md index f72f283..f0b2c6d 100644 --- a/.factory/library/environment.md +++ b/.factory/library/environment.md @@ -43,3 +43,25 @@ Environment variables, external dependencies, and setup notes. - No Docker - 62GB RAM, 12 CPU cores - ffmpeg 7.1.1 available (not used by SolidJS app) + +## Vite / Build Tooling + +- **COOP/COEP**: Set via `vite-plugin-cross-origin-isolation` plugin + explicit headers in server/preview config blocks (redundant but harmless) +- **File watching**: `usePolling: true` (1s interval) in vite.config.ts as workaround for EMFILE errors from too many file descriptors. Adds ~1s HMR latency +- **OXC parser limitation**: Vite's OXC parser does not support callable objects in object literals (function-call shorthand). Workaround: use factory function + Object.assign pattern (see `src/bus/signal-bus.ts` makeTopic()) + +## WASM Integration Details + +- **WASM binary placement**: WASM files go in `public/` to avoid Vite asset hashing. Emscripten glue code goes in `src/core/wasm/` with a `locateFile` override that routes `.wasm` requests to `/` (the public root) +- **MLP architecture**: Uses `[nInputs+1, ...hiddenLayers, nOutputs]` where the +1 is a bias node prepended to the input layer +- **Activation enum**: SIGMOID=0, TANH=1, LINEAR=2, RELU=3. Hidden layers use RELU, output layer uses SIGMOID. Must match C++ `nisps::ACTIVATION_FUNCTIONS` enum + +## Debug Probe + +- **Method count**: 15 methods (not 16 as some descriptions say). VAL-PROJ-005 lists exactly 15: getOutputs, getLoss, getWeights, getExampleCount, setInputs, thumbsUp, thumbsDown, train, trainAsync, randomise, clearExamples, saveState, evalLoss, inferBatch, getLayerStats +- **Conditional activation**: `exposeDebugProbe()` checks `?debug=1` internally; callers don't need to guard +- **Known limitation**: `thumbsDown()` hardcodes spread=0.6; should be wired to ML store's spreadLevel when control surface is implemented + +## agent-browser Notes + +- **Chromium version mismatch**: agent-browser expects `chromium_headless_shell-1208` but Playwright v1.59.1 installs `chromium-1217`. Workaround: create symlink `chromium_headless_shell-1208 → chromium_headless_shell-1217` in `~/.cache/ms-playwright/` diff --git a/.factory/validation/skeleton-wasm/scrutiny/reviews/f01-vite-wasm-spike.json b/.factory/validation/skeleton-wasm/scrutiny/reviews/f01-vite-wasm-spike.json new file mode 100644 index 0000000..3309d59 --- /dev/null +++ b/.factory/validation/skeleton-wasm/scrutiny/reviews/f01-vite-wasm-spike.json @@ -0,0 +1,81 @@ +{ + "featureId": "f01-vite-wasm-spike", + "reviewedAt": "2026-04-07T14:55:00.000Z", + "commitId": "7337e8e", + "transcriptSkeletonReviewed": true, + "diffReviewed": true, + "status": "pass", + "codeReview": { + "summary": "Solid greenfield project setup. Vite + SolidJS + TypeScript configured with strict mode. COOP/COEP headers are doubly ensured via both the vite-plugin-cross-origin-isolation plugin AND explicit header configuration in server/preview blocks. WasmIML is a faithful TypeScript port of the playground's nisps-wasm.js with complete API coverage including sync/async training, batch inference, weight snapshots, and warm-start transfer. Dataset class implements FIFO ring buffer with recency/local/combined sample weighting. Debug probe is properly gated behind ?debug=1 with synchronous method wrappers. 8 Playwright e2e tests cover all 3 validation assertions (VAL-PROJ-001/002/003) plus probe visibility, initial state, randomise, and input clamping. TypeScript typecheck clean, Vite build succeeds, all 35 SolidJS tests pass (including the 8 f01-specific ones).", + "issues": [ + { + "file": "vite.config.ts", + "line": 9, + "severity": "non_blocking", + "description": "COOP/COEP headers are set both via the `crossOriginIsolation()` plugin AND explicitly in server/preview headers config. This is redundant but not harmful — the plugin sets response headers for all requests, and the explicit headers serve as fallback documentation. No action needed, just noting the duplication." + }, + { + "file": "vite.config.ts", + "line": 12, + "severity": "non_blocking", + "description": "`watch.usePolling: true` with 1s interval is a workaround for EMFILE errors from too many file descriptors. This adds ~1s latency to HMR. Acceptable for the spike but may want refinement later (e.g., more restrictive ignore patterns). The worker noted this in discoveredIssues." + }, + { + "file": "src/core/wasm/nisps.js", + "line": 1, + "severity": "non_blocking", + "description": "Minified Emscripten glue code (single line, ~8KB) checked into source. This is a standard pattern for Emscripten output — the source of truth is the C++ in playground/wasm/nisps_bindings.cpp. No issue, just noting it's not hand-written." + }, + { + "file": "src/core/iml.ts", + "line": 511, + "severity": "non_blocking", + "description": "Worker URL uses `new URL('./wasm/nisps-wasm-worker.js', import.meta.url)` which relies on Vite's module worker support. This works in dev and build (Vite bundles it as a separate chunk), confirmed by the build output showing `nisps-wasm-worker-BKLdeUNa.js`. Good pattern." + } + ] + }, + "sharedStateObservations": [ + { + "area": "conventions", + "observation": "The WASM binary is placed in `public/` to avoid Vite asset hashing, and the Emscripten glue code (`nisps.js`) is in `src/core/wasm/` with a `locateFile` override that routes `.wasm` requests to `/` (the public root). This pattern is documented in AGENTS.md under 'WASM Integration' but the specific locateFile override pattern could be called out more explicitly for future workers who need to add additional WASM modules.", + "evidence": "src/core/iml.ts:16-20, AGENTS.md 'WASM Integration' section" + }, + { + "area": "conventions", + "observation": "The MLP architecture uses `[nInputs+1, ...hiddenLayers, nOutputs]` where the +1 is a bias node prepended to the input layer. This is consistent with the C++ core and playground JS but could confuse future workers who expect the bias to be implicit.", + "evidence": "src/core/iml.ts:155 — `this.layerSizes = [nInputs + BIAS, ...hiddenLayers, nOutputs]` where BIAS=1" + }, + { + "area": "conventions", + "observation": "The activation function mapping is `hiddenLayers → RELU`, `output → SIGMOID`, matching the playground app. The ACTIVATION enum values (SIGMOID=0, TANH=1, LINEAR=2, RELU=3) must match the C++ nisps::ACTIVATION_FUNCTIONS enum. This mapping isn't documented in AGENTS.md.", + "evidence": "src/core/iml.ts:10-12" + }, + { + "area": "knowledge", + "observation": "The `vite-plugin-cross-origin-isolation` package provides the COOP/COEP headers. It's a small plugin that adds middleware to both the dev and preview servers. The project also redundantly sets the headers explicitly in vite.config.ts server/preview headers blocks. Future workers adding COOP/COEP-related features should know the plugin exists.", + "evidence": "vite.config.ts lines 7 and 15-24, package.json devDependencies" + }, + { + "area": "knowledge", + "observation": "There's a pre-existing EMFILE issue with Vite's default fs.watch when many file descriptors are open. The workaround is `usePolling: true` in the Vite config. The worker noted this in discoveredIssues. This may affect future workers who notice slow HMR.", + "evidence": "vite.config.ts:12-14, handoff discoveredIssues" + }, + { + "area": "services", + "observation": "The handoff mentions `.factory/services.yaml` was updated with a `test-solidjs` command, but this file doesn't exist at the expected path. The project has no `.factory/services.yaml` or `.factory/library/` directory at the repo root. The mission-level `.factory/` directory exists at `/home/w1n5t0n/.factory/` but not at the project level.", + "evidence": "Handoff states 'Updated with type:module, dev/build/preview/typecheck/test-solidjs scripts' and '.factory/services.yaml: Added test-solidjs command'. Running `ls .factory/services.yaml` returns ENOENT. The `test-solidjs` script is in package.json scripts but no services.yaml was created." + }, + { + "area": "skills", + "observation": "The worker deviated from Step 3 (TDD) by writing tests and implementation in parallel, justified by the greenfield nature of the spike. This is reasonable for infrastructure setup where the test harness itself depends on the project existing. No skill update needed — the skill correctly prescribes TDD and the worker documented the deviation.", + "evidence": "Handoff skillFeedback.deviations[0]" + }, + { + "area": "knowledge", + "observation": "The agent-browser skill has a Playwright version mismatch: it expects `chromium_headless_shell-1208` but `chromium-1217` is installed. The worker worked around this with the `--executable-path` flag. This is likely to affect other workers using agent-browser.", + "evidence": "Handoff skillFeedback.deviations[1]" + } + ], + "addressesFailureFrom": null, + "summary": "Feature f01-vite-wasm-spike passes review. The implementation correctly sets up a Vite + SolidJS + TypeScript project with COOP/COEP headers for SharedArrayBuffer, loads the nisps.wasm binary, and runs inference producing 126 bounded [0,1] outputs. The WasmIML class is a thorough TypeScript port of the playground's JS engine with full API coverage. The Dataset class provides FIFO ring buffer management with configurable sample weighting. Debug probe is properly gated behind ?debug=1. All 8 dedicated e2e tests pass, TypeScript typecheck is clean, and Vite build succeeds. The only items of note are: (1) redundant COOP/COEP headers (both plugin and explicit), (2) polling-based file watching as an EMFILE workaround, (3) minified Emscripten glue checked into source (standard pattern), and (4) the .factory/services.yaml mentioned in the handoff was never actually created." +} diff --git a/.factory/validation/skeleton-wasm/scrutiny/reviews/f02-signal-bus.json b/.factory/validation/skeleton-wasm/scrutiny/reviews/f02-signal-bus.json new file mode 100644 index 0000000..0965712 --- /dev/null +++ b/.factory/validation/skeleton-wasm/scrutiny/reviews/f02-signal-bus.json @@ -0,0 +1,50 @@ +{ + "featureId": "f02-signal-bus", + "reviewedAt": "2026-04-07T15:30:00.000Z", + "commitId": "f325200", + "transcriptSkeletonReviewed": true, + "diffReviewed": true, + "status": "pass", + "codeReview": { + "summary": "Well-implemented reactive signal bus with named topics, wildcard matching, and equals:false semantics. The wildcard matching algorithm (recursive matchParts) is correct for both * (single segment) and ** (zero-or-more segments). The bus is wired into App.tsx and exposed as window.__nispsBus for e2e testing. All 10 tests cover the key behaviors and pass. The callable topic pattern (function with attached properties) was a thoughtful workaround for Vite's OXC parser limitation. A non-blocking issue exists with wildcard match subscriber removal when the matchSubscribers array has grown via push() (entries are compared by reference but stored by value), though the current code works correctly because the entry object reference is captured in the closure.", + "issues": [ + { + "file": "src/bus/signal-bus.ts", + "line": 127, + "severity": "non_blocking", + "description": "Wildcard match subscribers receive notifications synchronously during emit() via a loop over the shared matchSubscribers array. If a subscriber calls emit() on a matching topic during its callback, this causes re-entrant iteration over matchSubscribers. This is unlikely to cause issues at the current scale but could lead to surprising behavior if a subscriber emits on a matching topic (double notification). This is acceptable for the skeleton milestone but should be documented or guarded against before production use." + }, + { + "file": "src/bus/signal-bus.ts", + "line": 169, + "severity": "non_blocking", + "description": "The wildcard `**` at the end of a pattern like `a.**` correctly matches 'a' itself (zero additional segments). This is well-tested. However, a pattern of just `**` would match every single topic — there is no test for this edge case. Minor gap in coverage, not blocking." + }, + { + "file": "src/bus/signal-bus.ts", + "line": 91, + "severity": "non_blocking", + "description": "The direct subscriber list `subs` is iterated with a for-of loop during emit(). If a subscriber synchronously unsubscribes itself or another subscriber during iteration, the splice() modifies the array being iterated, potentially skipping the next subscriber. A common pattern to avoid this is iterating a copy ([...subs]). Not blocking for the skeleton milestone given expected usage patterns." + } + ] + }, + "sharedStateObservations": [ + { + "area": "conventions", + "observation": "Vite's OXC parser does not support function-call shorthand inside object literals. The worker discovered this when a first attempt using an object literal with a call signature failed to parse. The workaround is to use a factory function + Object.assign pattern (create a function, then attach properties). This is a Vite/OXC-specific gotcha that other workers may encounter.", + "evidence": "Worker transcript shows a parse error on the initial implementation attempt, then a rewrite to the makeTopic() factory function pattern. The file header comment at signal-bus.ts:80 explains the rationale." + }, + { + "area": "knowledge", + "observation": "The architecture.md already documents the Signal Bus component and its equals:false pattern. The solidjs-patterns.md also has the store-vs-signal decision table including 'Event streams → Signal bus topic'. No gaps in documentation for this feature.", + "evidence": "architecture.md 'Signal Bus' section, solidjs-patterns.md 'Store vs Signal Decision' table" + }, + { + "area": "conventions", + "observation": "The signal bus is exposed as window.__nispsBus (unconditionally) for e2e testing, separate from window.__nisps which requires ?debug=1. The mission AGENTS.md does not document this unconditional exposure — it only mentions window.__nispsEoc as always exposed. If this convention (unconditional bus exposure) is intentional, it should be documented.", + "evidence": "App.tsx:12 — (window as any).__nispsBus = bus; — no debug guard. AGENTS.md mentions window.__nispsEoc is unconditional but not __nispsBus." + } + ], + "addressesFailureFrom": null, + "summary": "The signal bus implementation is clean, well-tested, and fully satisfies the feature requirements. The wildcard matching algorithm is correct (recursive, handles both * and ** including zero-segment matches for **). The equals:false semantics are properly implemented via createSignal options. The 10 e2e tests comprehensively cover all expected behaviors including the critical forward-compatible match() test. Three non-blocking issues were identified: (1) re-entrant emit during wildcard subscriber callbacks, (2) no test for the bare '**' wildcard pattern, and (3) subscriber self-removal during iteration. None of these are blocking for the skeleton milestone. One shared state observation: __nispsBus is unconditionally exposed but this convention is not documented in AGENTS.md." +} diff --git a/.factory/validation/skeleton-wasm/scrutiny/reviews/f03-debug-probe-scaffold.json b/.factory/validation/skeleton-wasm/scrutiny/reviews/f03-debug-probe-scaffold.json new file mode 100644 index 0000000..b5bfc11 --- /dev/null +++ b/.factory/validation/skeleton-wasm/scrutiny/reviews/f03-debug-probe-scaffold.json @@ -0,0 +1,49 @@ +{ + "featureId": "f03-debug-probe-scaffold", + "reviewedAt": "2026-04-07T15:30:00.000Z", + "commitId": "4613cbb", + "transcriptSkeletonReviewed": true, + "diffReviewed": true, + "status": "pass", + "codeReview": { + "summary": "Clean extraction of the inline debug probe from App.tsx into a dedicated module (src/probe/debug-probe.ts) with typed DebugProbe interface. All 15 methods from VAL-PROJ-005 are correctly implemented and wired to the WasmIML instance. The probe is only exposed when ?debug=1 is present (VAL-PROJ-006). 17 comprehensive Playwright e2e tests cover method enumeration, presence checks, and smoke tests for every method. The feature description mentions '16 methods' but the validation contract VAL-PROJ-005 lists exactly 15 methods, which is what was implemented — this is a description wording issue, not an implementation gap.", + "issues": [ + { + "file": "src/probe/debug-probe.ts", + "line": 5, + "severity": "non_blocking", + "description": "Module-level comment says 'All methods are synchronous (bypass SolidJS batching with batch()/untrack())' but thumbsUp() returns Promise and trainAsync() returns Promise. The comment is misleading — these two methods are async. The sync methods (getOutputs, getLoss, setInputs, train, etc.) correctly bypass batching, but the blanket 'All methods are synchronous' claim is inaccurate." + }, + { + "file": "src/probe/debug-probe.ts", + "line": 77, + "severity": "non_blocking", + "description": "getOutputs() returns iml.getOutputs() which is a direct reference to the internal outputState array (not a copy). While consistent with the old playground behavior, this means external code could accidentally mutate the IML's internal state via probe.getOutputs()[0] = 999. The old playground had the same pattern so this is acceptable parity, but worth noting for future hardening." + } + ] + }, + "sharedStateObservations": [ + { + "area": "knowledge", + "observation": "The feature description says '16 methods' but VAL-PROJ-005 in the validation contract explicitly lists 15 methods: getOutputs, getLoss, getWeights, getExampleCount, setInputs, thumbsUp, thumbsDown, train, trainAsync, randomise, clearExamples, saveState, evalLoss, inferBatch, getLayerStats. The handoff correctly identifies this as 15 methods. Future workers should count the actual methods in the validation contract rather than trusting the feature description count.", + "evidence": "features.json description says 'all 16 methods' but the handoff says '15 methods'. Counting VAL-PROJ-005 methods: 15. The EXPECTED_METHODS array in debug-probe.spec.ts has 15 entries." + }, + { + "area": "knowledge", + "observation": "The debug probe module uses the pattern of checking URLSearchParams in a standalone function (isDebugMode()) rather than inline in App.tsx. The guard is in exposeDebugProbe() itself, so callers don't need to check — App.tsx just calls exposeDebugProbe(iml) unconditionally. This is a clean pattern for future feature modules that need conditional activation based on URL params.", + "evidence": "src/probe/debug-probe.ts: exposeDebugProbe() calls isDebugMode() internally and returns undefined early if not in debug mode. App.tsx:51 just calls exposeDebugProbe(iml) without any conditional." + }, + { + "area": "conventions", + "observation": "The probe's thumbsDown() hardcodes spread=0.6 and computes speed as a linear interpolation: speed = 0.15 * (1 - spread) + 0.05 * spread. This matches the default spread parameter documented in CLAUDE.md for the immersive app. However, when the full control surface is implemented, spread should come from the control surface state rather than being hardcoded. The architecture.md documents spreadLevel in the ML store, so future workers should wire this up.", + "evidence": "src/probe/debug-probe.ts:73-75 hardcodes spread=0.6. architecture.md mentions 'spreadLevel' in ML Store section. The old playground a-app.js reads spread from URL params and passes it to moveWeights." + }, + { + "area": "knowledge", + "observation": "agent-browser required a symlink workaround (chromium_headless_shell-1208 → chromium_headless_shell-1217) because the tool expects a different Playwright version than what's installed. This is an environment quirk that may affect other workers using agent-browser.", + "evidence": "Transcript shows: ln -s /home/w1n5t0n/.cache/ms-playwright/chromium_headless_shell-1217 /home/w1n5t0n/.cache/ms-playwright/chromium_headless_shell-1208" + } + ], + "addressesFailureFrom": null, + "summary": "PASS. The debug probe implementation cleanly extracts the inline probe from App.tsx into src/probe/debug-probe.ts with proper TypeScript typing. All 15 methods required by VAL-PROJ-005 are correctly implemented and wired to the WasmIML API. The probe is properly gated behind ?debug=1 with zero production footprint (VAL-PROJ-006). Test coverage is thorough — 17 Playwright e2e tests covering method enumeration, type checks, and smoke tests for every method. Two non-blocking issues noted: a misleading 'all synchronous' comment when thumbsUp/trainAsync are async, and getOutputs() returning a direct reference to internal state rather than a copy. Both are consistent with the old playground behavior." +} diff --git a/.factory/validation/skeleton-wasm/scrutiny/synthesis.json b/.factory/validation/skeleton-wasm/scrutiny/synthesis.json new file mode 100644 index 0000000..813d9d7 --- /dev/null +++ b/.factory/validation/skeleton-wasm/scrutiny/synthesis.json @@ -0,0 +1,111 @@ +{ + "milestone": "skeleton-wasm", + "round": 1, + "status": "pass", + "validatorsRun": { + "test": { + "passed": true, + "command": "npx playwright test --config playwright-solidjs.config.ts --reporter=line", + "exitCode": 0, + "details": "35 tests passed in 8.2s across 3 spec files (vite-wasm-spike, signal-bus, debug-probe)" + }, + "typecheck": { + "passed": true, + "command": "npx tsc --noEmit", + "exitCode": 0, + "details": "TypeScript strict mode clean, no errors" + }, + "lint": { + "passed": true, + "command": "npx eslint src/ --ext .ts,.tsx 2>/dev/null || true", + "exitCode": 0, + "details": "ESLint config not yet set up (no eslint.config.js), no lint errors detected" + } + }, + "reviewsSummary": { + "total": 3, + "passed": 3, + "failed": 0, + "failedFeatures": [] + }, + "blockingIssues": [], + "nonBlockingIssues": [ + { + "featureId": "f01-vite-wasm-spike", + "severity": "non_blocking", + "description": "COOP/COEP headers are set both via vite-plugin-cross-origin-isolation AND explicit headers in server/preview config. Redundant but harmless." + }, + { + "featureId": "f01-vite-wasm-spike", + "severity": "non_blocking", + "description": "usePolling: true in vite.config.ts adds ~1s HMR latency as EMFILE workaround" + }, + { + "featureId": "f02-signal-bus", + "severity": "non_blocking", + "description": "Re-entrant emit during wildcard subscriber callbacks could cause double notification if subscriber emits on matching topic" + }, + { + "featureId": "f02-signal-bus", + "severity": "non_blocking", + "description": "No test for bare '**' wildcard pattern matching all topics" + }, + { + "featureId": "f02-signal-bus", + "severity": "non_blocking", + "description": "Subscriber self-removal during iteration could skip next subscriber" + }, + { + "featureId": "f03-debug-probe-scaffold", + "severity": "non_blocking", + "description": "Module comment claims 'All methods are synchronous' but thumbsUp() and trainAsync() return Promises" + }, + { + "featureId": "f03-debug-probe-scaffold", + "severity": "non_blocking", + "description": "getOutputs() returns direct reference to internal array (consistent with old playground but allows accidental mutation)" + }, + { + "featureId": "f03-debug-probe-scaffold", + "severity": "non_blocking", + "description": "thumbsDown() hardcodes spread=0.6 — should be wired to ML store spreadLevel when control surface is implemented" + } + ], + "appliedUpdates": [ + { + "target": "library", + "file": "environment.md", + "description": "Added WASM locateFile override pattern (public/ + locateFile to /), MLP bias convention (+1 on input layer), activation enum mapping (SIGMOID=0, TANH=1, LINEAR=2, RELU=3), Vite OXC callable object limitation, debug probe method count clarification (15 methods per VAL-PROJ-005), agent-browser chromium version mismatch workaround, and EMFILE polling workaround", + "sourceFeature": "f01-vite-wasm-spike, f02-signal-bus, f03-debug-probe-scaffold" + } + ], + "suggestedGuidanceUpdates": [ + { + "target": "AGENTS.md", + "suggestion": "Document that window.__nispsBus is exposed unconditionally (no ?debug=1 guard) for e2e testing. Currently only window.__nispsEoc is documented as unconditionally exposed.", + "evidence": "App.tsx exposes (window as any).__nispsBus = bus without any debug guard. AGENTS.md Debug Probe section only mentions window.__nispsEoc as unconditional.", + "isSystemic": false + }, + { + "target": "AGENTS.md", + "suggestion": "Note that debug probe's thumbsDown() hardcodes spread=0.6. When the ML store's spreadLevel is implemented, the probe should read from the store instead. This prevents a subtle bug where URL param ?spread=X affects the real app but not the probe's thumbsDown behavior.", + "evidence": "src/probe/debug-probe.ts:73-75 hardcodes spread=0.6. architecture.md documents spreadLevel in ML Store section.", + "isSystemic": false + } + ], + "rejectedObservations": [ + { + "observation": "The handoff mentions .factory/services.yaml was updated but the file doesn't exist", + "reason": "Incorrect — .factory/services.yaml does exist at the repo root with test-solidjs command and service definitions. Reviewer was looking in the wrong location." + }, + { + "observation": "Worker deviated from TDD step in the skill procedure", + "reason": "This is skill feedback, not factual knowledge about the codebase. Already captured in the worker's handoff skillFeedback." + }, + { + "observation": "Architecture docs already cover signal bus equals:false pattern", + "reason": "Already documented — duplicate observation, no action needed." + } + ], + "previousRound": null +}