Neural decoders and foundation-model plumbing for the Phoebe neurotechnology domain (TODOS phase-181 §181.5). Pure TypeScript, dependency-free, ESM.
The package draws a hard line between what can be honestly computed here and
what needs GPU training on large neural corpora. The former is implemented
with real, tested algorithms; the latter is exposed as a fail-loud seam that
returns { status: 'not_configured', reason } rather than fabricating trained
weights or outputs.
Modules#
| Module | What it does | Real vs seam |
|---|---|---|
prng.ts |
Seeded LCG + Box–Muller Gaussian (no Math.random) |
real |
linalg.ts |
Matmul/inverse, Jacobi eig, Cholesky, SPD matrix functions, tall pseudo-inverse | real |
sequence.ts |
Levenshtein distance + error rate | real |
kalman.ts (181.5.1.1) |
Kalman-filter neural decoder (predict/update) + least-squares parameter fitting | real |
runtime.ts (181.5.1.1/.2) |
Hot-swappable Decoder runtime (linear / Elman-RNN / Kalman), versioned model registry, per-subject calibration store, injected-clock latency contract |
real |
brain-to-text.ts (181.5.1.3) |
CTC prefix beam search + n-gram LM rescoring around an injected acoustic model | decoding real; acoustic model injected |
foundation.ts (181.5.2.1–.3) |
POYO / NDT2 / LaBraM / MindEye tokenizers | tokenizers real; train/infer/reconstruct are fail-loud seams |
adaptation.ts (181.5.3.1/.2) |
Euclidean alignment, Riemannian recenter + Procrustes stretch, online recalibration | real |
benchmark.ts (181.5.2.4) |
WER, Wolpaw ITR, co-bps, leave-one-group-out CV, chance calibration | real |
Key verified numbers (from the test suite)#
- Kalman: on a simulated linear-Gaussian system the filter's state RMSE is
0.176vs0.338for the raw least-squares (H⁺z) estimate — a ~48% reduction the filter earns from its dynamics + noise model. - Brain-to-text: greedy CTC decode yields
[A,B,C→D](WER0.333); beam search + n-gram rescoring recovers[A,B,C](WER0.0). - Benchmark chance calibration: a fixed/random decoder scores at chance
(accuracy
0.25=1/K,0bits/selection); a decoder predicting the null mean rate scores exactly0co-bps. A trained decoder scores>0.95accuracy and>0.5co-bps — the metrics test decoding, not data flow.
The fail-loud seam#
Foundation-model training is not available in this package. train(),
loadPretrained() (without an injected WeightsBackend), infer(), and
MindEye reconstruct() all return not_configured with a reason. Tokenization
runs for real and the inference-dispatch plumbing is wired around the seam, so
injecting a genuine weights backend lights up loadPretrained with no code
change — but nothing here invents weights or outputs.
Development#
npx vitest run # tests
npx tsc --noEmit -p tsconfig.json # typecheck
Nx is bypassed on this box (worktree duplication); run vitest/tsc directly.