Repository navigation
Course infra: browser test runner must run hardware specs (calls, locals, struct fields, hex/binary/underscore literals) #1477
Description
Parent epic: #1476
Problem (measured 2026-10-07)
Every lesson promises a spec whose test blocks run in the reader's browser. For hardware specs this is false today. Running runSpecTests (scripts/viewport-from-spec.mjs) and constsOf (scripts/agents-from-specs.mjs) from apps/website over the hardware spec tree:
Tests that typecheck and lower to HIR but fail in the runner
| Spec | Result | Cause |
|---|---|---|
fpga/clock_domain.t27 |
12 tests fail | locals in test blocks (StmtLocal: "statement is not an assert") |
fpga/fifo.t27 |
18 fail | locals, calls |
fpga/axi4.t27 |
16 tests fail | ExprCall, ExprFieldAccess |
isa/tri27_machine.t27 |
93 fail | calls, struct fields |
fpga/formal, fpga/dft, fpga/power, fpga/timing, fpga/placement, pins/emitter_xdc |
fail | same three causes |
ternary/gft_smul.t27, ternary/comb_ternary_dot.t27 (already used by course ai-numbers) |
fail | calls |
constsOf throws on literal forms
| Form | Example |
|---|---|
| underscore separators | fpga/uart.t27 UART_CLOCK_HZ = 100_000_000; fpga/spi.t27 CLK_FREQ = 50_000_000 |
| binary | fpga/bpsk.t27 BARKER13_BITS = 0b... |
| hex | isa/registers.t27 0x03B1; isa/ternary_memory.t27 0x1; ternary/packed_trit.t27 TRIT_MASK = 0x03 |
| unary expression | fpga/mac.t27 MAC_LUT |
| identifier reference | vsa/vsa_core.t27 Hypervector |
src/lib/t27Compiler.ts exposes only analyze / loaders; there is no evaluator in the player, so these courses fall back to recorded tri casts.
Scope
- Evaluator support in the browser runner for: local bindings inside
test, function calls (pure functions in the same module), struct construction and field access,if/switchexpressions used in tests. constsOf: integer literals with_,0x,0b; unary minus/not; references to other consts.- Legacy hardware specs written as
module X { }that cannot be evaluated: port them, or list them as not-runnable with a reason. - A report:
node scripts/spec-runnable-report.mjs(or atrisubcommand) listing, per spec underspecs/fpga,specs/isa,specs/ternary,specs/pins,specs/boards: typecheck, HIR, tests run/passed, and the first unsupported node kind. Committed output is the ratchet; it only improves.
Acceptance
- All specs in the table above run their tests in the browser runner (pass or fail on real assertions, not on unsupported nodes).
-
constsOfreads every literal form above. - Ratchet file of runnable specs added to CI; a course lesson cannot name a non-runnable spec without a
castmarker. - Evaluator itself is specified in t27 where possible (only-t27 rule); any non-t27 code needs the
owner-approved-foreignlabel first.
This issue blocks every hardware course in the epic.
Activity
player: baseline carries the four specs main gained since the old bas…
player: absorb the buses course -- regen for 7 courses, baseline carr…