python-hwpx 2.18.0__py3-none-any.whl → 2.19.0__py3-none-any.whl

hwpx/tools/read_fidelity.py

@@ -0,0 +1,281 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Content-level read-fidelity harness for HWPX (M6 / S-060).
+
+Where :mod:`hwpx.tools.roundtrip_diff` measures *element-count* preservation,
+this module measures *content* fidelity:
+
+* :func:`resolve_run_spans` — the canonical per-run resolved formatting
+  (bold / italic / underline / strikeout / color / size / font). This is the
+  single source of truth the installed MCP surface is verified against.
+* :func:`collect_notes` — footnote / endnote instances with their body text and
+  body run formatting (the reading surfaces drop these today).
+* :func:`roundtrip_fidelity` / :func:`corpus_fidelity` — open->save->reopen
+  agreement, the lossless guard.
+* :func:`spans_fidelity` / :func:`notes_fidelity` — general comparators reused
+  to score a candidate extraction (e.g. an MCP tool payload) against the
+  canonical one.
+
+Purely structural — no Hancom oracle required.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Sequence
+
+from hwpx.document import HwpxDocument
+
+_HH = "{http://www.hancom.co.kr/hwpml/2011/head}"
+#: Values that mean "attribute is present but inactive".
+_OFF = {None, "", "NONE"}
+
+
+@dataclass(frozen=True)
+class RunSpan:
+    """Resolved inline formatting of a single ``<hp:run>``."""
+
+    text: str
+    bold: bool = False
+    italic: bool = False
+    underline: str | None = None  # underline TYPE (BOTTOM/CENTER/TOP...) or None when off
+    strikeout: bool = False
+    color: str | None = None
+    size_pt: float | None = None
+    font: str | None = None
+    superscript: bool = False
+    subscript: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "text": self.text,
+            "bold": self.bold,
+            "italic": self.italic,
+            "underline": self.underline,
+            "strikeout": self.strikeout,
+            "color": self.color,
+            "sizePt": self.size_pt,
+            "font": self.font,
+            "superscript": self.superscript,
+            "subscript": self.subscript,
+        }
+
+
+@dataclass(frozen=True)
+class NoteSpan:
+    """A footnote / endnote instance and its resolved body."""
+
+    kind: str  # "footNote" | "endNote"
+    inst_id: str | None
+    anchor_para_index: int
+    body_text: str
+    body_spans: tuple[RunSpan, ...] = field(default_factory=tuple)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "instId": self.inst_id,
+            "anchorParaIndex": self.anchor_para_index,
+            "bodyText": self.body_text,
+            "bodySpans": [s.to_dict() for s in self.body_spans],
+        }
+
+
+# ── resolution ───────────────────────────────────────────────────────
+def _fontface_maps(doc: HwpxDocument) -> dict[str, dict[str, str]]:
+    """Return ``{lang: {font_id: face_name}}`` from every header's fontfaces."""
+    maps: dict[str, dict[str, str]] = {}
+    for header in getattr(doc.oxml, "headers", []) or []:
+        element = getattr(header, "element", None)
+        if element is None:
+            continue
+        for fontface in element.iter(f"{_HH}fontface"):
+            lang = (fontface.get("lang") or "").lower()
+            bucket = maps.setdefault(lang, {})
+            for font in fontface.findall(f"{_HH}font"):
+                fid, face = font.get("id"), font.get("face")
+                if fid is not None and face is not None:
+                    bucket.setdefault(fid, face)
+    return maps
+
+
+def _resolve_font(style: Any, fontfaces: dict[str, dict[str, str]]) -> str | None:
+    font_ref = (style.child_attributes.get("fontRef") if style else None) or {}
+    fid = font_ref.get("hangul")
+    if fid is None:
+        fid = next(iter(font_ref.values()), None)
+    if fid is None:
+        return None
+    return fontfaces.get("hangul", {}).get(fid) or None
+
+
+def _int(value: Any, default: int = 0) -> int:
+    try:
+        return int(str(value))
+    except (TypeError, ValueError):
+        return default
+
+
+def _style_to_span(text: str, style: Any, fontfaces: dict[str, dict[str, str]]) -> RunSpan:
+    if style is None:
+        return RunSpan(text=text)
+    child = style.child_attributes or {}
+
+    underline_type = (child.get("underline") or {}).get("type")
+    if underline_type in _OFF:
+        underline_type = None
+
+    strike_shape = (child.get("strikeout") or {}).get("shape")
+    strikeout = strike_shape not in _OFF
+
+    height = style.attributes.get("height")
+    size_pt = round(_int(height) / 100.0, 2) if height and _int(height) > 0 else None
+
+    offset_h = _int((child.get("offset") or {}).get("hangul"))
+
+    return RunSpan(
+        text=text,
+        bold="bold" in child,
+        italic="italic" in child,
+        underline=underline_type,
+        strikeout=strikeout,
+        color=style.attributes.get("textColor"),
+        size_pt=size_pt,
+        font=_resolve_font(style, fontfaces),
+        superscript=offset_h > 0,
+        subscript=offset_h < 0,
+    )
+
+
+def fontface_maps(doc: HwpxDocument) -> dict[str, dict[str, str]]:
+    """Public: ``{lang: {font_id: face_name}}`` for surface reuse (MCP)."""
+    return _fontface_maps(doc)
+
+
+def run_span(text: str, style: Any, fontfaces: dict[str, dict[str, str]] | None = None) -> RunSpan:
+    """Public: resolve one run's :class:`RunSpan` (fontfaces from :func:`fontface_maps`)."""
+    return _style_to_span(text, style, fontfaces or {})
+
+
+def resolve_run_spans(doc: HwpxDocument) -> list[RunSpan]:
+    """Return the resolved inline formatting for every body run, in order."""
+    fontfaces = _fontface_maps(doc)
+    spans: list[RunSpan] = []
+    for section in doc.sections:
+        for paragraph in section.paragraphs:
+            for run in paragraph.runs:
+                spans.append(_style_to_span(run.text or "", run.style, fontfaces))
+    return spans
+
+
+def collect_notes(doc: HwpxDocument) -> list[NoteSpan]:
+    """Return every footnote / endnote with body text and body formatting."""
+    fontfaces = _fontface_maps(doc)
+    notes: list[NoteSpan] = []
+    para_index = 0
+    for section in doc.sections:
+        for paragraph in section.paragraphs:
+            for note in list(paragraph.footnotes) + list(paragraph.endnotes):
+                body_spans: tuple[RunSpan, ...] = ()
+                try:
+                    body = note.body_paragraph
+                    body_spans = tuple(
+                        _style_to_span(r.text or "", r.style, fontfaces) for r in body.runs
+                    )
+                except Exception:  # pragma: no cover - defensive
+                    body_spans = ()
+                notes.append(
+                    NoteSpan(
+                        kind=note.kind,
+                        inst_id=note.inst_id,
+                        anchor_para_index=para_index,
+                        body_text=note.text,
+                        body_spans=body_spans,
+                    )
+                )
+            para_index += 1
+    return notes
+
+
+# ── comparators ──────────────────────────────────────────────────────
+def _first_mismatch(ref: Sequence[Any], cand: Sequence[Any]) -> dict[str, Any] | None:
+    for i, a in enumerate(ref):
+        b = cand[i] if i < len(cand) else None
+        if a != b:
+            return {"index": i, "ref": a.to_dict() if a is not None else None,
+                    "cand": b.to_dict() if b is not None else None}
+    if len(cand) > len(ref):
+        return {"index": len(ref), "ref": None, "cand": cand[len(ref)].to_dict()}
+    return None
+
+
+def spans_fidelity(ref: Sequence[RunSpan], cand: Sequence[RunSpan]) -> dict[str, Any]:
+    """Fraction of reference run-spans reproduced identically by ``cand``."""
+    denom = max(len(ref), 1)
+    same = sum(1 for i, a in enumerate(ref) if i < len(cand) and a == cand[i])
+    return {
+        "count_ref": len(ref),
+        "count_cand": len(cand),
+        "same": same,
+        "fidelity": same / denom,
+        "count_match": len(ref) == len(cand),
+        "first_mismatch": _first_mismatch(ref, cand),
+    }
+
+
+def notes_fidelity(ref: Sequence[NoteSpan], cand: Sequence[NoteSpan]) -> dict[str, Any]:
+    """Fraction of reference notes reproduced identically by ``cand``."""
+    denom = max(len(ref), 1)
+    same = sum(1 for i, a in enumerate(ref) if i < len(cand) and a == cand[i])
+    return {
+        "count_ref": len(ref),
+        "count_cand": len(cand),
+        "same": same,
+        "fidelity": same / denom,
+        "count_match": len(ref) == len(cand),
+        "first_mismatch": _first_mismatch(ref, cand),
+    }
+
+
+# ── round-trip ───────────────────────────────────────────────────────
+def roundtrip_fidelity(source: str | Path | bytes) -> dict[str, Any]:
+    """Open->serialize->reopen and score run-format + note preservation."""
+    before = HwpxDocument.open(source)
+    runs_before = resolve_run_spans(before)
+    notes_before = collect_notes(before)
+
+    after = HwpxDocument.open(before.to_bytes())
+    runs_after = resolve_run_spans(after)
+    notes_after = collect_notes(after)
+
+    return {
+        "run_format": spans_fidelity(runs_before, runs_after),
+        "notes": notes_fidelity(notes_before, notes_after),
+    }
+
+
+def corpus_fidelity(paths: Sequence[str | Path]) -> dict[str, Any]:
+    """Aggregate run-format round-trip fidelity across a corpus."""
+    per_file: dict[str, Any] = {}
+    total_runs = same_runs = 0
+    below: list[dict[str, Any]] = []
+    errors: dict[str, str] = {}
+    for path in paths:
+        key = str(path)
+        try:
+            report = roundtrip_fidelity(path)["run_format"]
+        except Exception as exc:  # pragma: no cover - defensive
+            errors[key] = repr(exc)[:200]
+            continue
+        per_file[key] = report
+        total_runs += report["count_ref"]
+        same_runs += report["same"]
+        if report["fidelity"] < 1.0 or not report["count_match"]:
+            below.append({"file": key, "fidelity": report["fidelity"], "runs": report["count_ref"]})
+    return {
+        "files": len(per_file),
+        "total_runs": total_runs,
+        "run_format_fidelity": (same_runs / total_runs) if total_runs else 1.0,
+        "files_below_100pct": below,
+        "errors": errors,
+        "per_file": per_file,
+    }

hwpx/visual/_hancom_open_rate.ps1

@@ -0,0 +1,374 @@
+<#
+.SYNOPSIS
+    Measure the real-Hancom (한글) OPEN rate of a set of .hwpx files via COM.
+
+.DESCRIPTION
+    The hardened open-only oracle primitive for the M9 open-rate apparatus
+    (specs/007-open-rate). Cloned from scripts/hancom_com_open_verify.ps1 and
+    hardened per FR-002:
+
+      (a) SetMessageBoxMode(0x00020000) so corrupt-file / repair / save modals
+          do NOT block a babysat batch.
+      (b) Per-file checkpoint: each verdict record is APPENDED to --OutJsonl
+          IMMEDIATELY after Open(), so a mid-batch crash loses at most one file.
+      (c) RESUME (FR-002, this build): a re-run does NOT truncate the JSONL. On
+          startup it reads the existing checkpoint and SKIPS every file with a
+          FINAL verdict (a clean load, a clean refusal, or a completed retry). A
+          not-yet-retried COM-EXCEPTION error is NOT final and is re-attempted, so a
+          run killed mid-retry never freezes a clean file as a permanent failure.
+          After a hang/kill the owner re-runs; already-cleared clean popups are not
+          shown twice. To force a clean re-measure, delete --OutJsonl first.
+      (d) A single retry pass over files that errored on THIS run's pass 1; the
+          retried record (retried=$true) is appended and wins the basename join, so
+          the aggregator treats a retry-only open as NON-clean (never inflates the
+          opens-clean headline).
+      (e) Text-scan watchdog: the GetPageText loop (the free "parsed" tier signal)
+          is bounded by -OpenTimeoutSec so a pathological page scan cannot stall the
+          batch.
+
+    The script reuses ONE COM session for the common path (Hancom startup
+    dominates) but re-creates the session after any COM exception.
+
+    Open uses the fixed Hancom 2022 (v12) 3-arg signature Open(path,"","")
+    (auto-detect format), matching src/hwpx/visual/_render_hwpx.ps1.
+
+    *** LIMIT — a HUNG Open() ***
+    Open() is a synchronous STA COM call; it CANNOT be interrupted in-process
+    without killing the Hangul process (which would also kill an unrelated Hangul
+    the owner may have open). This script does NOT auto-kill on an Open() hang.
+    Mitigation relies on RESUME (c): if an Open() hangs, the babysitter kills the
+    run (Ctrl-C / close Hangul), re-runs, and RESUME skips every already-judged
+    file. A file that hangs Open() *persistently* is moved aside by the operator
+    (it stays unjudged → the aggregator reports it as unverified, coverage-visible).
+    An automatic per-file process-kill watchdog is deferred to the TARGET (unattended
+    CI) build and must be validated on the box before it is trusted.
+
+    *** BOX-VERIFICATION REQUIRED (FR-002, opens-clean tier) ***
+    SetMessageBoxMode(0x00020000) suppresses the modal, but the SUPPRESSED DEFAULT
+    ACTION must NOT be silent auto-repair. If Hancom's default answer to the
+    "손상된 파일을 복구하시겠습니까?" dialog is "복구"(repair), a corrupt input would be
+    auto-repaired and Open() would return $true — miscounting a broken file as
+    opens-clean. This is a Windows/Hancom-build behaviour that CANNOT be checked on
+    a Mac. The negative controls (FR-005) are the real check: the must_refuse
+    ``synthetic_corrupt_section`` canary is a structurally valid package whose body
+    is garbage — if it reports opened=$true, the default action is auto-repair and
+    the harness is INVALID (corpus_open_rate.py fails closed). Open the negatives
+    FIRST (spike gate) so a leak surfaces before the full sitting.
+
+    Per-file signal: after a successful Open() the script records ``isModifiedProbe``
+    (Hwp.IsModified). This is a BOX-UNVERIFIED auto-repair hint — a clean load
+    should read $false. It is recorded for audit only; it is NOT mapped to the
+    aggregator's ``repaired`` (non-clean) field until the box run confirms it reads
+    $false for known-clean files (measure-first: an unverified property must never
+    silently collapse the headline).
+
+    Windows-only PowerShell (5.1-compatible). Syntactically validated off-box; the
+    real run happens on the .161 box.
+
+.PARAMETER Path
+    One or more .hwpx file paths to open-check.
+
+.PARAMETER MaxPages
+    Max pages to scan with GetPageText for the free "parsed" (textLength>0) signal.
+
+.PARAMETER OutJsonl
+    Per-file checkpoint JSONL. One JSON object per line is APPENDED after each
+    Open(); a re-run resumes from it (skips already-judged files). Strongly
+    recommended for real (babysat) batches.
+
+.PARAMETER OutJson
+    Optional path to write the final consolidated JSON array (prior + this run).
+
+.PARAMETER OpenTimeoutSec
+    Bounds the per-file GetPageText scan loop (seconds). Does NOT bound a hung
+    Open() (see the LIMIT note above). Default 120.
+
+.PARAMETER ProbeRepairMode
+    When set (and starting fresh), records the queried SetMessageBoxMode value in a
+    leading {"_meta":...} JSONL record for the receipt.
+#>
+param(
+    [Parameter(Mandatory = $true)]
+    [string[]] $Path,
+
+    [int] $MaxPages = 20,
+
+    [string] $OutJsonl = "",
+
+    [string] $OutJson = "",
+
+    [int] $OpenTimeoutSec = 120,
+
+    [switch] $ProbeRepairMode
+)
+
+$ErrorActionPreference = "Stop"
+try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}
+
+# 0x00020000 = HWP_MESSAGE_BOX_MODE: auto-answer message boxes (suppress modals).
+$MESSAGE_BOX_MODE = 0x00020000
+
+function Resolve-InputPath {
+    param([string] $InputPath)
+    $resolved = Resolve-Path -LiteralPath $InputPath
+    return $resolved.ProviderPath
+}
+
+function Copy-ToTrustedTemp {
+    param([string] $InputPath)
+    $name = [System.IO.Path]::GetFileName($InputPath)
+    $dir = Join-Path $env:TEMP ("hwpx-open-rate-" + [System.Guid]::NewGuid().ToString("N"))
+    New-Item -ItemType Directory -Force -Path $dir | Out-Null
+    $target = Join-Path $dir $name
+    Copy-Item -LiteralPath $InputPath -Destination $target -Force
+    return @{ Directory = $dir; Path = $target }
+}
+
+function New-HwpObject {
+    $hwp = New-Object -ComObject "HWPFrame.HwpObject"
+    try {
+        $null = $hwp.RegisterModule("FilePathCheckerModule", "FilePathCheckerModuleExample")
+    } catch {
+        Write-Warning ("RegisterModule FilePathCheckerModule failed: " + $_.Exception.Message)
+    }
+    # FR-002a: suppress modal dialogs. The negative controls (FR-005) prove the
+    # suppressed default action is NOT silent auto-repair.
+    try { $null = $hwp.SetMessageBoxMode($MESSAGE_BOX_MODE) } catch {
+        Write-Warning ("SetMessageBoxMode failed: " + $_.Exception.Message)
+    }
+    return $hwp
+}
+
+function Close-HwpObject {
+    param([object] $Hwp)
+    if ($null -ne $Hwp) {
+        try { $Hwp.Quit() | Out-Null } catch {}
+        try { [System.Runtime.InteropServices.Marshal]::FinalReleaseComObject($Hwp) | Out-Null } catch {}
+    }
+}
+
+function Read-HwpText {
+    param(
+        [object] $Hwp,
+        [int] $PageLimit,
+        [int] $TimeoutSec
+    )
+    # Primary: GetTextFile("TEXT","") — the canonical whole-document text extractor.
+    # Box finding 2026-07-01: GetPageText(n) returned 0 chars for ALL real produced
+    # docs on the .161 Hancom build (it depends on page-render state), which would
+    # collapse the parsed headline to 0%. GetTextFile does not depend on rendering.
+    try {
+        $whole = $Hwp.GetTextFile("TEXT", "")
+        if ($null -ne $whole -and -not [string]::IsNullOrWhiteSpace([string]$whole)) {
+            return [string]$whole
+        }
+    } catch {}
+    # Fallback: per-page scan (older builds where GetTextFile is unavailable).
+    $parts = New-Object System.Collections.Generic.List[string]
+    $sw = [System.Diagnostics.Stopwatch]::StartNew()
+    for ($page = 1; $page -le $PageLimit; $page++) {
+        # (e) text-scan watchdog: stop scanning if the page loop overruns.
+        if ($TimeoutSec -gt 0 -and $sw.Elapsed.TotalSeconds -gt $TimeoutSec) { break }
+        try {
+            $text = $Hwp.GetPageText($page)
+        } catch {
+            break
+        }
+        if ($null -eq $text -or [string]::IsNullOrWhiteSpace([string]$text)) {
+            continue
+        }
+        $parts.Add([string]$text)
+    }
+    return ($parts -join "`n")
+}
+
+# Append one record as a single JSON line to the checkpoint file (FR-002b).
+function Write-Checkpoint {
+    param(
+        [string] $JsonlPath,
+        [object] $Record
+    )
+    if (-not $JsonlPath) { return }
+    $line = ($Record | ConvertTo-Json -Depth 4 -Compress)
+    Add-Content -LiteralPath $JsonlPath -Value $line -Encoding UTF8
+}
+
+# RESUME (FR-002c): basenames with a FINAL verdict in an existing checkpoint.
+# FINAL = a clean load OR a clean refusal (error is null, opened true or false),
+# OR a record from the single retry pass (retried=true). A COM-EXCEPTION error
+# (error != null) with retried=false is NOT final — it is a to-be-retried state,
+# so a resume RE-ATTEMPTS it. (Without this, a run killed mid-pass-2 would freeze a
+# pass-1 exception as a permanent open_failure and silently DEFLATE the headline —
+# a wrongly-low number is exactly as damaging as a wrongly-high one.) _meta probe
+# lines have no sourcePath and are skipped.
+function Get-JudgedBasenames {
+    param([string] $JsonlPath)
+    $set = @{}
+    if (-not $JsonlPath -or -not (Test-Path -LiteralPath $JsonlPath)) { return $set }
+    foreach ($line in (Get-Content -LiteralPath $JsonlPath -Encoding UTF8)) {
+        $line = $line.Trim()
+        if (-not $line) { continue }
+        try { $rec = $line | ConvertFrom-Json } catch { continue }
+        if ($rec.PSObject.Properties.Name -contains '_meta') { continue }
+        if (-not $rec.sourcePath) { continue }
+        $hasError = ($null -ne $rec.error) -and ([string]$rec.error -ne "")
+        $retried = [bool]$rec.retried
+        if ($hasError -and -not $retried) { continue }   # unretried exception -> re-attempt on resume
+        $set[[System.IO.Path]::GetFileName([string]$rec.sourcePath)] = $true
+    }
+    return $set
+}
+
+# Prior verdicts (for the consolidated OutJson array).
+function Read-ExistingRecords {
+    param([string] $JsonlPath)
+    $list = New-Object System.Collections.Generic.List[object]
+    if (-not $JsonlPath -or -not (Test-Path -LiteralPath $JsonlPath)) { return $list }
+    foreach ($line in (Get-Content -LiteralPath $JsonlPath -Encoding UTF8)) {
+        $line = $line.Trim()
+        if (-not $line) { continue }
+        try { $rec = $line | ConvertFrom-Json } catch { continue }
+        if ($rec.PSObject.Properties.Name -contains '_meta') { continue }
+        $list.Add($rec)
+    }
+    return $list
+}
+
+# Open one file and return the verdict record. A COM exception is the watchdog
+# trip: the caller re-creates the HwpObject when $record.error is non-null.
+function Invoke-OpenCheck {
+    param(
+        [object] $Hwp,
+        [string] $InputPath,
+        [int] $PageLimit,
+        [int] $TimeoutSec,
+        [bool] $Retried
+    )
+    $trusted = Copy-ToTrustedTemp $InputPath
+    $opened = $false
+    $text = ""
+    $errorMessage = $null
+    $isModifiedProbe = $null
+    $pageCount = $null
+    try {
+        # Hancom 2022 (v12): Open(path, format, arg); ("","") = auto-detect.
+        # NOTE (box finding 2026-07-01): Open() returns $true even for container-
+        # garbage (not-a-zip/empty/truncated), loading a BLANK doc with textLength=0.
+        # So 'opened' alone is NOT the headline — the aggregator uses PARSED
+        # (opened AND textLength>0). pageCount is a second "content really loaded"
+        # probe captured here so the headline bar can be set from real data.
+        $opened = [bool]$Hwp.Open($trusted.Path, "", "")
+        if ($opened) {
+            # BOX-UNVERIFIED auto-repair hint (recorded for audit; not headline).
+            try { $isModifiedProbe = [bool]$Hwp.IsModified } catch { $isModifiedProbe = $null }
+            try { $pageCount = [int]$Hwp.PageCount } catch { $pageCount = $null }
+            $text = Read-HwpText -Hwp $Hwp -PageLimit $PageLimit -TimeoutSec $TimeoutSec
+        }
+    } catch {
+        $errorMessage = $_.Exception.Message
+    } finally {
+        try { $Hwp.Clear(1) | Out-Null } catch {}
+        Remove-Item -LiteralPath $trusted.Directory -Recurse -Force -ErrorAction SilentlyContinue
+    }
+    return [ordered]@{
+        sourcePath = $InputPath
+        opened     = $opened
+        textLength = $text.Length
+        pageCount  = $pageCount
+        textPreview = if ($text.Length -gt 500) { $text.Substring(0, 500) } else { $text }
+        error      = $errorMessage
+        retried    = $Retried
+        isModifiedProbe = $isModifiedProbe
+    }
+}
+
+# RESUME: load prior verdicts + the already-judged basename set. Do NOT truncate.
+$judged = Get-JudgedBasenames $OutJsonl
+$records = New-Object System.Collections.Generic.List[object]
+foreach ($r in (Read-ExistingRecords $OutJsonl)) { $records.Add($r) }
+$resuming = ($judged.Count -gt 0)
+if ($resuming) {
+    Write-Host ("RESUME: " + $judged.Count + " file(s) already judged in " + $OutJsonl + " — skipping those.")
+}
+
+if ($ProbeRepairMode -and -not $resuming) {
+    # Record the queried message-box mode for the receipt (fresh run only).
+    $probeHwp = $null
+    $modeValue = $null
+    $modeError = $null
+    try {
+        $probeHwp = New-Object -ComObject "HWPFrame.HwpObject"
+        try { $modeValue = $probeHwp.SetMessageBoxMode($MESSAGE_BOX_MODE) } catch { $modeError = $_.Exception.Message }
+    } catch {
+        $modeError = $_.Exception.Message
+    } finally {
+        Close-HwpObject $probeHwp
+    }
+    Write-Checkpoint -JsonlPath $OutJsonl -Record ([ordered]@{
+        _meta = "repair-mode-probe"
+        requestedMode = $MESSAGE_BOX_MODE
+        previousModeReturned = $modeValue
+        error = $modeError
+        note = "Box must confirm suppressed default action is NOT auto-repair; the must_refuse negative controls (FR-005) are the real check."
+    })
+}
+
+# Pass 1: open every not-yet-judged file, checkpoint immediately, re-create the
+# session after any COM exception.
+$thisRunErrorPaths = New-Object System.Collections.Generic.List[string]
+$hwp = $null
+try {
+    $hwp = New-HwpObject
+    foreach ($item in $Path) {
+        $inputPath = Resolve-InputPath $item
+        $base = [System.IO.Path]::GetFileName($inputPath)
+        if ($judged.ContainsKey($base)) {
+            Write-Host ("skip (already judged): " + $base)
+            continue
+        }
+        $record = Invoke-OpenCheck -Hwp $hwp -InputPath $inputPath -PageLimit $MaxPages -TimeoutSec $OpenTimeoutSec -Retried $false
+        Write-Checkpoint -JsonlPath $OutJsonl -Record $record
+        $records.Add($record)
+        $judged[$base] = $true
+        if ($null -ne $record.error) {
+            $thisRunErrorPaths.Add($inputPath)
+            # Watchdog: a COM error may have poisoned the session — re-create it.
+            Close-HwpObject $hwp
+            $hwp = New-HwpObject
+        }
+    }
+} finally {
+    Close-HwpObject $hwp
+    $hwp = $null
+}
+
+# Pass 2 (FR-002d): single retry over files that errored on THIS run's pass 1. A
+# prior-run *unretried* exception is not treated as final — RESUME re-attempts it
+# in pass 1 above (see Get-JudgedBasenames), so it flows here again if it re-errors.
+# The retried record is appended and wins the aggregator's last-line basename join.
+if ($thisRunErrorPaths.Count -gt 0) {
+    $hwp = $null
+    try {
+        $hwp = New-HwpObject
+        foreach ($inputPath in $thisRunErrorPaths) {
+            $record = Invoke-OpenCheck -Hwp $hwp -InputPath $inputPath -PageLimit $MaxPages -TimeoutSec $OpenTimeoutSec -Retried $true
+            Write-Checkpoint -JsonlPath $OutJsonl -Record $record
+            $records.Add($record)
+            if ($null -ne $record.error) {
+                Close-HwpObject $hwp
+                $hwp = New-HwpObject
+            }
+        }
+    } finally {
+        Close-HwpObject $hwp
+        $hwp = $null
+    }
+}
+
+# Final consolidated array (prior + this run), mirroring the legacy shape.
+$json = $records | ConvertTo-Json -Depth 4
+if ($OutJson) {
+    Set-Content -LiteralPath $OutJson -Value $json -Encoding UTF8
+} else {
+    $json
+}

hwpx/visual/oracle.py

@@ -50,6 +50,7 @@ from .report import VisualReport
 from hwpx.form_fit.wordbox import WordBox
 
 _BACKEND_SCRIPT = "_render_hwpx.ps1"
+_OPEN_RATE_SCRIPT = "_hancom_open_rate.ps1"
 _MAC_BACKEND_SCRIPT = "_render_hwpx_mac.applescript"
 _COM_REGISTRY_KEYS = (
     r"HWPFrame.HwpObject\CLSID",
@@ -193,6 +194,190 @@ class WindowsComOracle(RenderBackend):
             os.close(handle)
         return self.render_many([(hwpx_path, out_pdf)]).get(hwpx_path)
 
+    def open_check_many(self, paths: list[str]) -> list[dict[str, object]]:
+        """OPEN-check ``paths`` through Hancom COM and return per-file verdicts.
+
+        This is the M9 open-rate primitive (specs/007-open-rate FR-001). It is
+        deliberately DISTINCT from :meth:`render_many`: it surfaces the real
+        Hancom ``opened`` boolean as its own signal — never conflated with the
+        ``saved``/render verdict that :meth:`render_many` (and ``visual_check``
+        at oracle.py:402) report. ``opened`` answers "did real Hancom load this
+        generated file without a corruption modal", which is the published
+        open-rate; ``saved`` answers a different question (did it render to PDF).
+
+        Each entry is::
+
+            {
+                "path": str,            # the input path as requested
+                "opened": bool | None,  # True/False from Hancom; None = unverified
+                "parsed": bool | None,  # opened and GetPageText(1..) textLength>0
+                "text_length": int | None,
+                "error": str | None,
+                "retried": bool,        # opened only on the single retry pass
+                "status": str,          # "ok" | "open_failed" | "unverified"
+            }
+
+        Honest degrade (constitution V/VI): off-Windows or where Hancom is not
+        reachable, EVERY entry is returned with ``opened=None`` and
+        ``status="unverified"`` — NEVER ``False`` (that would slander a file we
+        never tested) and NEVER a silent ``True``. The aggregator maps
+        ``unverified`` to the unverified bucket, not the numerator or denominator
+        success count.
+        """
+
+        if not paths:
+            return []
+        if not self.available():
+            return [self._unverified_entry(p) for p in paths]
+
+        abs_paths = [os.path.abspath(p) for p in paths]
+        # path -> requested (original) string, for surfacing the caller's path.
+        requested = {os.path.abspath(p): p for p in paths}
+
+        tmp = tempfile.mkdtemp(prefix="hwpx-open-rate-")
+        try:
+            jsonl_path = os.path.join(tmp, "checkpoint.jsonl")
+            res_path = os.path.join(tmp, "result.json")
+            with resources.as_file(
+                resources.files("hwpx.visual").joinpath(_OPEN_RATE_SCRIPT)
+            ) as ps1:
+                cmd = [
+                    self._powershell, "-NoProfile", "-NonInteractive",
+                    "-ExecutionPolicy", "Bypass", "-File", str(ps1),
+                    "-OutJsonl", jsonl_path, "-OutJson", res_path,
+                    "-Path", *abs_paths,
+                ]
+                try:
+                    subprocess.run(
+                        cmd, capture_output=True,
+                        timeout=self.timeout + 60.0 * len(paths), check=False,
+                    )
+                except (subprocess.TimeoutExpired, OSError):
+                    # Subprocess never finished: prefer the crash-safe checkpoint
+                    # (records written per-file) before degrading the rest.
+                    return self._merge_checkpoint(abs_paths, requested, jsonl_path)
+
+            entries = self._read_open_result(res_path)
+            if entries is None:
+                # No parseable consolidated result: fall back to the checkpoint.
+                return self._merge_checkpoint(abs_paths, requested, jsonl_path)
+            return self._entries_from_records(abs_paths, requested, entries)
+        finally:
+            shutil.rmtree(tmp, ignore_errors=True)
+
+    @staticmethod
+    def _unverified_entry(path: str) -> dict[str, object]:
+        return {
+            "path": path,
+            "opened": None,
+            "parsed": None,
+            "text_length": None,
+            "error": "OPEN_ORACLE_UNAVAILABLE: no Hancom reachable on this platform",
+            "retried": False,
+            "status": "unverified",
+        }
+
+    @staticmethod
+    def _normalise_record(record: dict[str, object]) -> dict[str, object]:
+        """Map one PS1 ``{sourcePath,opened,textLength,error,retried}`` record to
+        the ``open_check_many`` entry shape (open/render distinction preserved)."""
+
+        opened_raw = record.get("opened")
+        opened = bool(opened_raw) if opened_raw is not None else None
+        text_length = record.get("textLength")
+        try:
+            text_length = int(text_length) if text_length is not None else None
+        except (TypeError, ValueError):
+            text_length = None
+        error = record.get("error")
+        parsed: bool | None
+        if opened is None:
+            parsed = None
+        else:
+            parsed = bool(opened and (text_length or 0) > 0)
+        status = "ok" if opened else ("unverified" if opened is None else "open_failed")
+        return {
+            "path": record.get("sourcePath"),
+            "opened": opened,
+            "parsed": parsed,
+            "text_length": text_length,
+            "error": error,
+            "retried": bool(record.get("retried", False)),
+            "status": status,
+        }
+
+    @staticmethod
+    def _read_open_result(res_path: str) -> list[dict[str, object]] | None:
+        if not os.path.exists(res_path):
+            return None
+        try:
+            # PowerShell Set-Content -Encoding UTF8 prepends a BOM; utf-8-sig
+            # strips it (and reads BOM-less output fine too).
+            with open(res_path, encoding="utf-8-sig") as handle:
+                data = json.load(handle)
+        except (json.JSONDecodeError, ValueError, OSError):
+            return None
+        if isinstance(data, dict):  # single file -> ConvertTo-Json emits an object
+            data = [data]
+        if not isinstance(data, list):
+            return None
+        return data
+
+    def _entries_from_records(
+        self,
+        abs_paths: list[str],
+        requested: dict[str, str],
+        records: list[dict[str, object]],
+    ) -> list[dict[str, object]]:
+        """Align PS1 records back to the requested order, degrading any missing
+        file to ``unverified`` (never silently dropped)."""
+
+        by_path: dict[str, dict[str, object]] = {}
+        for record in records:
+            if not isinstance(record, dict):
+                continue
+            if record.get("_meta"):  # repair-mode-probe meta line, not a verdict
+                continue
+            norm = self._normalise_record(record)
+            src = norm.get("path")
+            if isinstance(src, str):
+                by_path[os.path.abspath(src)] = norm
+        out: list[dict[str, object]] = []
+        for abs_path in abs_paths:
+            norm = by_path.get(abs_path)
+            if norm is None:
+                out.append(self._unverified_entry(requested.get(abs_path, abs_path)))
+            else:
+                # Surface the caller's original path string.
+                norm["path"] = requested.get(abs_path, norm.get("path"))
+                out.append(norm)
+        return out
+
+    def _merge_checkpoint(
+        self,
+        abs_paths: list[str],
+        requested: dict[str, str],
+        jsonl_path: str,
+    ) -> list[dict[str, object]]:
+        """Recover verdicts from the per-file JSONL checkpoint after a crash or
+        timeout; files with no checkpoint record degrade to ``unverified``."""
+
+        records: list[dict[str, object]] = []
+        if os.path.exists(jsonl_path):
+            try:
+                with open(jsonl_path, encoding="utf-8-sig") as handle:
+                    for line in handle:
+                        line = line.strip()
+                        if not line:
+                            continue
+                        try:
+                            records.append(json.loads(line))
+                        except (json.JSONDecodeError, ValueError):
+                            continue
+            except OSError:
+                records = []
+        return self._entries_from_records(abs_paths, requested, records)
+
 
 class MacHancomOracle(RenderBackend):
     """Adapter that renders ``.hwpx`` → PDF through ``Hancom Office HWP.app``.

{python_hwpx-2.18.0.dist-info → python_hwpx-2.19.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 2.18.0
+Version: 2.19.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0

{python_hwpx-2.18.0.dist-info → python_hwpx-2.19.0.dist-info}/RECORD

@@ -117,6 +117,7 @@ hwpx/tools/package_reconcile.py,sha256=y1Hl7hbPh4YaV59LTdDLzQwgn4g1qEnFmSjmajnrE
 hwpx/tools/package_validator.py,sha256=AA5wy6YgwlU6BTq1p2qCbCVCM8lmIBLhPANKCfaPb-s,29369
 hwpx/tools/page_guard.py,sha256=nDAVPcvrnuyDxVTA_j22wiYD7CXAD6XlzsMzaz3h_q8,9701
 hwpx/tools/pii.py,sha256=N3c36eqblaVQ7o6jiT1BV0WrJK_G3gKhQh6MQGAbvCs,12617
+hwpx/tools/read_fidelity.py,sha256=g4r2GNVExEtL0C-6JMkPIjmH6CtJqNSS_-KsSPTnBbw,10541
 hwpx/tools/recover.py,sha256=EOVAzMFAqR9YAT3sinZKCdjSkKygo4dKrs6T6SbGA7o,4963
 hwpx/tools/redline.py,sha256=p6aMVDBOrkqywlrlxqhB-5ZjCEtgrCNa8cYeRMJlprk,6478
 hwpx/tools/repair.py,sha256=wYO4Zd8ZMwkbYy2_EPz0eyqvTCrzcAyvbEsVE1P87Zk,11197
@@ -140,17 +141,18 @@ hwpx/tools/fuzz/generator.py,sha256=G2tGmo4-i-i0v_-rqHsNKZjfpD5wAJZRMsLTPu_KZfg,
 hwpx/tools/fuzz/minimize.py,sha256=gv9fEU1PsmpXR-Z6wiejMC0umHV90GYhtO2Ht8x2__Y,1055
 hwpx/tools/fuzz/runner.py,sha256=NkSrlWUf813SqEwkhi05LmusMgM9r2j2JiPCqzzvPN8,17906
 hwpx/visual/__init__.py,sha256=KCmFghTLZjWA1reS-dHhdrn2i0FBUQMUv3qghZb7Fqo,2347
+hwpx/visual/_hancom_open_rate.ps1,sha256=stgE7ID2DuIpHWZHi414hmPuvPKnbecPO-oLrFWYBSg,16016
 hwpx/visual/_render_hwpx.ps1,sha256=r7bUPQvMMwVhz5YiUIEZPSAO18GbPPfnaK8iZb67d3w,2412
 hwpx/visual/_render_hwpx_mac.applescript,sha256=ghyvFNwtJ3-0cfy8jQ6HyuJVnFFfXt_Uy5tHjccd5os,7620
 hwpx/visual/detectors.py,sha256=WySbPnhyp4vTZWtkHoAiNY9G9AoZbVNgVgwaEZzt1R0,4853
 hwpx/visual/diff.py,sha256=0X5T9IgwRZU3td-7vnPrlowovtGud7P_ymq0KVehlKk,5677
 hwpx/visual/masks.py,sha256=oXhgynAb4uKjJtZ2BGHHdAjyvWGqSFlZFQ-iJxzHiuo,1832
-hwpx/visual/oracle.py,sha256=QXAyc0xVIjLPWUHM2rBjsustQTmwfoW2Xkb9iX9ai2E,21786
+hwpx/visual/oracle.py,sha256=aON9dPbpbYnUoQ7b1aD5bez2d8BevYeZgWbxdIhP_sA,29746
 hwpx/visual/report.py,sha256=2RhXN1KBYOZTim9FNpeUhaaDHR7oFxI6Z2DLUkDIiwE,1717
-python_hwpx-2.18.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
-python_hwpx-2.18.0.dist-info/licenses/NOTICE,sha256=k48h6EaGQE8Y1c0dS9sIOOcz4YqkbcImWClF7pBOgsg,2473
-python_hwpx-2.18.0.dist-info/METADATA,sha256=uHs8_pBm80hLCUNrfs20a6szLITYaWgK-s8UloSmA68,19982
-python_hwpx-2.18.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_hwpx-2.18.0.dist-info/entry_points.txt,sha256=4U6WXYWHxEiWp2VRHo97fvOYNh7ebu6roonk7chxKcY,453
-python_hwpx-2.18.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
-python_hwpx-2.18.0.dist-info/RECORD,,
+python_hwpx-2.19.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
+python_hwpx-2.19.0.dist-info/licenses/NOTICE,sha256=k48h6EaGQE8Y1c0dS9sIOOcz4YqkbcImWClF7pBOgsg,2473
+python_hwpx-2.19.0.dist-info/METADATA,sha256=R1wYmaa1RlVZuuDuGl4CyQsdl-56YSBbB1_IjZu1WGs,19982
+python_hwpx-2.19.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_hwpx-2.19.0.dist-info/entry_points.txt,sha256=4U6WXYWHxEiWp2VRHo97fvOYNh7ebu6roonk7chxKcY,453
+python_hwpx-2.19.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
+python_hwpx-2.19.0.dist-info/RECORD,,