# handoff-260210-1.md

## Problem framing

When estimating damping from impact tests, users often rely on visual inspection of decay plots (log-amplitude vs time) to judge whether a decay segment represents a valid, settled exponential regime. While automated curve fitting is powerful, it can obscure judgment calls that experienced analysts routinely make by eye: *Where does the decay look linear?*, *How far can I trust extrapolation?*, *Is this really a T60, or only a T20?*

This feature introduces an **interactive, analyst-driven measurement tool** that turns the decay plot into a *digital ruler*: the user explicitly selects a time span corresponding to a target decay (Tx), while the tool computes and reports objective diagnostics (slope, linearity, flags) that characterize the quality of that choice.

The intent is not to replace automated fitting, but to **augment it with a transparent, inspectable method** that mirrors how engineers reason on paper plots, while remaining machine-readable and integrable into larger workflows.

---

## Scope & intent

**S-260210_1-01 — Feature name**  
Span-based log-decay Tx measurement

**S-260210_1-02 — Feature positioning (LOCKED)**  
This is a **second available method** in the package. It must be implemented as an **opt-in** workflow that coexists with (and does not break) the current curve-fitting method.

**S-260210_1-03 — Primary purpose (LOCKED)**  
Multi-output diagnostic method exposing:
- user-measured Tx (T10 / T20 / T30 / T60)
- implied decay slope (dB/s)
- optional damping ratio ζ (if fn provided)

No strict hierarchy is enforced between outputs.

**S-260210_1-04 — Status (LOCKED)**  
Diagnostic **and recordable**. Results are stored/exported but do not override other methods by default.

**S-260210_1-05 — Package role (LOCKED)**  
`envelope-decay-fit` remains stand-alone, but is primarily designed for integration. UI returns pure data; persistence and arbitration are delegated to the integrator.

---

## Assumptions & non-goals

- Assumes analysis of **log-amplitude envelope** (not energy decay).
- Assumes user judgment is required; the tool does not enforce physical validity.
- Not intended for heavily damped or strongly nonlinear systems (though flags may reveal such behavior).
- Not an RT60 / room-acoustics EDC tool.

---

## Signal definition

**SIG-260210_1-01 — Input signal (LOCKED)**  
Uses the **same log-amplitude envelope** as the existing primary method:

```
20 * log10(|env(t)| / ref)
```

No additional preprocessing is introduced.

**SIG-260210_1-02 — dB reference (LOCKED)**  
0 dB is defined as the **maximum value of the envelope** over the analysis window.

**SIG-260210_1-03 — Peak robustness (LOCKED)**  
Strict maximum is used; no percentile or smoothing is applied to the reference.

---

## UX contract

**UX-260210_1-01 — Interaction primitive (LOCKED)**  
Horizontal `SpanSelector` selecting `[t0, t1]`.

**UX-260210_1-02 — Span semantics (LOCKED)**  
The span represents a **region of interest** (“look here”), not an assertion of linearity.

**UX-260210_1-03 — Commit behavior (LOCKED)**  
- User explores freely.
- Pressing `q` **commits** the current span and exits.
- Mirrors existing piecewise-fit workflow.

**UX-260210_1-04 — Tx selection (LOCKED)**  
A single active Tx is maintained and **cycled via keyboard** (e.g. `t`):

```
T10 → T20 → T30 → T60 → …
```

Minimal on-plot feedback indicates the active Tx.

---

## Visual semantics

**VIS-260210_1-01 — Overlays (LOCKED)**  
Both a **rectangle** and a **diagonal reference line** are drawn.

### Rectangle geometry (LOCKED)

- Height: `X dB` (X = active Tx)
- Top-left corner: `(t0, y(t0))`, aligned to local envelope value
- Bottom-right corner: `(t1, y(t0) - X)`
- Width: `t1 - t0` (user-measured Tx)

The rectangle is a **visual measuring aid**, not a projection.

### Diagonal reference (LOCKED)

- Drawn from rectangle top-left to bottom-right
- Represents the **ideal linear decay** corresponding to the chosen Tx over the span
- Used as both visual guide and analytical reference

---

## Computation & math contract

**ALG-260210_1-01 — Primary measurement (LOCKED)**  
```
Tx = t1 - t0
```

This is the declared, user-measured decay time.

**ALG-260210_1-02 — Implied slope (LOCKED)**  
```
slope_db_per_s = X / (t1 - t0)
```

**ALG-260210_1-03 — ζ computation (LOCKED)**  
If natural frequency `fn` is provided:

```
zeta = (slope_db_per_s * ln(10)) / (20 * 2π * fn)
```

If `fn` is missing, ζ is omitted or null.

---

## Validity, scoring & flags

**VAL-260210_1-01 — Linearity metrics (LOCKED)**  
Computed against the rectangle diagonal using **all envelope samples** in `[t0, t1]`:

- RMS deviation from diagonal (dB)
- R²-style goodness-of-fit

**VAL-260210_1-02 — Commit policy (LOCKED)**  
All selections are committable; diagnostics never block output.

### Diagnostic flags (LOCKED, v1)

Returned flags may include:

- `flag_low_linearity`
- `flag_high_rms_db`
- `flag_non_monotonic`
- `flag_span_too_short`
- `flag_db_drop_mismatch`
- `flag_hits_noise_floor`

All flags are **informational**.

---

## Returned data contract

**OUT-260210_1-01 — Mandatory fields (LOCKED)**

The UI returns a structured payload containing:

- `t0`, `t1`
- `Tx_active` (e.g. "T60")
- `Tx_value`
- `slope_db_per_s`
- `linearity_r2`
- `linearity_rms_db`
- `flags` (list or dict)
- `zeta` (nullable)

No file I/O is performed by this method.

---

## Implementation (suggested structure)

This section is **advisory**, not prescriptive.

Suggested responsibilities:

1. **UI / interaction layer**
   - Lives alongside existing manual segmentation tools
   - Manages SpanSelector, key bindings (`t`, `q`), and overlays
   - Returns a pure data object on commit

2. **Geometry & diagnostics helper**
   - Computes rectangle geometry and diagonal
   - Computes RMS / R² metrics and flags
   - Independent of Matplotlib (testable)

3. **Public API surface**
   - Exposes the method as an explicit, opt-in interactive workflow
   - Does not auto-trigger plotting or persistence

Data flow:

```
Envelope → UI span selection → geometry + diagnostics → payload → caller
```

---

## Integration notes

- Integrators (e.g. `wav-to-freq`) may:
  - store multiple Tx measurements per hit
  - compare this method with automated fitters
  - filter or rank results using flags

- This method does **not** decide which damping estimate is authoritative.

---

## Out-of-scope / future extensions

- Automatic projection-based Tx (extrapolation)
- Energy-based decay (EDC / RT60)
- Automated span suggestion
- Nonlinear / multi-slope modeling
- Confidence interval estimation

