Phase 1 plus some refactoring.

docs/AUDIO_ENGINE.md

@@ -25,3 +25,57 @@ Audio sample position is the authoritative playback clock. Use integer or
 rational timeline representations to avoid cumulative floating-point drift.
 Define tempo-map conversion and behavior at tempo changes before implementing
 tempo automation.
+
+## Phase 1 offline API
+
+`xtc_graph_create` accepts 1..256 nodes; IDs are insertion indexes, stable for
+that graph's lifetime. Supported nodes are gain (any finite multiplier), sine
+oscillator (finite nonnegative Hz), pass-through peak meter and audio output.
+Ports carry mono float audio: input 0, output 1. Oscillators have no input and
+output nodes have no output. Port lookup reports direction, signal type and
+channel count. MIDI/control ports and channel conversion are not implemented;
+invalid ports/directions, duplicate edges and cycles are rejected before an
+edit becomes visible. Fan-out copies a source to consumers; fan-in sums inputs
+without normalization. Failed additions leave IDs and graph contents unchanged.
+
+`xtc_graph_compile(graph, sample_rate, max_frames, &plan)` runs on the control
+thread. Empty graphs are rejected. Sample rate must be finite and positive,
+oscillators must be at or below Nyquist, and max_frames is 1..65536. Compilation
+allocates and copies topology/parameters, builds a topological schedule and
+input adjacency, and allocates one max_frames float buffer per node. The
+maximum buffer storage is 64 MiB per plan. Compilation may fail with an
+allocation error; output plan is then NULL. Destroy a plan on the control thread.
+
+`xtc_plan_process` uses only prepared state: no allocation/free, sorting,
+logging, I/O or locks. Each call accepts up to max_frames; oversized calls
+return capacity errors without modifying output or state. Output storage must
+hold frame_count floats. NULL input means silence; input/output may alias.
+Zero frames leaves all state unchanged. No plan operations may run concurrently
+with processing, including reset, meter reads or destruction.
+
+Unconnected non-oscillator nodes receive external input. Connected inputs
+receive only the sum of their upstream buffers. Explicit output nodes are
+summed to the caller's output. If none exist, terminal nodes are summed for
+compatibility with the original gain-chain API. Disconnected components cannot
+contribute when explicit outputs exist, but they are still processed. Floating
+point overflow and nonfinite input become silence per sample. No clipping or
+normalization is applied to finite samples.
+
+Oscillators start at phase zero and carry phase continuously across blocks;
+reset clears phases and meter peaks. Meter reads return the last nonempty
+block's absolute peak. These are same-thread reads, not a thread-safe GUI
+meter bridge. Rendering is deterministic on the same build/platform regardless
+of block partitioning; libm results need not be bit-identical across platforms.
+
+`xtc_graph_process_offline` remains a convenience helper, compiling at 48000 Hz
+and destroying the plan after one block. It accepts a finite external-input
+gain and requires non-NULL input/output. It now follows routing rather than
+multiplying every gain in insertion order. It allocates and is not suitable for
+an audio callback. Use a persistent plan for phase continuity and repeated blocks.
+
+Tests in `tests/unit/test_offline.c` cover known oscillator samples, gain and
+meter output, reset and partition equivalence, fan-out/fan-in, reverse insertion
+order, disconnected nodes, in-place processing, nonfinite input, invalid ports,
+cycles, capacity limits, plan lifetime and repeated compilation/cleanup.
+Hardware playback, concurrent graph publication and backend stress tests remain
+Phase 2 work; this offline API does not claim hardware real-time qualification.