Diagnostics: let an object report its condition to the host

[jcelerier]

Objects currently have no way to say "I am misconfigured right now".

avnd::logger is a stream of lines aimed at the developer — OFX draws the same
line between its Log and Message types — and a state rendered as a stream
becomes one identical console line per cook. TouchDesigner exposes exactly this
as node state (getErrorString / getWarningString / getInfoPopupString),
stubbed empty in every binding until now, and it feeds the Errors Dialog, the
Error DAT, op.errors() and OP Execute DAT callbacks. Houdini, Nuke, Blender
geometry nodes, OFX persistent messages and Node-RED all model the same thing.

Object-side API

struct MyObject
{
  halp::diagnostics diagnostics;          // the entire opt-in

  void operator()()
  {
    if(!connected)
      diagnostics.warning("no sender on port {}", port);
    diagnostics.info("{} points", count);
  }
};

Diagnostics are scoped to one run and cleared by the binding beforehand,
exactly as TouchDesigner's own addError/addWarning are ("only valid if added
while the operator is cooking") and as Blender and Houdini work. That is what
keeps the API this small — it removes:

• identifiers to manage — you restate what still holds
• clear() — not stating a condition is clearing it
• thread-safety — an object that learns something on a worker thread already
  has to publish that state for its outputs, and the cook reads it

Optional stable ids

For hosts that suppress or localise by id, for structured codes (GStreamer
domains), and for tests:

diagnostics.error<"port_in_use">("port {} is already in use", port);
REQUIRE(obj.diagnostics.has<"port_in_use">());

A template argument rather than a leading string, because
error("id", "fmt {}", x) is ambiguous with error("fmt {}", "x"). Compile-time
because a stable id is by definition not computed at runtime, so only a pointer
to a literal is stored. Users who do not want ids never type <...>.

Properties

• Fixed capacity throughout: raising a diagnostic never allocates and is usable
  from an audio callback.
• Text truncates at the capacity; when the entry array is full the lowest
  severity is evicted, so the most serious condition is never the one lost,
  and the drop count is reported.
• Severity vocabulary follows OFX: info / warning / error / fatal.
• Zero cost for objects that do not declare the member.

Contents

file
avnd/concepts/diagnostics.hpp	severity enum + has_diagnostics
halp/diagnostics.hpp	basic_diagnostics<MaxEntries, Capacity>
avnd/binding/touchdesigner/diagnostics.hpp	shared diagnostics_state, reusable by every TD family
.../pop/particle_processor.hpp	POP wiring: clear before cook, render the three channels
examples/Helpers/Diagnostics.hpp	example

Tested

Entries and severities, ids attached only where given, has<>, clear(),
eviction under overflow (12 info + 1 error → the error survives), and
truncation of a 1000-char message into a 128-byte buffer. The POP binding
compiles both for an object that opts in and one that does not.

Not done here

• The other TD families (TOP/CHOP/SOP/DAT) reuse diagnostics_state the same
  way — three lines each.
• Stream backends should emit on change: Max object_post/_warn/_error(x, …),
  Pd logpost/pd_error(x, …), CLAP clap_host_log, Godot
  push_error/push_warning.

Surveying the field for this also turned up four independent one-line defects in
the existing loggers, which I have deliberately left out of this PR:

1. TouchDesigner logging does nothing — logger::log_func / error_func are
   nullptr and never assigned anywhere in the tree, so every method
   early-returns.
2. Pd uses the wrong call — error() routes to ::bug(), which upstream Pd
   reserves for internal Pd faults; the object-facing call is pd_error(x, …).
3. Max and Pd pass NULL as the object, losing the console's
   click-to-highlight — the main reason object_error takes one.
4. CLAP discards messages it could deliver — clap_host_log exists with a
   full severity enum, but the backend uses halp::no_logger.

Happy to fix those in a separate PR.

🤖 Generated with Claude Code