windows-binary-validation.md

# Windows binary validation

## Current website-delivery artifact

The new Windows x64 onedir artifact passed **44 checks, 0 failed**, run `8928b30c`. Its executable SHA-256 is `b1ee7337a2d376ba7855658df49c5cfa2bf6f23cd24377c8da7ed9d0c916007e`. Evidence is `.work/website-windows-smoke.json` (internal development record, not shipped). It covered the complete copied application in a Unicode/space path, CLI, import, fallback, original sources/PNG, real MCP SDK and unchanged inputs. See [acceptance](acceptance.md) for separate Python/library installer and model validation.

## Previous artifact history

As recorded on **2026-10-03**, the previous rebuilt Windows x64 onedir artifact **passed acceptance: 44 checks passed, 0 failed**. Its machine-readable evidence is `.work/smoke-release-final.json`（工程内部验收记录，不随发行包提供）; the reusable harness is `packaging/smoke_binary.py` inside the delivered source archive. The earlier **35 checks, 0 failures**, intermediate **4 passed, 7 failed** and previous **44 checks, 0 failures** results belong to different executable hashes and are retained as history. The hashes and table below describe that historical artifact, not the current website-delivery executable.

## Historical rebuilt artifact: passed

| Item | Observed value |
| --- | --- |
| Run started (UTC) | `2026-10-03T02:57:34.766599+00:00` |
| Run ID | `0a3d5ab2` |
| Version | `0.1.0`; version command completed in `1.191` seconds |
| PE architecture | `0x8664` (Windows x64) |
| Executable SHA-256 | `880f5ae8bd6e8c169887ae901d81cf9b7768beeae60d175c8a64ef74eb2b00e6` |
| Executed copy | `.work/发行 测试/release-1003/book-agent/book-agent.exe` |
| External runtime state | `F:/workspace/BookAgentBinaryAcceptance/0a3d5ab2` |
| Outcome | `passed=true`; 44 passed, 0 failed |

The harness copied the complete `dist/book-agent/` directory to a fresh Chinese/space path and verified every copied file's SHA-256. Every runtime operation invoked that copied executable. Real PDF and EPUB imports completed in 0.949 and 1.423 seconds; synthetic 7z import in 1.028 seconds; actual-example import in 1.017 seconds. The development Python launches the harness and supplies independent fixture/MCP-client libraries; it does not import Book Agent Core.

The current run passed CLI, original-source, PNG/MCP, configured vector-mode fallback, host dry-run and read-only integrity checks. Its input archive/package hashes, sizes and modification times remained unchanged. It did not call a native host Agent or a vision model. Execution on a clean Windows VM, Linux native builds and macOS native builds remains untested. Deliver the onedir directory intact; copying `book-agent.exe` alone omits runtime dependencies.

## Intermediate rebuilt artifact: failed

The failed report `.work/binary-smoke.json`（工程内部验收记录，不随发行包提供） is retained separately: run `7184e39d`, started `2026-10-02T16:22:04.024045+00:00`, **4 passed, 7 failed**, executable SHA-256 `3e6fe838c49be2190b3e7e5a78fbcc6a31175f247c05c77d6320bcbfc5ae98bd`.

That run refused an unrelated existing Chinese/space copy destination. Direct executable calls for version and PDF/EPUB/synthetic 7z/actual-example import each exceeded 120 seconds; version equality consequently failed. Only PE architecture and three input-integrity checks passed. The startup log `.work/binary-smoke-startup.txt` did not establish a specific timeout cause. These failures remain part of the history and are not the result for final run `0a3d5ab2`.

## Previous 44-check successful artifact

Run `0155492f` also passed 44 checks and is retained at `.work/binary-smoke-delivery.json`（工程内部验收记录，不随发行包提供）. Its executable SHA-256 was `bf0657138afa3d8d5e94976b550b320c27a42426befae63c31beae047f3e441e`; the latest release artifact has a different hash. Timings and PNG fingerprints below refer to current run `0a3d5ab2`.

## Historical successful artifact

The following **35 passed, 0 failed** result was obtained on Windows 10 build 19045, AMD64 before the final rebuild. Its report is retained at `.work/binary-smoke.before-final.json`（工程内部验收记录，不随发行包提供）. Its executable hash differs from the later artifacts.

| Item | Observed value |
| --- | --- |
| Run started (UTC) | `2026-10-02T14:42:04.149246+00:00` |
| Run ID | `10906614` |
| Version | `0.1.0` |
| PE architecture | `0x8664` (Windows x64) |
| Executable SHA-256 | `2e4f15cb1d105afae4268850bff93f8dcb6e5c6e90470ae821444e44375df7c2` |
| Executed copy | `.work/发行 测试/book-agent/book-agent.exe` |
| External runtime state | `%LOCALAPPDATA%/BookAgentBinaryAcceptance/10906614` |

In this historical run, the harness copied the entire `dist/book-agent/` directory into the Chinese/space path and verified every copied file's SHA-256. It invoked the copied executable for every runtime operation. The development Python launches the acceptance harness and supplies its independent fixture/MCP-client libraries; the harness does not import Book Agent Core.

This run used the local development machine. Execution on a clean Windows VM, Linux native builds and macOS native builds remain untested. The onedir directory must be delivered intact; copying `book-agent.exe` alone omits its runtime dependencies.

## Reproduce

From the `book-agent/` project directory, after building the onedir artifact:

```powershell
& '.venv\Scripts\python.exe' -B packaging/smoke_binary.py --executable dist/book-agent/book-agent.exe --copy-dir '.work/发行 测试/new-run/book-agent' --report '.work/binary-smoke-new-run.json' --example-archive 'E:\000zips\Model Checking with Fly-Automata--ed514f974d3494ee.7z'
```

Omit `--example-archive` on a machine without this local example. Synthetic PDF, EPUB, SQLite and 7z checks always run. Each invocation creates a dedicated external runtime directory and new fixtures. Choose a fresh copy destination and report filename for each rebuilt artifact, then compare its executable hash. A copy destination must be new or owned by this harness with an unchanged `.book-agent-smoke-copy.json` marker; an unrelated existing directory is refused.

The smoke harness was also checked with:

```powershell
& '.venv\Scripts\python.exe' -B -m ruff check packaging/smoke_binary.py
```

## Current verified scope

| Area | Checks and result |
| --- | --- |
| Frozen runtime | Windows x64 PE header and version; complete onedir copy under Chinese characters and spaces |
| SQLite | Read-only import and diagnostics of an explicit-schema database; original record `p1` returned with a vector score using supplied `[1, 0]` |
| Retrieval | Natural-language lexical fallback is labeled `lexical_fallback`; configured `none`, `offline` and `online` modes retain that label when the synthetic package has no verified encoder; reranking is disabled |
| PDF | Real two-page PDF import, doctor, text locate/read and page-to-PNG rendering |
| EPUB | Real EPUB ZIP/container/OPF/chapter import, original XHTML text and embedded raster PNG read |
| 7z | Real synthetic 7z extraction/import and actual example archive import/status |
| MCP | Official SDK stdio initialization; required tool inventory; status/search/source calls; actual PDF and EPUB PNG `ImageContent` |
| MCP stdout | No non-JSONRPC stdout line was rejected by the client; a protocol parse warning fails the harness |
| Hosts | Codex, TRAE, WorkBuddy and Cherry Studio dry-run plans; none created its isolated host home |
| Integrity | Synthetic package file hashes/sizes/mtimes unchanged; no package `__pycache__`; synthetic and actual archive hashes/sizes/mtimes unchanged |

The synthetic figure contains a random nine-digit value solely in raster pixels. The harness confirmed that value was absent from Markdown, retrieved text and original PDF/EPUB text. It confirmed actual PNG bytes reached the MCP client. The PDF image in the current run was **33,885 bytes**, SHA-256 `377109453e0d37352bbed8e14f2047fcfef86a604f3cc4b65f98f865af566f27`.

The SQLite vector check uses a supplied synthetic vector against existing vectors. It does not establish a compatible natural-language query encoder. The synthetic package has no approved encoder and therefore correctly falls back to lexical retrieval for natural-language queries. Document embeddings were not regenerated. The actual example's audited BGE-M3 query contract was reported by `status`; remote queries were not authorized or sent by this harness.

## Current actual example integrity

Input: `E:\000zips\Model Checking with Fly-Automata--ed514f974d3494ee.7z`.

| Property | Before and after |
| --- | --- |
| SHA-256 | `9be2921444e388c26808ea6b223f9aec28aee965d38f454fd17ec3817af12e0a` |
| Size | `215750` bytes |
| Modification time | `1790943062558059400` ns |

The imported example retained its existing SQLite adapter `pipeline-bge-m3-lossless-v1`, 1024 dimensions and 3 records. Source diagnostics reported an 8-page PDF. Runtime state and extracted managed copies were written outside the original archive.

## Acceptance limits

- The final rebuilt executable passed 44 checks. Its lightweight binary does not bundle PyTorch or the BGE-M3 model; optional local encoding uses the separately validated Python runtime.
- Complete release pytest finished with 276 passed, 2 skipped in 161.38 seconds (`.work/tests-release-final.log` and `.xml`). Separate actual default Skill bootstrap installed 46 wheels in 73.259 seconds; the dedicated optional installer installed 67 packages offline with hash checks and a successful pip check in 233.145 seconds. Their independent receiving-venv probes passed in 16.747/245.664 seconds, checking default lexical/source/host-dry-run behavior; the optional probe also imported its neural dependencies and ran CPU tensor math. These are separate Python deployment results, not frozen-EXE tests. Optional bootstrap's 67-wheel route was planned but not actually installed through bootstrap. See [acceptance](acceptance.md) for reports.
- The optional receiving-runtime probe's 245.664 seconds includes cold imports and plan hash verification, not search latency; it did not repeat a complete BGE-M3 forward. Actual model-query timings remain the two reports below. Installation reports captured the same application code/dependencies before this documentation update; the final release manifest will be regenerated with the updated documents.
- Separate Python CPU offline-query acceptance passed with the actual BGE-M3 checkpoint under socket/urllib network blocking. It produced a finite 1024-dimensional CLS/L2 vector, retrieved the three original SQLite records and located physical PDF page 2; no document embeddings were generated and the archive plus 29 input files remained unchanged. Cold encoding took 33.609 seconds; the second Core search took 0.780 seconds for the same question after model/dependency warmup, with question encoding repeated. The complete 88.695-second run included weight registration/hash verification. Evidence: `.work/acceptance/offline-real-query.json`. This separate optional Python path does not validate the rebuilt lightweight executable.
- The layer-streaming encoder also passed 14 actual tiny-model tests in 131.04 seconds, including four numerical comparisons against the official full eager encoder. The full checkpoint was not compared numerically with the unpinned hosted provider; that parity remains unverified. Repeated faulthandler samples and native-library import stacks alone are not completed results.
- A second blocked-network run (`.work/acceptance/offline-query-instrumented.json`) passed and counted one actual forward each for the same-question and new-question searches, taking 0.973 and 0.869 seconds after warmup; the forwards themselves took 0.621 and 0.854 seconds. Its initial encoding took 155.887 seconds and complete run 256.183 seconds. These timings differ from the first run and are local observations, not latency guarantees. The implementation caches the tokenizer/model adapter and encodes each question again; it does not cache query vectors. Neither report records process peak memory.

- Host dry-runs establish configuration planning and bundled Skill availability. Separate native Codex CLI acceptance passed using an isolated Python MCP runtime: exit 0, 67.592 seconds, 18 events and six completed status/Skill/search/source/image calls with no errors (`.work/acceptance/codex-final-v2/codex-call.json`). It did not modify global configuration. Native Skill automatic triggering and other hosts' actual UI/model behavior remain untested; this Agent run did not use the frozen executable.
- PNG delivery establishes source-image transport. No vision-capable model interpreted the raster-only value in this smoke run; real visual understanding remains untested.
- Local rerank weights are not bundled. This run selected `--reranker none`; local model loading and reranking remain untested.
- The harness did not read credentials, install global host configuration or contact remote query/rerank services.

The older startup/stdout/resource failure is retained as `.work/binary-smoke.initial.json`; historical success as `.work/binary-smoke.before-final.json`; intermediate rebuilt-artifact failure as `.work/binary-smoke.json`; previous 44-check success as `.work/binary-smoke-delivery.json`; latest release success as `.work/smoke-release-final.json`. These are separate artifact/run results.