Skip to content

feat: machine-checked cache-stability theorems via Z3 (route 4, #2149) - #2159

Merged
ranxianglei merged 3 commits into
masterfrom
2026-10-05_solver-theorems-phase1
Oct 5, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-10-05_solver-theorems-phase1

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2149

What this is

The solver lane of #2149, delivered as route 4 (model specification) per the approved plan: the two theorems are proven by Z3 over a byte-level contract of outbound-body assembly, with two mechanisms keeping the contract honest against the code — grounding tests pinning each spec axiom to the real code it abstracts, and the already-merged #2144 billing suite as whole-body code↔spec sync evidence. Routes 1–3 (compiling the real pipeline into a symex front-end) remain available as follow-up hardening if the owner wants them after this lands.

Theorems (9 solver obligations, all < 1s total)

T1 — growth stability. For history H, message m, pipeline f: f(H+[m]) and f(H) share a byte prefix of depth D = envelope head + stable content of the merge-anchor element; everything past D may differ only at the existentially quantified declared carrier positions (MERGE family: nudge/hint text on the last-user turn; TAIL family: optional trailing element — imgNote / chain-checkpoint stamp with its clock impurity modeled x-at-interface / fresh-turn fallback). Two scenarios instantiated: merge anchor flips to the new message (S1) and stays stationary (S2). Proven UNSAT in refutation form (explicit shared-prefix term P, blen(P)=D — a decidable strengthening of the quantified ∃p≥D form, which Z3's string solver returns unknown on).

T2 — ref monotonicity / id-never-reused. Bounded 4-step session over the real allocator rules (kernel/src/refs.ts assignRefs/allocateFreeRef; archive op = the #421 operation): initial live map {a→5, b→2, c→3}, cursor 6, the session high (5) dies, archive prunes, two appends allocate.

  • t2-host: UNSAT — with the persisted monotone cursor (state.nextIndex carried verbatim), no allocation reissues an ever-issued number even though the high died. Machine-checked form of the host duty behind the kernel id-never-reused contract.
  • t2-mutation: SAT — if the cursor is instead recomputed from the pruned map after the archive (highestUsedIndex+1, the documented fix: archive blocks across omp native compaction instead of silently deactivating them (#395) #421 residual), the solver produces exactly the countermodel hui=3 creset=4 n3=4 n4=5: dead high 5 reissued. The residual window is characterized exactly: it opens iff the cursor drops below a dead ever-issued number.

Mutation discipline (acceptance criterion: proofs are not vacuous). Each theorem has a mutation twin injecting a stable-region defect (same-length content rewrite strictly below D in T1; the cursor reset in T2); the solver MUST find each as a counterexample within budget or the proof is treated as broken.

Files

  • proof/spec/*.smt2 (11 files) — the contract + obligations; dialect notes and trust-boundary statement in proof/README.md (read this first).
  • tests/cache-theorem.test.ts — z3 driver (PATH CLI or python module; solver subtests skip individually when absent so the main suite stays green on windows/no-z3 boxes) with per-check timing report, plus [grounding:*] subtests pinning esc algebra → JSON string encoder (200 randomized BMP pairs), mktag → indexToRef (200k round-trips), allocation rules → assignRefs/allocateFreeRef (incl. gap-below-cursor and BLOCKED-free cases).
  • .github/workflows/ci-theorem.yml — dedicated ubuntu-only lane, pinned z3-solver==4.9.1.0, paths-filtered to the assembly surface (src/loop/, wire-body, system-anchor, chain-checkpoint, image-note, server, fake-completion, degenerate-retry, kernel rebuild/refs/render-refs/segment/block-map/ccr, proof/). ci.yml untouched.

Verification

  • All 9 obligations green on BOTH Z3 4.9.1.0 (native, the CI pin) and 4.16.0.0 (WASM local iteration): identical verdicts and models; full test file 13/13 pass, no-solver path 4 pass/1 skip/0 fail, typecheck clean.
  • Pure test/proof surface: zero production code touched, kernel/** untouched (read-only for grounding), no config surface added, no behavior changes.

Add the solver lane of #2149 as a model-specification (route 4) proof:

- proof/spec/*.smt2: byte-level contract of outbound-body assembly
  (String theory over bytes; impure points modeled at the interface as
  free functions/free inputs per owner stance) plus nine obligations:
  T1 growth stability (f(H+[m]) vs f(H) share a prefix of depth D past
  the merge-anchor's stable content; two scenarios: anchor flip and
  stationary) proven UNSAT in refutation form, T2 ref non-reuse under
  the persisted monotone cursor (UNSAT), and mutation twins that MUST
  be found (stable-region byte rewrite below D; post-archive cursor
  reset reissuing the dead high number 5 = the documented #421
  residual, model hui=3 creset=4 n3=4 n4=5).
- tests/cache-theorem.test.ts: z3 driver (PATH CLI or python module;
  solver subtests skip individually when absent so the main suite stays
  green) with per-check timing, plus grounding subtests pinning each
  spec axiom to the real code it abstracts (esc algebra vs JSON string
  encoder, mktag vs indexToRef, allocation rules vs assignRefs/
  allocateFreeRef).
- .github/workflows/ci-theorem.yml: dedicated ubuntu-only theorem lane,
  pinned z3-solver==4.9.1.0, paths-filtered to the assembly surface.

Pure test/proof surface: zero production code touched, kernel/**
untouched, no config surface added, no behavior changes.
@github-actions

github-actions Bot commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-05_solver-theorems-phase1 (582c881)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2206-pr.2159.77be896

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr2159.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Reviewing now — interim status:

Theorem lane is RED on CI (theorem -> failure, all other 18 checks green). Root-caused and reproduced locally:

  • detectSolver() prefers a z3 CLI on PATH over the python module. The pinned z3-solver==4.9.1.0 wheel bundles a native z3 executable, so CI (and any box installing the wheel) takes the CLI path.
  • The CLI branch invokes z3 -smt2 <file> — but the spec files carry assertions only, no (check-sat) command (they were written for the python-API path, which calls s.check() programmatically). z3 executes zero check commands, prints nothing, exits 0 → driver parses no verdict → every obligation reports error.
  • Verified: the specs themselves are sound under the pinned solver — driving them through the python API of the exact 4.9.1.0 wheel gives t1-s1 context: sat, t1-s1 theorem: unsat, t2 context: sat as specified. The failure is purely the CLI invocation form, not the math.

Fix in progress on the PR branch (CLI trailer gets (check-sat); model witness extraction made to work on the CLI path too so the mutation-witness assertion isn't silently skipped there). Will follow up with the full structured conclusion once the lane is green.

ework-agent added 2 commits October 5, 2026 16:20
…ess there too (#2159)

The spec files carry assertions only. detectSolver() prefers a z3 CLI on
PATH, and the pinned z3-solver wheel bundles one, so CI took the CLI branch:
'z3 -smt2 <file>' executed no check command, printed no verdict, exited 0 —
all 9 obligations reported 'error'. Append (check-sat) (and get-model after
it for SAT checks) on the CLI path, parse z3's define-fun model output for
the mutation-witness assertion on both paths.
t2.smt2 grounds the archive op in applyCompactionArchive and the cursor
discipline in state.nextIndex carry-verbatim, both in src/session.ts; the
paths filter missed that file, so changes there could bypass the lane.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review complete — CI 全绿(19/19),可合并(merge 由人执行)。本轮 review 抓到并修掉了 theorem lane 的红灯,结论如下。

结构化七问

  1. 是什么问题:PR 自带的 theorem lane(CI 上唯一保证 9 条 Z3 obligation 真实执行的机制)在首版提交上是红的——9 个 solver 子测试全部报 error。也就是说,"machine-checked" 这个核心主张在 CI 上其实一次都没真正跑成过。
  2. 什么原因导致的:三层因果叠加——① spec 文件只含断言、没有 (check-sat) 命令(作者按 python API 路径写的,s.check() 是程序化调用的);② detectSolver() 优先选 PATH 上的 z3 CLI 而非 python 模块;③ 钉死的 z3-solver==4.9.1.0 wheel 自带原生 z3 可执行文件,pip 装完它就上了 PATH → CI 静默走了 CLI 分支 → z3 -smt2 <file> 执行了零条 check 命令、零输出、exit 0 → driver 解析不到 verdict → 全 error。作者本地验证走的是别的调用形态,恰好没踩中这个组合。spec 数学本身是好的:用同一 pinned 4.9.1.0 的 python API 驱动,verdict 与声称完全一致(本地复现验证)。
  3. 怎么修复的:两个标注 commit 推到 PR 分支(不替换原贡献):
    • 407f712f tests/cache-theorem.test.ts——CLI 分支补 (check-sat)(SAT 检查再加 (get-model));模型见证提取同时解析 z3 CLI 的 (define-fun name () Int value) 输出,见证断言从 py-only 变为两条路径都生效(此前 CLI 路径下 mutation-witness 验收标准被静默跳过——这正好打在 形式化求解器证明缓存字节稳定性:x-at-interface 建模,TS→C/C++/Rust 编译 / WASM / 汇编路线 #2149 三条验收标准的第②条上);
    • 582c8818 ci-theorem.yml——paths filter 补 src/session.ts:t2.smt2 把 archive op(applyCompactionArchive)和游标纪律(state.nextIndex carry-verbatim)都 grounding 在这个文件里,原 filter 漏掉它,改这个文件可以绕过 lane。
  4. 是否有回归问题:审过的既有行为——主 ci.yml 未动;py 路径 trailer 逐字节不变(无 CLI 的机器行为不变);CLI 路径此前没有任何能工作的行为(恒 error),纯改善;见证断言在 py 下 models 来源不变、无行为漂移;paths filter 只增不减(lane 只能更敏感)。生产代码/kernel/wire/config/persistence 零触碰。高危模式逐项:fal-fast→吞错 无;默认值/阈值/时序 无;输出格式 无(测试报告多打模型值属新增信息)。
  5. 是否破坏缓存:不涉及——纯 test/CI 面,无任何运行时路径变化。
  6. 是否改了设计方向:否。Route 4(契约 spec + grounding + test: code prover proving cache-byte stability across failure paths (#2138) #2144 sync gate)原样保留,修复只是让 lane 真的执行它声称要执行的东西。两点强度校准供 owner 判断(非阻塞):T1 定理在给定的定义下近乎构造性成立(P 是两个 body 的字面公共前缀,证明 = 共享子项上的 congruence)——这正是 route 4 已披露的取舍,字节级桥接由 test: code prover proving cache-byte stability across failure paths (#2138) #2144 承担,routes 1–3 仍是可选加固;T2-host 的 UNSAT 实际只依赖游标单调(FLOOR),分配器扫描语义由 [grounding:g1] 对真实 assignRefs/allocateFreeRef 钉住——分工正确,但读结论时应知道保证的边界在哪。
  7. 是否引入新配置:无。无新 env/config key/默认值。

验证证据

  • 本地完整复现首版失败(9×~13ms error,与 CI 日志一致),定位到 CLI 缺 (check-sat);
  • 修复后本地双路径 13/13(pinned 4.9.1.0:CLI 路径 total 162ms / py-only 路径 total 1196ms),T2 mutation 反例两路径一致:hui=3 creset=4 n3=4 n4=5(死高位 5 被重发,与 PR body 声称完全相同);typecheck clean;
  • CI(head 582c8818):theorem lane 绿,日志内 9 条 obligation verdict 齐全(2×unsat 定理 + 3×sat 上下文一致性 + 3×sat 突变反例 + 1×sat T2-reset),总耗时 149ms;其余 18 个 check 全绿;
  • 顺带记录一个脆弱点(不阻塞):z3-solver 4.9.1.0 的 python 模块 import 需要 pkg_resources(setuptools<81,新版 setuptools 已移除);当前 runner 镜像预置旧 setuptools 所以 py 回退可用,若未来镜像升级 setuptools≥81,py 检测会退化为 skip——影响有界,因为 wheel 自带 CLI 使主路径始终存活。

收工判定:theorem lane 已由红转绿且见证可见,方向(route 4)维持 owner 已批方案不变,两个小修均已标注 commit 推入分支。请 owner 合并:#2159

@ranxianglei
ranxianglei merged commit bbb6859 into master Oct 5, 2026
19 checks passed
@github-actions

github-actions Bot commented Oct 5, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.37-master.bbb6859 (rolling master tag).

npm install -g billion-context@0.0.37-master.bbb6859  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

形式化求解器证明缓存字节稳定性:x-at-interface 建模,TS→C/C++/Rust 编译 / WASM / 汇编路线

1 participant