From 28e394ddf3bc82d21ee0055e481002bf0ec03846 Mon Sep 17 00:00:00 2001 From: monkey-w1n5t0n Date: Sat, 18 Jul 2026 12:45:45 +0200 Subject: [PATCH] docs+ci: P5 doc sync; codegen golden wired into run-all-tests stage 5 --- AGENTS.md | 4 ++-- MAP.md | 6 +++--- docs/AGENT-REFERENCE.md | 4 ++-- scripts/run-all-tests.sh | 6 ++++++ 4 files changed, 13 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3222bb7..995c664 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,8 +2,8 @@ One C++20 NISPS core targets RP2350 firmware and the Manifold React/WASM browser app. Read `MAP.md`, `ALIGNMENT.md`, and `docs/AGENT-REFERENCE.md`; for Manifold UI work read -`manifold/ONBOARDING.md` first. Parameter JSON schemas generate the C++ contracts -(TS codegen returns at P5 of `docs/specs/plans/one-core-engine-refactor.md`). +`manifold/ONBOARDING.md` first. Parameter JSON schemas generate both C++ and TypeScript +contracts. ## Gates diff --git a/MAP.md b/MAP.md index 44d12e4..4f602ea 100644 --- a/MAP.md +++ b/MAP.md @@ -95,7 +95,7 @@ the "BUILD DELTAS" block at the top of `docs/specs/vcv-module.md`). `src/MEMLNau - `schemas/midi_devices/.json` (×6) — CC-controllable external synths (Moog Sub 37 / Sub Phatty, Creamware Pro-12 ASB, Elektron Analog Keys, ASM Hydrasynth, Roland JD-800). Each param: `{id, cc, label, min, max, default, group}`. Canonical source for both firmware + browser device pickers. Verified-CC provenance + sources live in `synth-midi-cc.json` (repo root). ### `codegen/` — schema → C++/TS code -- `codegen/generate.ts` — Bun script: validates schemas via ajv, emits per-mode `nisps/modes/generated/_schema.hpp` (`constexpr`, `nisps::modes::generated`). Idempotent. (TS emitters retained but dormant; re-targeted at `manifold/src/modes/generated/` in P5.) +- `codegen/generate.ts` — Bun script: validates schemas via ajv (incl. the P5 firmware-fit check: exactly 3 hidden layers, dims ≤4096), emits per-mode `nisps/modes/generated/_schema.hpp` (`constexpr`, `nisps::modes::generated`) and `manifold/src/modes/generated/_schema.ts` (+ `types.ts`, `index.ts`). Idempotent; golden-tested in `run-all-tests.sh` stage 5. - `codegen/generate-midi-devices.ts` — separate Bun script (isolated from the mode golden test): validates `schemas/midi_devices/` via ajv, emits `nisps/midi/generated/midi_devices.hpp` (no-heap `constexpr`) and `manifold/src/midi-devices/generated/{types,devices,index}.ts`. Idempotent. - `codegen/seed-midi-devices.ts` — one-time/idempotent seed deriving `schemas/midi_devices/*.json` from the `synth-midi-cc.json` research artifact (slugifies labels → ids, heuristic groups). - `codegen/templates/`, `codegen/tests/golden/` — reference templates + golden snapshot for paf_synth. @@ -136,7 +136,7 @@ the "BUILD DELTAS" block at the top of `docs/specs/vcv-module.md`). `src/MEMLNau - **Parity check**: `bash scripts/parity-check.sh`. - **All tests**: `bash scripts/run-all-tests.sh`. - **Playwright**: `cd manifold && node node_modules/.bin/playwright test` (non-snap node runner on the VPS — BUILD-PLAN gotcha; `bunx playwright test` works elsewhere). -- **Codegen**: `cd codegen && bun run generate.ts` (regenerates `nisps/modes/generated/`; TS target returns at P5 for manifold). +- **Codegen**: `cd codegen && bun run generate.ts` (regenerates `nisps/modes/generated/` and `manifold/src/modes/generated/`). ## Conventions @@ -144,7 +144,7 @@ the "BUILD DELTAS" block at the top of `docs/specs/vcv-module.md`). `src/MEMLNau - `nisps/` follows Chris's RP2350 perf rules globally: no heap, `static const float` for non-trivial constants, strict `.f` suffix, memory section attrs (`NISPS_AUDIO_MEM`, `NISPS_AUDIO_FUNC`, `NISPS_APP_SRAM`, `NISPS_HOT`, `NISPS_FORCE_INLINE`). - C++ identifiers: `PascalCase` types, `snake_case` functions/variables, `kPascalCase` constexpr. JSON keys `snake_case`. TS types `PascalCase`, components `PascalCase.tsx`, modules `kebab-case.ts`. - `Curve` enum lives in `nisps/core/math.hpp` (lowercase: `linear/exp/log/square/sqrt/sigmoid/cubic`, plus the parameterised `centered_power` free function); generated mode headers re-export via `using Curve = ::nisps::Curve;`. Since P4 there is NO TS mirror — the browser samples the WASM catalog (`nisps_curve_apply(+batch)`). -- Modes are TSX components composed of primitives; mode parameter contracts are JSON schemas with codegen → C++ types (TS codegen returns at P5). **No declarative JSON UI.** +- Modes are TSX components composed of primitives; mode parameter contracts are JSON schemas with codegen → C++ **and** TS types (`MF_MODES` derives params/ml-config from the generated schemas since P5; labels/ordering stay a manifold overlay). **No declarative JSON UI.** - WASM and firmware share the same C++; the browser MLP is runtime-shaped (`MLPCore`, since P2): `nisps_ml_create` honours `(input, output, hidden[3])` with non-positive/null args defaulting to `32→[10,14,18]→126`; `nisps_ml_reshape` warm-starts a new shape. Firmware keeps compile-time `MLP<...>` (zero heap). Modes currently still use a slice of the default 126 outputs (per-mode dims become schema-real at P5). - Cross-platform parity: `scripts/parity-check.sh` enforces native vs WASM agreement within 1e-5. diff --git a/docs/AGENT-REFERENCE.md b/docs/AGENT-REFERENCE.md index a2bae59..bf92baf 100644 --- a/docs/AGENT-REFERENCE.md +++ b/docs/AGENT-REFERENCE.md @@ -101,9 +101,9 @@ Each mode has a `schemas/modes/.json` describing its parameters (name, lab Codegen (`bun run codegen/generate.ts`) emits: - `nisps/modes/generated/_schema.hpp` — `constexpr` C++ data, namespace `nisps::modes::generated`, re-exports `nisps::Curve` from `nisps/core/math.hpp`. -- (TS emission is dormant since P1; it returns at P5 targeting `manifold/src/modes/generated/`.) +- `manifold/src/modes/generated/_schema.ts` (+ `types.ts`, `index.ts`) — typed const schemas; `MF_MODES` derives params/ml-config from them (P5). -Codegen is idempotent. Golden test ensures regenerating produces byte-identical output. +Codegen validates the firmware fit (exactly 3 hidden layers; dims ≤4096) and is idempotent. The golden test (both languages) runs in `run-all-tests.sh` stage 5. ## WASM bridge diff --git a/scripts/run-all-tests.sh b/scripts/run-all-tests.sh index c279327..a79c547 100755 --- a/scripts/run-all-tests.sh +++ b/scripts/run-all-tests.sh @@ -47,6 +47,12 @@ if [[ "${NISPS_SKIP_PLAYWRIGHT:-0}" != "1" ]]; then if ! command -v bun >/dev/null 2>&1; then echo "[run-all-tests] bun not on PATH; skipping manifold stage" else + ( + # Codegen idempotence golden (C++ + manifold TS outputs). + cd "$ROOT/codegen" + bun install --frozen-lockfile 2>/dev/null || bun install + bun run tests/golden_test.ts + ) ( cd "$ROOT/manifold" bun install --frozen-lockfile 2>/dev/null || bun install