dsh-vibe-math 2.7.2

dsh-vibe-math 2.7.2 — 发布说明

上一版本：2.7.1。本版是补丁版：只包含修复与附加（新增）响应字段，不改变任何既有行为契约——把真实引擎环境下的发现、证据与诊断补齐：装了但不在 PATH 的引擎能被发现、安装建议不再给出本机跑不了的命令、失败证据（超时/缺包/未校验约束）不再缺失或静默、归档身份与名册口径可直接核对。四套预设的参数默认值、数据格式与目录结构未变，DSH 支撑窗口不变，无需迁移。

概述

• 真实引擎发现更可靠：引擎发现顺序为 PATH → 宿主自带运行时 → 各操作系统的已知安装目录，因此在默认目录安装、但没有加进 PATH 的引擎（例如 R）也能被发现。
• 不再给出跑不了的安装命令：MATH_ENGINE_NOT_FOUND 只在本机的包管理器确实存在时才给出可执行命令，否则给出建议命令与官方地址，并说明原因。
• probe 不再"报喜不报忧"：除了可用引擎，还会列出已配置但本机未发现的引擎及原因。
• 失败证据完整：MATH_TIMEOUT 与 MATH_NONZERO_EXIT 携带同样的证据字段，超时的部分输出在响应与回执里都能拿到。
• 约束口径明说：版本约束只按存在性检查、从不校验，未校验的约束会被逐条列出，不再静默忽略。
• 归档身份可核对：运行响应直接给出归档 id 与 attempt；"编辑归档脚本后重跑"的语义有显式字段与警告解释。
• 名册口径统一（v4/v5）：一次验证/会议冻结一份名册快照并记录版本号，所有视图读同一份数据；成员变化时版本号递增，读到的集合是否过期一目了然。
• 诊断更具体：成员级调用失败时给出错误码、当前状态与下一步建议（而不是一句"不存在"）。

新增

• math_computation 的 run 响应新增 runId 与 attempt（此前归档 id 只存在于回执里，调用方无法直接核对"是不是同一个归档"）。
• probe 响应新增 configured（配置启用的引擎全集）与 absent[]：每个未发现的引擎带 why（not-found-on-this-machine 或 needs-a-caller-supplied-command）。
• 新增约束口径字段：成功响应与"缺包"失败都带 versionPolicy 与 constraintsNotEnforced（本次未校验的约束逐条列出；没有约束时为空数组）。
• MATH_TIMEOUT 响应新增 stdout/stderr（按上限截断）；回执 JSON 新增 partialStdout/partialStderr。
• MATH_ENGINE_NOT_FOUND 的 next 新增 suggestedCommand、packageManager、packageManagerAvailable、note（vendorUrl 视引擎而定）。
• run 响应新增 fileIsArchivedScript，并在 mode:'file' 指向归档脚本时给出 ARCHIVED_SCRIPT_RERUN 警告。
• v4：status() 新增 rosterVersion 与 frozenParticipants；consensus / meeting / verify 视图带各自的 rosterVersion。
• v4：paper 视图新增 dirProjected / dirSource / readSideEffect，明确该路径是投影还是真实状态。
• v2/v3：决策与子代理中断诊断新增 code 与 next（例如 VIBE_MATH_DECISION_NOT_FOUND，并说明队列现状）；v4 的成员级调用新增 V4_NO_SUCH_RESIDENT（带当前编制与下一步建议）。

变更

• 引擎发现顺序：PATH → 宿主自带运行时 → 已知的每操作系统安装目录（Windows 的 %ProgramFiles% / %ProgramFiles(x86)% / %LOCALAPPDATA%\Programs，macOS 的 framework 路径，Linux 的 /usr/lib/R、/opt/R 等）。存在性一律靠列目录证明，从不假设路径存在。
• 安装建议：只有在本机能解析出对应包管理器时，next.command 才是可执行命令；否则为空，并给出 note 与官方地址。安装流程仍是"计划 → planToken 确认 → 执行"，作用域默认用户级。
• 归档 id 的键：mode:'file' 以源路径为键，mode:'code'/'expr' 以脚本内容为键。因此编辑同一个源文件再跑会落到同一个归档（attempt ≥ 2、scriptChanged:true、previousReceipt 指向上一次，且旧 attempt 绝不被覆盖）；而指向另一个路径（例如上一份归档的副本）会写入新归档，此时 attempt:1、scriptChanged:false、previousReceipt:null 都是预期。归档 id 不含随机数。
• v4 名册冻结与修剪：验证/会议开始时冻结参与集合并记录 rosterVersion；移除成员会同时从冻结集合中剔除（否则在飞投票永远凑不齐），新增成员不进入已冻结集合，集合真正变化时 rosterVersion 递增。没有进行中的验证/会议时，status().frozenParticipants 为显式 null。
• v2/v3 票数与法定人数单一来源：每轮票数只由一个函数（voteCount，读验证任务创建时记录的期望人数快照 + 轮次）给出，"是否够票、是否都报、共识、最终判定"四个读取点不再各自重算，因此调高/调低验证人数不会让各视图分叉。刻意保持不变：MIN_REVIEWERS 下限与"全体一致"判据——正是这两条（而不是把判据简化成只看本轮）决定了什么时候能收束；把它们一起"简化"掉会让单审阅者的结论被过早采纳。
• 文档口径更新：计算工具的验证边界、已知差异与响应字段都写进了随包文档（含真机验证过的引擎版本与边界码）。

修复

• 装了却"看不见"的引擎：只扫描宿主进程 PATH 时，安装在默认目录但未加入 PATH 的引擎（实测：R 4.6.1）会被报成缺失；现在能从已知安装目录发现，并且版本探测与其他候选一致。
• 跑不了的安装命令：此前会给出本机并不存在的包管理器命令（例如 winget）；现在只在管理器确实存在时给出命令，否则给出官方地址与说明。
• 超时证据不完整：MATH_TIMEOUT 之前缺少 exit 与 stderr，部分输出只存在于磁盘上的 stdout.txt；现在响应与回执都带截断后的部分输出，字段与 MATH_NONZERO_EXIT 对齐。
• probe 只报可用项：可用性一行此前可能只列出少数引擎而不解释其余配置项；现在点名"已配置但本机未发现"的引擎与原因。
• 版本约束被静默忽略：现在明确说明"只按 base name 检查是否存在"，并把本次未校验的约束逐条列出。
• 归档脚本"编辑后重跑"易被误读：新增显式字段与警告说明"指向归档副本 ⇒ 新归档、无历史"与"指向原源文件 ⇒ 同一归档 + 新的 attempt"，并明确旧回执不能作为修改后代码的证据。
• v4 paper 字段可能被误读：没有论文状态时该字段是投影路径；现在标注 dirProjected/dirSource 并声明读 status 无文件系统副作用。
• 成员可见材料的路径口径：四个预设的成员材料补齐说明——文件工具按会话 cwd 解析路径，列出的相对路径需拼项目根的绝对前缀；计算产物请用回执的绝对字段 receipt.scriptAbs，或把 receipt.cwd 与 receipt.scriptPath 拼起来。
• 成员级调用只回一句"不存在"：v4 现在返回错误码、当前编制与下一步建议；v2/v3 的决策与中断诊断同样给出 code 与 next。

兼容性与迁移

• 破坏性变更：无。 四套预设的参数默认值、数据格式、目录结构均未改变。
• 纯新增：本版新增的响应字段都是附加的；遇到不认识的字段请忽略，不要据此报错。
• 迁移：无需迁移。
• DSH 支撑窗口与 2.7.1 相同（见 package.json 的 engines.dsh）。

已知限制

• Octave / Julia 未随包提供，在本次的验证机器上也未安装；相关模板与安装计划是静态校验过的，未经真机执行。
• 商业引擎（MATLAB / Maple / Wolfram）模板仍需在持证机器上确认，默认标记为 VERIFY。
• 版本约束只按存在性检查：具体版本求解仍由包管理器负责，本工具不解析约束。
• 插件无法强制禁网或限制写权限：subprocess 通道没有策略槽位，需要宿主侧沙箱。
• 2.7.0 之前的发布说明仅提供中文（英文历史索引见 README.en.md）。

验证方式

• node tests/run-tests.mjs —— 全部通过（65 项：44 个套件 + 21 个灵敏度探针）。
• 三个数学契约守卫：tests/audit-math-computation-parity.mjs、-contract.mjs、-sensitivity.mjs。
• 真机验证（python 3.12.10 与 R 4.6.1）：同一算式两边给出相同数值；原生路径与 cli 逃生口数字一致且 scriptHash 相同；超时 → MATH_TIMEOUT，语法错误 → MATH_NONZERO_EXIT（带 stderr 与回执），缺包 → MATH_MISSING_PACKAGES（不写回执目录），引擎警告 → 正常退出并保留 stderr。

依赖

• 无新增运行时依赖；DSH 支撑窗口不变。

---

dsh-vibe-math 2.7.2 — Release Notes (English)

Previous release: 2.7.1. This is a PATCH release that contains fixes and additive response fields only — no existing behaviour contract changes. It completes engine discovery, evidence and diagnostics on real hosts: an engine that is installed but not on PATH is now found, install guidance never hands over a command that cannot run, and failure evidence (timeout, missing packages, unenforced constraints) is neither absent nor silent. The archive identity and the participant-set semantics are directly checkable. Parameter defaults, data formats and the directory layout are unchanged, the DSH support window is unchanged, and no migration is needed.

Overview

• More reliable discovery on real hosts: discovery now runs PATH → runtimes shipped by the host → the known per-OS install locations, so an engine installed in its default directory but never added to PATH (R, for example) is found.
• No more unrunnable install commands: MATH_ENGINE_NOT_FOUND only offers an executable command when that package manager really exists on this machine; otherwise it gives the suggested command, the official location and the reason.
• probe no longer reports only the good news: besides the engines that resolved, it names the configured but not found engines and why.
• Complete failure evidence: MATH_TIMEOUT carries the same fields as MATH_NONZERO_EXIT, and a timeout's partial output is available in both the response and the receipt.
• The constraint policy is stated: version constraints are checked for existence only and never enforced, and the constraints that were not checked are listed instead of being dropped silently.
• Checkable archive identity: the run response carries the archive id and attempt, and the "edit an archived script, then re-run" semantics are explained by an explicit field and warning.
• One participant set per verify/meeting (v4/v5): the roster is snapshotted with a version, every view reads the same snapshot, and the version increments when the set really changes so a stale set is detectable.
• More specific diagnostics: member-level failures return a code, the current state and a next step instead of a bare "no such resident".

Added

• The math_computation run response now carries runId and attempt (previously the archive id existed only inside the receipt, so a caller could not verify "same archive").
• The probe response now carries configured (every engine enabled in the configuration) and absent[], where each missing engine states why (not-found-on-this-machine or needs-a-caller-supplied-command).
• Constraint policy fields: both a successful response and a "missing packages" failure carry versionPolicy and constraintsNotEnforced (the constraints that were not checked, or an empty array).
• MATH_TIMEOUT responses carry stdout/stderr (capped); the receipt JSON carries partialStdout/partialStderr.
• MATH_ENGINE_NOT_FOUND's next carries suggestedCommand, packageManager, packageManagerAvailable and note (plus vendorUrl where the engine has one).
• The run response carries fileIsArchivedScript, and emits an ARCHIVED_SCRIPT_RERUN warning when mode:'file' targets an archived script.
• v4: status() carries rosterVersion and frozenParticipants; the consensus / meeting / verify views carry their own rosterVersion.
• v4: the paper view carries dirProjected / dirSource / readSideEffect, saying whether the path is a projection or real state.
• v2/v3: decision and sub-agent interrupt diagnostics carry code and next (for example VIBE_MATH_DECISION_NOT_FOUND, with the current queue state); v4 member-level calls carry V4_NO_SUCH_RESIDENT with the current roster and a next step.

Changed

• Discovery order: PATH → runtimes shipped by the host → the known per-OS install locations (Windows %ProgramFiles%, %ProgramFiles(x86)%, %LOCALAPPDATA%\Programs; the macOS framework path; Linux /usr/lib/R, /opt/R, and similar). Existence is always proven by listing a directory, never assumed.
• Install guidance: next.command is an executable command only when the corresponding package manager resolves on this machine; otherwise it is empty and a note plus the official location is given. Installation is still plan → planToken confirmation → execution, with user scope by default.
• The archive key: mode:'file' is keyed by the source path and mode:'code'/'expr' by the script content. Editing the same source file and re-running therefore lands on the same archive (attempt ≥ 2, scriptChanged:true, previousReceipt pointing at the previous attempt, and the earlier attempt is never overwritten). Pointing at a different path (a copy of the archived script, say) writes a new archive, where attempt:1, scriptChanged:false and previousReceipt:null are expected. The archive id contains no random value.
• v4 roster freeze and prune: a verify/meeting freezes its participant set and records rosterVersion; removing a member also prunes it from the frozen set (otherwise in-flight votes could never close), new members do not join a frozen set, and rosterVersion increments whenever the set really changes. With no verify/meeting in progress, status().frozenParticipants is an explicit null.
• v2/v3 single-source vote counting: the per-round counts come from one function (voteCount, reading the expectation recorded when the verify task was created plus the round), so the four readers (enough votes, all reported, consensus, final verdict) no longer derive them separately — raising or lowering the verifier count can no longer make the views disagree. Deliberately unchanged: the MIN_REVIEWERS floor and the "everyone agrees" predicate. That combination — not a simplified predicate over the current round alone — is what decides when a verification may conclude; collapsing the two would let a single reviewer's verdict be accepted too early.
• Documentation now states the verification boundary, the known differences and the new response fields, including the engine versions verified on real hosts and the confirmed edge codes.

Fixed

• Installed but invisible engines: scanning only the host process's PATH reported an engine installed in its default directory (measured: R 4.6.1) as missing; it is now discovered from the known install locations and version-probed like any other candidate.
• Unrunnable install commands: the tool used to suggest a package manager that does not exist on the machine (for example winget); it now only offers the command when the manager resolves, and otherwise gives the official location plus an explanation.
• Incomplete timeout evidence: MATH_TIMEOUT previously lacked exit and stderr, and its partial output existed only in the on-disk stdout.txt; the response and the receipt now both carry the capped partial output, aligned with MATH_NONZERO_EXIT.
• probe listing only what worked: the availability line could show a few engines without explaining the rest of the configuration; it now names the configured but not found engines and why.
• Version constraints silently ignored: the response now states that constraints are existence-only and lists every constraint it did not check.
• Confusing "edit an archived script, then re-run": an explicit field and warning now distinguish "targeting a copy of an archive ⇒ a new archive with no history" from "targeting the original source ⇒ the same archive with a new attempt", and state that an old receipt is not evidence for edited code.
• A misleading paper field in v4: with no paper state the field is a projected path; it is now flagged via dirProjected/dirSource and declares that reading status has no filesystem side effect.
• Path basis in member-visible material: all four presets now state that member file tools resolve against the session cwd, that the listed relative paths need the absolute project-root prefix, and that computation artifacts should be opened via the absolute receipt.scriptAbs or by joining receipt.cwd with receipt.scriptPath.
• Member-level calls answering only "not found": v4 now returns an error code, the current roster and a next step; v2/v3 decision and interrupt diagnostics likewise return code and next.

Compatibility & Migration

• Breaking changes: none. Parameter defaults, data formats and the directory layout of all four presets are unchanged.
• Additive only: every field added in this release is additional; please ignore unknown fields rather than failing on them.
• Migration: none needed.
• The DSH support window is the same as 2.7.1 (see engines.dsh in package.json).

Known Limitations

• Octave / Julia are not shipped and were not installed on the verification machine; their templates and install plans are statically validated but have not been executed on a real host.
• Commercial engine templates (MATLAB / Maple / Wolfram) still need confirmation on a licensed machine and remain marked VERIFY by default.
• Version constraints are existence-only: version solving still belongs to the package manager; this tool does not parse constraints.
• The plugin cannot enforce network or write restrictions: the subprocess channel has no policy slot; that requires a host-side sandbox.
• Release notes before 2.7.0 are Chinese-only (see the English history index in README.en.md).

Verification

• node tests/run-tests.mjs — all green (65 items: 44 suites + 21 sensitivity probes).
• Three math-contract guards: tests/audit-math-computation-parity.mjs, -contract.mjs, -sensitivity.mjs.
• Real-host verification (python 3.12.10 and R 4.6.1): both engines produce the same numbers for the same computation; the native path and the cli escape hatch agree numerically and share the same scriptHash; timeout → MATH_TIMEOUT, syntax error → MATH_NONZERO_EXIT (with stderr and a receipt), missing package → MATH_MISSING_PACKAGES (no receipt directory written), an engine warning → a normal exit with stderr preserved.

Dependencies

• No new runtime dependencies; the DSH support window is unchanged.