feat(closed loop): bias/disturbance waveforms for FicTrac trials (LAB-185)

[isabel-hess]

Closes LAB-185.

Adds a bias waveform to the FicTrac closed loop, so the display keeps moving even
when the fly holds still — the stimulus for measuring disturbance rejection in the
fly-on-ball assay.

Semantics

Authored as an added rotational velocity in deg/s (bias_amplitude = peak). The
bridge integrates it analytically into an angle and folds that into its
heading→frame-index mapping alongside the existing offset:

idx = round((heading_deg + offset + b(t)) / gain) mod n_frames

bias_type	velocity v(t)	bias angle b(t) = ∫v	position range
none	0	0	—
constant	A	A·t	steady drift
sine	A·cos(ωt)	(A/ω)·sin(ωt)	±A/(2πf)
square	A·sign(cos ωt)	symmetric triangle	±A/(4f)

Three properties are load-bearing, each pinned by a test:

1. b(0) = 0 for every waveform — closed-loop onset never jumps the display.
2. The periodic waveforms are zero-mean in position — the display is pushed equally
   both ways rather than drifting to one side. (square uses sign(cos ωt), not
   sign(sin ωt), which would integrate to a one-sided ramp.)
3. b is evaluated analytically, never integrated incrementally — a dropped
   FicTrac frame costs nothing and the value is exactly reproducible offline.

Because amplitude is a velocity, position excursion shrinks as frequency rises:
at 90 deg/s a sine covers ±28.6° at 0.5 Hz but only ±14.3° at 1 Hz.

On-arena direction (confirmed by eye): at the normal positive gain, a positive
bias_amplitude turns the display clockwise — equivalently the pattern sweeps
rightward across the fly's visual field. This is the sign an analysis must assume; get
it backwards and a fly correctly counter-turning reads as following the disturbance. A
negative gain flips it, since the bias is divided by gain along with the heading.

Where it lives

Layer	File	Owns
Math	fictrac-bridge/bridge.py	bias_angle_deg() (pure), BIAS_TYPES, the bias_deg arg to frame_index_from_fictrac()
Clock + logging	fictrac-bridge/bridge.py	Pipeline.set_bias(), LogWriter.write_event(), the config dispatch, --bias-* flags, v2.1
Transport	js/fictrac-bridge-client.js	bias as the one object-valued config key; setBias(), 'bias' event, biasAngleDeg
Schema	js/plugin-registry.js	the three startClosedLoop params
Validation	js/arena-runner-g6.js	normalizeBias() → {bias, warning}; the fictracApply IR
UI (read-only)	arena_studio.html	#rbBias in the Run-view bridge strip

Authored per condition on the fictrac plugin's startClosedLoop — deliberately
not in the plugin's configFields and not a Console input, so there is one source of
truth. The three fields render automatically in both designers from the registry
schema; no designer HTML knows them by name.

The none|constant|sine|square vocabulary is declared in three places (bridge, runner,
registry) and a registry test pins all three equal.

Validation policy

Input	Result
bias_type omitted / none / ""	no bias
unknown bias_type, non-finite amplitude/frequency	fails the step, run continues
sine/square with bias_frequency == 0	fails the step (divide-by-ω=0)
constant with bias_frequency == 0	fine, frequency ignored
negative bias_frequency	warns, then runs (it's a no-op — both velocities are cosines, even in ω; negate the amplitude to reverse direction)

Failing the step rather than aborting the run follows the duty precedent in
buildTrialParams. 0 Hz is a hard failure because the bridge's defensive fallback
returns a 0 bias, which at the bench reads as "the disturbance didn't work" — a silent
no-op is the worst outcome.

A bug this found on the bench

Stopping a run mid-trial skips the protocol's own stopClosedLoop, so the bias stayed
installed with its phase clock running and the next run inherited a stale,
already-drifted disturbance. Investigating turned up a second consequence of the same
root cause: the three teardown paths cleared the LED activator but never touched the
bridge, so setApply was also left ON — after STOP the bridge kept streaming
SET_FRAME_POSITION at the arena.

Two independent guards, either of which alone fixes the reported symptom:

1. ArenaRunner._clearClosedLoop() — setApply(false) + a bias:{type:'none'} push —
   called from all three teardown paths, symmetric with _clearLedActivator().
   Bridge-only, so it works when the serial link is already gone. Clears the bias only
   when the client has one installed, so a --bias-type CLI default survives a run.
2. startClosedLoop always carries an explicit bias ({type:'none'} when none is
   authored), so an epoch can never inherit what the bridge still had.

The regression test was verified to fail against the pre-fix code (7 checks).

Logging

Not a per-frame column — BEHAVIOR_V1_COLS is deliberately not widened, since the
positional row format is parsed by js/runlog-replay.js and the dashboard's vendored
parser. Instead the bridge writes one bias_config event per push whose ms is in the
same relative timebase as the frame rows, marking the waveform's phase-clock zero:

{"type":"bias_config","dir":"bridge","ms":45024,"bias":{"type":"sine","amplitude":90.0,"frequency":0.5}}

Because the waveform is analytic, that plus the ms column recovers b(t) exactly.
js/runlog-replay.js now surfaces each epoch as a status event
(status.phase === 'bias_config') so it flows through buildTimeline and existing
consumers skip it rather than break. idx in every frame row already has the bias
folded in, so what the fly saw needs no reconstruction at all.

Verification

Automated — pixi run test green (28 suites). New coverage: the closed forms and
the zero-mean regression guard (tests/test-bridge-behavior.py), runner validation and
teardown, client transport, registry schema, YAML round-trip, and replay parsing. Also
closes a pre-existing gap: tests/fixtures/v3_fictrac_closed_loop.yaml matched the CI
path filter but was loaded by no test.

On arena hardware — a full 8-condition run of protocols/fictrac_bias_test.yaml
drove a real G6 controller (32,499 SET_FRAME_POSITION commands). From the 24 MB log:

• round((heading + bias)/gain) mod 200 reproduces the logged idx for all 328,733
  frame rows — 4 mismatches (0.0012%), all ±1 frame from millisecond rounding
• constant 90 deg/s measured 50.0 frames/s = 90.0 deg/s = one revolution per 4.00 s
• every amplitude exact: sine ±28.6 / ±14.3 / ±9.5, square ±45.0 / ±22.5
• b(0) = 0 at all 16 epoch onsets; 8 waveform pushes each cleared by a none

Compatibility — a stale pre-2.1 bridge receiving the new bias key keeps streaming
normally and simply applies no disturbance (tested against the pre-change bridge.py).
Needs pixi run bridge reporting 2.1; the bias is computed there.

Also in here

• New CI workflow validate-fictrac-bridge.yml. tests/test-bridge-behavior.py
  ran in pixi run test but in no GitHub workflow, leaving all the bias math
  without CI coverage.
• Fixed the protocol-yaml skill's closed-loop example, which typed
  startClosedLoop/stopClosedLoop as controller commands. The runner skips those,
  so the loop would silently never open and the trial would run open-loop.
• Authoring-time lint in validate-protocol.mjs mirroring the runner's rules, so a
  0 Hz sine is caught when the YAML is validated rather than at run time.
• De-brittled an Alt test that pinned Classic's exact footer version, which broke on
  every Studio version bump (which CLAUDE.md mandates).

Not covered

• An experiment with a behaving fly. The validation run used a moving ball, but
  nothing depended on the fly's behaviour.
• Bias as a position disturbance, phase offset, square duty cycle — all explicit
  v1 non-goals.
• A live scope channel for the bias. Epochs reach the replay timeline but nothing
  draws them; a channel would mean touching js/kinematics.js and the dashboard's
  vendored parser.
• Any Mode-4 equivalent — the controller computes that frame from an analog input,
  so the host has no injection point.

Full spec: docs/development/closed-loop-bias.md.