quantized-lab 0.8.0__py3-none-any.whl

quantized/io/origin_project/annotation_marks.py

@@ -0,0 +1,288 @@
+"""Positioned free-text annotation marks for Origin figures (both containers).
+
+Origin graphs carry floating text objects ("Field applied in-plane\\r\\nT =
+1.3 K") whose text the figure decoders already recover into the flat
+``annotations: list[str]`` field. This module adds the POSITION: each text
+object stores its box's **top-left corner** as two little-endian float64
+layer-fractions ``(frac_a, frac_b)``, converted to data coordinates with the
+layer's own axis range::
+
+    x1 = x_from + frac_a * (x_to - x_from)
+    y1 = y_to   - frac_b * (y_to - y_from)      # y measured from the TOP
+
+Validated against a live-COM oracle (``ground_truth/<stem>/annotations.json``,
+the box corner Origin itself reports as ``x1``/``y1``): all 5 captured
+instances (hc2convert.opj Graph1/2/3, Hc2 data.opju Graph1/2) reproduce to
+~1e-9. The oracle graphs are all linear-scale; how Origin maps the fraction
+on a LOG axis is unverified — the linear formula above is applied regardless
+(it is the confirmed model; no log-axis oracle instance exists yet).
+
+**Where the fractions live**
+
+* ``.opj``: the text object's 133-byte header block (ASCII name at payload
+  offset 70, see ``figures.py``) holds ``frac_a`` at payload offset **19**
+  and ``frac_b`` at **27** — two consecutive LE doubles. Confirmed exact on
+  every oracle instance and plausibility-scanned across ~2000 ``Text*``/
+  ``Line*`` headers corpus-wide (all decode to sane layer fractions).
+* ``.opju`` (CPYUA): a tagged field ``85 13 <frac_a:8> <frac_b:8> 80 00 …``
+  ending exactly **32 bytes before** the object-name header that
+  ``opju_figure_text._object_headers`` locates (i.e. tag at ``h-32``,
+  ``frac_a`` at ``h-30``, ``frac_b`` at ``h-22``, and the constant ``80 00``
+  field boundary right after ``frac_b`` at ``h-14``). Confirmed at that
+  exact distance for every positioned ``Text*`` header in the 5-file real
+  corpus, and exact against both oracle instances.
+
+**Known negatives (omitted, never guessed):** RockingCurve.opju's composite
+panel-label Texts use an ``86 13`` tag and UnpolPlots.opju one ``85 1f``
+variant — same neighbourhood, different framing, no oracle coverage — so
+those objects keep their text in ``annotations`` but ship no position. The
+oracle's ``attach`` mode (all captured instances are 0 = layer-scale) is not
+decoded; a non-zero attach presumably reinterprets the fractions.
+
+Pure library: bytes in → dicts out. No fastapi/pydantic/routes imports.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import struct
+from typing import Any
+
+from quantized.io.origin_project.origin_richtext import clean_richtext
+
+__all__ = [
+    "build_mark",
+    "frac_to_data",
+    "opj_object_box",
+    "opj_object_fractions",
+    "opj_text_fractions",
+    "opju_text_fractions",
+    "page_point_fractions",
+]
+
+# ── shared annotation-text cleanup (moved here from figures.py so this module
+# stays a leaf both containers' figure decoders can import) ──────────────────
+
+_AUTO_TITLE = re.compile(r"^%\(\?[XY]\)")
+
+# Internal Origin storage/style markers that leak into raw text scans — see
+# figures.py's module docstring ("Axis-title / legend-label routing").
+# ``SYSTEM`` and ``SRCINFO`` are matched as UPPERCASE whole words only (the
+# internal tokens are always all-caps): the old case-insensitive substring
+# match silently dropped legitimate annotations like "System pressure = 3
+# bar" (2026-07-06 genericity audit #12). The remaining tokens are unusual
+# enough that a case-insensitive substring can't hit real prose.
+_INTERNAL_ANN_RE = re.compile(
+    r"\bSYSTEM\b|\bSRCINFO\b"
+    r"|(?i:STYLEHOLDER|OriginStorage|AxesDlgSettings|UseSameOptions)"
+)
+_SHEETREF_ANN_RE = re.compile(r"^Sheet\d+<?$")  # internal sheet source reference, not a title
+
+
+def _clean_annotations(titles: list[str]) -> list[str]:
+    """Drop internal Origin storage/style markers and bare sheet references
+    from recovered floating-text lines. Shared by BOTH containers' figure
+    decoders (``figures.py`` re-exports it; ``figures_opju.py`` additionally
+    truncates at its embedded PNG thumbnail first) and by ``build_mark``
+    below, so the flat ``annotations`` list and the positioned marks can
+    never disagree on what counts as user text."""
+    out: list[str] = []
+    for t in titles:
+        s = t.strip()
+        if not s or _INTERNAL_ANN_RE.search(s) or _SHEETREF_ANN_RE.match(s):
+            continue
+        out.append(s)
+    return out
+
+
+# ── position decode ──────────────────────────────────────────────────────────
+
+# .opj object BOX: four u16 LE at header payload offsets 3-10 = the object's
+# bounding box (x1, y1, x2, y2) in PAGE units, post-rotation (solved
+# 2026-07-06 against the 111-instance annotations.json oracle: XRD's rotated
+# peak labels store their pre-rotation anchor in the FRACTION pair, so a
+# fraction-only model is off by a font-proportional vector — the page box is
+# exact for every object kind). Mapped to data coordinates through the layer
+# FRAME quad (figures.py, layer-block offsets 113-119, same page units).
+_OPJ_BOX_OFFSET = 3
+
+# .opj: fraction doubles inside the 133-byte object header payload — the
+# object's pre-rotation ANCHOR. Kept as the fallback when the box/frame quad
+# is missing or implausible (older 4.3227 layer blocks); exact for
+# horizontal text, offset for rotated labels.
+_OPJ_FRACA_OFFSET = 19
+_OPJ_FRACB_OFFSET = 27
+
+# .opju: the position field's tag pair and its fixed distance before the
+# object-name header (see module docstring). The `80 00` right after frac_b
+# is the next field's boundary — constant across every corpus instance, kept
+# as a cheap structural check against false tag matches. Three tag flavours
+# carry the same <fracA:8><fracB:8> payload, each at its own fixed distance:
+# `85 13` at header-32 (Text* objects, the original 2026-07-05 decode),
+# `86 13` at header-32 (panel-label Text objects — verified 2026-07-06 when
+# the expanded annotations COM oracle finally covered RockingCurve's
+# instances under the identical fraction model; previously a known-negative),
+# and `85 1f` at header-33 (Legend objects and some panel Texts — resolved
+# 2026-07-06 via the legend-position oracle).
+_OPJU_POS_TAG_LOOKBACK = {b"\x85\x13": 32, b"\x86\x13": 32, b"\x85\x1f": 33}
+_OPJU_POS_SENTINEL = b"\x80\x00"
+
+# Corpus-wide the fractions stay within ~[-0.2, 4] (text can sit outside the
+# layer frame); a misread double is astronomically large or non-finite.
+_FRAC_BOUND = 50.0
+
+
+def _plausible(v: float) -> bool:
+    return math.isfinite(v) and abs(v) <= _FRAC_BOUND
+
+
+def _interp(frac: float, lo: float, hi: float, log: bool) -> float:
+    """Axis-fraction -> data value, linear or log10-space.
+
+    The log mapping was CONFIRMED 2026-07-06 against the legend-position COM
+    oracle on two log-Y graphs (XRD Graph2: linear read 9.73e4 vs oracle
+    7.291e4; log10 read 7.291e4 exact — same for Si-YIG-Py): on a log axis
+    Origin stores the fraction of the DECADE span. Non-positive bounds can't
+    be a real log axis — degrade to linear rather than crash."""
+    if log and lo > 0 and hi > 0:
+        return float(10 ** (math.log10(lo) + frac * (math.log10(hi) - math.log10(lo))))
+    return lo + frac * (hi - lo)
+
+
+def frac_to_data(
+    frac_a: float,
+    frac_b: float,
+    x_from: float,
+    x_to: float,
+    y_from: float,
+    y_to: float,
+    x_log: bool = False,
+    y_log: bool = False,
+) -> tuple[float, float]:
+    """The confirmed fraction→data model (module docstring): the box top-left
+    corner in data coordinates. ``frac_b`` measures down from the axis TOP;
+    log axes interpolate in log10 space (see ``_interp``)."""
+    return (
+        _interp(frac_a, x_from, x_to, x_log),
+        _interp(frac_b, y_to, y_from, y_log),  # from the TOP: hi -> lo
+    )
+
+
+def opj_object_box(payload: bytes) -> tuple[int, int, int, int] | None:
+    """The object's page-unit bounding box ``(x1, y1, x2, y2)`` from a
+    ``.opj`` 133-byte object header, or ``None`` when the quad is not a
+    plausible box (degenerate/reversed — dropped, never guessed)."""
+    if len(payload) < _OPJ_BOX_OFFSET + 8:
+        return None
+    x1, y1, x2, y2 = struct.unpack_from("<4H", payload, _OPJ_BOX_OFFSET)
+    if not (x1 < x2 and y1 < y2 and x2 - x1 < 60_000 and y2 - y1 < 60_000):
+        return None
+    return int(x1), int(y1), int(x2), int(y2)
+
+
+def page_point_fractions(
+    x: float, y: float, frame: tuple[int, int, int, int]
+) -> tuple[float, float] | None:
+    """A page-unit point as layer-frame fractions (x from left, y from the
+    frame TOP — the same convention :func:`frac_to_data` takes), or ``None``
+    on a degenerate frame."""
+    fx1, fy1, fx2, fy2 = frame
+    if fx2 <= fx1 or fy2 <= fy1:
+        return None
+    return (x - fx1) / (fx2 - fx1), (y - fy1) / (fy2 - fy1)
+
+
+def opj_text_fractions(payload: bytes) -> tuple[float, float] | None:
+    """``(frac_a, frac_b)`` from a ``.opj`` text object's 133-byte header
+    payload, or ``None`` when the doubles are missing/implausible (the text
+    then still ships in ``annotations``, just without a position)."""
+    if len(payload) < _OPJ_FRACB_OFFSET + 8:
+        return None
+    frac_a = float(struct.unpack_from("<d", payload, _OPJ_FRACA_OFFSET)[0])
+    frac_b = float(struct.unpack_from("<d", payload, _OPJ_FRACB_OFFSET)[0])
+    if not (_plausible(frac_a) and _plausible(frac_b)):
+        return None
+    return frac_a, frac_b
+
+
+def opj_object_fractions(
+    payload: bytes, frame: tuple[int, int, int, int] | None
+) -> tuple[float, float] | None:
+    """Anchor fractions for one ``.opj`` object header (solved 2026-07-06 vs
+    the 111-instance annotations oracle; hoisted out of ``figures.py``
+    2026-07-11, unchanged). Two independent position fields exist: the
+    FRACTION pair (the text anchor — exact for every unrotated object,
+    bordered or not) and the page-unit bounding BOX (post-rotation
+    geometry). For a 90-degree-rotated label the fraction pair stores only
+    the PRE-rotation anchor, which lands at exactly ``(+d, -d)`` page units
+    from the box's bottom-left — the signature of rotation about the first
+    character's baseline point (d = the font ascent; measured
+    equal-magnitude on every rotated corpus instance, XRD's 46 peak
+    labels). A bordered horizontal label's anchor sits at
+    ``(+inset, -boxheight+inset)`` instead — never the equal-magnitude
+    diagonal — so the test is geometric, not a corpus threshold. Rotated:
+    anchor at the box bottom-left (the text-start corner Origin itself
+    reports); everything else: the fraction pair (the pre-2026-07-06
+    behaviour, still exact for those)."""
+    fracs = opj_text_fractions(payload)
+    if frame is None or fracs is None:
+        return fracs
+    box = opj_object_box(payload)
+    if box is None:
+        return fracs
+    fl, ft, fr, fb = frame
+    anchor_x = fl + fracs[0] * (fr - fl)
+    anchor_y = ft + fracs[1] * (fb - ft)
+    dx = anchor_x - box[0]
+    dy = anchor_y - box[3]
+    if dx > 0 > dy and abs(dx + dy) <= 0.25 * dx:
+        return page_point_fractions(box[0], box[3], frame)
+    return fracs
+
+
+def opju_text_fractions(b: bytes, header_pos: int) -> tuple[float, float] | None:
+    """``(frac_a, frac_b)`` for the ``.opju`` text object whose name header
+    starts at ``header_pos``, or ``None`` when the fixed-distance ``85 13``
+    field isn't there (the known ``86 13``/``85 1f`` variants, or no position
+    at all — omitted, never guessed; see the module docstring)."""
+    for tag, lookback in _OPJU_POS_TAG_LOOKBACK.items():
+        q = header_pos - lookback
+        if q < 0 or b[q : q + 2] != tag:
+            continue
+        if b[q + 18 : q + 20] != _OPJU_POS_SENTINEL:
+            continue
+        frac_a = float(struct.unpack_from("<d", b, q + 2)[0])
+        frac_b = float(struct.unpack_from("<d", b, q + 10)[0])
+        if _plausible(frac_a) and _plausible(frac_b):
+            return frac_a, frac_b
+    return None
+
+
+def build_mark(
+    fracs: tuple[float, float] | None,
+    lines: list[str],
+    x_from: float,
+    x_to: float,
+    y_from: float,
+    y_to: float,
+    x_log: bool = False,
+    y_log: bool = False,
+) -> dict[str, Any] | None:
+    """One positioned annotation mark ``{"text", "x", "y"}`` — or ``None``
+    when the position never decoded or no user text survives cleanup.
+
+    ``lines`` are the object's raw recovered text runs, one per line; they go
+    through the exact same cleanup pipeline as the flat ``annotations`` field
+    (auto-title/legend filtering, internal-noise drop, rich-text decode) and
+    re-join with ``"\\n"`` — one mark per text OBJECT, multi-line preserved.
+    """
+    if fracs is None:
+        return None
+    kept = [t for t in lines if not _AUTO_TITLE.match(t) and "\\l(" not in t]
+    cleaned = [clean_richtext(t) for t in _clean_annotations(kept)]
+    text = "\n".join(s for s in cleaned if s.strip())
+    if not text:
+        return None
+    x, y = frac_to_data(fracs[0], fracs[1], x_from, x_to, y_from, y_to, x_log, y_log)
+    return {"text": text, "x": x, "y": y}

quantized/io/origin_project/container.py

@@ -0,0 +1,262 @@
+"""CPY container primitives shared by the Origin ``.opj``/``.opju`` readers.
+
+The ``.opj`` (CPYA) container is a stream of
+``<uint32 size LE><0x0A><payload><0x0A>`` blocks (``size==0`` = 5-byte spacer);
+worksheet columns, window definitions, and graph windows all live in that one
+walkable stream (see ``docs/origin_re/``). Format facts derived clean-room from
+local specimens — no GPL code consulted (``docs/origin_project_format.md``).
+"""
+
+from __future__ import annotations
+
+import re
+import struct
+from collections.abc import Iterator
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+
+__all__ = [
+    "ORIGIN_MISSING",
+    "NAME_RE",
+    "OriginProjectError",
+    "decode_doubles",
+    "decode_inline_text",
+    "decode_report_strings",
+    "fallback",
+    "plausible_column",
+    "salvage_column",
+    "walk_blocks",
+]
+
+_VIEWER = "the free Origin Viewer (https://www.originlab.com/viewer/)"
+
+# Origin's "missing value" sentinel for an empty numeric cell (-1.23456789e-300);
+# stored in the data, not flagged by the mask, so we map it to NaN on decode.
+ORIGIN_MISSING = struct.unpack("<d", b"\x0e\x2c\x13\x1c\xfe\x74\xaa\x81")[0]
+
+# A dataset name inside a column-header block: "<book>_<col>[@sheet]\0"
+# (the @N suffix marks columns of sheet N>1 in multi-sheet workbooks).
+# Bounds are deliberately WIDER than anything corpus-observed (book 62,
+# column 16, sheet 999): the old {0,40}/{1,4}/{1,2} caps were corpus maxima,
+# and a user-renamed 5+-char column short name (e.g. "Book1_Field") silently
+# lost its whole column when the regex refused the name (2026-07-06
+# genericity audit). The NUL terminator + the paired data-block structure in
+# ``opj.py`` remain the actual validity gates.
+NAME_RE = re.compile(rb"([A-Za-z][\w ]{0,62}_[A-Za-z0-9]{1,16}(?:@\d{1,3})?)\x00")
+
+
+class OriginProjectError(ValueError):
+    """An Origin project can't (yet) be read directly; the message explains why
+    and how to recover the data (subclasses ValueError so the import route maps
+    it to a 422 with the message intact)."""
+
+
+def fallback(path: Path, detail: str) -> OriginProjectError:
+    return OriginProjectError(
+        f"{detail} For now, open '{path.name}' in {_VIEWER} and export the "
+        f"worksheet(s) to CSV or ASCII, then import that file here."
+    )
+
+
+def walk_blocks(b: bytes) -> Iterator[tuple[int, bytes]]:
+    """Yield ``(size, payload)`` for each CPY block after the header line.
+
+    A ``size==0`` block is a section spacer yielded as ``(0, b"")``. Iteration
+    stops at the first framing break — the start of the trailing global-storage
+    / analysis-log area (which is framed differently).
+    """
+    nl = b.find(b"\n")
+    if nl < 0:
+        return
+    pos = nl + 1
+    n = len(b)
+    while pos + 5 <= n:
+        size = int.from_bytes(b[pos : pos + 4], "little")
+        if b[pos + 4] != 0x0A:  # expected delimiter missing → framing ended
+            return
+        pos += 5
+        if size == 0:
+            yield 0, b""
+            continue
+        if pos + size >= n or b[pos + size] != 0x0A:
+            return
+        yield size, b[pos : pos + size]
+        pos += size + 1
+
+
+def decode_doubles(data: bytes) -> NDArray[np.float64]:
+    """Decode a data block of 10-byte ``<uint16 mask><float64>`` records → values.
+
+    Byte-offset explicit (slice cols 2:10 of each record and view as float64) so
+    it is independent of numpy structured-dtype alignment.
+    """
+    n = len(data) // 10
+    rows = np.frombuffer(data, dtype=np.uint8, count=n * 10).reshape(n, 10)
+    vals = np.ascontiguousarray(rows[:, 2:]).view("<f8").reshape(n).copy()
+    vals[vals == ORIGIN_MISSING] = np.nan  # empty cells → NaN, not a bogus -1e-300
+    return vals
+
+
+_INLINE_TEXT_PRINTABLE = frozenset(range(0x20, 0x7F))
+
+
+def decode_inline_text(data: bytes) -> list[str] | None:
+    """Decode a data block as one short inline-text string per 10-byte record,
+    or ``None`` if it doesn't fit that shape (plan item 4 — the non-double
+    "text" column case).
+
+    A double column's record is ``<u16 mask><f8 value>``; a **Text & Numeric**
+    column reuses the exact same 10-byte record, but the 8-byte value area
+    holds a NUL-terminated ASCII/latin-1 string (up to 7 chars) followed by a
+    single ``0x00``/``0x01`` tag byte and zero padding out to 8 bytes, instead
+    of a raw float64. Pinned against ``hc2convert.opj``: every one of its 58
+    dropped "text" columns is exactly this shape, ``prefix="NaN"`` (Origin's
+    literal text sentinel for a fit that produced no critical-field value),
+    tag byte at value-offset 3 — 112,887 matching records, zero
+    counter-examples in a 6-file real-corpus scan. No header type-field byte
+    was found that reliably discriminates this from a double column (every
+    offset in the 147-byte column-storage header matches between the two);
+    this is a content-shape detector, same spirit as ``plausible_column`` and
+    the existing ``_looks_textual`` gate.
+
+    A record with no NUL in its 8-byte value area (a string longer than 7
+    chars, overflowing into the next record — seen in Origin's FitLinear/
+    NLFit auto-generated "Notes"/"Summary" report-sheet columns) makes the
+    WHOLE column unsafe to decode this way: return ``None`` rather than emit
+    misaligned rows. That family gets a second, dedicated try via
+    :func:`decode_report_strings` (a completely different, wider record
+    shape) before being dropped for good.
+    """
+    if not data or len(data) % 10 != 0:
+        return None
+    n = len(data) // 10
+    rows: list[str] = []
+    for k in range(n):
+        value = data[10 * k + 2 : 10 * k + 10]
+        nul = value.find(b"\x00")
+        if nul < 0:
+            return None
+        prefix = value[:nul]
+        if prefix and not all(c in _INLINE_TEXT_PRINTABLE for c in prefix):
+            return None
+        tail = value[nul + 1 :]
+        if tail and not (tail[0] in (0x00, 0x01) and all(c == 0 for c in tail[1:])):
+            return None
+        rows.append(prefix.decode("latin1"))
+    return rows
+
+
+_REPORT_MASK = b"\x01\x00"
+
+
+def decode_report_strings(data: bytes) -> list[str] | None:
+    """Decode a data block as Origin's auto-generated *report-sheet* column
+    shape — the ``decode_inline_text`` overflow residue of plan item 4:
+    FitLinear/NLFit "Notes"/"Summary"/"Parameters"/"RegStats"/"ANOVA" columns
+    whose cells hold a variable-length ``cell://<Section>.<Row>.<Field>``
+    reference string (e.g. ``"cell://Parameters.Slope.Value"``) too long for
+    ``decode_inline_text``'s fixed 8-byte value area.
+
+    This is a genuinely **different, wider** fixed-per-column record, not a
+    variant of the 10-byte double record: ``<u16 mask=0x0001><NUL-terminated
+    ASCII/latin-1 string><zero padding>``. The *width* is constant within one
+    column (Origin reserves it uniformly, sized to that column's longest
+    cell) but **varies column to column** — unlike a double column's constant
+    10-byte stride. The ``0x0001`` mask (vs. plain data's/inline-text's
+    ``0x0000``) is the tell that discriminates this shape outright; the width
+    itself is recovered from the block's own byte content (the spacing
+    between consecutive mask markers), then the whole block is re-validated
+    at that width before being accepted — a coincidental short match never
+    survives more than one row's validation.
+
+    Pinned against ``hc2convert.opj``'s 407 previously honest-dropped
+    report-sheet columns (Notes/Input/Parameters/RegStats/Summary/ANOVA
+    families, widths from 21 bytes up to 45+ depending on the longest
+    ``cell://`` string in that column): **407/407 decode cleanly, 0
+    validation failures, 0 collisions with the 10-byte double/inline-text
+    shapes** (both already ruled out a data block before this is tried).
+    Recovers the *reference string* naming which fit statistic a report cell
+    represents — not the fit's computed number itself (e.g. a Slope's actual
+    value); that is a separate, harder gap documented in
+    ``docs/origin_project_format.md`` "Non-double column values".
+    """
+    n = len(data)
+    if n < 3:
+        return None
+    idxs: list[int] = []
+    i = data.find(_REPORT_MASK)
+    while i >= 0:
+        idxs.append(i)
+        i = data.find(_REPORT_MASK, i + 1)
+    if not idxs or idxs[0] != 0:
+        return None  # every record must open with the mask, starting at byte 0
+    width = n if len(idxs) == 1 else min(idxs[k + 1] - idxs[k] for k in range(len(idxs) - 1))
+    if width < 3 or n % width != 0:
+        return None
+    rows: list[str] = []
+    for k in range(n // width):
+        rec = data[width * k : width * k + width]
+        if rec[:2] != _REPORT_MASK:
+            return None
+        value = rec[2:]
+        nul = value.find(b"\x00")
+        if nul < 0:
+            return None
+        text, pad = value[:nul], value[nul + 1 :]
+        if any(pad) or not all(c in _INLINE_TEXT_PRINTABLE for c in text):
+            return None
+        rows.append(text.decode("latin1"))
+    return rows
+
+
+def plausible_column(vals: NDArray[np.float64], *, allow_all_nan: bool = False) -> bool:
+    """Reject a decoded column whose values betray a non-double payload.
+
+    Text / integer / float32 columns (the 147-byte column header carries a
+    type field the readers don't decode yet — plan item 4) reinterpret as
+    float64 garbage: subnormals (|v| ≲ 1e-300) and absurd magnitudes
+    (|v| ≳ 1e290) that real instrument data never contains. Dropping the whole
+    column on the first such value is honest-absent; silent garbage is worse
+    than a gap. ``allow_all_nan`` keeps genuinely empty columns (the ``.opj``
+    reader pads ragged books with them).
+    """
+    finite = vals[np.isfinite(vals)]
+    if finite.size == 0:
+        return allow_all_nan
+    mag = np.abs(finite)
+    wrecked = ((mag < 1e-290) & (finite != 0.0)) | (mag > 1e290)
+    return not bool(np.any(wrecked))
+
+
+# A real double column may carry a couple of stray junk cells (denormals in the
+# missing-sentinel magnitude band) without being a non-double payload — XRD.opj
+# Book6_A (1543 2-theta values + 4 denormals) is the measured case. True garbage
+# (text/int reinterpretations) runs >=5% wrecked across the corpus; the gap
+# between <=0.26% (real) and >=0.83% (the report-sheet family, which the
+# text/report decoders claim FIRST) motivates the tight bound below.
+_SALVAGE_MAX_FRAC = 0.005
+_SALVAGE_MAX_CELLS = 4
+
+
+def salvage_column(vals: NDArray[np.float64]) -> NDArray[np.float64] | None:
+    """``vals`` with stray wrecked cells masked to NaN, or None if not salvageable.
+
+    Last-resort classification (after the text and report decoders have
+    passed): accepts only columns whose wrecked cells are both rare
+    (<= 0.5% of finite values) and few (<= 4 absolute) — measured to separate
+    real columns with junk cells from every true-garbage column in the corpus.
+    """
+    finite_mask = np.isfinite(vals)
+    finite = vals[finite_mask]
+    if finite.size == 0:
+        return None
+    mag = np.abs(vals)
+    wrecked = np.isfinite(vals) & (((mag < 1e-290) & (vals != 0.0)) | (mag > 1e290))
+    n = int(wrecked.sum())
+    if n == 0 or n > _SALVAGE_MAX_CELLS or n / finite.size > _SALVAGE_MAX_FRAC:
+        return None
+    out = vals.copy()
+    out[wrecked] = np.nan
+    return out