ModuLisp/README.md

# ModuLisp

Standalone build of the portable uSEQ signal engine. Meson + ninja:

```
meson setup build && ninja -C build && meson test -C build
```

## Module map

- `src/modulisp/lisp/` — header-only symbol interning (`symbol_intern.h`).
- `src/signal_engine/` — the language core:
  - `token` → `cell_store` → `graph_builder` → `node_pool`: source text to
    fixed-pool signal DAG (deterministic compile, CSE, bounded diagnostics).
  - `compiler_pipeline`: parse + graph-mutation transactions (LKG rollback).
  - `cold_eval`: top-level evaluation — definitions, output assignment,
    external sink assignment (including the descriptor-gated vector sugar:
    `[base…] :offset [mod…]` and `[[base mod] …]` pairs expand to the same
    per-channel graphs as the flat form, spec §4.3–§4.5), cold commands,
    transport control.
  - `executor`: tick-time DAG execution + `publish_sink_values`.
  - `ext_registry`: generic named external-input / external-sink /
    cold-command registries — the firmware-profile seam (see MAP.md). A sink
    descriptor sets `vec_base_ch`/`vec_mod_ch` to accept the vector sugar.
- `src/utils/`, `src/devtools/`, `src/ports/` — support libraries, gated
  telemetry, and hardware port interfaces with host mocks.
- `test/` — Catch2 executables over the host subset of the engine.

External registers are generic: firmware registers names like `nn/*` or
`midi/*` at boot; the engine ships no such builtins. A sink registered with
vector packing accepts its channels flat or sugar-packed — all forms bind
identically and publish through the same pool output slots.