fix(openclaw-plugin): declare OpenClaw 2026.8.1 durable-turn contract

[ZaynJarvis]

起因

OpenClaw 2026.8.1-beta 上装 openviking 插件后，每轮都刷：

[context-engine] Context engine "openviking" degraded to "legacy": current-turn transcript fencing is not declared.

auto-capture / auto-recall 全程不工作（#4103）。

为什么是这个性质

不是 assemble 的问题。对照 openclaw 2026.8.1-beta.3 dist：

• context-engine-logical-turn.ts（dist context-engine-turn-attempt-*.js:63-64）在每个 turn 开始做三项检查：info.transcriptSemantics.currentTurnFence === "before-current-turn-entry-v1"、turnAdvancementIdempotency === "atomic-idempotent-v1"、typeof engine.commitTurn === "function"。任一缺失就把整个 logical turn 交给 legacy 引擎，插件的 assemble / afterTurn 根本没被调到。
• assemble 的两种调用形态（preflight 带 prompt/availableTools/citationsMode，transformContext 不带）和 afterTurn 的调用点与 2026.7.1 相同，插件现有分支逻辑不需要改。
• 契约来自 openclaw PR #119325（crash-durable、exactly-once 的 turn 提交：host 先写 SQLite outbox，再调 commitTurn(advancementKey, messages)，失败下轮同 key 重试）。后续 #121461、#126593 修的是 host 侧 bug，beta.3 已含。

改法

examples/openclaw-plugin/context-engine.ts：

1. info.transcriptSemantics 声明两个字段。
2. 新增 commitTurn({ advancementKey })：内存 Set 记 key，首次返回 committed，重复返回 duplicate（上限 1024 个 key）。

取舍

• commitTurn 不写 OV，只做 ack。 host 在新路径下仍然调 afterTurn（transformContext 每次 LLM call 一次 + finalize 一次），capture 留在那里；commitTurn 再写一次就是双写。
• key 集合不跨进程持久。host 自己的 outbox 是持久的，重启后重试同 key 我们回 committed，行被删；这和改动前的持久性一致（afterTurn 没跑完就 crash 的 turn 原本也会丢）。如果后续 OpenClaw 把 afterTurn 从 durable 路径拿掉，capture 需要搬进 commitTurn。
• engines.openclaw 保持 >=2026.5.27：旧版忽略多余 info 字段和未知方法。

没动什么

assemble / afterTurn / compact 逻辑、README。#4415 第 5 条（isMainAssemble duck-typing）这次核实在 8.1 仍成立，不在本 PR 处理。

验证

• npm run typecheck 通过。
• vitest run：750/754 通过；4 个失败在 tests/ut/architecture-boundaries.test.ts，main 上（stash 后）同样失败，与本改动无关。
• 新增 tests/ut/context-engine-commit-turn.test.ts：断言 transcriptSemantics 值、commitTurn 同 key 二次调用返回 duplicate。
• 未在真实 OpenClaw 2026.8.1 上跑（npm 尚无稳定版，只有 beta.1-3）。

Fixes #4103

🤖 Generated with Claude Code

https://claude.ai/code/session_012TsbqPJYxEqGWrBqYeodWR

[ZaynJarvis]

本地实跑验证通过，结论：这个 PR 同时满足“旧版兼容”和“8.1 能调用 assemble hook”两点。

测试环境：

• PR HEAD：d16712b8984d1cd706d7beebccd6ed8774dbbe84
• Node：22.22.3
• 8.1：npm 当前没有稳定版 openclaw@2026.8.1（该版本返回 E404），因此使用目前最新的 openclaw@2026.8.1-beta.3
• 旧版基线：openclaw@2026.7.1
• 用本地 mock OpenAI-compatible 模型和 mock OpenViking context endpoint 跑完整的 openclaw agent --local embedded turn，隔离 state/config，不依赖外部服务

验证结果：

1. 新接口本身

   • npm run typecheck、npm run build 均通过。
   • 新增测试 tests/ut/context-engine-commit-turn.test.ts：2/2 通过；确认 transcript semantics 两个字段，以及同一 advancementKey 第一次返回 committed、第二次返回 duplicate。

2. 8.1-beta.3 正向验证（PR HEAD）

   • 插件正常注册为 contextEngine=openviking。
   • 实际日志出现两轮 openviking: diag 的 assemble_entry / assemble_result（preflight + main transformContext）。
   • turn 完成后实际调用了新增的 commitTurn，日志含非空 advancementKey。
   • agent turn exit 0、正常得到 mock reply；没有 degraded to legacy 警告。

3. 8.1-beta.3 负向对照（PR base cd8580c6f8a50ec44593618b3102799ab0b553fd，无本 PR 改动）

   • 同一套环境立即出现：Context engine "openviking" degraded to "legacy" ... current-turn transcript fencing is not declared。
   • 没有任何 openviking: diag assemble_*，证明 assemble 确实被绕过。

4. 旧版兼容验证（OpenClaw 2026.7.1 + PR HEAD）

   • 插件可正常加载，配置校验通过，完整 agent turn exit 0。
   • 实际日志同样出现 assemble_entry / assemble_result，assemble 正常执行。
   • 旧 host 不调用 commitTurn（符合预期），新增 info 字段和方法被安全忽略，没有回归。

明确结论：可通过。 这个 PR 修复了 8.1 durable-turn contract 缺失导致的每轮 legacy 降级；同时保持对 2026.7.1 旧 host 的运行时兼容。唯一需要在 PR 描述里继续注明的是：本次 8.1 实跑针对 npm 可获得的 2026.8.1-beta.3，不是尚未发布的 stable 2026.8.1。