loopgain 0.2.0__tar.gz → 0.3.0__tar.gz

{loopgain-0.2.0 → loopgain-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopgain
-Version: 0.2.0
+Version: 0.3.0
 Summary: Barkhausen stability monitor for AI agent loops. Real-time loop-gain (Aβ) monitoring with five named threshold bands, best-so-far rollback, and ETA prediction.
 Author-email: Dave Fitzsimmons <hello@loopgain.ai>
 License: Apache-2.0
@@ -51,12 +51,12 @@ Dynamic: license-file
 
 **Barkhausen stability monitor for AI agent loops.**
 
-Replace `max_iterations=5` with a real-time loop-gain (`Aβ`) monitor that knows whether your agent loop is converging, stalling, oscillating, or diverging — and what to do in each case.
+Replace `max_iterations=5` with a real-time trajectory classifier that reads four features off the loop's error series and routes it into one of five named states — knowing whether your agent loop is converging, stalling, oscillating, or diverging, and what to do in each case.
 
 [![PyPI](https://img.shields.io/pypi/v/loopgain.svg)](https://pypi.org/project/loopgain/)
 [![Python](https://img.shields.io/pypi/pyversions/loopgain.svg)](https://pypi.org/project/loopgain/)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-119_passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-157_passing-brightgreen.svg)](tests/)
 
 **Home:** [loopgain.ai](https://loopgain.ai)
 
@@ -97,7 +97,7 @@ while lg.should_continue():
     output = reviser.revise(output, errors)
 
 result = lg.result
-print(result.outcome)              # "converged" | "oscillating" | "diverged" | "max_iterations"
+print(result.outcome)              # "converged" | "oscillating" | "diverged" | "stalled" | "max_iterations"
 print(result.best_output)          # the lowest-error iteration's output
 print(result.iterations_used)
 print(result.gain_margin)          # 1 / max(Aβ_smooth)
@@ -110,28 +110,32 @@ print(result.savings_vs_fixed_cap)
 
 ## How it works
 
-LoopGain measures empirical loop gain at every iteration, then smooths it with an EMA:
+LoopGain measures empirical loop gain (`Aβ = E(n) / E(n-1)`) at every iteration and exposes it as a smoothed time series for visualization. The decision engine, however, classifies the **full error trajectory** using four features:
 
 ```
-Aβ(n)     = E(n) / E(n-1)
-Aβ_smooth = EMA(Aβ, w=3)
+E_ratio   = E_current / E_first      # cumulative reduction
+slope_log = OLS slope of log10(E)    # geometric trend direction
+slope_p   = t-test p-value of slope  # statistical significance
+osc_std   = std of detrended log10(E) # oscillation magnitude
 ```
 
-It classifies `Aβ_smooth` into five named bands:
+It routes the trajectory into one of five named states:
 
-| `Aβ_smooth` range | State | Action |
+| State | Condition | Action |
 | --- | --- | --- |
-| `< 0.3` | `FAST_CONVERGE` | Continue, predict ETA |
-| `0.3 ≤ Aβ < 0.85` | `CONVERGING` | Continue, watch for upward drift |
-| `0.85 ≤ Aβ < 0.95` | `STALLING` | Warn — diminishing returns |
-| `0.95 ≤ Aβ ≤ 1.05` | `OSCILLATING` | Break — return best-so-far |
-| `> 1.05` | `DIVERGING` | Abort — roll back to best-so-far |
+| `FAST_CONVERGE` | cumulative reduction to ≤ 10% of E_first | Continue, predict ETA |
+| `CONVERGING` | negative slope with `p < 0.05`, OR cumulative ≤ 50% | Continue, watch for upward drift |
+| `STALLING` | no significant slope, no detectable oscillation | Stop after 2 consecutive readings — return best-so-far |
+| `OSCILLATING` | high residual variance with flat trend | Stop — return best-so-far |
+| `DIVERGING` | positive slope with `p < 0.05` AND cumulative > 110% | Abort — roll back to best-so-far |
 
 Plus a short-circuit: if observed error drops at or below `target_error`, the loop stops immediately with state `TARGET_MET`. The default `target_error=0.0` short-circuits on exactly zero error — the natural completion signal for verifier-driven loops. Pass `target_error=None` to disable the short-circuit and rely on stability detection alone.
 
-The `±0.05` noise band around `Aβ=1` absorbs stochastic jitter from agent outputs without triggering false-positive aborts. The `0.85` `STALLING` boundary is an early warning — by the time `Aβ` crosses `1.0`, you've already wasted iterations.
+The decision is **conservative by design**: requiring both statistical significance and meaningful cumulative motion before terminating prevents false-positive aborts on noisy real-LLM error series. Validated at 98.8% macro-averaged accuracy across 5 regimes on N=1000 deterministic-mock trajectories (see `RESULTS_v2_classifier.md`). The STALLING ceiling of ~94% is the t-test's irreducible 5% type-I error rate, not a classifier weakness.
 
-These threshold defaults are derived from the Barkhausen-stability analysis and serve as reasonable starting points. Tune them per domain (via the `ThresholdBands` argument) once you have production traces.
+**Recommended minimum: 6 iterations** for reliable trend significance. At n≤4 the t-test is severely underpowered (df=2 requires |t|>4.3 for p<0.05) — the classifier conservatively falls back to STALLING when evidence is thin. The thresholds are derived analytically (control theory + statistical convention), not fitted; tune them per domain via the `TrajectoryThresholds` argument once you have production traces.
+
+**Legacy single-feature classifier:** the original v0.1 single-Aβ-band classifier (thresholds 0.3 / 0.85 / 0.95 / 1.05) is still available via `LoopGain(classifier='legacy_bands')` for callers that have empirically tuned the bands to a specific workload.
 
 ---
 
@@ -163,14 +167,16 @@ This transforms divergence detection from "abort with garbage" into "abort with
 
 ## API reference
 
-### `LoopGain(target_error=0.0, max_iterations=None, thresholds=None, smoothing_window=3, assumed_fixed_cap=10)`
+### `LoopGain(target_error=0.0, max_iterations=None, thresholds=None, trajectory_thresholds=None, classifier='trajectory', smoothing_window=3, assumed_fixed_cap=10)`
 
 Construct the monitor.
 
 - `target_error` — Stop when an observed error drops at or below this. Default `0.0` short-circuits on exactly zero error (the natural completion signal for verifier-driven loops). Pass `None` to disable the short-circuit entirely.
 - `max_iterations` — Hard safety cap. Default `None` (rely on stability detection). Recommended ~20–50 for production.
-- `thresholds` — Custom `ThresholdBands` if defaults don't fit your domain.
-- `smoothing_window` — EMA window for the smoothed Aβ. Default 3.
+- `thresholds` — Custom `ThresholdBands` for the legacy single-Aβ-band classifier. Ignored when `classifier='trajectory'`.
+- `trajectory_thresholds` — Custom `TrajectoryThresholds` for the multi-feature classifier (the default). Override only with workload-specific evidence.
+- `classifier` — `'trajectory'` (default, v0.2 multi-feature classifier) or `'legacy_bands'` (v0.1 single-Aβ-band classifier).
+- `smoothing_window` — EMA window for the smoothed Aβ series (always maintained for visualization, regardless of classifier choice). Default 3.
 - `assumed_fixed_cap` — Used to compute `savings_vs_fixed_cap`. Default 10.
 
 ### `lg.observe(errors, output=None) -> str`
@@ -183,7 +189,7 @@ Returns `False` once a terminal state fires.
 
 ### `lg.state -> str`
 
-Current state name. One of `INIT`, `FAST_CONVERGE`, `CONVERGING`, `STALLING`, `OSCILLATING`, `DIVERGING`, `TARGET_MET`, `MAX_ITERATIONS`.
+Current state name. One of `INIT`, `FAST_CONVERGE`, `CONVERGING`, `STALLING`, `OSCILLATING`, `DIVERGING`, `TARGET_MET`, `MAX_ITERATIONS`. The corresponding terminal `result.outcome` values are `converged`, `oscillating`, `diverged`, `stalled` (v0.2 trajectory mode only — STALLING terminating after 2 consecutive readings), `max_iterations`, or `in_progress`.
 
 ### `lg.eta -> int | None`
 
@@ -233,6 +239,32 @@ What is sent: state transitions, Aβ summary (min/max/median), gain margin, roll
 
 The hosted endpoint at `telemetry.loopgain.ai` is one acceptable destination. The [receiver](https://github.com/loopgain-ai/telemetry-receiver) and [dashboard](https://github.com/loopgain-ai/dashboard) are both open-source — self-host to keep telemetry fully under your control.
 
+> **This is not the same as anonymous usage telemetry.** `send_telemetry` sends *your* loop data to *your* dashboard, and only when you call it. There's a separate, opt-in **funnel** telemetry described below. The two never share data or code.
+
+---
+
+## Anonymous funnel telemetry (opt-in, off by default)
+
+LoopGain can report **anonymous usage counts** so a solo maintainer can tell whether the library is actually being used — install → first `observe()` → recurring use. **It is opt-in and default-decline: nothing is sent unless you explicitly turn it on.**
+
+```bash
+loopgain telemetry --show       # status + exactly what would be sent
+loopgain telemetry --enable     # opt in   (or: export LOOPGAIN_TELEMETRY=1)
+loopgain telemetry --disable    # opt out  (or: export LOOPGAIN_TELEMETRY=0)
+```
+
+`DO_NOT_TRACK=1` is honored as a hard opt-out, and CI environments are auto-detected and declined silently. When enabled, payloads carry only a locally-generated random id (not derived from your machine), hour-bucketed timestamps, library/Python/OS versions, the adapter in use, and a coarse outcome count. **Prompts, outputs, error contents, keys, paths, and IPs are never collected.** Delivery is batched, async, https-only, and fail-silent — it can never break your loop. Full details and the privacy contract: **[TELEMETRY.md](TELEMETRY.md)**.
+
+---
+
+## Command-line interface
+
+```bash
+loopgain --version              # or: loopgain version
+loopgain telemetry --show       # inspect / control anonymous funnel telemetry
+python -m loopgain telemetry --show   # equivalent, without the console script
+```
+
 ---
 
 ## Framework adapters

{loopgain-0.2.0 → loopgain-0.3.0}/README.md

@@ -2,12 +2,12 @@
 
 **Barkhausen stability monitor for AI agent loops.**
 
-Replace `max_iterations=5` with a real-time loop-gain (`Aβ`) monitor that knows whether your agent loop is converging, stalling, oscillating, or diverging — and what to do in each case.
+Replace `max_iterations=5` with a real-time trajectory classifier that reads four features off the loop's error series and routes it into one of five named states — knowing whether your agent loop is converging, stalling, oscillating, or diverging, and what to do in each case.
 
 [![PyPI](https://img.shields.io/pypi/v/loopgain.svg)](https://pypi.org/project/loopgain/)
 [![Python](https://img.shields.io/pypi/pyversions/loopgain.svg)](https://pypi.org/project/loopgain/)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-119_passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-157_passing-brightgreen.svg)](tests/)
 
 **Home:** [loopgain.ai](https://loopgain.ai)
 
@@ -48,7 +48,7 @@ while lg.should_continue():
     output = reviser.revise(output, errors)
 
 result = lg.result
-print(result.outcome)              # "converged" | "oscillating" | "diverged" | "max_iterations"
+print(result.outcome)              # "converged" | "oscillating" | "diverged" | "stalled" | "max_iterations"
 print(result.best_output)          # the lowest-error iteration's output
 print(result.iterations_used)
 print(result.gain_margin)          # 1 / max(Aβ_smooth)
@@ -61,28 +61,32 @@ print(result.savings_vs_fixed_cap)
 
 ## How it works
 
-LoopGain measures empirical loop gain at every iteration, then smooths it with an EMA:
+LoopGain measures empirical loop gain (`Aβ = E(n) / E(n-1)`) at every iteration and exposes it as a smoothed time series for visualization. The decision engine, however, classifies the **full error trajectory** using four features:
 
 ```
-Aβ(n)     = E(n) / E(n-1)
-Aβ_smooth = EMA(Aβ, w=3)
+E_ratio   = E_current / E_first      # cumulative reduction
+slope_log = OLS slope of log10(E)    # geometric trend direction
+slope_p   = t-test p-value of slope  # statistical significance
+osc_std   = std of detrended log10(E) # oscillation magnitude
 ```
 
-It classifies `Aβ_smooth` into five named bands:
+It routes the trajectory into one of five named states:
 
-| `Aβ_smooth` range | State | Action |
+| State | Condition | Action |
 | --- | --- | --- |
-| `< 0.3` | `FAST_CONVERGE` | Continue, predict ETA |
-| `0.3 ≤ Aβ < 0.85` | `CONVERGING` | Continue, watch for upward drift |
-| `0.85 ≤ Aβ < 0.95` | `STALLING` | Warn — diminishing returns |
-| `0.95 ≤ Aβ ≤ 1.05` | `OSCILLATING` | Break — return best-so-far |
-| `> 1.05` | `DIVERGING` | Abort — roll back to best-so-far |
+| `FAST_CONVERGE` | cumulative reduction to ≤ 10% of E_first | Continue, predict ETA |
+| `CONVERGING` | negative slope with `p < 0.05`, OR cumulative ≤ 50% | Continue, watch for upward drift |
+| `STALLING` | no significant slope, no detectable oscillation | Stop after 2 consecutive readings — return best-so-far |
+| `OSCILLATING` | high residual variance with flat trend | Stop — return best-so-far |
+| `DIVERGING` | positive slope with `p < 0.05` AND cumulative > 110% | Abort — roll back to best-so-far |
 
 Plus a short-circuit: if observed error drops at or below `target_error`, the loop stops immediately with state `TARGET_MET`. The default `target_error=0.0` short-circuits on exactly zero error — the natural completion signal for verifier-driven loops. Pass `target_error=None` to disable the short-circuit and rely on stability detection alone.
 
-The `±0.05` noise band around `Aβ=1` absorbs stochastic jitter from agent outputs without triggering false-positive aborts. The `0.85` `STALLING` boundary is an early warning — by the time `Aβ` crosses `1.0`, you've already wasted iterations.
+The decision is **conservative by design**: requiring both statistical significance and meaningful cumulative motion before terminating prevents false-positive aborts on noisy real-LLM error series. Validated at 98.8% macro-averaged accuracy across 5 regimes on N=1000 deterministic-mock trajectories (see `RESULTS_v2_classifier.md`). The STALLING ceiling of ~94% is the t-test's irreducible 5% type-I error rate, not a classifier weakness.
 
-These threshold defaults are derived from the Barkhausen-stability analysis and serve as reasonable starting points. Tune them per domain (via the `ThresholdBands` argument) once you have production traces.
+**Recommended minimum: 6 iterations** for reliable trend significance. At n≤4 the t-test is severely underpowered (df=2 requires |t|>4.3 for p<0.05) — the classifier conservatively falls back to STALLING when evidence is thin. The thresholds are derived analytically (control theory + statistical convention), not fitted; tune them per domain via the `TrajectoryThresholds` argument once you have production traces.
+
+**Legacy single-feature classifier:** the original v0.1 single-Aβ-band classifier (thresholds 0.3 / 0.85 / 0.95 / 1.05) is still available via `LoopGain(classifier='legacy_bands')` for callers that have empirically tuned the bands to a specific workload.
 
 ---
 
@@ -114,14 +118,16 @@ This transforms divergence detection from "abort with garbage" into "abort with
 
 ## API reference
 
-### `LoopGain(target_error=0.0, max_iterations=None, thresholds=None, smoothing_window=3, assumed_fixed_cap=10)`
+### `LoopGain(target_error=0.0, max_iterations=None, thresholds=None, trajectory_thresholds=None, classifier='trajectory', smoothing_window=3, assumed_fixed_cap=10)`
 
 Construct the monitor.
 
 - `target_error` — Stop when an observed error drops at or below this. Default `0.0` short-circuits on exactly zero error (the natural completion signal for verifier-driven loops). Pass `None` to disable the short-circuit entirely.
 - `max_iterations` — Hard safety cap. Default `None` (rely on stability detection). Recommended ~20–50 for production.
-- `thresholds` — Custom `ThresholdBands` if defaults don't fit your domain.
-- `smoothing_window` — EMA window for the smoothed Aβ. Default 3.
+- `thresholds` — Custom `ThresholdBands` for the legacy single-Aβ-band classifier. Ignored when `classifier='trajectory'`.
+- `trajectory_thresholds` — Custom `TrajectoryThresholds` for the multi-feature classifier (the default). Override only with workload-specific evidence.
+- `classifier` — `'trajectory'` (default, v0.2 multi-feature classifier) or `'legacy_bands'` (v0.1 single-Aβ-band classifier).
+- `smoothing_window` — EMA window for the smoothed Aβ series (always maintained for visualization, regardless of classifier choice). Default 3.
 - `assumed_fixed_cap` — Used to compute `savings_vs_fixed_cap`. Default 10.
 
 ### `lg.observe(errors, output=None) -> str`
@@ -134,7 +140,7 @@ Returns `False` once a terminal state fires.
 
 ### `lg.state -> str`
 
-Current state name. One of `INIT`, `FAST_CONVERGE`, `CONVERGING`, `STALLING`, `OSCILLATING`, `DIVERGING`, `TARGET_MET`, `MAX_ITERATIONS`.
+Current state name. One of `INIT`, `FAST_CONVERGE`, `CONVERGING`, `STALLING`, `OSCILLATING`, `DIVERGING`, `TARGET_MET`, `MAX_ITERATIONS`. The corresponding terminal `result.outcome` values are `converged`, `oscillating`, `diverged`, `stalled` (v0.2 trajectory mode only — STALLING terminating after 2 consecutive readings), `max_iterations`, or `in_progress`.
 
 ### `lg.eta -> int | None`
 
@@ -184,6 +190,32 @@ What is sent: state transitions, Aβ summary (min/max/median), gain margin, roll
 
 The hosted endpoint at `telemetry.loopgain.ai` is one acceptable destination. The [receiver](https://github.com/loopgain-ai/telemetry-receiver) and [dashboard](https://github.com/loopgain-ai/dashboard) are both open-source — self-host to keep telemetry fully under your control.
 
+> **This is not the same as anonymous usage telemetry.** `send_telemetry` sends *your* loop data to *your* dashboard, and only when you call it. There's a separate, opt-in **funnel** telemetry described below. The two never share data or code.
+
+---
+
+## Anonymous funnel telemetry (opt-in, off by default)
+
+LoopGain can report **anonymous usage counts** so a solo maintainer can tell whether the library is actually being used — install → first `observe()` → recurring use. **It is opt-in and default-decline: nothing is sent unless you explicitly turn it on.**
+
+```bash
+loopgain telemetry --show       # status + exactly what would be sent
+loopgain telemetry --enable     # opt in   (or: export LOOPGAIN_TELEMETRY=1)
+loopgain telemetry --disable    # opt out  (or: export LOOPGAIN_TELEMETRY=0)
+```
+
+`DO_NOT_TRACK=1` is honored as a hard opt-out, and CI environments are auto-detected and declined silently. When enabled, payloads carry only a locally-generated random id (not derived from your machine), hour-bucketed timestamps, library/Python/OS versions, the adapter in use, and a coarse outcome count. **Prompts, outputs, error contents, keys, paths, and IPs are never collected.** Delivery is batched, async, https-only, and fail-silent — it can never break your loop. Full details and the privacy contract: **[TELEMETRY.md](TELEMETRY.md)**.
+
+---
+
+## Command-line interface
+
+```bash
+loopgain --version              # or: loopgain version
+loopgain telemetry --show       # inspect / control anonymous funnel telemetry
+python -m loopgain telemetry --show   # equivalent, without the console script
+```
+
 ---
 
 ## Framework adapters

{loopgain-0.2.0 → loopgain-0.3.0}/loopgain/__init__.py

@@ -10,6 +10,12 @@ Public API:
 """
 
 from loopgain._version import __version__
+from loopgain.classifier import (
+    TrajectoryFeatures,
+    TrajectoryThresholds,
+    classify_trajectory,
+    extract_features,
+)
 from loopgain.core import (
     LoopGain,
     LoopGainResult,
@@ -29,6 +35,10 @@ __all__ = [
     "LoopGain",
     "LoopGainResult",
     "ThresholdBands",
+    "TrajectoryThresholds",
+    "TrajectoryFeatures",
+    "classify_trajectory",
+    "extract_features",
     "INIT",
     "FAST_CONVERGE",
     "CONVERGING",

loopgain-0.3.0/loopgain/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m loopgain`` to invoke the CLI."""
+
+import sys
+
+from loopgain.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

loopgain-0.3.0/loopgain/_version.py

@@ -0,0 +1,10 @@
+"""Single source of truth for the package version.
+
+``loopgain/__init__.py``, ``loopgain/telemetry.py`` (product receiver), and
+``loopgain/funnel.py`` (opt-in funnel telemetry) all import ``__version__``
+from here so the value never drifts between ``__version__`` and the
+``library_version`` field on any telemetry payload. Update this file (and
+``pyproject.toml``) for each release.
+"""
+
+__version__ = "0.3.0"

loopgain-0.3.0/loopgain/classifier.py

@@ -0,0 +1,323 @@
+"""Multi-feature trajectory classifier for LoopGain.
+
+The v0.1 classifier maps a single instantaneous smoothed loop-gain Aβ_smooth
+into one of five named states using fixed thresholds. Empirical validation
+on real GVR loops (Component Algebra Experiment 3, 2026-04-10, n=150) showed
+37.3% accuracy against intended ground truth — the single-feature design
+cannot disambiguate floor-noise convergence, slow monotone improvement, and
+mild drift-style divergence from one another.
+
+This module replaces that with a multi-feature classifier that operates on
+the full error trajectory. See ``PROTOCOL_v2_classifier.md`` for the
+pre-registered design, threshold derivations, and validation plan.
+
+The five state names are preserved (FAST_CONVERGE / CONVERGING / STALLING /
+OSCILLATING / DIVERGING) so the telemetry schema, dashboard, and integrations
+contract are not broken.
+"""
+
+from __future__ import annotations
+
+import math
+import statistics
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+
+# State constants — re-imported from core to avoid a circular import.
+# These strings must stay in lockstep with core.py.
+INIT = "INIT"
+FAST_CONVERGE = "FAST_CONVERGE"
+CONVERGING = "CONVERGING"
+STALLING = "STALLING"
+OSCILLATING = "OSCILLATING"
+DIVERGING = "DIVERGING"
+
+
+# ----- Pre-registered thresholds (PROTOCOL_v2_classifier.md §"Thresholds")
+#
+# Do not tune these to make individual workloads pass. The whole point of the
+# pre-registration is that the thresholds are derived from textbook control
+# theory and statistical convention, not fit. If a workload needs different
+# behavior, pass a custom TrajectoryThresholds instance rather than editing
+# these defaults.
+
+# Cumulative E_current/E_first reduction below which we call FAST_CONVERGE.
+# Derivation: one decade reduction = standard step-response 90% criterion.
+DEFAULT_E_RATIO_FAST = 0.1
+
+# E_current/E_first reduction below which we call CONVERGING even if the
+# slope p-value is not significant (the cumulative reduction is enough
+# evidence). Derivation: -3 dB / half-life.
+DEFAULT_E_RATIO_CONV = 0.5
+
+# Two-sided p-value below which the trend is "significant". Standard.
+DEFAULT_P_SIG = 0.05
+
+# Cumulative growth above which a positive slope counts as divergence. Below
+# this margin a positive slope is treated as noise around stalling.
+DEFAULT_DIV_MARGIN = 0.10
+
+# Detrended log10(E) residual std above which we call OSCILLATING. Derivation:
+# 0.30 log10 units ≈ ±2× ripple, matching an underdamped Q≈3 response.
+DEFAULT_OSC_STD_THRESHOLD = 0.30
+
+# Per-iteration log10 slope magnitude below which we call the trend flat
+# for the oscillation gate.
+DEFAULT_SLOPE_TOL = 0.05
+
+# Numerical floor to avoid log(0).
+_EPS = 1e-12
+
+
+@dataclass(frozen=True)
+class TrajectoryThresholds:
+    """Pre-registered thresholds for the multi-feature classifier.
+
+    Defaults match ``PROTOCOL_v2_classifier.md``. Override only when you have
+    workload-specific evidence; do not tune to inflate accuracy numbers
+    against held-out scenarios.
+    """
+
+    e_ratio_fast: float = DEFAULT_E_RATIO_FAST
+    e_ratio_conv: float = DEFAULT_E_RATIO_CONV
+    p_sig: float = DEFAULT_P_SIG
+    div_margin: float = DEFAULT_DIV_MARGIN
+    osc_std_threshold: float = DEFAULT_OSC_STD_THRESHOLD
+    slope_tol: float = DEFAULT_SLOPE_TOL
+
+
+@dataclass(frozen=True)
+class TrajectoryFeatures:
+    """Computed features for one trajectory at a point in time.
+
+    Returned by :func:`extract_features` so callers (e.g., telemetry, the
+    dashboard, downstream tests) can inspect the inputs to the classification
+    decision.
+    """
+
+    e_current: float
+    e_first: float
+    e_min: float
+    e_ratio: float
+    slope_log: float
+    slope_p: float
+    osc_std: float
+    n: int
+
+
+def _ols_slope_and_p(
+    x: Sequence[float], y: Sequence[float]
+) -> tuple[float, float]:
+    """Closed-form OLS slope + two-sided t-test p-value for the slope.
+
+    Pure stdlib — no scipy dependency in the core package.
+    Returns (0.0, 1.0) if n < 3 or x has zero variance.
+
+    The p-value uses a Student-t CDF approximation via the regularized
+    incomplete beta function from the math module (Python 3.12+:
+    ``math.lgamma`` is enough to build the survival function we need with
+    Wilson-Hilferty for any df ≥ 3).
+    """
+    n = len(x)
+    if n < 3:
+        # Need at least 3 points to estimate slope with any degrees of freedom.
+        if n == 2:
+            # Degenerate: slope is well defined, p-value is not.
+            dx = x[1] - x[0]
+            if dx == 0:
+                return 0.0, 1.0
+            return (y[1] - y[0]) / dx, 1.0
+        return 0.0, 1.0
+
+    mean_x = sum(x) / n
+    mean_y = sum(y) / n
+    sxx = sum((xi - mean_x) ** 2 for xi in x)
+    if sxx == 0:
+        return 0.0, 1.0
+    sxy = sum((xi - mean_x) * (yi - mean_y) for xi, yi in zip(x, y))
+    slope = sxy / sxx
+    intercept = mean_y - slope * mean_x
+
+    # Residual sum of squares; SE of slope; t-stat.
+    rss = sum((yi - (intercept + slope * xi)) ** 2 for xi, yi in zip(x, y))
+    df = n - 2
+    if df <= 0 or rss <= 0:
+        # Perfect fit (rss=0) — slope is exact; p ≈ 0 if slope != 0.
+        return slope, 0.0 if slope != 0 else 1.0
+    s2 = rss / df
+    se = math.sqrt(s2 / sxx)
+    if se == 0:
+        return slope, 0.0 if slope != 0 else 1.0
+    t_stat = slope / se
+    p = _two_sided_t_p(abs(t_stat), df)
+    return slope, p
+
+
+def _two_sided_t_p(t_abs: float, df: int) -> float:
+    """Two-sided Student-t p-value via a Wilson-Hilferty normal approximation.
+
+    Accurate enough for the classifier's purpose (decision threshold at
+    p=0.05) for df ≥ 3. Returns a value in [0, 1].
+
+    For df=2 (n=4 observations of x,y), uses the exact closed form
+    P(|T| > t) = 2 / (2 + t²)^(1/2) for one-sided, doubled.
+    """
+    if df <= 0:
+        return 1.0
+    if df == 1:
+        # exact: cdf_t(t,1) = 0.5 + arctan(t)/pi
+        return 2.0 * (0.5 - math.atan(t_abs) / math.pi)
+    if df == 2:
+        # exact one-sided survival: 1 - (1 + t²/2)^(-1) doubled
+        return min(1.0, 2.0 * (1.0 - t_abs / math.sqrt(2.0 + t_abs * t_abs) / 1.0) * 0.5
+                   + 2.0 * (0.5 - 0.5 * t_abs / math.sqrt(2.0 + t_abs * t_abs)))
+    # Wilson-Hilferty: transform t² ~ F(1, df), then F → chi-square via
+    # cube-root approximation. For our purposes the simpler normal-approx
+    # to the t with the Hill / Abramowitz adjustment is enough.
+    # Use the standard correction: z = t * (1 - 1/(4·df)) / sqrt(1 + t²/(2·df))
+    z = t_abs * (1.0 - 1.0 / (4.0 * df)) / math.sqrt(1.0 + t_abs * t_abs / (2.0 * df))
+    # Two-sided normal survival via erfc.
+    return math.erfc(z / math.sqrt(2.0))
+
+
+def extract_features(error_history: Sequence[float]) -> TrajectoryFeatures:
+    """Compute trajectory-level features from the error history.
+
+    Operates on log10(max(E, ε)) so geometric (multiplicative) trends become
+    linear. This is the standard transformation for any signal that obeys
+    Barkhausen's E_n = Aβ · E_{n−1}.
+    """
+    n = len(error_history)
+    if n == 0:
+        return TrajectoryFeatures(0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0)
+
+    e_first = error_history[0]
+    e_current = error_history[-1]
+    e_min = min(error_history)
+    e_ratio = e_current / max(abs(e_first), _EPS)
+
+    if n < 2:
+        return TrajectoryFeatures(
+            e_current=e_current,
+            e_first=e_first,
+            e_min=e_min,
+            e_ratio=e_ratio,
+            slope_log=0.0,
+            slope_p=1.0,
+            osc_std=0.0,
+            n=n,
+        )
+
+    xs = list(range(n))
+    log_e = [math.log10(max(e, _EPS)) for e in error_history]
+    slope, p = _ols_slope_and_p(xs, log_e)
+
+    # Detrended residual std (sample std).
+    intercept = sum(log_e) / n - slope * (sum(xs) / n)
+    residuals = [log_e[i] - (intercept + slope * xs[i]) for i in range(n)]
+    if n >= 2:
+        osc_std = statistics.pstdev(residuals)
+    else:
+        osc_std = 0.0
+
+    return TrajectoryFeatures(
+        e_current=e_current,
+        e_first=e_first,
+        e_min=e_min,
+        e_ratio=e_ratio,
+        slope_log=slope,
+        slope_p=p,
+        osc_std=osc_std,
+        n=n,
+    )
+
+
+def classify_trajectory(
+    error_history: Sequence[float],
+    *,
+    target_error: Optional[float] = None,
+    thresholds: Optional[TrajectoryThresholds] = None,
+) -> str:
+    """Classify a full error history into one of the five named states.
+
+    Decision rule (pre-registered, see PROTOCOL_v2_classifier.md):
+
+        TARGET_MET     if  E_current ≤ target_error
+        INIT           if  n < 2
+        FAST_CONVERGE  if  E_ratio  ≤ E_RATIO_FAST
+        CONVERGING     if  slope_log < 0 AND (slope_p < P_SIG OR E_ratio ≤ E_RATIO_CONV)
+        DIVERGING      if  slope_log > 0 AND slope_p < P_SIG AND E_ratio > 1 + DIV_MARGIN
+        OSCILLATING    if  osc_std ≥ OSC_STD_THRESHOLD AND |slope_log| < SLOPE_TOL
+        STALLING       otherwise
+
+    Note: TARGET_MET is returned only when ``target_error`` is supplied AND
+    ``E_current ≤ target_error``. This module does not own the TARGET_MET
+    short-circuit; ``LoopGain.observe`` handles that, and the classifier is
+    called only when the short-circuit has not fired. We accept the
+    ``target_error`` parameter so callers that want to classify a stored
+    trajectory get the same answer the live engine would have produced.
+    """
+    th = thresholds or TrajectoryThresholds()
+    if not error_history:
+        return INIT
+
+    e_current = error_history[-1]
+    if target_error is not None and e_current <= target_error:
+        # State name for "target met" is exposed by core, not this module.
+        # Callers that want the literal "TARGET_MET" string should check
+        # target_error themselves; we return FAST_CONVERGE as the classifier's
+        # opinion of a trajectory that's already at its floor.
+        return FAST_CONVERGE
+
+    n = len(error_history)
+    if n < 2:
+        return INIT
+
+    f = extract_features(error_history)
+
+    # n == 2 special case: with two observations, the slope is well defined
+    # but its p-value is not (zero residual degrees of freedom). Fall back to
+    # the sign of the change. This is the same conservatism as a Wilcoxon
+    # signed-rank test with n=1: insufficient evidence for a significance
+    # claim, but the *direction* is unambiguous.
+    if n == 2:
+        if f.e_ratio <= th.e_ratio_fast:
+            return FAST_CONVERGE
+        if f.e_ratio < 1.0:
+            return CONVERGING
+        if f.e_ratio > 1.0 + th.div_margin:
+            return DIVERGING
+        return STALLING
+
+    # Order matters: FAST_CONVERGE precedes CONVERGING; both precede the
+    # remaining gates.
+    if f.e_ratio <= th.e_ratio_fast:
+        return FAST_CONVERGE
+
+    slope_significant = f.slope_p < th.p_sig
+
+    if f.slope_log < 0 and (slope_significant or f.e_ratio <= th.e_ratio_conv):
+        return CONVERGING
+
+    if f.slope_log > 0 and slope_significant and f.e_ratio > 1.0 + th.div_margin:
+        return DIVERGING
+
+    if f.osc_std >= th.osc_std_threshold and abs(f.slope_log) < th.slope_tol:
+        return OSCILLATING
+
+    return STALLING
+
+
+__all__ = [
+    "TrajectoryThresholds",
+    "TrajectoryFeatures",
+    "extract_features",
+    "classify_trajectory",
+    "DEFAULT_E_RATIO_FAST",
+    "DEFAULT_E_RATIO_CONV",
+    "DEFAULT_P_SIG",
+    "DEFAULT_DIV_MARGIN",
+    "DEFAULT_OSC_STD_THRESHOLD",
+    "DEFAULT_SLOPE_TOL",
+]