Skip to content

Commit 1e3c3b7

Browse files
committed
feat(foundation): add heavy sqlite runtime proof
1 parent 0e379b1 commit 1e3c3b7

19 files changed

Lines changed: 338 additions & 70 deletions

docs/diataxis/en/explanation/development-progress-dashboard.md

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ It tracks what is already implemented, where the hard gaps remain, and how to ve
1919
- What is real at HEAD:
2020
- graph/store operations semantics exist in `src/learning/store.ts`, including file-backed ops, embedded SQLite graphdb persistence/query paths, and HTTP adapter paths with fallback diagnostics,
2121
- the embedded sqlite baseline now also has restart-durability proof: shutdown closes the store cleanly, the adapter can reopen safely, and server integration covers ingest -> shutdown -> fresh module reload -> diagnostics/query/readiness continuity,
22-
- a new host-level verifier now exercises that same embedded sqlite baseline through both `dist` runtime and packaged sidecar flows on the current Windows host: ingest -> store diagnostics/foundation readiness -> restart -> query continuity (`scripts/verify-foundation-sqlite-runtime.js`),
22+
- a host-level verifier now exercises that same embedded sqlite baseline through both `dist` runtime and packaged sidecar flows on the current Windows host: ingest -> store diagnostics/foundation readiness -> restart -> query continuity (`scripts/verify-foundation-sqlite-runtime.js`),
23+
- a heavier host-level verifier now extends that proof to a 180-document workload on the same two runtime paths, including snapshot metadata counts plus restart and multi-point query continuity (`scripts/verify-foundation-sqlite-runtime.js --heavy`),
2324
- ANN-style prefilter, representation telemetry, circuit health, remote index sync, and live `external_http` connector proof now exist in `src/learning/queryBackend.ts` and `src/learning/vectorAccelerationAdapter.ts`,
2425
- runtime capability/runbook governance now includes explicit ANN remote index-sync health (`query_vector_acceleration_index_sync_health`) in addition to prefilter, health, traceability, and circuit checks,
2526
- runtime capability governance now also includes explicit gate `query_vector_acceleration_calibration_readiness`, which formalizes whether the ANN path is even ready for release-grade threshold tuning,
@@ -31,12 +32,12 @@ It tracks what is already implemented, where the hard gaps remain, and how to ve
3132
- Phase-2 runtime diagnostics are now materially implemented in `src/learning/KnowledgeLearningPlatform.ts` for query-backend comparison/history/trend, knowledge staleness diagnostics/rebuild planning, learning-quality history/trend, session-plan quality evaluation/history/trend/runtime-threshold diagnostics, query-backend config, and query-backend diagnostics,
3233
- Phase-3 tutor/memory diagnostics remain real and now include an active default runtime tutor adapter path in `src/server.ts`, so normal server execution can emit adapter telemetry instead of staying catalog-only.
3334
- What is not closed yet:
34-
- Phase-1 A8 has advanced beyond a file-only default: `src/server.ts` now defaults to `graphdb/sqlite` with explicit file fallback, restart durability is already proved, and host-level dist/runtime + packaged sidecar proof is now in place, but heavier-workload hardening is still open before calling the local graph backend production-closed,
35+
- Phase-1 A8 has advanced beyond a file-only default: `src/server.ts` now defaults to `graphdb/sqlite` with explicit file fallback, restart durability is already proved, host-level dist/runtime + packaged sidecar proof is in place, and a 180-document host-level workload smoke is now in place, but broader workload-envelope / soak / performance hardening is still open before calling the local graph backend production-closed,
3536
- Phase-1 A9 is now operational rather than scaffold-only, but recall/latency calibration and larger-workload validation are still open before calling the ANN layer production-closed,
3637
- Phase-2 quality/session/query observability is now real, but it is not yet release-closed because these gates still require release-grade calibration on top of the current graph/ANN operational baseline; the new ANN calibration-readiness gate only formalizes prerequisites, not closure,
3738
- default tutor routing is no longer catalog-only, but the runtime is still effectively `local`-first and retains explicit rule-engine fallback rather than a production-proven multi-provider routing policy.
3839
- Active execution focus therefore shifts to truth-first foundation recovery:
39-
- finish the remaining heavier-workload closure for the embedded graph backend baseline while keeping the new dist/runtime + packaged sidecar proof green,
40+
- finish the remaining broader-workload closure for the embedded graph backend baseline while keeping the new dist/runtime + packaged sidecar proof and 180-document workload smoke green,
4041
- finish the remaining workload/threshold closure for the now-live ANN connector baseline,
4142
- move the newly surfaced ANN runbook visibility from operator-readable summaries to workload-calibrated release gates,
4243
- keep the new diagnostic surfaces honest against the same runtime truth,
@@ -134,9 +135,9 @@ Current branch status for this slice:
134135
## Latest Validation Snapshot (2026-05-14)
135136

136137
- Reconfirmed on the current Windows host in this turn: `node node_modules/jest/bin/jest.js src/learning/runtimeCapability.test.ts src/knowledge.api.contract.test.ts --runInBand --no-cache`, `node node_modules/jest/bin/jest.js src/agent_workspace.frontend.test.ts --runInBand --no-cache`, `npm run test:agent-workspace:contracts`, `npm run build:with-vite`, `npm run docs:diataxis:check`, `npm run docs:site:build`, `NOTE_CONNECTION_AGENT_WORKSPACE_BROWSER_STRICT=1 NOTE_CONNECTION_AGENT_WORKSPACE_BROWSER_UI_STRICT=1 NOTE_CONNECTION_AGENT_WORKSPACE_BROWSER_UI_DYNAMIC_STRICT=1 node scripts/verify-agent-workspace-browser.js`.
137-
- Reconfirmed on the current Windows host in this turn: `npm run build:sidecar`, `npm run verify:foundation:sqlite-runtime`.
138+
- Reconfirmed on the current Windows host in this turn: `npm run build:sidecar`, `npm run verify:foundation:sqlite-runtime`, `npm run verify:foundation:sqlite-runtime:heavy`.
138139
- The strict browser proof now explicitly verifies the bilingual runtime-runbook verify/checks ANN governance labels that were added in this slice: sync-health plus circuit, traceability, and prefilter summaries, along with the threshold/signal drilldowns and calibration-readiness cues that support budget-tuning work.
139-
- The embedded sqlite graph baseline now also has a repeatable host-level runtime proof outside Jest integration scope: both `dist` runtime and packaged sidecar flows preserve ingest -> diagnostics/readiness -> restart -> query continuity on the same runtime data directory.
140+
- The embedded sqlite graph baseline now also has repeatable host-level runtime proofs outside Jest integration scope: the lighter verifier keeps `dist` runtime and packaged sidecar ingest -> diagnostics/readiness -> restart -> query continuity green, and the heavier verifier proves the same two runtime paths across 180 ingested documents with snapshot metadata counts and multi-point restart queries.
140141
- Tauri strict evidence is implementation-closed but still host-dependent:
141142
- the current Windows host proves non-strict tauri/runtime behavior and load-flow parity,
142143
- Linux strict evidence commands (`verify:agent-workspace:tauri:rust:strict`, `verify:agent-workspace:tauri:window-evidence:strict`, strict evidence index/manifest) still require provisioned `webkit2gtk-4.1`, `javascriptcoregtk-4.1`, and `libsoup-3.0`.

docs/diataxis/en/explanation/knowledge-mastery-evolution-roadmap.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,17 +54,17 @@ This requires:
5454

5555
- The branch now contains real Phase-3 tutor/memory slices, but current HEAD should not be described as "Phase-1 closed".
5656
- The accurate state is:
57-
- Phase-1 A8 has advanced into an embedded local-backend baseline: graph/store ops semantics, embedded SQLite graphdb persistence/query paths, and HTTP adapter paths exist, the default runtime now targets `graphdb/sqlite` with explicit file fallback, and restart durability is integration-proved; packaged/runtime proof and heavier workload hardening are still open.
57+
- Phase-1 A8 has advanced into an embedded local-backend baseline: graph/store ops semantics, embedded SQLite graphdb persistence/query paths, and HTTP adapter paths exist, the default runtime now targets `graphdb/sqlite` with explicit file fallback, restart durability is integration-proved, host-level dist/runtime + packaged sidecar proof is in place, and a 180-document host-level heavier-workload smoke is in place; broader workload-envelope / soak / performance hardening are still open.
5858
- Phase-1 A9 has advanced into an ANN connector operational baseline: ANN-style prefilter, representation telemetry, remote index sync, and live `external_http` query proof now exist, but recall/latency calibration and larger-workload validation are still open.
5959
- Phase-2 now has an operational diagnostics baseline: `learning quality`, `session plan quality`, query comparison, staleness, query-backend config, and query-backend diagnostics are live in `KnowledgeLearningPlatform.ts`, but they are not yet release-closed because they still require release-grade calibration on top of the current graph/ANN operational baseline.
6060
- Phase-3 is now operational-baseline rather than catalog-only: tutor telemetry, tutor trace/provider trends, conversation memory, memory-policy diagnostics, and default runtime tutor-adapter injection are real, but production-proven multi-provider routing policy is still open.
61-
- Active rollout focus therefore changes from "assume closure and move on" to "finish the remaining A8 packaged/runtime closure plus A9 workload calibration, then move next into honest Phase-2 gate promotion."
61+
- Active rollout focus therefore changes from "assume closure and move on" to "keep the new A8 packaged/runtime and 180-document workload proofs green, finish the remaining broader A8 workload closure plus A9 workload calibration, then move next into honest Phase-2 gate promotion."
6262

6363
## Primary Structural Gaps Still Open
6464

6565
1. Real graph backend closure:
6666
- keep the new embedded `graphdb/sqlite` default alive across packaged/runtime paths,
67-
- treat restart durability as already proved and extend verification into ops-preferred query semantics, fallback consistency, packaged/runtime behavior, and heavier-workload durability against that local graph engine.
67+
- treat restart durability, host-level packaged/runtime proof, and the new 180-document workload smoke as already proved, then extend verification into ops-preferred query semantics, fallback consistency, and broader heavier-workload durability against that local graph engine.
6868
2. Real ANN connector closure:
6969
- keep the new live `external_http` connector path healthy under real sync/query traffic,
7070
- benchmark recall/latency thresholds before calling the vector layer production-ready.

docs/diataxis/zh/explanation/development-progress-dashboard.md

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@
99
- 当前已经真实落地的部分:
1010
- `src/learning/store.ts` 已具备 file-backed ops、embedded SQLite graphdb persistence/query 路径,以及 HTTP adapter 语义路径,
1111
- embedded sqlite 基线现在还具备了重启耐久性证明:shutdown 会干净关闭 store,adapter 可安全重开,server integration 已覆盖 ingest -> shutdown -> fresh module reload -> diagnostics/query/readiness 连续性,
12-
- 现在还有一条新的主机级验证器,会在当前 Windows 宿主上分别走 `dist` runtime 与 packaged sidecar 两条路径,证明同一条 embedded sqlite 基线可以完成 ingest -> store diagnostics/foundation readiness -> restart -> query 连续性(`scripts/verify-foundation-sqlite-runtime.js`),
12+
- 现在已有一条主机级验证器,会在当前 Windows 宿主上分别走 `dist` runtime 与 packaged sidecar 两条路径,证明同一条 embedded sqlite 基线可以完成 ingest -> store diagnostics/foundation readiness -> restart -> query 连续性(`scripts/verify-foundation-sqlite-runtime.js`),
13+
- 现在还有一条更重的主机级验证器,把同样的证明扩展到 `180` 文档 workload:在同样两条 runtime 路径上验证 snapshot metadata 计数、restart 连续性与多点 query 连续性(`scripts/verify-foundation-sqlite-runtime.js --heavy`),
1314
- `src/learning/queryBackend.ts` / `src/learning/vectorAccelerationAdapter.ts` 现已具备 ANN 风格 prefilter、representation telemetry、circuit health、远端索引同步,以及 live `external_http` connector 证明,
1415
- runtime capability / runbook 治理也已新增显式的 ANN 远端索引同步健康度检查(`query_vector_acceleration_index_sync_health`),与 prefilter、health、traceability、circuit 并列,
1516
- runtime capability 治理现在也新增了显式门禁 `query_vector_acceleration_calibration_readiness`,用来正式回答当前 ANN 路径是否已经具备进入发布级阈值校准的前提条件,
@@ -21,12 +22,12 @@
2122
- `src/learning/KnowledgeLearningPlatform.ts` 中的 Phase-2 运行时诊断面已接通真实实现,包括 query-backend comparison/history/trend、knowledge staleness diagnostics/rebuild planning、learning-quality history/trend、session-plan quality evaluate/history/trend/runtime-threshold diagnostics、query-backend config、query-backend diagnostics,
2223
- Phase-3 的导师/记忆诊断仍为真实实现,且 `src/server.ts` 现已注入默认激活态 tutor adapter,正常 server 路径可直接产出 adapter telemetry。
2324
- 当前仍未闭环的部分:
24-
- Phase-1 A8 已经超出 file-only 默认态:`src/server.ts` 现在默认走 `graphdb/sqlite` 并保留显式 file fallback,重启耐久性已证明,而且主机级 dist/runtime + packaged sidecar 证明也已具备;但在宣布本地图后端达到生产闭环之前,更重工作负载级加固仍未完成
25+
- Phase-1 A8 已经超出 file-only 默认态:`src/server.ts` 现在默认走 `graphdb/sqlite` 并保留显式 file fallback,重启耐久性已证明,主机级 dist/runtime + packaged sidecar 证明也已具备,而且 `180` 文档级主机端 workload smoke 也已具备;但在宣布本地图后端达到生产闭环之前,更广工作负载包络、soak 与性能级加固仍未完成
2526
- Phase-1 A9 现已进入 operational baseline,而不再只是 scaffolding:但在宣布 ANN 层达到生产闭环前,仍需补齐 recall/latency 校准与更大工作负载验证;
2627
- Phase-2 的 quality/session/query 可观测性已不再是空占位,但它们仍需要建立在当前 graph/ANN operational baseline 之上的发布级校准,因此还不能宣称发布级闭环;新的 ANN calibration-readiness gate 只是把前提条件正式化,并不等于校准完成;
2728
- 默认 tutor routing 已不再只是 catalog-only,但当前 runtime 仍是 `local`-first,并保留显式 rule-engine fallback,而不是已验证的生产级多 provider 路由策略。
2829
- 因此当前活跃重心不是“默认认为 Phase-1 已完成然后推进上层”,而是:
29-
1. 在保持新的 dist/runtime + packaged sidecar 证明持续为绿的前提下,先补完 embedded graph backend 基线剩余的更重工作负载闭环
30+
1. 在保持新的 dist/runtime + packaged sidecar 证明以及 `180` 文档 workload smoke 持续为绿的前提下,先补完 embedded graph backend 基线剩余的更广工作负载闭环
3031
2. 补完当前 live ANN connector baseline 的工作负载与阈值闭环,
3132
3. 把当前已前推到 runbook 卡片中的 ANN 指标可见性,继续推进为带工作负载校准的发布级门禁,
3233
4. 让这批新诊断面始终与同一份运行时真相保持一致,
@@ -146,9 +147,9 @@
146147
## 最新验证快照(2026-05-14)
147148

148149
- 本轮已在当前 Windows 宿主重新确认通过:`node node_modules/jest/bin/jest.js src/learning/runtimeCapability.test.ts src/knowledge.api.contract.test.ts --runInBand --no-cache``node node_modules/jest/bin/jest.js src/agent_workspace.frontend.test.ts --runInBand --no-cache``npm run test:agent-workspace:contracts``npm run build:with-vite``npm run docs:diataxis:check``npm run docs:site:build``NOTE_CONNECTION_AGENT_WORKSPACE_BROWSER_STRICT=1 NOTE_CONNECTION_AGENT_WORKSPACE_BROWSER_UI_STRICT=1 NOTE_CONNECTION_AGENT_WORKSPACE_BROWSER_UI_DYNAMIC_STRICT=1 node scripts/verify-agent-workspace-browser.js`
149-
- 本轮已在当前 Windows 宿主重新确认通过:`npm run build:sidecar``npm run verify:foundation:sqlite-runtime`
150+
- 本轮已在当前 Windows 宿主重新确认通过:`npm run build:sidecar``npm run verify:foundation:sqlite-runtime``npm run verify:foundation:sqlite-runtime:heavy`
150151
- 严格浏览器证据现在已显式校验本轮新增的双语 runtime-runbook verify/checks ANN 治理标签:不仅验证 sync-health,也验证熔断、可追踪性、预筛选摘要,以及支撑校准工作的阈值/信号钻取和校准就绪态。
151-
- embedded sqlite 图基线现在也具备了 Jest 集成测试之外、可重复执行的主机级运行时证明:`dist` runtime 与 packaged sidecar 两条路径都会在同一个 runtime data 目录上保持 ingest -> diagnostics/readiness -> restart -> query 连续性。
152+
- embedded sqlite 图基线现在也具备了 Jest 集成测试之外、可重复执行的主机级运行时证明:轻载验证会让 `dist` runtime 与 packaged sidecar 两条路径持续保持 ingest -> diagnostics/readiness -> restart -> query 连续性,而更重验证则会在同样两条路径上证明 `180` 文档 workload 的 snapshot metadata / restart / 多点 query 连续性。
152153
- Tauri strict 证据链在实现层面已经闭环,但仍受宿主依赖约束:
153154
- 当前 Windows 宿主已经证明 non-strict tauri/runtime 行为与 load-flow parity,
154155
- Linux strict 证据命令(`verify:agent-workspace:tauri:rust:strict``verify:agent-workspace:tauri:window-evidence:strict` 及 strict evidence index/manifest)仍要求宿主预装 `webkit2gtk-4.1``javascriptcoregtk-4.1``libsoup-3.0`

0 commit comments

Comments
 (0)