Skip to content

Commit 08f5ddc

Browse files
tzhouamtzhouam
committed
Add durable nightly knowledge audit and containment lifecycle
1 parent 1a653bf commit 08f5ddc

47 files changed

Lines changed: 6007 additions & 46 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

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

‎doc/architecture/SPEC/app/run_service.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# app/run_service.py —— 规范
22

3-
<!-- verified-against: 2026-10-06 -->
3+
<!-- verified-against: 2026-10-08 -->
44

55
`RunService` is the durable application boundary shared by the embedded
66
Strict SDK and MCP transport. It owns policy-checked reserve/start, a queue
@@ -76,3 +76,8 @@ services and the CLI as well. Not covered: two agent sessions *inside one run*
7676
(ensemble lenses, per-comment verification, bounded by
7777
`strict_backend_concurrency`) still share their run's own tree; that predates
7878
this change and is independent of the worker count.
79+
80+
81+
## 2026-10-08 Signed containment
82+
83+
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‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# direct_routing.py —— 规范
22

3-
<!-- verified-against: 2026-10-06 -->
3+
<!-- verified-against: 2026-10-08 -->
44

55
`LOC ~880 · Direct 模式完整策略包与仓库中立的知识路由 · refactor-status: stable`
66

@@ -87,3 +87,10 @@ SDK 完成校验钉住计划时快照、模块源码不含仓库名）；`test_c
8787
## 重构备注
8888
原 `_DIRECT_OWNER_ROUTES`/`_REPO_ALIASES` 已外置（`known-debt` 清零），
8989
`test_v2_p0.py` 与 `test_repo_vocabulary.py` 中本模块的泄漏上限随之移除。
90+
91+
92+
## 2026-10-08 Signed containment
93+
94+
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.
95+
96+
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. The public `direct_completion_result` requires that receipt and rechecks the 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/kb_service.md‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# kb_service/ —— 规范
22

3-
<!-- verified-against: 2026-10-07 -->
3+
<!-- verified-against: 2026-10-08 -->
44

55
`知识服务核心：仓库配置、账本、outbox、CLI · refactor-status: new`
66

@@ -39,6 +39,37 @@ stdlib + PyYAML + `cryptography`（`kb` extra）+ `.adapters` + `.knowledge_serv
3939
## 测试
4040
`test_kb_service_core.py`。
4141

42+
## 2026-10-08 持久夜间维护与撤回
43+
44+
- `maintenance` 在现有 scheduler 租约内运行 Shanghai 01:00 的可恢复周期；
45+
`maintenance_units` 对不变的规则和说明文本也重新质疑，快照、策略与公平分母在周期开始时固定。
46+
`maintenance_audit` 读取原始版本的源码行段、校验 pin/span/hash，缺失证据保持 unknown，
47+
execution_error 与 contradicted 分开。不能以旧 verdict 或最新 HEAD 代替原始证据。
48+
- `maintenance_store` 以附加表保存 runs/items/findings/usage/budget/requests/resolutions，
49+
不改写原 intake、verdict、pin、激活和 reviewed 回执。所有执行写入受现有租约栅栏保护，
50+
CLI 只可并发入队请求；每次模型调用先记不可重复派发的预算预留，恢复不能重发已预留调用。
51+
每日 $50 上限含 $10 公平保留；未知价格或 API transport 不能证明硬上界时拒绝调用。
52+
- `maintenance_correction` 复用 owner-scoped retire/replace、保护字段与普通质量门；
53+
提案不等于已修正，原始 verdict、退役与应用历史均保留。`maintenance_calibration`
54+
只消费具明确人工标签和原始证据的签名案例；校准调用也纳入预算和模型记录。
55+
- `maintenance_commands` 提供 `kb maintain plan|run|status (--repo ID|--all)`；
56+
plan/status 不调用模型，run 必须带稳定 `--request-id` 且只入队，可额外选择
57+
`--calibrate` 或 `--drill`。`kb correction resolve --id ID --decision confirm|dismiss
58+
--evidence JSON|@FILE` 用实际 gh 登录并检查 `KB_MAINTENANCE_OWNERS`，签名请求由持租约
59+
scheduler 重新验证。confirm 必须明确 expected 及可重读原始行段；只由 scheduler 签名人工案例。
60+
correction_oracle 只保存负责人显式提供的预期，dismiss 不造案例，所有人工请求不计有效夜次。
61+
- 默认关闭 `KB_MAINTENANCE_ENABLED`。显式成本、模型、提示词和 consumer roster 组成策略；
62+
校准变化或策略变化不能复用旧就绪声明。有效夜次按冻结公开仓库分母、语义审计、真实消费者
63+
撤回演练等证据判定，安静/no-op 夜次不自动构成新鲜度。
64+
- operational containment 签名代际独立于 active snapshot 和 paired release；现有 owner
65+
SSH publisher 安装签名策略并收集真实 consumer ACK。60 秒心跳、10 分钟新鲜度、实际 release
66+
字节摘要及协议版本均须匹配；高水位/签发登记/协议 latch 放在 shared state，rollback 不清除。
67+
installer 与最终 review publication 共锁；Direct 区分 retrieved/injected，Strict 保留 provider
68+
receipt。失效上下文 held 并保留原 verdict 供复核，不剥离已消费断言，不发布 GitHub review。
69+
70+
操作、证据格式及默认关闭的部署步骤见 [nightly maintenance](../knowledge-maintenance.md)。
71+
测试：`test_kb_maintenance_store.py`、`test_kb_maintenance_flow.py`、`test_kb_maintenance_commands.py`。
72+
4273
## 2026-09-28 intake 与质量门
4374
- `models`：生成与评审模型按 (provider, model, effort) 钉死（默认 `claude-code:claude-opus-5-5`
4475
与 `codex:gpt-6-sol:medium`，评审必须与主/备用生成器不同家族；`KB_JUDGE_FAMILY_WAIVER=1`

‎doc/architecture/SPEC/knowledge_context.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# knowledge_context.py —— 规范
22

3-
<!-- verified-against: 2026-10-06 -->
3+
<!-- verified-against: 2026-10-08 -->
44

55
## 职责与公开契约
66

@@ -43,3 +43,8 @@ MCP 暴露同一 open/read/search/related/expand；Strict 在注册表快照默
4343

4444
`test_knowledge_context.py`、`test_knowledge_retrieval.py` 验证累计预算、并发、恢复、
4545
留白、跨仓库权限、缓存篡改、实际注入标签以及 SDK/Strict 的固定快照接入。
46+
47+
48+
## 2026-10-08 Signed containment
49+
50+
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.

‎doc/architecture/SPEC/knowledge_docs.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# knowledge_docs.py —— 规范
22

3-
<!-- verified-against: 2026-10-06 -->
3+
<!-- verified-against: 2026-10-08 -->
44

55
`LOC ~280 · 供 Direct 与 Agent 共用的只读知识检索 · refactor-status: ok`
66

@@ -69,3 +69,8 @@ stdlib 与 `knowledge_service.lifecycle` 的页面/完整深读正文解析；
6969
仍由 `KnowledgeContextService` 累计预算裁剪。这些是字符限制，不是模型实际 token 用量。
7070
纯解析缓存按原文内容寻址，所有命中仍先验证固定快照的真实字节；不缓存路径读取以绕过
7171
完整性检查。此读取器没有累计补读账本；累计预算由显式会话服务负责。
72+
73+
74+
## 2026-10-08 Signed containment
75+
76+
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/containment.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# knowledge_service/containment.py — contract
2+
3+
<!-- verified-against: 2026-10-08 -->
4+
5+
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.
6+
7+
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.
8+
9+
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.
10+
11+
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.
12+
13+
Focused offline tests: `test_kb_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‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# knowledge_view.py —— 规范
22

3-
<!-- verified-against: 2026-09-29 -->
3+
<!-- verified-against: 2026-10-08 -->
44

55
`LOC ~170 · 每请求的知识树视图（打包知识或激活快照） · refactor-status: stable`
66

@@ -40,3 +40,8 @@ stdlib + `.sdk._resources`。叶子模块。
4040
知识树在顶层 `knowledge/_format.yaml` 声明其格式（`format_version`；当前为 2：规则生命周期尾注、类型化操作、
4141
`_routes.yaml`、`_tombstones.yaml`）。`knowledge_format(root)` 读取它，`build_manifest` 把它记入 `MANIFEST.json` 的
4242
`knowledge_format`。该文件位于自动合并白名单之外，改动它需要人工。
43+
44+
45+
## 2026-10-08 Signed containment
46+
47+
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‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# sdk/ —— 规范
22

3-
<!-- verified-against: 2026-10-06 -->
3+
<!-- verified-against: 2026-10-08 -->
44

55

66
`Python SDK v1 · 跨仓库唯一 typed 边界 · refactor-status: ok`
@@ -156,3 +156,8 @@ Direct 1.1 / Strict 1.3 accept typed `CarriedFinding` inputs (unique IDs, source
156156
## 2026-09-29 未测公开函数候选
157157
`DirectReviewRequest` 新增可选 `diff`（冻结 head 的 unified diff），`DirectReviewPlan` 新增
158158
`untested_public_api`（`direct_routing` 的同名块，默认空字典）。两者都是可选增量字段，旧调用方不受影响（#164）。
159+
160+
161+
## 2026-10-08 Signed containment
162+
163+
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.

‎doc/architecture/SPEC/thin_mcp_server.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# thin_mcp_server.py —— 规范
22

3-
<!-- verified-against: 2026-10-06 -->
3+
<!-- verified-against: 2026-10-08 -->
44

55
`LOC ~490 · 默认 MCP：Direct 门面 + Strict 入口 · refactor-status: ok`
66

@@ -47,6 +47,11 @@
4747
`subtraction_signal` 的自洽性（`none` 不得附带证据；`triggered` 需要减法项或最小性
4848
证明）、以及证明本次评审读的是固定提交的 `evidence_head_sha`。
4949
**它不能也没有**去验证被引用的证据是否真实 —— 声称它能，比不声称更糟。
50+
启用 containment 后，legacy 和 adaptive Direct 计划另带实际 provider 签发登记的
51+
`knowledge_usage`；完成工具把该收据原样交给公开 `direct_completion_result`，
52+
后者按当前签名策略重查知识可用性。缺失、伪造、过期或被 hold 的来源均返回
53+
`partial_review` / `publish_ready=false`，要求重新取用可用知识并复核。
54+
这项来源与可用性校验独立于评审结论的证据真伪；未启用时旧返回形状不变。
5055
- **路由绝不静默替换。** `title`/`body` 选 owner；`changed_files` 通常只做范围校验。
5156
它们只在**最后手段**下选路（当存活路由无一命中它们推导出的 owner 时），且该情况是
5257
**显式的**：`status="scope_fallback"`、`selected_by="title_body+changed_files"`，

0 commit comments

Comments
 (0)