max: fix the jitter crash, polyphony, atom conversion; and the golden harness that invented crashes

[jcelerier]

A tooling/run_max_golden.py sweep over the 112 objects reported 3 crashes and
10 audio mismatches. Investigating found one real crash, two harness bugs
that manufactured the other two, and a series of further defects on both sides.

Result: 3 crashes → 0, 13 mismatches → 8, 75 → 80 matching, and all 112
objects now get a turn (43 never ran before, silently).

Independent of #183 (help patches); this touches only the Max binding, the
harness, and one example object.

The real crash — avnd_test_gpu_buffer_in

jitter_processor.hpp registered matrix_calc as a lambda returning void,
but process_mop() reads that method's return value back through
jit_object_method and feeds it to jit_error_code(). The "error code" was
whatever happened to be left in the return register, and jit_error_code
dereferences codes it does not recognise → access violation inside jitlib.

Minidump: c0000005 reading 0x77f8f67f38e at jit_error_code+0x176, reached
from the external's process_mop frame. Other matrix operators survived only
because the leftover register value happened to be benign.

Also relaxed: an analyzer with matrix inputs but no matrix output gets a null
output list, and the guard rejected it, making every bang an error.

The two that were not crashes — avnd_all_ports_types, avnd_poles

Both pass every case in isolation. Three compounding harness faults:

1. Max's File.writeline truncates at 32767 characters — it does not split,
   which is what parse_report's comment assumed. Both objects emit longer
   report lines, so their entry was never valid JSON and they never counted as
   done. Long lines now go out in sub-32K writestring chunks, and
   loadExisting rejoins continuation lines.
2. The breadcrumb was deleted once per invocation, not per launch, so a
   stale one read as "already started" and the 60 s stall clock ran through
   Max's own 30–45 s startup.
3. Progress was counted in parseable report entries, which for an object hit
   by (1) never appear. It is now the breadcrumb advancing.

The kill then stamped whichever object was current — re-running the same object
blamed a different case number each time, which is what proved it was timing
noise.

Binding defects

• matrix_calc return type (above).
• to_atoms wrote every element to atoms[0]. The iterable overload
  advanced the write index only in the integral branch; float, string and enum
  wrote atoms[i] with i never incremented.
• The bitset overload sized for 2 * N atoms, filled N, sent
  atoms.size() — N uninitialised atoms after the data. Pd had the same
  over-allocation but passed N explicitly, so it was latent; corrected in both.
• perform() handed the adapter fewer channels than the object was prepared
  for, so an object iterating its declared channel count read past the end of
  ins[]. A crash dump caught avnd_helpers_per_bus_as_args faulting in its
  perform loop on exactly that. Input-side counterpart of max: fix crash on DSP start with fixed/wider output buses #127. A memory-safety
  fix; it is not what fixed the mismatches.
• Polyphony was initialised with the compile-time channel count. init() can
  only use the declared count — 1 for a mono object — so with a multichannel
  inlet the container held a single per-channel instance and every channel above
  the first came out an exact copy of channel 0. The golden generator does
  allocate_buffers → init_channels(runtime) → prepare; dsp() now does the
  same. This is what the audio mismatches were. Fixed
  avnd_test_audio_mono, avnd_test_audio_sample_ports,
  avnd_helpers_per_sample_as_args, avnd_helpers_per_sample_as_ports,
  avnd_persample_2.

Harness defects

• CHANS was 2, the number of buffer~ pairs in the driver patch, and
  anything above was silently truncated: avnd_modular and
  avnd_helpers_per_bus_as_ports_fixed (4 inputs), oscr_AudioSidechainExample
  (3 outputs), avnd_vb_fourses_tilde (4 outputs) were compared on 2 channels
  against goldens using all of them. Now 8 pairs, and the driver warns rather
  than truncating quietly.
• Texture analyzers were never fed an image. The kind test looked only at
  texture outputs, so an analyzer (matrix in, control out) was built by
  buildControl, which never sends a jit_matrix — avnd_test_tex_variable
  reported Width=0 against a golden of 16. Anything with a matrix on either
  side is now a matrix operator.
• A degenerate golden texture failed instead of being skipped.
  oscr_TextureFilterExample case 4 downscales 16×16 by 32, so the object's
  output is 0×0 — which no host matrix type can represent. Cases 0–3 matched
  exactly all along.

One example object was reading uninitialised memory

AllPortsTypes is struct inputs outputs; with an empty operator(), so the
outputs are never written — and not one port member had an initialiser. The
recorded int output was 1065353216, i.e. 0x3F800000, the bit pattern of
1.0f; running the same golden binary twice produced different values for
array_double/array_int. All 192 members are now value-initialised and the
golden is bit-identical across runs.

Tests

• tests/objects/polyphony_channels.cpp (Catch2, no host required) pins the
  contract the bindings rely on: N channels means N effect instances, each
  reading its own channel's samples, no shared state. A stateless object catches
  a channel coming out as a copy of another; a stateful one catches instances
  being shared.
• tooling/tests/ (25 tests) covers report parsing, the stall detector
  (extracted into a StallTracker so it could be tested at all — the key case is
  a breadcrumb advancing while no entry ever becomes parseable), object-kind
  classification including the analyzer regression, and the degenerate-texture
  rule including that one degenerate port does not excuse a wrong sibling.
  Registered with CTest when Python is available.

to_atoms and the Max outlet writers have no unit test. Their symbols live
in MaxAPI.dll, which exists only inside the Max application — a standalone test
binary links but cannot load it (verified). They are covered by the harness.

What still mismatches (8 of 112)

• Max binding, not fixed here (2) — avnd_helpers_ui, avnd_ui declare an
  audio output they never write; the oracle emits silence, Max emits stale buffer
  contents (traced to input channel 1 verbatim). Max should zero output buffers.
• Not investigated (2) — oscr_AudioSidechainExample, avnd_vb_fourses_tilde.
  Both now compare at the correct shape (3ch/3ch, 4ch/4ch), so what remains is a
  real value difference rather than truncation.
• Oracle-side (3) — avnd_persample_1 (golden emits silence; hand-computing
  the first sample confirms Max is right, the generator does not process
  float operator()(float, const inputs&, outputs&, tick)), avnd_test_prepare
  (message objects deliberately prepare with one frame per bang; the oracle
  assumes 64), avnd_test_initialize (Max runs initialize(), the oracle
  does not).
• Expected (1) — avnd_random is a noise generator and can never match.

Verification

• All 112 Max externals and 98 Pd externals rebuild cleanly; CTest green.
• Full sweep: 80 match / 8 mismatch / 0 crash, every object reached.
• No regression: avnd_poles, avnd_lowpass, avnd_peak, avnd_sines,
  avnd_helpers_lowpass, avnd_helpers_per_bus_as_args, avnd_test_audio_poly
  and avnd_test_gpu_buffer_in all still match.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YYaRCC6UEG1spai7orCUBb