Add durable nightly knowledge review, correction and containment

README.md

@@ -371,4 +371,5 @@ zero（`vllm-omni`），可传任何已接入仓库的短名、别名或 owner/n
 其余：[发版漂移审计](doc/contributing/release-maintenance.md) ·
 [知识库贡献规范](doc/knowledge/CONTRIBUTING.md) ·
 [知识维护示例](doc/knowledge/maintainer-walkthrough.md) ·
+[夜间维护与撤回](doc/architecture/knowledge-maintenance.md) ·
 [评测结论](doc/evaluation/README.md)

doc/architecture/SPEC/app/run_service.md

@@ -1,6 +1,6 @@
 # app/run_service.py —— 规范
 
-<!-- verified-against: 2026-10-06 -->
+<!-- verified-against: 2026-10-08 -->
 
 `RunService` is the durable application boundary shared by the embedded
 Strict SDK and MCP transport. It owns policy-checked reserve/start, a queue
@@ -46,6 +46,9 @@ run is pinned to this server's effective `knowledge_dir` (reported as `packaged`
 or `unverified` for a custom directory), with `KNOWLEDGE_ROOT` removed from the
 child's environment. Runs reserved before pinning
 existed have no record and use the process default.
+Containment repository resolution and the issued scope receipt use this same
+effective view, including a custom `knowledge_dir`; packaged bytes cannot stand
+in for the custom bytes that the child consumes.
 
 ## 2026-09-30 Concurrent workers
 `Settings.strict_max_workers` (`STRICT_MAX_WORKERS`, 1–32, default 1; embedded
@@ -76,3 +79,8 @@ services and the CLI as well. Not covered: two agent sessions *inside one run*
 (ensemble lenses, per-comment verification, bounded by
 `strict_backend_concurrency`) still share their run's own tree; that predates
 this change and is independent of the worker count.
+
+
+## 2026-10-08 Signed containment
+
+When containment is explicitly enabled, reservation issues a private provider receipt for the pinned repository/shared snapshot scope into `knowledge.json`. It identifies conservative publication dependencies; it does not claim every scoped unit was injected. Launch rechecks the receipt and forwards only explicit maintenance configuration to the child. Old reservations without issuance fail closed until reassessed.

doc/architecture/SPEC/direct_routing.md

@@ -1,6 +1,6 @@
 # direct_routing.py —— 规范
 
-<!-- verified-against: 2026-10-06 -->
+<!-- verified-against: 2026-10-08 -->
 
 `LOC ~880 · Direct 模式完整策略包与仓库中立的知识路由 · refactor-status: stable`
 
@@ -87,3 +87,10 @@ SDK 完成校验钉住计划时快照、模块源码不含仓库名）；`test_c
 ## 重构备注
 原 `_DIRECT_OWNER_ROUTES`/`_REPO_ALIASES` 已外置（`known-debt` 清零），
 `test_v2_p0.py` 与 `test_repo_vocabulary.py` 中本模块的泄漏上限随之移除。
+
+
+## 2026-10-08 Signed containment
+
+Route-table validation checks unused navigation targets for integrity without serving their content. Selected owner/model reads pass `KnowledgeView.path` and current containment. Quickmap extraction first removes retired rules. Related retrieval excludes specifically held pages; invalid or stale policy still fails the request closed.
+
+With containment enabled, the raw `direct_review_plan` also returns a private-registry-backed `knowledge_usage` receipt for its selected route, procedure, and related-document dependencies. It binds a private delivery session for later raw document reads/searches without claiming model injection inside the planner. The public `direct_completion_result` requires that receipt and rechecks all original and follow-up issued resources against the current policy. Missing, forged, stale, or held provenance returns `partial_review` with `publish_ready=false`; the original structural evidence checks remain in force. The SDK forwards its own issued context receipt to the same gate. Disabled deployments retain the existing bundle and completion result shape.

doc/architecture/SPEC/engine/steps/pr.md

@@ -1,6 +1,6 @@
 # engine/steps/pr/ —— 规范
 
-<!-- verified-against: 2026-10-04 -->
+<!-- verified-against: 2026-10-08 -->
 
 `LOC ~1988（6 个文件） · step 库（PR） · refactor-status: ok`
 
@@ -82,6 +82,9 @@ rebase，不修改配置 checkout 的分支或文件，不推送。该树是一
 - `pr.fetch_ci_failures` 经 profile 选定的 CI provider 富化日志，否则记一条
   `capability_gap`（**E2**）；`pr.group_failures` 按**归一化后**的签名分组。
 - `pr.post_review` 是**双闸**的（**C5**）。
+- 启用知识撤回协议后，`pr.post_review` 在实际 GitHub 写入处持有消费端发布锁，
+  复查本次固定知识回执的可用性。缺失、失效或命中撤回的回执会阻止发布并要求重评；
+  策略安装与发布共用该锁，确认回执不能越过尚未结束的旧代际写入。
 - `pr.harvest_debug_knowledge` **只在真实推送后落盘**（push 输出存在且非 dry-run，
   且至少一组修复同时有 root_cause 与 verification —— 与 debug memory 同一门槛），
   投递到两个**彼此独立**的 sink：`settings.knowledge_intake_dir`（同主机落盘）与

doc/architecture/SPEC/kb_service.md

@@ -1,6 +1,6 @@
 # kb_service/ —— 规范
 
-<!-- verified-against: 2026-10-07 -->
+<!-- verified-against: 2026-10-08 -->
 
 `知识服务核心：仓库配置、账本、outbox、CLI · refactor-status: new`
 
@@ -39,6 +39,37 @@ stdlib + PyYAML + `cryptography`（`kb` extra）+ `.adapters` + `.knowledge_serv
 ## 测试
 `test_kb_service_core.py`。
 
+## 2026-10-08 持久夜间维护与撤回
+
+- `maintenance` 在现有 scheduler 租约内运行 Shanghai 01:00 的可恢复周期；
+  `maintenance_units` 对不变的规则和说明文本也重新质疑，快照、策略与公平分母在周期开始时固定。
+  `maintenance_audit` 读取原始版本的源码行段、校验 pin/span/hash，缺失证据保持 unknown，
+  execution_error 与 contradicted 分开。不能以旧 verdict 或最新 HEAD 代替原始证据。
+- `maintenance_store` 以附加表保存 runs/items/findings/usage/budget/requests/resolutions，
+  不改写原 intake、verdict、pin、激活和 reviewed 回执。所有执行写入受现有租约栅栏保护，
+  CLI 只可并发入队请求；每次模型调用先记不可重复派发的预算预留，恢复不能重发已预留调用。
+  每日 $50 上限含 $10 公平保留；未知价格或 API transport 不能证明硬上界时拒绝调用。
+- `maintenance_correction` 复用 owner-scoped retire/replace、保护字段与普通质量门；
+  提案不等于已修正，原始 verdict、退役与应用历史均保留。`maintenance_calibration`
+  只消费具明确人工标签和原始证据的签名案例；校准调用也纳入预算和模型记录。
+- `maintenance_commands` 提供 `kb maintain plan|run|status (--repo ID|--all)`；
+  plan/status 不调用模型，run 必须带稳定 `--request-id` 且只入队，可额外选择
+  `--calibrate` 或 `--drill`。`kb correction resolve --id ID --decision confirm|dismiss
+  --evidence JSON|@FILE` 用实际 gh 登录并检查 `KB_MAINTENANCE_OWNERS`，签名请求由持租约
+  scheduler 重新验证。confirm 必须明确 expected 及可重读原始行段；只由 scheduler 签名人工案例。
+  correction_oracle 只保存负责人显式提供的预期，dismiss 不造案例，所有人工请求不计有效夜次。
+- 默认关闭 `KB_MAINTENANCE_ENABLED`。显式成本、模型、提示词和 consumer roster 组成策略；
+  校准变化或策略变化不能复用旧就绪声明。有效夜次按冻结公开仓库分母、语义审计、真实消费者
+  撤回演练等证据判定，安静/no-op 夜次不自动构成新鲜度。
+- operational containment 签名代际独立于 active snapshot 和 paired release；现有 owner
+  SSH publisher 安装签名策略并收集真实 consumer ACK。60 秒心跳、10 分钟新鲜度、实际 release
+  字节摘要及协议版本均须匹配；高水位/签发登记/协议 latch 放在 shared state，rollback 不清除。
+  installer 与最终 review publication 共锁；Direct 区分 retrieved/injected，Strict 保留 provider
+  receipt。失效上下文 held 并保留原 verdict 供复核，不剥离已消费断言，不发布 GitHub review。
+
+操作、证据格式及默认关闭的部署步骤见 [nightly maintenance](../knowledge-maintenance.md)。
+测试：`test_kb_maintenance_store.py`、`test_kb_maintenance_flow.py`、`test_kb_maintenance_commands.py`。
+
 ## 2026-09-28 intake 与质量门
 - `models`：生成与评审模型按 (provider, model, effort) 钉死（默认 `claude-code:claude-opus-5-5`
   与 `codex:gpt-6-sol:medium`，评审必须与主/备用生成器不同家族；`KB_JUDGE_FAMILY_WAIVER=1`
@@ -75,6 +106,9 @@ stdlib + PyYAML + `cryptography`（`kb` extra）+ `.adapters` + `.knowledge_serv
   T2/T3 按规则页让生成器对照发版 diff 逐条给出 keep/edit/replace/retire；purge；全局熔断强制 human。
 - `scheduler`（`kb serve`）：终身持有租约；每 tick 重签控制记录、处理回执、按仓库
   advance/intake/sweep（仓库间隔离）、main 变化即激活；24 小时内 2 个知识 PR 被人关闭 → 暂停该仓库。
+- `detect_release` 的可选 observation 输出只记录本次真实 release/tag 查询；缺少 release/tag、
+  关闭 observer 或恢复旧 sweep 均保持 `not_observed`，不能用缓存基线推断当天 `no_code_update`。
+  scheduler 分别记录观察状态、实际观察 tag 与基线比较，语义审计覆盖不由该状态替代。
 - CLI：`kb serve [--once]`、`kb activate`、`kb rollback --to SHA`；`kb pause`/`kb resume` 只改代际与暂停状态。
 - 每个变更集记录其待回执的 outbox 项（`pending_item`）：未过期时不重复签发；回执只作用于与之匹配的项和
   对应的前置状态，迟到的重复项回执不改变状态。

doc/architecture/SPEC/knowledge_context.md

@@ -1,6 +1,6 @@
 # knowledge_context.py —— 规范
 
-<!-- verified-against: 2026-10-06 -->
+<!-- verified-against: 2026-10-08 -->
 
 ## 职责与公开契约
 
@@ -43,3 +43,10 @@ MCP 暴露同一 open/read/search/related/expand；Strict 在注册表快照默
 
 `test_knowledge_context.py`、`test_knowledge_retrieval.py` 验证累计预算、并发、恢复、
 留白、跨仓库权限、缓存篡改、实际注入标签以及 SDK/Strict 的固定快照接入。
+
+
+## 2026-10-08 Signed containment
+
+With explicit `knowledge_maintenance` configuration, session/cache identity additionally binds current containment generation and policy digest. Every delivery rechecks this identity and verifies document admissibility before cached content is returned; old contexts require reassessment after containment changes. Disabled configuration preserves the previous session identity.
+
+Every nonempty adaptive delivery also enters the provider-private durable session issuance journal before it is returned, including cached reads and search/related continuations after a budget expansion. Earlier plan receipts resolve that complete journal during final availability checks; a newly held follow-up page therefore blocks completion even after SDK restart. Budget expansion alone delivers no source content and creates no injected-usage claim.

doc/architecture/SPEC/knowledge_docs.md

@@ -1,6 +1,6 @@
 # knowledge_docs.py —— 规范
 
-<!-- verified-against: 2026-10-06 -->
+<!-- verified-against: 2026-10-08 -->
 
 `LOC ~280 · 供 Direct 与 Agent 共用的只读知识检索 · refactor-status: ok`
 
@@ -69,3 +69,8 @@ stdlib 与 `knowledge_service.lifecycle` 的页面/完整深读正文解析；
 仍由 `KnowledgeContextService` 累计预算裁剪。这些是字符限制，不是模型实际 token 用量。
 纯解析缓存按原文内容寻址，所有命中仍先验证固定快照的真实字节；不缓存路径读取以绕过
 完整性检查。此读取器没有累计补读账本；累计预算由显式会话服务负责。
+
+
+## 2026-10-08 Signed containment
+
+Every read checks opt-in containment even when no manifest verifier was supplied. Explicit reads of held pages refuse; search and related retrieval omit held pages before reading their text. Corrupt snapshots and stale, forged or replayed policy fail the request closed rather than appearing as an empty valid search.

doc/architecture/SPEC/knowledge_service.md

@@ -1,6 +1,6 @@
 # knowledge_service/ — provider curation components
 
-<!-- verified-against: 2026-10-07 -->
+<!-- verified-against: 2026-10-08 -->
 
 Pinned source identities and depth markers accept full SHA-1 or SHA-256 Git
 commits. Evidence bodies, stored hashes and native approval semantics remain
@@ -55,6 +55,16 @@ reconciliation receipt) never verifies for another. Plans use
 automatic gate verdict or publisher action. It
 needs only `cryptography`.
 
+`containment` implements the opt-in consumer protocol independently of knowledge
+snapshots and physical releases: signed fresh policies, durable monotonic
+high-water state, private provider issuance and usage receipts, availability
+checks and a shared installation/publication fence. Invalid signatures, stale
+policy, replay or unavailable issued knowledge fail closed. It does not create
+authority decisions or model judgements. Signing also separates containment,
+authenticated transport, maintenance resolution, human case, calibration, drill
+and short-lived merge authorization purposes. See
+[containment.md](knowledge_service/containment.md).
+
 ## 2026-09-28 verdict
 `verdict` defines the signed gate verdict (`kb-gate-verdict/1`): identity
 (repository, PR, exact head, nonce, 72-hour issue window), the complete patch

doc/architecture/SPEC/knowledge_service/containment.md

@@ -0,0 +1,15 @@
+# knowledge_service/containment.py — contract
+
+<!-- verified-against: 2026-10-08 -->
+
+External opt-in containment protocol for immutable knowledge and issued review contexts. The module is inert by default and imports crypto only after enforcement is enabled.
+
+A policy is an Ed25519 `kb-containment-policy` envelope with exact fields `schema_version`, `generation`, `issued_at`, `expires_at`, `consumers`, `decisions`. Its validity window is at most ten minutes. Each enrolled consumer has an owner-controlled durable highwater outside releases/snapshots; lower generations, conflicting generation content, older refreshes and forgotten original denied hashes refuse. Corrected bytes are explicitly approved while original bad hashes remain denied through rollback. Expiry never releases a hold.
+
+Provider context issuance is held in a private local registry binding exact context digest, physical pinned knowledge root, snapshot/tree and document hashes. Public usage recording requires this issuance; availability rechecks bytes and current policy. Public receipts contain only portable unit/page identities and hashes, not private physical roots. Bounded usage export returns metadata for authenticated owner transport; successful delivery acknowledges queue entries without deleting original usage receipts.
+
+Direct receipts additionally bind an internally issued delivery session. A private durable flat journal retains every actual delivery receipt, including adaptive follow-ups, legacy document pages and injected variants. Availability resolves the complete current journal rather than only the initial packet's pages; restart does not discard dependencies. The journal is capped at 4,096 unique receipts, every member must match the same consumer/session/immutable view and its private issuance digest, and missing or malformed journals fail closed. No caller-controlled recursive dependency graph is traversed. Injection attribution decodes actual JSON-fenced model fragments; metadata-only expansion records no injected content.
+
+The installer verifies pinned public keys and strict signature purpose, waits for the shared publication lock, validates highwater and atomically publishes the policy, then records an ACK. The ACK binds consumer/release/generation/digest/freshness plus observed current knowledge snapshot/tree and per-corrected-unit actual byte readiness. The publication guard covers the caller's final availability check and external write. Install and publication use the same lock; neither caller-supplied booleans nor missing usage provenance permit publication.
+
+Focused offline tests: `test_kb_containment.py`, `test_kb_adaptive_containment.py`, SDK, knowledge-view/routing and context regression suites. The signed offline acceptance drill is implemented separately in `kb_service/containment_drill.py`; it proves isolated SDK protocol behavior and never replaces production consumer ACKs.

doc/architecture/SPEC/knowledge_view.md

@@ -1,6 +1,6 @@
 # knowledge_view.py —— 规范
 
-<!-- verified-against: 2026-09-29 -->
+<!-- verified-against: 2026-10-08 -->
 
 `LOC ~170 · 每请求的知识树视图（打包知识或激活快照） · refactor-status: stable`
 
@@ -40,3 +40,8 @@ stdlib + `.sdk._resources`。叶子模块。
 知识树在顶层 `knowledge/_format.yaml` 声明其格式（`format_version`；当前为 2：规则生命周期尾注、类型化操作、
 `_routes.yaml`、`_tombstones.yaml`）。`knowledge_format(root)` 读取它，`build_manifest` 把它记入 `MANIFEST.json` 的
 `knowledge_format`。该文件位于自动合并白名单之外，改动它需要人工。
+
+
+## 2026-10-08 Signed containment
+
+Opt-in containment checks follow manifest integrity on every serving `path`/`read_text`. The signed policy lives outside snapshots; freshness and durable generation highwater survive active-snapshot rollback. `_integrity_path` only validates navigation metadata; selected content still uses the serving path. Held evidence raises `HeldKnowledgeError`; a stale or invalid policy raises `ContainmentError`.

doc/architecture/SPEC/sdk.md

@@ -1,6 +1,6 @@
 # sdk/ —— 规范
 
-<!-- verified-against: 2026-10-06 -->
+<!-- verified-against: 2026-10-08 -->
 
 
 `Python SDK v1 · 跨仓库唯一 typed 边界 · refactor-status: ok`
@@ -156,3 +156,10 @@ Direct 1.1 / Strict 1.3 accept typed `CarriedFinding` inputs (unique IDs, source
 ## 2026-09-29 未测公开函数候选
 `DirectReviewRequest` 新增可选 `diff`（冻结 head 的 unified diff），`DirectReviewPlan` 新增
 `untested_public_api`（`direct_routing` 的同名块，默认空字典）。两者都是可选增量字段，旧调用方不受影响（#164）。
+
+
+## 2026-10-08 Signed containment
+
+Opt-in protocol 1 exports `knowledge_maintenance_status`, `knowledge_usage_record`, `knowledge_availability_check`, `knowledge_publication_guard` and `knowledge_policy_install`. DirectClient and StrictRuntimeConfig accept explicit maintenance configuration. Usage accepts an exact privately issued provider context; arbitrary caller hashes cannot mint provenance. Retrieved and actually injected units are separate from conservative Strict snapshot scope. Current generation is checked at Direct validation and Strict polling; held Strict results retain the original result with top-level state `held`. Hosts hold the publication guard around final admissibility and the external write; the installer drains that same lock before signed policy publication and ACK. ACK includes actual current knowledge snapshot/tree and corrected-content observations, separately from protocol readiness. No service private key crosses this SDK boundary.
+
+Direct plan receipts bind a provider-private durable delivery session. Adaptive follow-up read/search/related deliveries and continuations after expansion join the same session before returning; legacy `read_document(review_context_id=...)` pages join their original review's session as well. `validate` and the generic final `knowledge_availability_check` resolve all delivered dependencies, including when the host reuses its initial receipt after another SDK instance resumes an adaptive session. Caller-supplied session IDs cannot create that binding. Enforced document reads require the existing provider-issued `review_context_id` and include it in `DocumentPage.to_dict()` so identical pages in concurrent reviews retain separate provenance. The optional field is omitted when empty; disabled standalone reads retain compatibility. SDK retrieval does not claim model injection; the host records actual injection separately.