quantized-lab 0.8.0__py3-none-any.whl

quantized/io/origin_project/windows.py

@@ -0,0 +1,238 @@
+"""Extract per-column metadata from the ``.opj`` windows section.
+
+Worksheet *window definitions* live in the same block stream as the column
+data, after the datasets section. Each worksheet window opens with a header
+block (``00 00 <BookShort> 00 …``, long name ending at the ``@${`` storage
+marker) and contains, per column, a **property block** (≥500 B; designation at
+``0x11``, NUL-terminated short name at ``0x12``) immediately followed by a
+**label-text block** (``LongName\\r\\nUnit\\r\\nComment``, cut at ``@${``).
+Column ``S`` of book ``B`` maps to the dataset named ``"B_S"``.
+
+A property block's byte 0x06 varies with the column's storage flavour --
+``0x09`` for a plain sheet-1 column, ``0x0B`` for a formula/derived column
+*and* for every column of an auto-generated report sheet (FitLinear/FitNL's
+"Parameters"/"Notes"/etc. sheets) -- so it does not distinguish sheet
+identity; both values are accepted (plan item: report-sheet leak fix).
+
+**Multi-sheet books** (a workbook with a report/curve sheet appended after
+the real data, e.g. Origin's FitLinear auto-adds "FitLinear1"/
+"FitLinearCurve1" siblings to the sheet it fits) restart column lettering at
+"A" for each extra sheet, and *also* reuse the very same 0x0B property-block
+shape as a real formula column -- so neither the storage-flavour byte nor a
+short-name repeat is a reliable, early sheet-boundary signal on its own (a
+report sheet's own property/label blocks can front-run a repeat detection
+by many columns). The real signal is a fixed 365-byte **sheet/layer
+sub-header** block carrying ``Pd<Name>\\0`` at a constant offset (0xD0) --
+one appears at the very start of every worksheet sheet (and every graph
+layer, tagged ``Pd1``/``Pd2``/…) inside a window's block span. The *second*
+one seen since the enclosing window header is the true start of sheet 2+;
+everything from there on (property blocks, labels, formulas) is excluded.
+Validated against Moke.opj's ``Book4`` (Sheet1 / FitLinear1 /
+FitLinearCurve1 — three ``Pd...`` markers, one per sheet, exactly bracketing
+each sheet's real column-property-block run) and every single-sheet corpus
+book (exactly one marker, at the window's very start). Older-format (CPYA
+4.3227) files carry no such marker at all; the short-name-repeat guard is
+kept as a fallback for that case (unverified whether any 4.3227 file in the
+corpus has a real multi-sheet book -- none observed to date).
+
+Byte layout validated against the local corpus — see
+``docs/origin_re/opj_windows_section.md`` (plan item 1).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from quantized.io.origin_project.container import walk_blocks
+
+__all__ = ["BookMeta", "ColumnMeta", "window_metadata"]
+
+# Origin's published plot-designation enum (format fact).
+_DESIGNATION = {
+    0: "Y",
+    1: "disregard",
+    2: "Y-error",
+    3: "X",
+    4: "label",
+    5: "Z",
+    6: "X-error",
+}
+
+
+@dataclass(frozen=True)
+class ColumnMeta:
+    short: str
+    designation: str
+    long_name: str = ""
+    unit: str = ""
+    comment: str = ""
+
+
+@dataclass
+class BookMeta:
+    short: str
+    long_name: str
+    columns: dict[str, ColumnMeta] = field(default_factory=dict)
+
+
+def _cstring(payload: bytes, start: int, limit: int = 48) -> str | None:
+    """Printable NUL-terminated ASCII at ``start``, or None."""
+    end = payload.find(b"\x00", start, start + limit)
+    if end <= start:
+        return None
+    raw = payload[start:end]
+    if not all(0x20 <= c < 0x7F for c in raw):
+        return None
+    return raw.decode("latin1")
+
+
+def _is_window_header(payload: bytes) -> str | None:
+    """A window-header block starts ``00 00 <Name> 00``; return the name.
+
+    Digit-led names are real (``tree.py``'s module docstring documents
+    ``30nmADPNR`` and six digit-led graph names in the corpus, COM-verified),
+    so the first-char gate is ``isalnum``, not ``isalpha`` — the old
+    alpha-first check silently hid digit-led graph windows from
+    ``figures.py`` AND let their internal blocks poison
+    ``opj_curves.column_id_map`` (a digit-led graph was not recognized as a
+    graph, so its 519-byte curve records were scanned as column storage)."""
+    if len(payload) < 150 or payload[0] or payload[1]:
+        return None
+    name = _cstring(payload, 2, 64)
+    return name if name and name[0].isalnum() else None
+
+
+def _book_long_name(payload: bytes, short: str) -> str:
+    """The display title, stored in the header tail.
+
+    v4.3380 headers end the title at an ``@${…}<OriginStorage>`` marker;
+    v4.3227 headers have no storage blob — the title is simply the last
+    printable run after the fixed-format region (offset > 0x60).
+    """
+    anchor = payload.find(b"@${")
+    if anchor >= 0:
+        start = payload.rfind(b"\x00", 0, anchor) + 1
+        raw = payload[start:anchor]
+        if raw and all(0x20 <= c < 0x7F for c in raw):
+            return raw.decode("latin1")
+        return short
+    runs = [m for m in re.finditer(rb"[\x20-\x7e]{2,}", payload) if m.start() > 0x60]
+    if runs:
+        cand = runs[-1].group().decode("latin1")
+        if cand != short:
+            return cand
+    return short
+
+
+def _is_column_block(payload: bytes) -> bool:
+    """Robust, version-independent column-property block detector.
+
+    Byte 0x06 is ``0x09`` for a plain (never-recalculated) sheet-1 column and
+    ``0x0B`` for a formula/derived column or any report-sheet column -- both
+    are real column-property blocks, so both are accepted (a Moke.opj Book4
+    Sheet1 measurement had 14/15 columns at ``0x09``; only its one formula
+    column, "Normalized1", was ``0x0B`` -- the old ``==0x0B``-only check
+    dropped those 14 silently instead of mapping them).
+    """
+    return (
+        len(payload) >= 500
+        and payload[0x06] in (0x09, 0x0B)
+        and payload[0x25] in (0x21, 0x30)  # 0x30 observed on Y-error columns
+        and _cstring(payload, 0x12, 8) is not None
+    )
+
+
+_SHEET_HEADER_SIZE = 365
+_SHEET_NAME_OFFSET = 0xD0  # 208: fixed offset of the "Pd<Name>" marker
+
+
+def _is_sheet_header(payload: bytes) -> str | None:
+    """A per-sheet (or per-graph-layer) sub-header: the real sheet-boundary
+    signal (see module docstring). Always exactly 365 B, carrying
+    NUL-terminated ``Pd<Name>`` at a fixed offset -- never observed to
+    collide with a window-header or column-property block's size/shape
+    across the local corpus (window headers range 195-359 B in every
+    corpus file; a column-property block is always >=500 B)."""
+    if len(payload) != _SHEET_HEADER_SIZE:
+        return None
+    if payload[_SHEET_NAME_OFFSET : _SHEET_NAME_OFFSET + 2] != b"Pd":
+        return None
+    return _cstring(payload, _SHEET_NAME_OFFSET + 2, 40)
+
+
+def _label_rows(payload: bytes) -> tuple[str, str, str]:
+    """Parse a label-text block: LongName / Unit / Comment (missing → "")."""
+    text = payload.split(b"\x00", 1)[0]
+    cut = text.find(b"@${")
+    if cut >= 0:
+        text = text[:cut]
+    rows = text.decode("latin1", errors="replace").split("\r\n")
+    rows += ["", "", ""]
+    return rows[0], rows[1], rows[2]
+
+
+def window_metadata(b: bytes) -> dict[str, BookMeta]:
+    """Map book short name → :class:`BookMeta` with per-column names/units.
+
+    Only primary-sheet columns are mapped for now (multi-sheet ``@N`` datasets
+    are plan item 5). Graph windows contain no column blocks and drop out
+    naturally.
+
+    A report/curve sheet appended after the primary sheet (Origin's
+    FitLinear/FitNL auto-add, e.g. "FitLinear1"/"FitLinearCurve1") must never
+    reach ``current.columns`` — that dict is the *primary-sheet* map. The
+    ``Pd<Name>`` sheet sub-header (`_is_sheet_header`) is the precise
+    boundary: the second one seen since the enclosing window header closes
+    collection immediately, before that sheet's first property block. The
+    short-name-repeat check stays as a fallback for the older container
+    version that carries no such marker (plan item 5's original guard).
+    """
+    books: dict[str, BookMeta] = {}
+    current: BookMeta | None = None
+    pending: tuple[str, str] | None = None  # (short, designation) awaiting label
+    closed = False  # set once the current window moves past its primary sheet
+    sheets_seen = 0  # count of Pd<Name> markers since the current window header
+
+    def commit(long_name: str = "", unit: str = "", comment: str = "") -> None:
+        nonlocal pending, closed
+        if pending is not None and current is not None and not closed:
+            short, desig = pending
+            if short in current.columns:
+                # A repeated short means sheet 2+ started (every sheet restarts
+                # at column A); only the primary sheet maps to plain
+                # "<Book>_<Col>" datasets, so stop collecting (plan item 5;
+                # fallback for containers with no Pd<Name> marker).
+                closed = True
+            else:
+                current.columns[short] = ColumnMeta(short, desig, long_name, unit, comment)
+        pending = None
+
+    for size, payload in walk_blocks(b):
+        if size == 0:
+            continue
+        header_name = _is_window_header(payload)
+        sheet_name = _is_sheet_header(payload) if header_name is None else None
+        is_col = (
+            _is_column_block(payload) if header_name is None and sheet_name is None else False
+        )
+        if pending is not None:
+            if header_name is None and sheet_name is None and not is_col and size < 500:
+                commit(*_label_rows(payload))  # the label block for the pending column
+                continue
+            commit()  # structural block follows — column had no label text
+        if header_name is not None:
+            current = books.setdefault(
+                header_name, BookMeta(header_name, _book_long_name(payload, header_name))
+            )
+            closed = False
+            sheets_seen = 0
+        elif sheet_name is not None:
+            sheets_seen += 1
+            if sheets_seen > 1:  # the 2nd+ sheet/layer marker: stop mapping columns
+                closed = True
+        elif current is not None and is_col and not closed:
+            short = _cstring(payload, 0x12, 8) or "?"
+            pending = (short, _DESIGNATION.get(payload[0x11], "Y"))
+    commit()
+    return books

quantized/io/origin_project/windows_opju.py

@@ -0,0 +1,393 @@
+"""Extract per-column long-names/units from the ``.opju`` (CPYUA) windows section.
+
+The CPYUA container's worksheet windows section is not `.opj`'s CPY block
+stream (see ``docs/origin_re/opj_windows_section.md``) — it uses its own
+tag/length framing that this module does not fully parse. What IS pinned,
+validated against Origin's own exported ground truth across five real
+corpus files (XAS, RockingCurve, UnpolPlots, "Fixed Lambdas SI", plus the
+``rosetta_*`` specimens — 145/145 names, units, and comments matched):
+
+* Every worksheet column carries a 2-byte **plot-designation marker**:
+  ``21 51`` for X, ``21 61`` for Y, ``30 61`` for Y-error — the same
+  marker-byte + display-code convention `.opj` uses at property-block
+  offsets 0x25/0x26 (see ``opj_windows_section.md`` sec 4.1), reused inside
+  CPYUA's own framing.
+* A fixed-shape run (default column-format doubles) follows every marker,
+  then an OPTIONAL length-prefixed embedded blob (``<len><tag=0x01><bytes>
+  <NUL>``) carrying that column's ``ColumnInfo``/``ImportFile`` storage
+  (only present for imported-file columns — a long file path, possibly
+  using Origin's internal string back-reference shorthand which this
+  module never tries to decode), then the REAL label record in the SAME
+  ``<len:u8><tag:u8><text><NUL>`` shape (``len`` counts tag+text+NUL).
+  ``text`` splits on ``\\r\\n`` into long_name/unit/comment (0-3 rows); a
+  zero-length text (tag ``0x01``, no ``\\r\\n``) means "no label" (e.g. an
+  unlabeled Y column) and some columns carry only a bare long name with no
+  ``\\r\\n`` at all (single-row form).
+* Every column emits its own marker (+ optional label) record, in true
+  sheet column order (A, B, C, ...) — INCLUDING columns that never decode
+  as data (e.g. a blank/text column between two decoded numeric ones).
+  That is why association is by ORDINAL POSITION within one book's
+  contiguous marker run, mapped through Origin's column lettering
+  (A, B, ... Z, AA, AB, ... — wide measurement sheets run well past Z),
+  rather than by parsing an internal short-name field — no such field was
+  pinned for CPYUA (unlike `.opj`'s offset-0x12 short name). Each book is
+  anchored INDEPENDENTLY (not via a forward-only cursor): a project's book
+  windows are not in decoded-book order, so a monotonic cursor drops every
+  book whose window sits before an already-anchored one (the Hc2 project
+  interleaves 30+ of them). Anchors are exact, so independent search is safe.
+* Each book's own marker run is anchored via ONE OF: (a) the embedded
+  ``ColumnInfo``/``ImportFile`` path's filename, alnum-stripped and matched
+  against the book's known short name (handles Origin's habit of dropping
+  underscores when deriving a book short name from an imported filename,
+  e.g. ``bl11_YIGPy_032.dat`` -> book ``bl11YIGPy032``); or (b) a
+  ``<len=namelen+2> 00 00 <name>`` window/book-header reference that
+  appears even for books never imported from a file (manually-typed
+  sheets, e.g. the ``rosetta_*`` specimens).
+
+Positional guessing is NOT used to *detect* a label: every accepted record
+matches the exact ``<len><tag><text><NUL>`` byte count PLUS a character-
+class + known-internal-token filter (rejects embedded blob fragments like
+a truncated ``ResultsLog``/``OriginStorage`` token, which the length-prefix
+match alone can accidentally land inside). Association across a book's
+columns IS positional, but only after that book's boundary is independently
+confirmed by anchor (a) or (b) above — never by scanning the whole file for
+ASCII runs. When no anchor is found, or the marker run doesn't cover every
+column ``opju_codec.scan_columns`` actually decoded for that book, the book
+is left out of the result entirely (A/B/C fallback stays in force) rather
+than guessed at.
+
+See ``docs/origin_re/opju_container.md`` for the full byte-level trail.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+
+from quantized.io.origin_project.opju_codec import tail_start
+from quantized.io.origin_project.windows import BookMeta, ColumnMeta
+
+__all__ = ["opju_window_metadata"]
+
+_X_MARK = b"\x21\x51"
+_Y_MARK = b"\x21\x61"
+_YERR_MARK = b"\x30\x61"
+# Label / Z / X-error markers, pinned 2026-07-06 by the designations.opju
+# by-construction specimen (one column per designation): Label = `21 41`;
+# Z and X-error SHARE `20 61` and are told apart by the record's own
+# designation code byte (`82 02 <code>`: 1=label 2=Y-error 3=X 4=Z
+# 5=X-error; a plain Y stores no code field at all). Before these, a book
+# containing ANY such column failed the cover-check and silently lost its
+# ENTIRE metadata run (names, units, and the X designation) — the audit's
+# whole-book blast radius (#10).
+_LABEL_MARK = b"\x21\x41"
+_ZX_MARK = b"\x20\x61"  # Z or X-error; resolved via the code byte
+_DESIGNATION = {
+    "X": "X",
+    "Y": "Y",
+    "Y-error": "Y-error",
+    "label": "label",
+    "Z": "Z",
+    "X-error": "X-error",
+}
+
+# A backslash-delimited filename token, as embedded in a column's ImportFile path.
+_FILENAME_RE = re.compile(rb"\\([\w \-]{1,60}?\.[A-Za-z0-9]{2,5})(?=[^\w.]|$)")
+# A plausible bare long-name (no unit/comment row): starts with a letter, then
+# the punctuation real scientific column names use -- parens/brackets/colons/
+# underscores (e.g. "Nb Hc2 (T)", "NiBi_3::R", "temperature: T1",
+# "multi[0]:iterator"). Still excludes path/markup chars (backslash, <, >), which
+# the _JUNK_MARKERS filter rejects separately, so a length-prefix coincidence
+# landing inside a storage blob is still caught. Checked on the DECODED string
+# (see _is_single_row_label) so non-ASCII scientific glyphs -- degree, Angstrom,
+# micro, ohm, Greek, sub/superscripts -- are accepted; the .opju container is
+# UTF-8, so "tilt 45<deg>" arrives as bytes c2 b0 and a byte-only ASCII regex
+# both rejected it and (via latin-1) mojibaked it (2026-07-06 genericity audit).
+_LABEL_PUNCT = frozenset(" _:()[]./+%#*,-")
+# Text containing any of these is inside an embedded storage blob, not a real label.
+_JUNK_MARKERS = (b"\\", b"OriginStorage", b"ColumnInfo", b"ImportFile", b"<", b">")
+# Single-row candidates that are themselves a fragment of one of these internal
+# tokens (e.g. a length-prefix match landing mid-string, "esultsLog") are noise.
+_KNOWN_TOKENS = (
+    b"ResultsLog",
+    b"OriginStorage",
+    b"ColumnInfo",
+    b"ImportFile",
+    b"TREE",
+    b"Organizer",
+    b"IMGEXP",
+    b"AXISTYPE",
+    b"Script",
+    b"History",
+    b"PConst",
+)
+_MAX_GAP = 600  # max byte spacing between one column-property record and the next
+
+
+def _zx_designation(b: bytes, mark_pos: int) -> str:
+    """Resolve the shared ``20 61`` marker to Z or X-error via the record's
+    own designation code (``82 02 <code>`` a few bytes earlier: 4=Z,
+    5=X-error). An unresolvable record reads as "Z" (either way the column
+    is a non-plottable auxiliary; the marker still COUNTS the column, which
+    is what protects the book's metadata run)."""
+    j = b.rfind(b"\x82\x02", max(0, mark_pos - 16), mark_pos)
+    if j >= 0 and j + 2 < len(b) and b[j + 2] == 5:
+        return "X-error"
+    return "Z"
+
+
+def _decode_cell_text(raw: bytes) -> str | None:
+    """Decode a column-label cell, or ``None`` if it isn't text.
+
+    The ``.opju`` container stores text as UTF-8 (degree = ``c2 b0``, micro =
+    ``c2 b5``, Greek mu = ``ce bc``); fall back to latin-1 for the rare cell
+    that is valid latin-1 but not UTF-8. Reject any cell holding a C0 control
+    other than TAB/CR/LF — that is a binary/format block, never a label."""
+    for enc in ("utf-8", "latin1"):
+        try:
+            s = raw.decode(enc)
+        except UnicodeDecodeError:
+            continue
+        if any(ord(c) < 0x20 and c not in "\t\r\n" for c in s):
+            return None
+        return s
+    return None
+
+
+def _is_single_row_label(s: str) -> bool:
+    """Whether ``s`` is a plausible bare long-name (see ``_LABEL_PUNCT``).
+
+    Unicode-aware: the first char is any letter (incl. Greek/Cyrillic) and the
+    rest are alphanumerics, the scientific punctuation set, or ANY non-ASCII
+    printable (``ord >= 0x80``) — the glyphs real column names use. Markup/path
+    chars (``\\``, ``<``, ``>``) are ASCII and not in the set, so they still
+    fail here on top of the ``_JUNK_MARKERS`` pre-filter."""
+    if not s or not s[0].isalpha() or len(s) > 60:
+        return False
+    return all(c.isalnum() or c in _LABEL_PUNCT or ord(c) >= 0x80 for c in s)
+
+
+def _strip_alnum(s: bytes) -> bytes:
+    return re.sub(rb"[^A-Za-z0-9]", b"", s)
+
+
+def _excel_col(i: int) -> str:
+    """0-based column index -> Origin/Excel column letter (0->A, 25->Z, 26->AA...)."""
+    letters = ""
+    i += 1
+    while i:
+        i, rem = divmod(i - 1, 26)
+        letters = chr(ord("A") + rem) + letters
+    return letters
+
+
+def _filename_anchors(b: bytes, start: int) -> list[tuple[int, bytes, bytes]]:
+    """``(position, alnum-stripped-basename, raw-filename)`` per backslash token."""
+    out: list[tuple[int, bytes, bytes]] = []
+    for m in _FILENAME_RE.finditer(b):
+        if m.start() < start:
+            continue
+        raw = m.group(1)
+        base = raw.rsplit(b".", 1)[0]
+        out.append((m.start(), _strip_alnum(base), raw))
+    return out
+
+
+def _book_anchor(
+    b: bytes, short: str, search_from: int, filename_hits: list[tuple[int, bytes, bytes]]
+) -> tuple[int, bytes | None] | None:
+    """First ``(position, raw_filename_or_None)`` identifying this book's window section."""
+    short_b = short.encode("latin1")
+    for pos, stripped, raw in filename_hits:
+        if pos >= search_from and stripped == short_b:
+            return pos, raw
+    header_len = len(short_b) + 2
+    if header_len < 256:
+        idx = b.find(bytes([header_len]) + b"\x00\x00" + short_b, search_from)
+        if idx >= 0:
+            return idx, None
+    if len(short) >= 4:  # storage-tail reference; too ambiguous for short names alone
+        storage_len = len(short_b) + 1
+        if storage_len < 256:
+            idx = b.find(bytes([storage_len]) + short_b + b"\x00", search_from)
+            if idx >= 0:
+                return idx, None
+    return None
+
+
+def _gap_text_span(b: bytes, start: int, end: int) -> int:
+    """Longest run of consecutive text bytes in ``[start, end)``.
+
+    A text byte is printable ASCII / TAB / CR / LF, or a UTF-8 high byte
+    (>= 0x80 — a label glyph). Used only to WIDEN the inter-marker gap
+    allowance by the label content actually present, so a long column comment
+    (a long contiguous printable run) can't split a book's metadata run. A
+    real book boundary is a multi-KB BINARY window header — no comparable
+    printable run — so this never merges two books. Framing-agnostic on
+    purpose: the comment's length prefix is a multi-byte varint we don't parse
+    here, and we don't need to."""
+
+    def _is_text(c: int) -> bool:
+        return c in (0x09, 0x0A, 0x0D) or 0x20 <= c <= 0x7E or c >= 0x80
+
+    best = run = 0
+    for c in b[start : min(end, len(b))]:
+        run = run + 1 if _is_text(c) else 0
+        if run > best:
+            best = run
+    return best
+
+
+def _parse_label_record(b: bytes, p: int) -> bytes | None:
+    """One label record at ``p``: ``<LEB128 length><chunks>`` where each chunk
+    is ``<len:1><data>``, non-final chunks are exactly 127 bytes, and the
+    concatenated data is ``<text><NUL>``.
+
+    The common short label is the single-chunk case (the old fixed-shape
+    read). A >127-byte label — a long column comment — stores a 2-byte
+    varint length and 127-byte chunking; the old single-byte read silently
+    dropped that column's WHOLE label (long-name included), the §13.2 #13
+    residual, pinned by the ``long_comment.opju`` specimen (record:
+    varint ``e8 05`` = 744, chunks 127×5 + 103, text 737)."""
+    length = b[p]
+    off = 1
+    if length & 0x80:  # LEB128 continuation bit -> 2-byte varint
+        if p + 2 > len(b):
+            return None
+        length = (length & 0x7F) | (b[p + 1] << 7)
+        off = 2
+        if length <= 0x7F or length > 4096:  # a real 2-byte varint is >127
+            return None
+    elif length < 2:
+        return None
+    end_rec = p + off + length
+    if end_rec > len(b):
+        return None
+    payload = b[p + off : end_rec]
+    data = bytearray()
+    i = 0
+    while i < len(payload):
+        clen = payload[i]
+        last = i + 1 + clen == len(payload)
+        if clen == 0 or (not last and clen != 0x7F) or i + 1 + clen > len(payload):
+            return None
+        data += payload[i + 1 : i + 1 + clen]
+        i += 1 + clen
+    if not data or data[-1] != 0:
+        return None
+    return bytes(data[:-1])
+
+
+def _find_label(b: bytes, start: int, end: int) -> str | None:
+    """First label-shaped record in ``[start, end)``.
+
+    Prefers a ``\\r\\n``-split multi-row label (long_name/unit/comment); falls
+    back to a single-row (long-name-only) record when no multi-row match
+    exists in range.
+    """
+    multi = single = None
+    limit = min(end, len(b) - 2)
+    for p in range(start, limit):
+        text = _parse_label_record(b, p)
+        if text is None or not text:
+            continue
+        if any(marker in text for marker in _JUNK_MARKERS):
+            continue
+        decoded = _decode_cell_text(text)
+        if decoded is None:
+            continue
+        if "\r\n" in decoded:
+            multi = decoded
+            break
+        if single is None and _is_single_row_label(decoded):
+            if len(text) >= 4 and any(text in token for token in _KNOWN_TOKENS):
+                continue
+            single = decoded
+    return multi if multi is not None else single
+
+
+def opju_window_metadata(
+    b: bytes, book_columns: Mapping[str, Sequence[str]]
+) -> dict[str, BookMeta]:
+    """Map book short name -> :class:`~quantized.io.origin_project.windows.BookMeta`.
+
+    ``book_columns`` is the already-decoded ``{book: [col_letter, ...]}``
+    ordering (see ``opj._group``) — this function never invents a column
+    that ``opju_codec.scan_columns`` didn't independently decode; it only
+    attaches a label to it when the book's marker run can be confirmed.
+    """
+    start = tail_start(b)
+    markers = sorted(
+        [(m.start(), "X") for m in re.finditer(_X_MARK, b) if m.start() >= start]
+        + [(m.start(), "Y") for m in re.finditer(_Y_MARK, b) if m.start() >= start]
+        + [(m.start(), "Y-error") for m in re.finditer(_YERR_MARK, b) if m.start() >= start]
+        + [(m.start(), "label") for m in re.finditer(_LABEL_MARK, b) if m.start() >= start]
+        + [
+            (m.start(), _zx_designation(b, m.start()))
+            for m in re.finditer(_ZX_MARK, b)
+            if m.start() >= start
+        ]
+    )
+    filename_hits = _filename_anchors(b, start)
+    books: dict[str, BookMeta] = {}
+    # Anchor each book INDEPENDENTLY from the tail start (not a forward-only
+    # cursor): a project's book windows are not laid out in decoded-book order
+    # (the Hc2 project interleaves them), so a monotonic cursor drops every book
+    # whose window section sits before an already-anchored one. Anchors are exact
+    # (length-prefixed name / filename basename), so independent search cannot
+    # cross-match a different book.
+    for book, cols in book_columns.items():
+        if not cols:
+            continue
+        anchored = _book_anchor(b, book, start, filename_hits)
+        if anchored is None:
+            continue
+        anchor, raw_filename = anchored
+        candidates = [t for t in markers if t[0] > anchor]
+        x_positions = [i for i, t in enumerate(candidates) if t[1] == "X"]
+        letter_map: dict[str, tuple[int, str]] | None = None
+        run: list[tuple[int, str]] = []
+        # The run bound is DERIVED from the column count (the old fixed
+        # _MAX_RUN=128 cap silently dropped ALL metadata of a >128-column
+        # book — names, units, and the X designation; 2026-07-06 genericity
+        # audit). The >_MAX_GAP break remains the real book-boundary signal;
+        # len(cols) + slack is only the runaway backstop.
+        max_run = len(cols) + 32
+        for xi in x_positions:
+            attempt = [candidates[xi]]
+            j = xi + 1
+            while j < len(candidates) and len(attempt) < max_run:
+                # The gap to the NEXT column marker is set by how much label
+                # content THIS column carries: long_name + unit + comment, and
+                # a comment can run to hundreds of chars. So the allowance is
+                # _MAX_GAP plus the length of the label record that actually
+                # sits in the gap (structural), not a fixed byte cap that a
+                # long comment silently overruns -- which used to drop the
+                # whole book's metadata (2026-07-06 genericity audit). The
+                # real book boundary is a multi-KB window header, far past any
+                # single label record, so this never merges two books.
+                gap = candidates[j][0] - attempt[-1][0]
+                allow = _MAX_GAP + _gap_text_span(b, attempt[-1][0] + 2, candidates[j][0])
+                if gap > allow:
+                    break
+                attempt.append(candidates[j])
+                j += 1
+            if len(attempt) < len(cols):
+                continue
+            candidate_map = {_excel_col(i): attempt[i] for i in range(len(attempt))}
+            if all(c in candidate_map for c in cols):
+                letter_map, run = candidate_map, attempt
+                break
+        if letter_map is None:
+            continue
+        long_name = raw_filename.decode("latin1", errors="replace") if raw_filename else book
+        columns: dict[str, ColumnMeta] = {}
+        for col in cols:
+            pos, desig = letter_map[col]
+            ordinal = run.index(letter_map[col])
+            next_pos = run[ordinal + 1][0] if ordinal + 1 < len(run) else pos + 3000
+            label = _find_label(b, pos + 2, min(next_pos, pos + 3000))
+            rows = (label.split("\r\n") if label else []) + ["", "", ""]
+            columns[col] = ColumnMeta(col, _DESIGNATION.get(desig, "Y"), rows[0], rows[1], rows[2])
+        books[book] = BookMeta(book, long_name, columns)
+    return books