ADR-v2-153 — The biosignal false-positive governor: measure a proxy, desensitize first, suspend only on evidence, release in one action¶

Status: Proposed (2026-10-29) Deciders: Mohsen Seyedkazemi Ardebili Context links: [[adr-v2-152-biosignal-artifact-switches]] (the package this governs; its section 2 names the budget, this ADR records the mechanism), [[adr-021-invest-in-error-cost]] (rule 9: a guard is judged on how rarely it fires), [[adr-v2-148-hands-free-composition]] (one global safety state; the governor is a per-source guard beneath it, not a replacement), [[adr-v2-129-killer-features-10x]] (the activation seam), research: docs/research/muscle-brain-control.md, spec: design/specs/biosignal-pipeline.md, field protocol: design/specs/biosignal-validation-protocol.md

Context¶

ADR-v2-152 commits the yazses.biosignal package to a measured, bounded, enforced false-activation rate. Three facts shape how that can be done:

1. A running system cannot see false positives directly. It can see what the user did next. The only observable is that the user cancelled or undid an activation shortly after it fired. That is a proxy: a user may cancel a correct activation (changed their mind), or leave a wrong one uncorrected (did not notice). Ground truth needs a labelled session, which is an evaluation job, not a daemon job.
2. Small samples lie. Three cancellations out of three activations is three samples, not "100%". A governor that acts on a point estimate will fire on the first unlucky quarter hour.
3. A guard that fires too often is worse than no guard (ADR-021, AGENTS.md rule 9). It interrupts the user, teaches them to dismiss it, and then catches nothing. A guard that cannot be dismissed in one move teaches them to turn the whole feature off.

The research page records the published ceiling this is measured against: the best published blink switch reaches 0.10 false positives per minute, about 50 phantom activations in a workday, and one paper reports no false-activation rate at all. A switch worse than that is not livable, and a switch nobody can measure cannot be tuned.

Decision¶

Add a budget governor to the biosignal package (biosignal/fprate.py), driven by a local activation ledger, with these rules. Every numeric value below is a design choice with its rationale stated, not a measured operating point; the budget structure is the decision, the numbers are to be changed with data.

1. Measure a cancelled-fraction proxy, and report its uncertainty¶

• The ledger counts each activating event (everything except SQUEEZE_OFF, which is a release, not a new activation) and counts it as cancelled when the integrator reports an undo or cancel of the latest switch-initiated action inside a short grace window (design default 3 s). An undo later than that is the user editing, not the trigger misfiring.
• The cancelled fraction is shown with a Wilson score interval, which behaves at small n and at the 0 and 1 edges where the normal interval collapses. Every place that prints the number also carries the proxy caveat (PROXY_NOTE).
• Rates use active exposure time as the denominator, not wall time. Time is accrued only while the trigger is live: a laptop left open overnight, a paused session, a period where the quality gate suppressed the detectors and a period where the governor itself suspended the source add nothing. Wall time would flatter the trigger.
• The ledger is local. What is persisted is aggregate counters only (sessions, active seconds, activations and cancellations per event kind); no raw signal, no per-event record.

2. The governor acts on evidence, not on the point estimate¶

The governor does not act on the displayed fraction. It compares a conservative lower confidence bound of the cancelled rate per active hour (a one-sided bound, design default about 90%) against the budget max_cancelled_per_hour (design default 6 an hour, the best published blink switch expressed per hour). It acts only when there is enough evidence for the signal to mean anything: a minimum of active minutes and a minimum number of cancellations since the last change of state (design defaults 5 min and 3). Below that there is no signal, only noise, and the governor stays out of the way.

3. Desensitize first, then suspend¶

States: OK, DESENSITIZE, SUSPEND. "Desensitize then suspend" is the escalation order, and it means exactly this:

Desensitizing is the gentle fix and is always tried first. Suspension is a stop, not a degradation to a quieter detector that keeps firing. The desensitize scale resets to 1.0 when the state returns to OK; leaving a stale scale in force after recovery would silently make the switch permanently harder to use.

4. Auto-recovery with backoff¶

A suspension ends by itself after a timer (design default 5 min), longer by a backoff factor on each repeat (design default 2x) and capped (design default 1 h), and it recovers into DESENSITIZE, not straight to OK. A switch that suspends repeatedly therefore stays off for longer each time, while a one-off bad patch heals without anyone touching it. The timer exists so that the feature cannot be left dead for good by a single bad hour.

5. One-action release, bound by the integrator¶

release() returns the governor to OK at any state, immediately, and starts a fresh evidence window so it cannot re-fire until enough new cancellations have been seen. The governor module only exposes release() and the text that tells the user how to invoke it; binding it to a single word, button or gesture is the integrator's job, and the release must be one action (ADR-021: the release is one word). A suspended switch whose release needs a settings visit is a defect. The release path must not depend on the suspended source itself, because the source is the thing that is off.

A release also arms a one-shot hold: the next evaluation only refreshes the rate numbers and applies no transition. The recent rate is an exponentially weighted average that still contains the cancellations the user just dismissed, so without the hold a release followed by one more cancel could be judged on the old evidence and suspend the switch again at once. After that one evaluation the fresh evidence window and the existing hysteresis do the rest. A stream gap, reconnect or recalibration does not release the governor (pipeline.reset(keep_governor_state=True), the default): a dropout is not evidence that the false-positive problem went away. Only an explicit release, or keep_governor_state=False, does. Paused time (the global hands-free pause) does not accrue as exposure, because the daemon calls the runner's pause_accounting() while the gate refuses.

6. The governor is conservative about when it fires, because the cost of firing is borne by the user¶

• It fires only on a specific, checkable signal (a credibly high cancelled rate with enough evidence), never on a heuristic.
• It is off in the module by default (FalsePositiveBudget.enabled = False reports OK and the ledger still measures), so the numbers exist before anything is allowed to change behaviour. In the package it is armed only when [biosignal] max_cancelled_per_hour is greater than 0; 0 means "count, never act".
• It is explicable: explain() returns one or two plain sentences stating what is happening, why, and how to undo it.
• Its firing rate is itself a measurement the evaluation harness should report (how often it desensitizes or suspends on a clean synthetic stream, which should be never, and on a noisy one). A governor that fires on a clean stream is broken.

Alternatives rejected¶

• Fixed refractory period only. A refractory period stops one burst being counted twice; it says nothing about a switch that fires spuriously once every ten minutes. It is kept as a detector property (ADR-v2-152) and is not a substitute for a budget.
• No governor; report the rate and let the user decide. This is "fire first, report later". The report is kept (yazses biosignal report), but a user who is being interrupted every few minutes should not need to open a report to stop it.
• Act on the displayed cancelled fraction. Fires on small samples, and the fraction has no exposure-time denominator, so it cannot be compared with a per-hour budget.
• Suspend immediately over budget. Skips the cheap, reversible step. Many over-budget cases are a threshold slightly too low for today's electrode contact, which a modest desensitization fixes while keeping the switch usable.
• Suspend forever until the user re-enables. Teaches users to disable the feature and never turn it on again; the auto-recovery timer with backoff is the compromise.
• A trained classifier that rejects "likely false" activations (ML post-filter). Needs a labelled corpus of real false positives that does not exist, would train on exactly the proxy this ADR calls unreliable, hides the failure mode, and cannot be explained to a user whose switch misfired. Revisit only with measured data and its own ADR.

Consequences¶

• A misbehaving switch ends up quieter, and if that is not enough, off, with a plain-language reason and a one-action way back.
• The cancelled signal must be wired by the integrator. If nothing reports a cancel, the governor sees zero cancellations and never acts; that is a safe failure (the switch is just ungoverned), but it makes the budget a no-op, and doctor / report should say so rather than imply protection.
• The proxy can punish a user who cancels for reasons unrelated to the switch, and can miss false positives the user never notices. Both are accepted and documented; neither is solvable without ground truth.
• No new data leaves the machine. The ledger holds counts, not signals (ADR-011, ADR-019).

Evidence and what it does not show¶

• The published reference point. The budget default of 6 cancelled activations an hour is the best published blink switch (0.10 false positives per minute; Li et al., Neurocomputing 2018, as recorded on the research page) expressed per hour. That figure comes from a different detector and setup, and counts false positives by the study's own definition. It is a yardstick for "no worse than the best published artifact switch", not an estimate of what this package will do and not a statement that 6 an hour is acceptable to a user.
• Nothing published validates a cancelled-activation proxy. Using "the user undid it within a grace window" as a stand-in for a false positive is a design choice made here because it is the only observable a running daemon has. The repository has never compared it with labelled phantom activations on a real person. Its two known failure directions (cancels unrelated to the switch; false positives never noticed) are argued, not measured.
• The statistics are textbook; their fit is untested. A Wilson interval for a proportion and a lower confidence bound on a Poisson rate are standard tools and are tested against known values. Whether cancellations behave like a Poisson process (they will cluster: a bad electrode contact produces bursts) is an assumption. Clustering makes the lower bound less conservative than it looks.
• Every governor number is a design choice with no field validation: the factor, the multiples, the dwell, the timer, the backoff, the confidence level, the grace window, the evidence floor. The unit tests show the state machine moves as written; they say nothing about whether those values suit any person.
• Our results are synthetic. That the governor stays quiet on a clean synthetic stream and escalates on a scripted noisy one shows the machine works, not that it fires at the right times in a room.

Falsifiable acceptance criteria¶

The governor is part of the Tier 1 gates of [[adr-v2-152-biosignal-artifact-switches]] (A5) and is judged against design/specs/biosignal-validation-protocol.md. Note what the field test can and cannot show here: yazses biosignal field-test acts on nothing and reports no cancels, so the governor cannot move during it. The governor is therefore judged in live use (a participant's own days with the daemon running and the ledger on, read through yazses biosignal report and the status block) plus one deliberately noisy live session, with thresholds frozen before the round:

1. It stays out of the way when nothing is wrong. Over the live-use days of participants whose field-test phantom bounds meet the A1 bound of ADR-v2-152, the governor entered DESENSITIZE or SUSPEND zero times. (A firing rate on a clean stream is the first measurement of a guard, ADR-021; a governor that fires there is broken, not cautious.) A participant who meets A1 but whose governor fires anyway is the proxy-versus-phantom disagreement of criterion 5, not a pass.
2. It acts when it should. In a deliberately noisy live session (electrode loosened or a source of interference added on purpose, with the participant cancelling the resulting mistakes), the governor reached DESENSITIZE and, if the noise persisted, SUSPEND, and the user-facing text said why and how to resume. The time to act, in active minutes, is recorded and reported; no latency bound is set before data exists.
3. Release is one action, every time it is tried. In every state (DESENSITIZE, SUSPEND) a single release returned the switch to normal and it did not re-suspend without fresh evidence.
4. Recovery works. A suspension ended by its own timer into DESENSITIZE, never straight to OK, and a switch that suspended repeatedly stayed off longer each time up to the cap.
5. The proxy is checked. The live ledger's cancelled counts and the field test's labelled phantom counts are reported side by side for the same sessions. There is no numeric gate on their agreement before data exists (inventing one would be a guess); a recorded finding that they disagree strongly triggers kill criterion 2 below.

Kill criteria¶

1. Unusable fire rate. If, after two tuning rounds, the governor still fires in the clean rest and hands_busy rounds on a configuration whose labelled phantom rate is within budget, its evidence floor and bound are wrong; the shipped default of max_cancelled_per_hour becomes 0 (count, never act) until a new ADR replaces the mechanism.
2. The proxy does not track phantoms. If the field test shows the cancelled-activation proxy is uninformative (quiet when labelled phantoms are frequent, loud when there are none), the proxy-driven governor is retired: the ledger and the report stay as a measurement, and the enforcement is replaced by something that does not depend on a proxy (for example a fixed conservative threshold set from the field-test phantom rate) in a new ADR.
3. Release cannot be made one action. If the integrator cannot offer a release that does not depend on the suspended source, a suspended switch is a lock-out, and the suspend step is removed (desensitize only) until it can.
4. Nobody reports cancels. If integrators never wire the cancel signal in practice, the budget is a no-op everywhere. The governor is then documented as measure-only and the budget key is removed rather than left to imply protection.

Not decided here¶

• The numbers (budget, factor, multiples, dwell, timer, backoff, confidence level). Measure first.
• Whether the desensitize step should scale thresholds by a fixed factor or by the observed margin (spec, open question 3).
• Whether the budget should be per event kind rather than one budget for the whole source. The current design is one governor per ledger; per-kind governors are possible by giving each kind its own ledger.
• How the integrator should word and bind the release (that is the global hands-free surface, ADR-v2-148).