Perlines/docs/system-map.md

Perlines System Map

Objective

Perlines rebuilds the 2012 Aethervis trail demo as a Fensalir client whose visible form is driven by a key-aware, adaptively whitened FFT reservoir.

The real outcome is not a port of Unity LineRenderer state. The outcome is a below-native spectral field that Fensalir can lower through the same TubeField, reservoir, denoising, and presentation machinery used by the engine.

Authority Map

• Owner: PerlinesSignalProcessor owns FFT whitening, key detection, and projection from frequency bins into musical scale-note lanes.
• Inputs: a Fensalir-owned Windows system-loopback capture stem when available; otherwise frame time and delta time drive the procedural fallback signal.
• Outputs: one normalized Float32 column of scale-note energy per frame, transposed into note-owned TubeField splines for rendering.
• Derived state: detected key, flux, tonal center, and energy are diagnostic readouts derived from the same spectral pass.
• Forbidden writers: render passes, UI controls, tube lowerings, and audio stem metadata do not decide spectral content. They only feed or consume the field evidence path.
• Shared path: visible splines, TubeField evidence, headless captures, and UI telemetry all read the same rolling note reservoir and version counter.
• Deletion line: Unity trail ownership, arbitrary band-to-spline assignment, and per-object procedural line state are dead. The renderer owns visibility.

Pipeline

1. Perlines requests a system-loopback capture stem from the Fensalir audio host, drains published audio stem frames when available, and mixes their channels to a mono analysis window. If no stem frame arrives, a procedural signal is synthesized as a test fallback.
2. A Hann-windowed FFT measures the current frame.
3. Each FFT bin is divided by a smoothed envelope, producing adaptive whitening so persistent loud bands stop monopolizing the field.
4. Whitened bins accumulate into chroma energy.
5. Major/minor key templates with hysteresis choose the current key.
6. The detected key defines 70 scale-note lanes across octaves.
7. Each lane samples nearby whitened FFT bins for the note frequency.
8. The rolling note history is transposed into one contiguous curve per note lane.
9. Perlines uploads that compact 70 by 96 Float32 field resource.
10. Fensalir lowers each note lane through AquariumFieldTubeSplineLowering.
11. A Fensalir spline presentation reads the same note history and gives each lane a radial path advected by cross(position, d/dxyz noise4(position,t)), giving the presentation a divergence-free curl-noise style flow without restoring Unity object ownership.
12. The D3D12 TubeField path feeds the shared reservoir and final presentation.

Invariants

• Musical lanes are keyed scale notes, not arbitrary FFT bins.
• Each TubeField spline belongs to one detected-key note lane.
• Live audio stems are inputs to the same spectral owner as the fallback signal; they do not bypass whitening, key detection, or lane projection.
• Perlines uploads a compact 70 by 96 Float32 resource, not a native-resolution buffer.
• The showy dance splines are derived from the same note reservoir. They do not own signal truth.
• Low-energy bands fade to invisible brushstroke segments; dead lanes do not keep an always-on tube silhouette.
• The rolling spectrum is a field-evidence resource, not private renderer geometry.
• Fensalir owns D3D12 buffers, TubeField dispatch, reservoir reuse, bloom, and final reconstruction.
• Headless verification must exercise the same client assembly and TubeField lowering path as interactive runs.