v0.4.1

⚠ BREAKING — CLI binaries renamed: nkido-cli → nkido, akkado-cli → akkado

The bytecode player and compiler CLIs were renamed and their build output
moved to build/bin/. Update any wrapper scripts, CI, or shell aliases.
Source folders tools/nkido-cli/ and tools/akkado-cli/ were renamed to
tools/nkido/ and tools/akkado/ to match.

⚠ BREAKING — pat builtin and p"…" literal removed

The untyped pat("…") builtin and the p"…" raw-pattern literal were
removed in favor of typed prefixes (n"…", s"…", etc.). The typed
forms carry full event semantics; the raw form only ever surfaced step
indices and is unused by any shipped patch.

⚠ BREAKING — euclid() default span changed from 1 cycle to 4 cycles (1 bar)

The runtime euclid(hits, steps) builtin previously packed all steps into a
single cycle (= 1 beat under cycle=beat). At common BPMs this ran at near-32nd-
note rate — far from the "tresillo" feel the docs claimed. We added an explicit
dur parameter (audio-rate signal, default 4 cycles) so euclid(3, 8) now
spans 1 bar at 4/4 by default, matching the classic Strudel/Tidal feel.

Existing patches using euclid(3, 8) will now sound 4× slower. To preserve the
old feel pass dur=1 explicitly: euclid(3, 8, 0, 1). To stretch further, raise
dur: euclid(5, 16, 0, 8) spans 2 bars.

.fast() and .slow() remain pattern-only and still do not apply to
euclid() (it returns a signal, not a pattern). Trying to use them now emits a
targeted hint pointing at the dur parameter instead of the generic
E133 first argument must be a pattern. For pattern-style rate scaling over an
Euclidean rhythm, use mini-notation Euclidean syntax: n"c4(3,8)".slow(2).

⚠ BREAKING — mini-notation: cycle = beat, top-level = alternation

The clock unit and the mini-notation top-level grouping rule both
change to a single coherent model:

• 1 cycle = 1 beat. BPM directly sets the cycle rate.
• Top-level spaces play one element per cycle. "a b c d" plays
  four cycles in sequence (one element per cycle), exactly equivalent
  to the angle-bracket form <a b c d>.
• [a b c d] packs four elements into one cycle (the explicit
  subdivision form). Use this when you want Strudel/Tidal-style
  in-cycle subdivision.
• <a b c> is a documented synonym of the top-level form.

This is a deliberate divergence from Strudel/Tidal, which treats
top-level as subdivision. We chose per-cycle alternation so long
melodies stay readable as "c d e f g a b c5" without anyone having
to count elements to predict playback speed.

Engine-side: ExecutionContext::samples_per_cycle() no longer
multiplies by 4; every cycle_length default flipped from 4 beats to
1 beat; bar phase collapses to beat phase. The codegen dispatch for
MiniPattern routes through compile_alternate_sequence (the same
path as <…>), with the existing single-child inline guard preserving
pat("a") ≡ pat("<a>") ≡ pat("[a]") byte-equivalence.

⚠ BREAKING — delay-family default mix changed

The delay, delay_ms, delay_smp, tap_delay, tap_delay_ms,
tap_delay_smp, and pingpong builtins migrated from full-wet output
to the new unified Category-A defaults dry=1, wet=0.5 (parallel mix).
Patches that called delay(in, time, fb) or pingpong(s, time, fb)
and relied on a fully-wet output now get a balanced parallel mix and
will sound different. Set wet=1 (or dry=0, wet=1) explicitly to
restore the previous behaviour. The pingpong opcode previously did
out = in + delayed (effectively dry=1, wet=1) — pass wet: 1.0 to
reproduce the prior echo loudness.

⚠ BREAKING — ChordLit (C4') syntax removed

The Strudel-style chord literal — an identifier-shaped token with a
trailing apostrophe, e.g. C4', F#m7_4' — has been removed from the
language. It was an MVP stub that only ever emitted the chord's root
note, was unused in any shipped patch, and is superseded by pattern
events carrying real chord data. Write chords as patterns instead
(n"[c4,e4,g4]", chord("Am G C")); C4' now lexes as the identifier
C4 followed by a quote. The internal chord_parser API (used by
mini-notation) is unaffected.

⚠ BREAKING — scale() array builtin removed

The scale(array, lo, hi) array builtin has been removed. It was
functionally identical to normalize(array, lo, hi), which already
maps an array's value range to an arbitrary [lo, hi] range (its
lo/hi arguments are optional, defaulting to 0/1) and emits
identical bytecode. Replace any scale(arr, lo, hi) call with
normalize(arr, lo, hi). Removing the builtin frees the scale name
for the planned Strudel-style scale-quantize transform
(prd-runtime-event-transforms.md).

Added

• Flexible poly() / mono() / legato() instrument callbacks — the
  instrument is no longer fixed to a 3-parameter (freq, gate, vel)
  signature. It can read any pattern event field: by record destructure
  (({freq, note, dur, cutoff}) -> …), by positional prefix (canonical
  order freq, gate, vel, trig, type, note, dur, chance, time, phase, sample_id), by a mix of the two, or by a rest param binding the whole
  event ((...e) -> e.freq). Custom mini-notation record-suffix fields
  (c4{cutoff:0.8}) are readable per voice; an absent field binds to 0
  or to an explicit {cutoff = 0.5} destructure default. The historical
  (freq, gate, vel) positional form stays valid; mono and legato
  accept every callback shape identically. Record form is now the
  canonical idiom across all docs and example patches.

• Destructure-param closures compile in every context — a closure
  assigned to a name (stab = ({freq, gate, vel}) -> …) and used as a
  poly/mono/legato instrument, or called directly, not only when
  passed inline as a direct poly() argument.

• Pattern event arrays — notes() / freqs() — surface a pattern
  event's chord notes as a first-class dynamic array (an array
  whose length is a runtime signal). notes(e) returns MIDI numbers,
  freqs(e) returns Hz; the method forms e.notes / e.freqs are
  equivalent. len() is now polymorphic (compile-time constant for
  static arrays, runtime signal for dynamic ones), arr[i] indexes
  dynamic arrays with wrap-by-default, and map() over a dynamic
  array stays dynamic. Combined with step() / counter() this makes
  arpeggiators and harmonizers userspace closures — no new C++ opcode
  per musical operator. A stateful UGen cannot auto-fan-out over a
  dynamic array (osc("sin", e.freqs) → E181, use poly()). New
  SEQPAT_VALUES opcode; demo patches arpeggio-demo and
  harmonizer-demo.

• Unified dry/wet convention across every effect builtin — all 33
  effect builtins (delays incl. pingpong, reverbs, modulation, comb,
  filters, distortion, dynamics) now expose dry and wet as their
  last two parameters and apply the standard mix
  out = dry_in * dry + processed * wet per channel. Two category-based
  defaults:

  • Category A — Additive (delays, reverbs, modulation, comb):
    dry=1.0, wet=0.5 (balanced parallel mix out of the box).
  • Category B — Transform (filters, distortion, dynamics):
    dry=0.0, wet=1.0 (back-compat — no audible change; set dry>0
    for NY compression / parallel filter / parallel distortion).

• cedar::drywet::{coeff, mix} inline helpers
  (cedar/include/cedar/opcodes/drywet.hpp) used by every effect
  opcode for the standard resolve + mix line.

• Catch2 dry/wet contract tests in cedar/tests/test_drywet.cpp
  covering one slot-based and one ExtendedParams-based example per
  category.

• Bus routing — diamond <> operator (signal <> 3 routes to bus 3),
  numbered buses with always-safe master, per-bus FX via mixer/master
  closures. Three phases shipped: numbered buses + master, per-bus FX,
  and the <> operator at pipe precedence.

• Per-element *N / /N rate modifiers in mini-notation —
  n"c4*2 d4/2" doubles/halves individual event durations under one
  uniform per-element mechanism (no top-level vs inner split).

• Runtime event transforms — closure-taking event_map /
  event_filter, runtime fast() / slow() (EVENT_RATE_SCALE),
  structural EVENT_REORDER / EVENT_FANOUT, and stdlib key /
  scale / voice / invert / swing / swingBy / early / late
  / 5 property modifiers. Chord-array READ/WRITE inside event_map
  closures. New fmod builtin + stdlib .ak embed mechanism.

• Block-rate control flow — when() { … } conditional bypass,
  loop(N) { body } bounded static iteration, #inline annotation
  with recursion rejection, each() / reduce() over event records,
  FOREACH_EVENT + subprogram table (POLY migrated onto it),
  BLOCK_CALL shared-block fn dispatch, BLOCK_BIND for shareable
  fns with >5 params.

• Parameter type annotations Phase 2 — evs / sig / num /
  rec / arr / str / fn annotations parsed via name: type
  grammar, propagated through analyzer, dispatched in
  handle_user_function_call. New E184 type-mismatch diagnostic.

• Built-in Tidal Drum Machines sample catalog — TR-808/909/etc.
  packs ship inside the WASM bundle, addressable from s"…" patterns.

• SF_VOICE opcode — single-voice soundfont primitive (poly
  unification Phase 1).

• transport() builtin is now reachable — previously declared but
  unregistered.

• Live-editor → embedding parent postMessage — iframe embeds can
  observe code edits.

Changed

• chorus, flanger, phaser extend their existing ExtendedParams
  with dry / wet slots (chorus 1→3, flanger 1→3, phaser 3→5). The
  positional argument order is unchanged for existing call sites.
• phaser internal topology: the opcode now emits just the
  all-pass cascade output and lets the dry/wet mix produce the
  canonical Bode/MXR phaser sum. With default dry=1, wet=0.5 the
  phaser sounds milder than the pre-migration canonical sum; set
  wet=1.0 to recover the previous +6 dB-peak topology. Math is
  bit-identical to the prior code at dry=1, wet=1.
• freeverb, dattorro, moog, diode, formant, sallenkey,
  tape, xfmr, excite, gate, fold, pingpong migrate to
  ExtendedParams<2> for dry/wet (their input slots were full).
  pingpong's custom codegen handler now emits the ExtendedParams init
  manually and accepts dry: / wet: as kwargs in both overloads
  (pingpong(stereo, t, fb) and pingpong(L, R, t, fb, width)).
• Documentation: every effect doc page in
  web/static/docs/reference/builtins/ carries a Category-A/B intro
  paragraph and per-effect dry/wet rows in the parameter tables.
  CLAUDE.md §"Effect Parameters" rewritten with the full convention.

Fixed

• legato() no longer retriggers on every note. A pre-existing VM bug
  set the gate-on edge unconditionally for both mono and legato, so
  legato re-attacked the envelope identically to mono. Overlapping
  legato notes now glide without re-attacking (gate stays high); a note
  arriving after the previous one's release tail still retriggers, as
  documented.
• Hot-swap robustness — ExtendedParams<N> slots, SEQPAT_QUERY
  cycle cache, and foreach_event state all survive recompiles; audio
  arena buffers are deep-copied into the crossfade snapshot; state pool
  is snapshotted across crossfade dual-execution; byte-identical
  recompiles skip the crossfade entirely.
• SEQPAT_STEP mid-block cycle wrap — state.output is refreshed
  on the wrap, eliminating a one-block stale-value glitch.
• Rest as first event — no longer fires a phantom trigger on the
  cycle wrap.
• Mixer-closure stereo copy-back — must not alias the L bus into
  both channels.
• fn arrow body — no longer swallows the line that follows.
• ..record spread — fields now bind to builtin params by name.
• <> operator — parses as a pipe-precedence infix, not
  statement-only.
• Canonical closure-body recovery — handles bare-identifier bodies.
• Step-highlighting offsets — accurate source ranges for pattern
  step highlights in the editor.
• StatePool tables are heap-allocated so the VM fits on the default
  thread stack.

Known limitations / deferred work

• experiments/test_op_phaser.py notch-depth check now reports
  ~9–10 dB (threshold 12 dB) — investigation shows the algorithm is
  bit-identical pre/post when called with dry=1, wet=1, but the
  test's _find_notch measurement is sensitive to RNG / FFT window
  alignment that drifts when the StatePool state-id layout changes.
  Pre-existing measurement fragility, not a behavioral regression.
• experiments/test_op_diode.py failures are pre-existing (unrelated
  to this PRD).