fix(extensions): stage history export documents byte-exact

[JasonBuildAI]

Goal And Delivered Outcome

• Outcome basis / optional anchor: Closes [Bug]: Windows host cannot publish the OpenViking history-conclusion corpus (staged document readback fails) #6253 (reproduced defect on a native Windows host; no board anchor)
• Goal/source and gap: on Windows, every openviking-semantic-preference history-conclusion export aborts at the staged readback, because _publish_generation stages documents through Path.write_text, whose text-layer newline translation (LF to CRLF) contradicts the byte-exact readback and the manifest sha256 validated in the same function. No corpus was ever published or replaced on that host.
• Observable before to after, with the validation row that proves it: the shipped loopx-openviking-history-export entry point exits 1 with RuntimeError: staged history document failed readback: <name> before; it exits 0 with the JSON receipt, a published generation, and manifest digests equal to the on-disk bytes after (real_entrypoint row).
• Issue/task and intended base: Closes [Bug]: Windows host cannot publish the OpenViking history-conclusion corpus (staged document readback fails) #6253; base main.

Author Declaration

• Written by: OpenAI Codex agent - drafted with AI assistance at the requester's direction, under human-set constraints and review.

Implemented against

• Specification and revision: the reproduced request in [Bug]: Windows host cannot publish the OpenViking history-conclusion corpus (staged document readback fails) #6253 and the exporter's existing byte-exact publication contract in loopx/extensions/openviking_semantic_preference/history_export.py at 3054cdcc1 / rebased c51ec1a60.
• Criteria:

Criterion (spec clause)	Disposition	Symbol / path	Test or command
Published documents equal the bytes the manifest pins	implemented	_publish_generation	examples/loopx-history-conclusion-recall-smoke.py
Staged generation readback stays byte-exact on a host that translates newlines	implemented	_validate_staged_generation	new smoke case _case_staged_documents_stay_byte_exact_on_a_windows_host
A failure while staging documents still propagates and preserves the prior corpus	implemented	_case_export_write_failure_preserves_prior_owned_corpus	smoke case, injection moved to the write-open seam

• Self-check before submission: ran the focused pytest contract, the public contract smoke, the full-public smoke runner entry for this script, ruff, py_compile, and the shipped console entry point on a native Windows host before and after. The accompanying smoke adjustments were made only where the previous assertions encoded the POSIX text layer or the removed write API.

Scope And Continuation

• Completed scope and remaining work: complete within this scope. Only the staged document write changes; the manifest stays a parsed JSON artifact, as before.
• Slice boundary / successor: N/A. The adjacent merged work in this file (fix(extensions): pin bundled extension entrypoint stdio to UTF-8 #6168 stdio pinning, fix(openviking): reject symlinked history export roots #5779 symlink roots) is untouched.

Validation

• Tested revision: c7a1f1e (rebased onto c51ec1a; older runs used 3054cdc + fix)
• Run state: finished
• Input classes: synthetic

Check kind	Result	Public-safe evidence / limitation
static	passed	ruff check on the two changed files and py_compile via loopx canary premerge; git diff --check clean.
unit	passed	python -m pytest -q tests/extensions/test_openviking_history_export.py tests/extensions/test_extension_provider_stdio_utf8.py -> 4 passed.
integration	passed	python examples/loopx-history-conclusion-recall-smoke.py -> ok: 25 history-conclusion export cases passed (14 of them failed before the change with staged history document failed readback); python examples/run-smokes.py --suite full-public --script examples/loopx-history-conclusion-recall-smoke.py -> status: passed.
real_entrypoint	passed	loopx-openviking-history-export against a synthetic runtime root with one run record on a native Windows host: before, exit 1 with RuntimeError: staged history document failed readback: <name>; after, exit 0, written: 1, published document sha256 equals the manifest digest, no CRLF in the document, and a second run re-validates the prior generation (retired_prior_generation: 1).
regression_parity	passed	the new smoke case simulates the Windows text layer and fails on the pre-fix revision with the production error, passes after; the staged-write-failure injection moved below the write API so the case still fails without the fix but no longer pins Path.write_text.
manual	passed	loopx canary premerge --from-git-diff --git-diff-base <upstream main> selects this change's surfaces; its six failing checks (lark inbox/event, extension presentation, finance value discovery, semantic-vocabulary drift) fail identically on the pristine base revision on this host, so they are environment limitations rather than effects of this change.

• Coverage and gaps: the changed write executes in every publish path, covered by the contract smoke's publish/replace/rollback cases and by the real entry point. The only untested path is a host whose text layer differs from both POSIX and Windows, which is not a supported platform claim.

Frontend / Visual Evidence

• UI impact: none
• Before: N/A
• After: N/A
• States and viewports shown: N/A
• Source data: none
• Attention review: N/A (no user-visible surface)
• Craft review: N/A (no user-visible surface)

Type of Change

• Bug fix
• New feature
• Breaking change
• Refactoring (no functional changes)
• Documentation update
• Test update

LoopX Area

• Control plane (goals, todos, quota, scheduler, registry, runtime)
• Benchmark boundary (adapters, runners, verifiers, scoring, evidence)
• Capability or extension (providers, adapters, skills)
• Public docs or presentation surface (README, protocols, dashboard)
• Build, packaging, installer, or CI
• Host or runtime integration

Technical Direction

• Direction / acceptance reference, when applicable: N/A (self-contained reproduced defect)

Shared-authority RFC fixture impact

• Production-scale fixture schema: N/A
• Semantic dimensions changed, or reviewed no-impact rationale: N/A
• Provider conformance arms run: N/A
• Read-only legacy/file/PostgreSQL three-arm rehearsal (required for promotion, runtime-routing, or compatibility-projection changes): N/A

Boundary Checklist

• Neither the diff nor this PR body/comments/attachments disclose private state, credentials, raw traces or verifier output, internal links, or local machine paths (including .loopx/, .codex/goals/, and live ACTIVE_GOAL_STATE.md).
• I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
• I kept the change scoped to the linked issue/task.
• I completed the visual evidence section for UI changes, or marked UI impact none.
• Every commit includes a DCO Signed-off-by trailer (git commit -s).

[loopx-agent]

Reviewer: model_agent; gpt-6.1-sol; OpenAI; runtime_reported; reasoning_effort=xhigh

APPROVE；精确 head c7a1f1ec474d8358ec98299c45aee9e46202ad94。

动机

在 Windows 上把运行结论导出为本地文档的用户。

用户执行历史结论导出时，旧版本把原有换行通过文本写入变成 CRLF，暂存校验随即失败，无法获得文档；此修改改用字节写入，使文档与清单记录的摘要一致，能继续替换下一代文档。

本机真实历史读取和 CLI、独立安装 wheel 均能发布与再次替换语料；模拟 Windows 文本换行时，旧版本失败，新 head 的文档保持原始 UTF-8 字节。

交付边界为现有导出命令的本地文档发布，不包含 OpenViking ingest、记忆写入、在线模型或权限变更。

改动思路

把已经编码且由清单校验的 bytes 直接写入，是现有导出 owner 内最小且完整的修复；放宽校验会隐藏数据漂移，强制全局换行策略会扩大影响。 比较不修复、放松校验和扩大通用框架后，现有 owner 内的 IO 修复最容易验证和回退；输入、作用域和失败保护应一起验收。

本批只改变暂存文档 IO，并同步原有故障注入和路径断言，保留清单、回滚与重复发布的既有语义。 Python 在这里是稳定的文件系统/provider IO 边界，未新建通用控制面决策源，无需为语言迁移扩大本批。

具体改动

独立规格 https://github.com/loopx-project/loopx/issues/6253，spec_revision：c51ec1a60671edb8ef536ef0651836b9d7642878；使用变更前的合同。Issue #6253 创建/更新于 2026-10-11T17:11:13Z；同时对照该 commit 的既有 byte-exact exporter contract。

• byte-exact-documents：implemented；Published document bytes match the manifest SHA-256 and staged expected bytes.
• successful-repeat-export：implemented；The shipped export command publishes a generation and can replace/revalidate it.
• staging-failure-preservation：implemented；Failure while staging must preserve the prior managed generation.

关键代码讲解

• _publish_generation 在逐个暂存文档时由解码后文本写入改为 write_bytes(data)，沿用同一数据源、顺序、目录替换和回滚，未绕过校验。
• _validate_staged_generation 继续逐字节比较文档，清单继续解析 JSON 比较；JSON 的宿主换行不影响这份结构性校验。
• export_goal_conclusions 仍通过实际 collect_history 取结论，使用已有 public-safe sanitizer，并将本地路径留在 local receipt；不增加 provider 访问。
• 公共 smoke 的旧写失败注入下移到 Path.open，仍真实失败且保护前代；路径断言使用 Path.parts 保留目标身份，新增用例模拟 CRLF 写入并覆盖二次发布。

对主干的风险

4 项 focused pytest、25 项公共 smoke、Ruff、完整语义检查与 291-site IO manifest 检查通过。冻结独立 CLI oracle 在 base 上仅 Windows 文本换行用例失败，其余 4 项对照通过；head 与独立 wheel 的 5 项全部通过，字节期望是固定 literal，并非调用被测渲染器生成。 对 source、base 与安装 wheel 检查了解释器和模块来源；native filesystem 操作没有替换为成功 mock。初始测试路径错误不计通过；未准备前端 assets 的 wheel 构建先失败，完成正常 npm ci / build:chat 后构建和隔离安装，未绕过包装校验。

Windows 原生宿主未由本评审运行；模拟覆盖的是 Python 文本换行行为，不能声称 Windows junction、杀进程竞态或 provider 采用已获验证。未改存储 provider，无需把 PostgreSQL 验收当作此文件 IO 修复的前置条件。 CI 按当前配置未查询、轮询或等待；作者的外部平台/测试声明不作为本评审的独立证明。语义 advisory 没检测到支持的新词汇载体，完整检查通过但仍保留 45 个 unresolved producer sites，不能由此宣称全树语义安全。

未发现本批阻塞问题。故障注入覆盖两种写 API，先暂存并读回再发布的顺序未改变；发布失败、清单所有权、外部内容和 symlink 保护继续由完整公共 smoke 与独立反例约束。

我的整体评价

长期重复导出和用户取得文档的路径得到改善；这一局部修复已经通过真实入口、二次执行及失败保存的完整结果验收。 把已经编码且由清单校验的 bytes 直接写入，是现有导出 owner 内最小且完整的修复；放宽校验会隐藏数据漂移，强制全局换行策略会扩大影响。 本批只改变暂存文档 IO，并同步原有故障注入和路径断言，保留清单、回滚与重复发布的既有语义。 未来维护整理已检查：删除 bytes/text 往返就是相关简化，无需新增 helper。 已有阶段恢复经验仅作提示，本结论没有继承历史 verdict，也不声明生产采用、整条 roadmap 关闭或合并授权。

English verdict: APPROVE - exact head c7a1f1e. Byte-exact staged writes preserve the existing manifest and rollback contract. Immutable base fails the simulated Windows text-layer case; head and installed wheel pass all 5 independent CLI cases plus 4 focused tests and 25 public smoke cases. No native Windows/provider-adoption claim.

[loopx-agent]

Reviewer: model_agent; gpt-6.1-sol; OpenAI; runtime_reported; reasoning_effort=xhigh

English verdict: APPROVE - exact head c7a1f1e. Byte-exact staged writes preserve the existing manifest and rollback contract. Immutable base fails the simulated Windows text-layer case; head and installed wheel pass all 5 independent CLI cases plus 4 focused tests and 25 public smoke cases. No native Windows/provider-adoption claim.