quantized-lab 0.8.0__py3-none-any.whl

quantized/io/origin_project/opj_curves.py

@@ -0,0 +1,297 @@
+"""Curve->column binding for ``.opj`` (CPYA) graph figures (item 11, long
+presumed permanently undecodable -- solved 2026-07-04).
+
+``docs/origin_project_format.md`` sec 6.1 previously documented the DataPlot
+("X-block") record as `` 58 00 00 00 98 03 40 b3 <u32 bodyLen> <enum> ...``
+with "the column selector is inside the undecoded body -- no ASCII, no plain
+indices found". That body is a fixed style/geometry record and genuinely
+carries no selector. The selector lives one level up: immediately BEFORE each
+DataPlot's style+body pair sits a small, previously-uninvestigated "curve
+anchor" record --
+
+```
+01 00 00 00  <id:u16 LE>  00 01 00 00  00 00 a1 00  ...
+```
+
+-- whose first 6 bytes are the whole story: a fixed ``01 00 00 00`` marker,
+then a little-endian ``u16`` that is the plotted column's own **global,
+project-wide, monotonically-assigned serial id**. Detected structurally (no
+fixed size -- ``519`` in ``Moke.opj``, ``515`` in ``XRD.opj``, evidently a
+per-file/build constant, not part of the encoding) by requiring the anchor be
+immediately followed by a block starting with the DataPlot magic itself
+(``58 00 00 00 98 03 40 b3``, the same 8 bytes sec 6.1 already documents) --
+this pairing is what a real curve looks like; nothing else in a graph window
+matches both halves at once.
+
+**How this was found.** The designed experiment from the RE brief: Moke's
+``Graph8``/``Graph9`` both plot ``[Book4]Sheet1!B`` and have byte-identical
+block-size sequences end to end -- diffing them block-by-block isolates
+*noise* (every difference was a per-graph object/window serial counter,
+always off by a small constant like +7, or the window's own creation index,
+off by exactly 1 between adjacent windows -- never anything column-shaped).
+Diffing ``Graph8`` against ``Graph2`` (``[Book4]Sheet1!O`` -- same book,
+different column, same style family) with the SAME block alignment isolates
+exactly one block that is identical between ``Graph8``/``Graph9`` (the noise
+pair) but differs between ``Graph8``/``Graph2`` (the signal pair): the 519-
+byte block immediately preceding the first DataPlot style+body pair. Its
+first differing byte (offset 4, `` 1f`` vs ``5d`` = 31 vs 93) looked at first
+like a per-book column ordinal (Book2's ``D``/``H``/``L`` curves read 12/16/
+20 -- exactly ``letter_position + 8``; Book3's ``B``/``C``/``D``/``E`` read
+26/27/28/29 -- exactly ``letter_position + 24``) but Book4 broke that model
+outright (``B``=31, ``H``=94, ``O``=93, ``M``=53, ``N``=92 -- no additive
+constant fits, and creation-order position fares no better). The values
+*were* unique per (book, column) pair across 15 distinct pairs and 8
+independently-authored graphs, though -- exactly the profile of a real
+per-column identifier, just not one derivable from position within its own
+book. Cross-checking the SAME 16-bit value against each column's own
+storage block in the windows section (searched independently via each
+column's ``"<Book>_<Col>\\0"`` dataset-name string, unrelated to any graph) found
+it verbatim, at the identical relative offset (4, u16 LE) in that block's own
+header -- 5-for-5 exact matches on the first pass, then every one of the 45
+curves validated below. **Book and column are resolved together by this one
+id** -- there is no separate "book selector" field to find; the column's own
+id implicitly carries which book it belongs to, since ids are assigned
+globally across the whole project, not restarted per book.
+
+**Column-storage lookup (`column_id_map`).** Every ≥500-byte column-storage
+block in the windows section (``00 00 <Book> 00 …`` window header, then one
+block per column, per sheet -- see ``windows.py``) opens with the SAME 4-byte
+tag family the curve anchor uses, then this same u16 id at offset 4, then
+(among other things) the column's NUL-terminated short name at offset 0x12
+and its plot designation byte at 0x11 (``windows.py``'s ``_DESIGNATION``
+enum: 0=Y, 3=X, ...). ``windows.py``'s own ``_is_column_block`` additionally
+requires ``payload[0x06] == 0x0B``, which is too strict for this corpus --
+most of ``Moke.opj``'s ``Book4``/``Book1`` Sheet1 columns carry ``0x09``
+there instead (only a handful, e.g. ``Book4``'s ``H``, carry ``0x0B``), so
+reusing it silently drops most columns. This module's own detector
+(``_column_short_name``) only requires the size floor + a clean printable
+alpha-first short name, and is scanned across ALL sheets of a book (not just
+the primary one, unlike ``windows.window_metadata``) so a curve referencing
+a report-sheet column (e.g. Moke's ``FitLinearCurve1``) can still resolve --
+none of the corpus's *locatable* graphs happen to need this, but nothing
+about the id scheme restricts it to primary-sheet columns.
+
+**Aside -- a ``windows.window_metadata`` bug surfaced by this investigation,
+FIXED 2026-07-04.** Because most of ``Book4`` Sheet1's columns failed
+``_is_column_block``'s old strict check (they carry header byte ``0x09``, not
+``0x0B``), ``window_metadata``'s "sheet 2 restarted" guard never triggered for
+Book4's real primary sheet -- so its ``FitLinear1`` report-sheet columns got
+committed as if they were the *primary* sheet's data, mislabeling Book4's
+``A``-``G`` designations/long-names. Fixed in ``windows.py`` by accepting
+``0x06 in (0x09, 0x0B)`` and using the real sheet-boundary signal (a 365-byte
+``Pd<Name>`` sub-header at offset 0xD0) to close collection at the 2nd marker
+per window. This was orthogonal to the curve/column-id decode here (which uses
+its own more permissive scan and never touches ``windows.py``).
+
+**X is a structural inference, exactly as in ``.opju`` (`book_x_columns`).**
+No oracle (Moke's or XRD's ``index.json``) records which column is plotted as
+X -- only the axis *range*, which doesn't identify a column. Exactly
+mirroring ``opju_curves.py``'s "X is not decoded" section: ``x`` is inferred
+as the book's own designated-X column (primary sheet, designation byte ``3``)
+falling back to the sheet's first column when no column is explicitly marked
+X. This is unverified against any oracle, here or in the ``.opju`` sibling --
+a documented structural assumption, not a decoded value.
+
+**Validation (2026-07-04, both required oracle files).**
+
+* ``Moke.opj``: 39/39 correct, 0 wrong, on every graph reachable via a
+  ``00 00 <Name> 00`` window header (``Graph1``-``Graph12``, all single- and
+  multi-curve, multi-layer and cross-book cases -- ``Graph7``/``Graph10``
+  each mix ``Book4``/``Book5`` curves in one window). ``FitLine``/
+  ``Residual`` (the FitLinear analysis's own auto-generated report graphs, 7
+  more oracle refs) have **no** ``00 00 <Name> 00`` header anywhere in the
+  block stream at all (confirmed by an exhaustive string search) -- these
+  live in the FitLinear analysis's own embedded storage, structurally
+  unreachable via ``container.walk_blocks``, not a decode failure.
+* ``XRD.opj``: 6/6 correct on ``Graph1`` (all 6 curves, one per book,
+  ``Book1``/``Book5``/``Book4``/``Book3``/``Book2``/``Book6`` in that
+  cross-book order -- also confirms the "book resolved via the same id, no
+  separate selector" claim across 6 different books in one layer). The 18
+  ``sparkline*`` refs are a structurally different feature -- per-COLUMN
+  inline mini-plots embedded in the worksheet, not separate Graph windows at
+  all (no ``00 00 sparklineN 00`` header exists, and a whole-file scan for
+  the curve-anchor pattern -- ``01 00 00 00`` + DataPlot magic -- finds
+  exactly 6 hits total in the entire file, all inside ``Graph1``): out of
+  reach for this decoder by construction, not a missed match.
+* **Aggregate: 45/45 correct (100% precision) on every curve this decoder can
+  see at all; 45/70 (64.3%) of the full task-level oracle**, the remaining 25
+  being two structurally distinct, out-of-scope window kinds (FitLinear
+  report graphs; per-column sparklines) rather than undecoded curves.
+
+See ``tests/test_io_origin_figures_opj_curves.py`` for the synthetic + real-
+corpus tests and ``tools/origin_trial/score_curve_bindings_opj.py`` for a
+standalone rescorer.
+"""
+
+from __future__ import annotations
+
+import struct
+from collections.abc import Sequence
+
+from quantized.io.origin_project.curve_style_color import apply_increment_colors, style_fields
+from quantized.io.origin_project.windows import _cstring, _is_window_header
+
+__all__ = ["book_x_columns", "column_id_map", "extract_curves"]
+
+# The curve-anchor record's fixed 4-byte marker (see module docstring).
+_CURVE_PREFIX = b"\x01\x00\x00\x00"
+
+# The DataPlot ("X-block") magic already documented in
+# docs/origin_project_format.md sec 6.1 ("0x58 marker byte, constant magic
+# 0xB3400398"). A real curve anchor is always immediately followed by a block
+# opening with this exact sequence -- the co-occurrence is what makes the
+# anchor detector precise without needing a fixed block size.
+_DATAPLOT_MAGIC = b"\x58\x00\x00\x00\x98\x03\x40\xb3"
+
+# windows.py's plot-designation enum (0=Y, 3=X, ...) -- see its `_DESIGNATION`.
+_DESIGNATION_X = 3
+
+
+def _column_short_name(payload: bytes) -> str | None:
+    """A column-storage block's short name (e.g. ``"B"``), or ``None``.
+
+    Printable, NUL-terminated, alpha-first, at payload offset ``0x12`` --
+    mirrors ``windows.py``'s column-property-block layout but WITHOUT
+    ``windows._is_column_block``'s stricter type-byte check, which misses
+    most real columns in this corpus (see module docstring)."""
+    if len(payload) < 500:
+        return None
+    name = _cstring(payload, 0x12, 8)
+    return name if name and name[0].isalpha() else None
+
+
+def _is_graph_header(blocks: Sequence[tuple[int, bytes]], i: int) -> str | None:
+    """``True`` (the window name) when block ``i`` opens a GRAPH window --
+    mirrors ``figures.py``'s own detector: a window header whose immediately
+    following block is a layer-continuation block (>=90 B, head
+    ``00 00 1f 00``)."""
+    _, payload = blocks[i]
+    name = _is_window_header(payload)
+    if name is None:
+        return None
+    nxt = blocks[i + 1][1] if i + 1 < len(blocks) else b""
+    if len(nxt) >= 90 and nxt[:4] == b"\x00\x00\x1f\x00":
+        return name
+    return None
+
+
+def column_id_map(blocks: Sequence[tuple[int, bytes]]) -> dict[int, tuple[str, str]]:
+    """Every workbook column's global serial id -> ``(book, column)``.
+
+    Scanned across the whole windows section (ALL sheets of every book, not
+    just the primary one -- see module docstring), skipping graph windows
+    entirely (they hold no column-storage blocks of their own, but their
+    internal 519-ish-byte records could otherwise false-positive against the
+    permissive short-name check)."""
+    id_map: dict[int, tuple[str, str]] = {}
+    current_book: str | None = None
+    in_graph = False
+    i = 0
+    n = len(blocks)
+    while i < n:
+        if _is_graph_header(blocks, i) is not None:
+            in_graph, current_book = True, None
+            i += 2
+            continue
+        _, payload = blocks[i]
+        name = _is_window_header(payload)
+        if name is not None:
+            in_graph, current_book = False, name
+            i += 1
+            continue
+        if not in_graph and current_book is not None and len(payload) >= 6:
+            short = _column_short_name(payload)
+            if short is not None:
+                cid = struct.unpack_from("<H", payload, 4)[0]
+                id_map[cid] = (current_book, short)
+        i += 1
+    return id_map
+
+
+def book_x_columns(blocks: Sequence[tuple[int, bytes]]) -> dict[str, str]:
+    """book -> its designated X column's short name (structural inference).
+
+    Primary sheet only -- stops collecting for a book at the first repeated
+    short name (the same "sheet 2 restarts at column A" signal
+    ``windows.window_metadata`` uses, reimplemented here against this
+    module's more permissive column detector). Picks the column whose
+    designation byte is ``3`` (X); falls back to the sheet's first column
+    when none is explicitly marked. See module docstring: this is NOT
+    verified against any oracle, exactly like ``opju_curves.py``'s X.
+    """
+    seen: dict[str, dict[str, int]] = {}
+    closed: set[str] = set()
+    current_book: str | None = None
+    in_graph = False
+    i = 0
+    n = len(blocks)
+    while i < n:
+        if _is_graph_header(blocks, i) is not None:
+            in_graph, current_book = True, None
+            i += 2
+            continue
+        _, payload = blocks[i]
+        name = _is_window_header(payload)
+        if name is not None:
+            in_graph, current_book = False, name
+            i += 1
+            continue
+        if not in_graph and current_book is not None and current_book not in closed:
+            short = _column_short_name(payload)
+            if short is not None and len(payload) > 0x11:
+                cols = seen.setdefault(current_book, {})
+                if short in cols:
+                    closed.add(current_book)  # sheet 2 restarting at the same letters
+                else:
+                    cols[short] = payload[0x11]
+        i += 1
+    out: dict[str, str] = {}
+    for book, cols in seen.items():
+        if not cols:
+            continue
+        x_col = next((c for c, d in cols.items() if d == _DESIGNATION_X), None)
+        out[book] = x_col if x_col is not None else next(iter(cols))
+    return out
+
+
+def extract_curves(
+    blocks: Sequence[tuple[int, bytes]],
+    start: int,
+    end: int,
+    id_map: dict[int, tuple[str, str]],
+    x_columns: dict[str, str],
+) -> list[dict[str, str | float]]:
+    """Every curve's ``{book, x, y}`` binding found in ``blocks[start:end)``.
+
+    ``y`` is decoded exactly via the curve anchor's own global column id (see
+    module docstring); a curve whose id doesn't resolve to a known column, or
+    whose book has no inferable X column, is silently dropped -- never
+    guessed. The anchor payload is also the curve's fixed style record
+    (``curve_style_color.py``: symbol color/kind, line color, line-vs-
+    scatter -- oracle-verified on ``hc2convert.opj``), so any decodable
+    ``color``/``symbol``/``style`` keys ride along; undecodable fields
+    (auto color, unmapped bytes) are absent, never defaulted."""
+    out: list[dict[str, str | float]] = []
+    records: list[bytes | None] = []
+    last = min(end, len(blocks) - 1)
+    for j in range(start, last):
+        _, payload = blocks[j]
+        if len(payload) < 6 or payload[:4] != _CURVE_PREFIX:
+            continue
+        _, npayload = blocks[j + 1]
+        if npayload[:8] != _DATAPLOT_MAGIC:
+            continue
+        cid = struct.unpack_from("<H", payload, 4)[0]
+        info = id_map.get(cid)
+        if info is None:
+            continue
+        book, col = info
+        x = x_columns.get(book)
+        if x is None:
+            continue  # unknown/columnless book: drop, never guess
+        out.append({"book": book, "x": x, "y": col, **style_fields(payload)})
+        records.append(payload)
+    # auto/increment placeholders resolve by group role + plot order
+    # (curve_style_color.apply_increment_colors, pixel-oracle-verified)
+    apply_increment_colors(out, records)
+    return out

quantized/io/origin_project/opj_shapes.py

@@ -0,0 +1,148 @@
+"""Region-shape graphic objects (``Rect*``) in ``.opj`` graph layers
+(decode-plan item 41 — the Graph1 SLD-profile "layer bands").
+
+Origin lets a user drop filled rectangles onto a graph layer — the corpus
+uses them as vertical film-stack region bands (PNR.opj ``Graph1``:
+SiO2/Pt/YIG/Py/Ru/Air, each a full-height pastel band). These are a
+distinct graph-child object class the figure decoder previously routed to
+"ignore":
+
+* the universal **133-byte object header** (``figures.py``) with type tag
+  ``0x31`` at payload offset 2 (a previously-undocumented value — the known
+  tags were 0x00 text / 0x07 curve / 0x22 line / 0x23 storage) and the
+  object's own name (``Rect``, ``Rect1``…) at offset 70;
+* followed by one **130-byte body block** holding the geometry + fill:
+
+  ========  =====================================================
+  offset    field
+  ========  =====================================================
+  7         fill colour low byte (mirrors the u32 at 66; equal for
+            every palette-type instance corpus-wide)
+  10 (f64)  left edge, layer-frame fraction (== the header's own
+            anchor fraction at header offset 19)
+  18 (f64)  top edge fraction (from the frame TOP — the same
+            convention as text-object anchors, ``frac_to_data``)
+  26 (f64)  width fraction
+  34 (f64)  height fraction
+  66 (u32)  fill colour, on-disk **ocolor** encoding — high byte
+            0x00 = 0-BASED classic-palette index (the same disk
+            convention as curve colours, ``curve_style_color``),
+            0x01 = direct COLORREF ``0x01BBGGRR``
+  ========  =====================================================
+
+Corpus evidence (2026-07-11 sweep, all local ``.opj`` + ``.otp``): 329
+instances across 4 files (PNR 156, SuperlatticeFits 151, MnN_Diffusion_PNR
+16, SLD_DoubleY.otp 6) — every one named ``Rect*``, every body exactly 130
+bytes, every fraction quad plausible. The width fraction reproduces the
+header's page-unit box width / the layer frame width exactly (PNR Graph1
+Rect5: 207/4913 = 0.04213 = the offset-26 double). Fill colours validated
+against the live-Origin PNG oracle on PNR ``Graph1`` — 6/6 bands match
+(Ru=1 red, Air/SiO2=0x12 light gray, Py=0x0b olive, YIG=3 blue, Pt=0x0e
+orange, all 0-based palette); 29 corpus instances carry direct-RGB type-1
+values (e.g. ``0x012DAFE6`` → #E6AF2D) — the same two-type ocolor model
+``ocolor_to_rgb`` already decodes for curves. No ``Circle*``/other shape
+name exists anywhere in the corpus, and the real ``.opju`` corpus has no
+shape objects at all (only the ``SLDdouble.otpu`` template twin) — so this
+module decodes exactly what is evidenced: the CPYA rectangle record.
+
+**Known-not-decoded (honest gaps, see docs/origin_project_format.md):** a
+fill *transparency* field could not be isolated (all instances within any
+one graph share whatever it is; no body byte reads like an alpha across
+files) — rendering opacity is a frontend presentation choice, documented
+as such, not a decoded value. The rare non-zero bytes at body offsets
+49-65 (6 instances) and the 3-value field at 114-115 are uncharacterized;
+nothing here reads them.
+
+Pure library: bytes in → dicts out. No fastapi/pydantic/routes imports.
+"""
+
+from __future__ import annotations
+
+from struct import unpack_from
+from typing import Any
+
+from quantized.io.origin_project.annotation_marks import frac_to_data
+from quantized.io.origin_project.curve_style_color import ORIGIN_PALETTE, ocolor_to_rgb
+
+__all__ = ["SHAPE_TYPE", "build_region_shade", "rect_fill_color", "rect_shape_fractions"]
+
+# The 133-byte object header's type tag for closed-shape graphic objects.
+SHAPE_TYPE = 0x31
+
+_FRAC_LEFT_OFF = 10
+_FRAC_TOP_OFF = 18
+_FRAC_WIDTH_OFF = 26
+_FRAC_HEIGHT_OFF = 34
+_FILL_COLOR_OFF = 66
+_BODY_MIN_LEN = _FILL_COLOR_OFF + 4
+
+# Same plausibility bound as annotation anchors (annotation_marks): a shape
+# can legitimately hang outside its layer frame (MnN's cross-panel bands
+# reach height fraction ~2.0), but a misread double is astronomical.
+_FRAC_BOUND = 50.0
+
+
+def rect_shape_fractions(body: bytes) -> tuple[float, float, float, float] | None:
+    """``(left, top, width, height)`` layer-frame fractions from a shape
+    object's body block, or ``None`` when the block is too short or any
+    double is implausible (dropped, never guessed)."""
+    if len(body) < _BODY_MIN_LEN:
+        return None
+    left = float(unpack_from("<d", body, _FRAC_LEFT_OFF)[0])
+    top = float(unpack_from("<d", body, _FRAC_TOP_OFF)[0])
+    width = float(unpack_from("<d", body, _FRAC_WIDTH_OFF)[0])
+    height = float(unpack_from("<d", body, _FRAC_HEIGHT_OFF)[0])
+    values = (left, top, width, height)
+    if not all(abs(v) <= _FRAC_BOUND for v in values):
+        return None
+    if width <= 0 or height <= 0:
+        return None
+    return values
+
+
+def rect_fill_color(body: bytes) -> str | None:
+    """The shape's fill as ``"#RRGGBB"`` from the body's ocolor u32 (offset
+    66), or ``None`` for auto/unrecognized encodings (never guessed).
+
+    The on-disk field uses the SAME two-type ocolor model as curve colours
+    (``curve_style_color``): high byte 0x00 = 0-based classic-palette index
+    (converted to the 1-based form ``ocolor_to_rgb`` takes), 0x01 = direct
+    COLORREF."""
+    if len(body) < _BODY_MIN_LEN:
+        return None
+    field = int(unpack_from("<I", body, _FILL_COLOR_OFF)[0])
+    kind = field >> 24
+    if kind == 0:
+        return ocolor_to_rgb(field + 1) if field < len(ORIGIN_PALETTE) else None
+    return ocolor_to_rgb(field) if kind == 1 else None
+
+
+def build_region_shade(
+    body: bytes,
+    x_from: float,
+    x_to: float,
+    y_from: float,
+    y_to: float,
+    x_log: bool,
+    y_log: bool,
+) -> dict[str, Any] | None:
+    """One region-shade dict ``{"x1","x2","y1","y2","fill"}`` in DATA
+    coordinates (``x1 < x2``, ``y1 < y2``; log axes interpolate in log10
+    space via :func:`frac_to_data`, the confirmed position model), or
+    ``None`` when the geometry never decoded. ``fill`` is ``"#RRGGBB"`` or
+    ``None`` (colour undecoded — the shape still ships so the extent isn't
+    lost, but a renderer should skip a fill-less shade rather than guess a
+    colour)."""
+    fracs = rect_shape_fractions(body)
+    if fracs is None:
+        return None
+    left, top, width, height = fracs
+    xa, ya = frac_to_data(left, top, x_from, x_to, y_from, y_to, x_log, y_log)
+    xb, yb = frac_to_data(left + width, top + height, x_from, x_to, y_from, y_to, x_log, y_log)
+    return {
+        "x1": min(xa, xb),
+        "x2": max(xa, xb),
+        "y1": min(ya, yb),
+        "y2": max(ya, yb),
+        "fill": rect_fill_color(body),
+    }

quantized/io/origin_project/opju.py

@@ -0,0 +1,146 @@
+"""Read Origin ``.opju`` (CPYUA, 2018+) projects: worksheet data → DataStruct.
+
+The worksheet-column codec is solved (``opju_codec.py``): each column is an
+FPC-compressed float64 stream, located by its LEB128-varint record header and
+labelled by the nearest preceding ``<Book>_<Col>[@sheet]`` dataset name. Books
+are grouped and assembled exactly like the ``.opj`` reader (shared ``_group``
+/ ``_build_book`` / ``_inventory``). Column long-names/units/comments come
+from the CPYUA windows section (``windows_opju.py``, plan item 10) the same
+way `.opj`'s windows-section metadata feeds ``_build_book`` — designation-X
+becomes the x axis, real labels/units/comments attach where a book's window
+section can be structurally confirmed, and book display titles recover from
+the embedded import filename where available. Columns/books that can't be
+confirmed keep the Origin short-designation fallback (A, B, C…) rather than
+being guessed at.
+
+Plan item 4's report-sheet residue (``opju_reports.py``) is folded in the
+same way ``.opj``'s ``text_cols``/``report_cols`` are: a book made entirely
+of report-sheet columns (e.g. a fit's "FitNL1" sheet, with zero
+plausible-numeric columns of its own) still gets its own pseudo-book via
+``_build_book``'s empty-``cols`` branch, rather than being silently dropped
+for having nothing in ``books``.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from pathlib import Path
+
+from quantized.datastruct import DataStruct
+from quantized.io.origin_project.container import fallback
+from quantized.io.origin_project.opj import (
+    Columns,
+    TextColumns,
+    _build_book,
+    _group,
+    _group_named,
+    _inventory,
+)
+from quantized.io.origin_project.opju_codec import scan_columns
+from quantized.io.origin_project.opju_reports import scan_report_columns
+from quantized.io.origin_project.windows import BookMeta
+from quantized.io.origin_project.windows_opju import opju_window_metadata
+
+__all__ = [
+    "build_opju_books",
+    "build_opju_primary",
+    "parse_opju",
+    "read_opju",
+    "read_opju_books",
+]
+
+_ParseResult = tuple[
+    OrderedDict[str, Columns],
+    OrderedDict[str, TextColumns],
+    dict[str, BookMeta],
+    list[dict[str, object]],
+]
+
+
+def _parse(path: Path, *, raw: bytes | None = None) -> _ParseResult:
+    """Decode the project once. ``raw`` lets a caller that already has the
+    file's bytes (e.g. :func:`parse_opju`'s callers in
+    ``origin_project/__init__.py``) skip a second disk read; ``None`` (the
+    default) reads ``path`` itself, unchanged from before."""
+    b = path.read_bytes() if raw is None else raw
+    if not b.startswith(b"CPYUA"):
+        raise fallback(path, f"'{path.name}' does not look like a CPYUA .opju (bad header).")
+    columns = scan_columns(b)
+    if not columns:
+        raise fallback(path, f"no worksheet columns could be decoded from '{path.name}'.")
+    books = _group(columns)
+    report_books = _group_named(scan_report_columns(b))
+    books_meta = opju_window_metadata(b, {k: [c for c, _ in v] for k, v in books.items()})
+    return books, report_books, books_meta, _inventory(books, books_meta, report_books)
+
+
+def _primary_key(books: OrderedDict[str, Columns]) -> str:
+    """The book :func:`read_opju`/:func:`build_opju_primary` treat as *the*
+    primary dataset — see ``opj._primary_key`` (identical selection rule,
+    duplicated here since the two containers' ``Columns`` groupings are
+    built independently)."""
+    primary_pool = [k for k in books if "@" not in k] or list(books)
+    return max(primary_pool, key=lambda k: sum(len(v) for _, v in books[k]))
+
+
+def parse_opju(path: Path, *, raw: bytes | None = None) -> _ParseResult:
+    """Public single-parse entry point — see ``opj.parse_opj``. Lets a caller
+    that needs both the primary book (:func:`build_opju_primary`) and every
+    book (:func:`build_opju_books`) parse the project once."""
+    return _parse(path, raw=raw)
+
+
+def build_opju_primary(parsed: _ParseResult) -> DataStruct:
+    """Build the primary book's DataStruct from an already-:func:`parse_opju`'d
+    project — see ``opj.build_opj_primary``."""
+    books, report_books, books_meta, inventory = parsed
+    primary = _primary_key(books)
+    return _build_book(
+        primary,
+        books[primary],
+        books_meta,
+        inventory,
+        source_format="origin_opju",
+        report_cols=report_books.get(primary),
+    )
+
+
+def build_opju_books(parsed: _ParseResult) -> list[DataStruct]:
+    """Build every book's DataStruct from an already-:func:`parse_opju`'d
+    project — see ``opj.build_opj_books``.
+
+    A sheet made entirely of report-sheet columns (plan item 4) has no
+    plausible-numeric columns, so it never appears in ``books`` — the union
+    with ``report_books`` below still surfaces it as its own pseudo-book
+    (see ``_build_book``'s empty-``cols`` branch).
+    """
+    books, report_books, books_meta, inventory = parsed
+    keys = list(books) + [k for k in report_books if k not in books]
+    return [
+        _build_book(
+            k,
+            books.get(k, []),
+            books_meta,
+            inventory,
+            source_format="origin_opju",
+            report_cols=report_books.get(k),
+        )
+        for k in keys
+        if books.get(k) or report_books.get(k)
+    ]
+
+
+def read_opju(path: Path) -> DataStruct:
+    """The single-DataStruct contract: the largest workbook (inventory in metadata)."""
+    return build_opju_primary(_parse(path))
+
+
+def read_opju_books(path: Path) -> list[DataStruct]:
+    """Every workbook in the project as its own DataStruct (plan item 3/16).
+
+    A sheet made entirely of report-sheet columns (plan item 4) has no
+    plausible-numeric columns, so it never appears in ``books`` — the union
+    with ``report_books`` below still surfaces it as its own pseudo-book
+    (see ``_build_book``'s empty-``cols`` branch).
+    """
+    return build_opju_books(_parse(path))