border-customs 0.4.0 → 0.4.1

package/README.md

@@ -222,9 +222,10 @@ staged artifact, `border check` can no longer PASS that channel on signatures al
 artifact's sha256 must also carry a **fresh empirical roundtrip verdict** in the ledger.
 
 The check gate NEVER runs Docker itself (there is nothing to trust it to run); the proof is
-pre-supplied out-of-band by `border roundtrip <spec>`, which installs the real bytes, diffs the
+pre-supplied out-of-band by `border roundtrip <spec-or-local-file>`, which installs the real
+bytes — fetched from a registry or read from a local artifact (W2.4(b)) — diffs the
 filesystem, and appends a `t:"roundtrip"` ledger record — `{artifactSha256, verdict:
-clean|residue, rulesHash, ts, rows}` — keyed by the exact bytes it fetched. A `residue` verdict
+clean|residue, rulesHash, ts, rows}` — keyed by the exact bytes it proved. A `residue` verdict
 still counts as a proof-of-fact: the valve demands *evidence someone looked*, and the finding
 itself keeps blocking until it stops tripping the scan.
 
@@ -236,17 +237,76 @@ itself keeps blocking until it stops tripping the scan.
 - Both new rules are ordinary findings: the allow-list can waive them and every waiver is
   enumerated in `allowHits` — no hidden channel.
 
+### Release coherence (0.4.1)
+
+Founding case — **aihr**: the wheel published on PyPI under version `0.2.2` carried
+`__init__.__version__ = "0.2.1"` while `pyproject.toml` declared `0.2.2`. The artifact's name,
+its metadata and its actual module behaviour disagreed, and every consumer who pinned `==0.2.2`
+silently installed the older behaviour. The same drift class bit this repo twice: the published
+npm tarball's User-Agent string said `0.3.0` while `package.json` said `0.3.1`, and
+`package-lock.json`'s root version sat at `0.1.0` through two releases. Version truth must AGREE
+across every source **inside the artifact** before anything ships — so the publish-stage artifact
+scanners cross-check those sources statically. No second source of truth outside the artifact is
+consulted: no registry, no git tag.
+
+| Rule | Severity | Fires when |
+| --- | --- | --- |
+| `release-coherence-version-drift` | CRITICAL | two version sources packed in one artifact disagree: `package.json` vs a force-packed `package-lock.json` root or `packages[""]` (npm); wheel filename vs `*-*.dist-info` directory vs `METADATA Version:` vs a literal `__version__` in any `__init__.py`; sdist `pyproject.toml [project].version` vs `PKG-INFO` / `setup.cfg` / `setup.py` string literals vs `__init__`; `Cargo.toml [package].version` vs the `Cargo.lock` entry when the lock is packed; `.gemspec` first-literal vs the built gem's `metadata.gz` name/version; `dist` filename vs the packed root `PKG-INFO` (sdist) |
+| `release-coherence-unverifiable-source` | MEDIUM | a second version source is present but not statically parseable — a computed/dynamic `__version__`, a `setup.cfg` `attr:`/interpolation, a `dynamic = ["version"]` pyproject, a malformed lockfile, a missing `Cargo.lock` entry, an unreadable gemspec block. Fail-closed beats silent-clean: the gate refuses to call uncheckable "clean" |
+| `release-coherence-twin-drift` | CRITICAL | opt-in `release.twin` pairs (see Configuration): a configured PyPI↔npm twin pair publishes different versions. This is the one cross-manager equality that is statically enforceable — both artifacts are already in `.border/dist/` in the same run |
+
+The absent-source boundary is load-bearing: a missing `package-lock.json`/`Cargo.lock`/`PKG-INFO`
+means nothing was packed — **not** that anything drifted — and no row is emitted. Publishing
+gatekeepers that cry wolf train users to pass `--force`; these rules fire only on evidence inside
+the shipped bytes. Like the residue rule table, this family's source folds into `rulesHash`, so
+editing a matcher invalidates every cached PASS.
+
 ### Running `border roundtrip`
 
-`border roundtrip <[ecosystem:]name@version>` fetches the real registry bytes, installs them in a
-throwaway Docker container (per-ecosystem image, whole-filesystem content-hash manifest before
-install and after the manager's own uninstall), prints the residue manifest, and records the
-verdict. Known fidelity envelope, from the W2.0 spike and the W2.3 registrar-chain demo:
+`border roundtrip <[ecosystem:]name@version | local-artifact-file>` fetches the real registry
+bytes — or, since W2.4(b), accepts a LOCAL artifact file (`border roundtrip
+dist/foo-1.0.0-py3-none-any.whl`) — installs them in a throwaway Docker container
+(per-ecosystem image, whole-filesystem content-hash manifest before install and after the
+manager's own uninstall), prints the residue manifest, and records the verdict.
+
+The local lane exists so unpublished/hardened artifacts can be proven **pre-publish**. Its rules
+are deliberately narrow: the ecosystem comes from the extension alone, a closed table
+(`.whl`→pypi, `.tgz`→npm, `.crate`→crates, `.gem`→rubygems); anything else exits 2, because
+content-sniffing would grade an artifact through a guessed manager's install/uninstall contract.
+Local mode touches no network: the file passes one streaming sha256 pass (the 200 MiB cap fails
+closed mid-stream), the exact bytes are staged and `docker cp`'d, and every later leg — closure
+resolution, m1/m2/m3, residue rows, ledger proof — runs the identical registry pipeline.
+Provenance stays honest: human and `--json` output stamp `source: "local:<abs-path>"` plus the
+`artifactSha256` — the digest is the identity, and the requireProof valve consumes a local proof
+by the same digest it uses for a fetched one. A directory argument, or a path-shaped argument
+that does not resolve to an existing file, exits 2 before anything is fetched.
+
+Wheel-lane boundary, stated honestly: the LOCAL PyPI-wheel lane is residue-INERT by
+construction — pip fully records what it installs and prunes its own directories, so even a
+wheel planted with hostile `.data/data/...` entries leaves a zero survivor set after uninstall
+(verified live on pip 25.0.1 AND 24.0, 2026-09-11, verifier harness); a PASS on such a plant is
+pip's contract working, not a missed detection. The local wheel roundtrip still proves
+installability, benign-clean, and exact-bytes identity — but planted-detection demos belong to
+the lanes whose managers execute install hooks: npm (`.tgz` postinstall EXECUTES under
+`npm install -g --foreground-scripts`), gem (extconf custom writes) and crates (build.rs).
+
+Known fidelity envelope, from the W2.0 spike and the W2.3 registrar-chain demo:
 
 - Docker is required; absence or any step failure ⇒ exit 2, never a silent `clean`.
-- npm/gem/crates lanes diff exactly; the pypi lane reports pip's left-behind **transitive
-  dependencies** as orphan rows (calibration to a target-only diff is a known follow-up —
-  the over-report direction is deliberately conservative).
+- A local run proves its own bytes and says so: `source`/`artifactSha256` in the report and the
+  `t:"roundtrip"` ledger record all key on the streamed digest of the file given — never phrased
+  as registry-verified.
+- npm/gem/crates lanes diff exactly; the pypi lane calibrates pip's left-behind **transitive
+  dependencies** (W2.4): before install, `pip install --dry-run --report` resolves the closure in a
+  throwaway resolver container, and post-uninstall rows still claimed by a still-installed closure
+  dist demote to LOW `residue-roundtrip-dep-owned` — non-blocking, owner named, still printed.
+  A claim only counts from a legitimate claimant: its dist-info must match the resolver's
+  name-version pin exactly, be canonically named and the unique dist-info for that name, and may
+  only claim paths inside its own site-packages root — a shadow or forged `X-Y.dist-info` planted
+  by install code launders nothing. What the demotion cannot see stays blocking, deliberately:
+  dependency writes outside their own RECORD, paths ambiguously claimed by two dists, every MODIFIED
+  row (the W2.3 founding run's genuine `/usr/local/share/aihr` orphan is exactly this shape), and if the
+  closure itself cannot be resolved the run exits 2 — cannot-verify is never clean.
 - Only manager-lifecycle surfaces are observed: persistence performed by explicitly-invoked
   bins (not npm hooks) is outside what the roundtrip watches — W2.3 measured exactly this
   blind spot on our own registrar and documented its `{"plugin": []}` config residue.
@@ -510,6 +570,8 @@ engines:
   require: [gitleaks, secretlint]           # trufflehog: true adds the third-party engine
 residue:
   enabled: true                             # default; false hides ONLY the residue-* rows
+release:
+  twin: []                                  # opt-in [{pypi, npm}] pairs — see Release coherence
 ```
 
 Notes that change behavior:
@@ -613,6 +675,25 @@ same one that wrote the commit) how to run the five subcommands, how to produce
 
 ## Changelog
 
+### 0.4.1 (2026-09-11)
+- Add: release-coherence rule family — every version source inside a published artifact
+  must agree (pyproject vs MODULE vs filename, gemspec vs gem metadata, Cargo.toml vs
+  crate filename, package.json self-consistency; the git-tag half is a publish-workflow
+  hard gate). Trigger: the aihr incident where a wheel labeled 0.2.2 shipped modules
+  self-reporting 0.2.1 — every pinned consumer silently got old behavior.
+- Add: `border roundtrip` local-artifact input — an argument resolving to an existing
+  file (.whl/.tgz/.crate/.gem, closed table) proves unpublished bytes end-to-end; the
+  streaming sha256 of those exact bytes is the ledger identity and the report carries
+  `source:local:<abs>` provenance. Honest boundary documented: the local PyPI-wheel lane
+  is residue-INERT by construction (pip fully tracks and prunes; verified live on pip
+  24.0 AND 25.0.1) — planted-detection demos belong to the hook-executing lanes
+  (npm postinstall, gem extconf, crates build.rs).
+- Change: pypi roundtrip lane dep-closure calibration — pip's resolver report demotes
+  dependency-storm files to LOW `dep-owned` rows, so genuine orphans stand alone; the
+  demotion requires a legitimate claimant dist-info (pin Name+Version match, canonical
+  dirname, unique, own site-packages root, not the target) after an independent verifier
+  proved a shadow `*-9.9.9.dist-info` could otherwise launder hostile writes.
+
 ### 0.4.0 (2026-09-10)
 - Add: `border roundtrip <[ecosystem:]name@version>` — fact-proof valve. Installs the
   package inside a throwaway Docker container, content-hashes the whole filesystem before
@@ -683,11 +764,30 @@ MIT, see [LICENSE](LICENSE).
 border 是一个 fail-closed(失败即拦截)的推送前门禁 CLI:`npm install -g border-customs` 安装,在仓库里跑 `border check`。它扫描 git 历史、工作区(未跟踪文件同样是一等输入)、归档、tag 注释和将要发布的 npm/PyPI/crates/RubyGems 字节,检出密钥与供应链风险;只有当"当前状态指纹"存在新鲜且完整的 PASS 记录时才允许 `border push --yes` 放行。指纹是 sha256(head、porcelain 摘要、规则哈希、暴露面、ref 集合、有效目标)六元组,任何一处变动,旧的 PASS 立即失效,必须重查。流水线:gitleaks(历史+工作区+tag,内置 8.30.1 规则,仓库自带的 ignore 文件直接判 CRITICAL)+ secretlint(进程内,AWS Key 规则强制开启)+ 原生规则(AI 会话产物闭集、提交身份白名单含传输对象检查)+ 注册表预检(版本已存在=必须 bump,名称被外人占有=拒绝;空响应/超时/解析失败一律 exit 2,沉默绝不等于不存在)。构件只构建一次进 `.border/dist/`,扫描的就是发布的字节,发布时再哈希比对,不一致直接拒发。跳过台账让重复检查不到 1 秒,但回放前先重算指纹并重新 pack 验证新鲜度。报告只输出掩码片段(sha256 摘要 + 前4…后4)。push 是多目标状态机,多 remote 先做全有或全无的 fast-forward 预检,永不 force-push;npm/twine/cargo/gem 的凭据经 stdio 透传,border 从不触碰。0.2.0 新增 crates.io 与 RubyGems 通道(公开 crates.io 固定、rubygems 可用 host 覆盖私有镜像),既有配置行为不变。0.3.0 新增残留扫描(residue gate):发布字节里的安装期钩子按 T0-T4 闭集签名表分类(闭集 T1 树内钩子降为 MEDIUM,未知形态原样保留 CRITICAL),外加跨包管理器写入、配对标记缺失(`# BEGIN` 块只检测不豁免)与 gem 不可解析扩展共七条 `residue-*` 规则;`residue.enabled` 是唯一豁免开关且改动指纹使旧 PASS 失效,规则表与分类器源码进入 rulesHash,改一个签名即强制重查。静态分析只证明"能力"不证明"事实",border 不是恶意软件沙箱,从不执行被读代码。0.4.0 新增证明阀
 `residue.requireProof`(默认关,strict):开启后,发布构件若触发阻断级 `residue-*` 发现,通道 PASS
 还要求账本里存在按其 sha256 索引且 rulesHash 新鲜的 `border roundtrip` 实测记录——check 自身从不
-运行 Docker,证据由 `border roundtrip` 离线写入(默认记账,`--no-record` 关闭),clean 与 residue
+运行 Docker,证据由 `border roundtrip`(注册表 spec 或本地构件文件,W2.4b)离线写入(默认记账,`--no-record` 关闭),clean 与 residue
 两种裁决都算"事实已在";缺记录判 `roundtrip-proof-missing`、rulesHash 过期判
 `roundtrip-proof-stale`(均 CRITICAL/native,与普通发现同受白名单管辖并在 allowHits 枚举),翻转
 该配置即轮换 rulesHash,所有缓存 PASS 自动失效。`border roundtrip` 本身保真边界:Docker 必需、
-缺失即 exit 2 绝不假装干净;pypi 通道会把 pip 遗留的传递依赖如实报成孤儿行(收窄到目标包自身是
-已知后续项);只有包管理器生命周期触发的写入被观测,显式调用的 bin 自写配置不在射程——W2.3 在
+ 缺失即 exit 2 绝不假装干净;本地构件输入(W2.4b)——参数解析为已存在的文件即走本地模式,生态仅由扩展名闭表判定
+  (.whl→pypi、.tgz→npm、.crate→crates、.gem→rubygems),表外一律 exit 2:内容嗅探等于猜测某个管理器的装卸契约,
+  按猜测定级不予采纳;本地模式全程不触网,文件流式过一遍 sha256(200 MiB 上限在流内超限即闭),同一批字节暂存后
+  docker cp,闭包解析、m1/m2/m3、残留行与账本证明走的都是与注册表模式完全相同的流水线;出处保持诚实:人机与
+  --json 输出都盖上 `source: "local:<绝对路径>"` 与 artifactSha256——摘要即身份,requireProof 阀按同一摘要原样
+   消费本地证明,本地证明绝不表述为注册表已验证;目录参数、或形如路径却并不存在的参数,在任何拉取发生之前即 exit 2;
+   wheel 通道诚实边界:本地 PyPI-wheel 通道天然残留惰性(residue-INERT)——pip 完整登记所装文件并清理自建目录,
+   即便往 wheel 里种入恶意 `.data/data/...` 条目,卸载后幸存集也为空(2026-09-11 在 pip 25.0.1 与 24.0 上实机验证,
+   验证器工装);对这种种植判 PASS 是 pip 契约在起作用,不是漏检。本地 wheel 往返仍证明可安装性、benign-clean
+   与字节级同一性,但种植检测演示属于会执行安装钩子的通道:npm(.tgz 的 postinstall 在 `npm install -g
+   --foreground-scripts` 下真实执行)、gem(extconf 自定义写入)与 crates(build.rs);
+   pypi 通道已做目标收窄校准(W2.4)——安装前先在一次性解析容器里用
+ `pip install --dry-run --report` 解析依赖闭包,卸载后仍被闭包内在册依赖认领的残留行降级为 LOW
+ `residue-roundtrip-dep-owned`(非阻断,注明归属依赖,仍照常打印);认领只对合法主张者生效:其 dist-info 必须与
+ 解析器的 name-version 钉值完全一致、目录名规范且为该名字唯一发行版,且只能认领自身 site-packages 根内的路径——
+ 安装代码私设的伪影 shadow dist-info 洗白不了任何残留;分类器看不见的刻意继续阻断:
+ 依赖写在自身 RECORD 之外的路径、被两个发行包同时认领的歧义路径、一切 MODIFIED 行(W2.3 首轮那条真实孤儿
+ `/usr/local/share/aihr` 正是此类),闭包解析失败则整轮 exit 2,不可验证绝不等于干净;
+只有包管理器生命周期触发的写入被观测,显式调用的 bin 自写配置不在射程——W2.3 在
 自家 registrar 链上实测到该盲区并留下了 `{"plugin": []}` 残留证据。clean 是"某一版本构件在某类
 机器上"的事实证明,不是安全担保。可选 LLM 层 border 自身从不调用模型 API:`llm-request` 导出掩码审阅包,`llm-ingest` 严格校验 agent 结论并重算裁决。退出码即合同:0 通过、1 拦截、2 门禁无法作答,任何"工具不健康"都不可能被误读为干净。MIT 许可,无遥测,除你配置的注册表预检外不联网。
+
+发布一致性(0.4.1):起因是 aihr 事故——PyPI 上标为 0.2.2 的 wheel 里 `__init__.__version__` 却写着 0.2.1,构件名、元数据与实际模块行为三者不一致,所有 `==0.2.2` 的用户静默装上了旧行为;同类漂移在本仓库也出现过两次(npm tarball 的 User-Agent 停在 0.3.0 而 package.json 是 0.3.1;package-lock.json 根版本两个 release 一直躺在 0.1.0)。发布阶段扫描器因此在构件内部逐源交叉核对版本号:`release-coherence-version-drift` 为 CRITICAL(package.json 与被强制打包的 package-lock、wheel 文件名对 dist-info 目录对 METADATA `Version:` 对 `__init__` 字面量、sdist 的 pyproject 对 PKG-INFO/setup 系字面量、Cargo.toml 对已打包的 Cargo.lock、.gemspec 对 metadata.gz、dist 文件名对 sdist 内 PKG-INFO);版本源存在但无法静态解析(动态 `__version__`、`attr:`、`dynamic = ["version"]`、坏 lockfile)判 MEDIUM `release-coherence-unverifiable-source`——不可核查绝不静默算干净;第二版本源根本没被打包时不发现在内,缺源不是漂移,这条边界是承重的,误报的门禁会把用户训练成 `--force`。唯一可静态强制的跨包管理器声明是 opt-in `release.twin`(`{pypi, npm}` 严格 zod 对列表,未知键 exit 2):同一 run 的 dist 里孪生版本不等 ⇒ CRITICAL `release-coherence-twin-drift`,消息点名两个构件。规则源文件与 residue 指纹表一样并入 rulesHash,改一个匹配器即令全部缓存 PASS 失效。

package/dist/assets/release-src/releaseCoherence.ts

@@ -0,0 +1,423 @@
+// provenance: border-inspect-roadmap.md W4.1/W4.2 — the release-coherence rule family.
+//
+// FOUNDING CASE (aihr incident): a wheel labeled version 0.2.2 on PyPI shipped a package whose
+// `__init__.__version__` said 0.2.1 (pyproject itself said 0.2.2) — users installed "0.2.2"
+// bytes carrying older module behavior. A second drift class bit border directly: the published
+// npm tarball's User-Agent said 0.3.0 while package.json said 0.3.1, and package-lock.json's
+// root version sat at 0.1.0 through two releases. Version truth must AGREE across every source
+// packed INSIDE the artifact before anything ships. This module is the closed-table analyzers;
+// the ecosystem stages (artifacts/{npm,pypi,crates,rubygems}.ts) route their extracted trees
+// here and the check pipeline routes release.twin pairs after the channel loop (src/check.ts).
+//
+// ABSENT-SOURCE BOUNDARY (load-bearing, documented here per plan W4.1): an absent SECOND
+// version source is NOT drift and NEVER a finding. package-lock.json / Cargo.lock / PKG-INFO
+// are usually not packed at all (npm `files` whitelists, cargo default ignores) — a rule that
+// fired on "not packed" would false-green-block honest releases and train users to pass
+// --force, which is exactly how gate credibility dies. Conversely, a source that IS present
+// but statically unreadable (dynamic `__version__`, malformed lock) is 'cannot-verify' — it
+// emits release-coherence-unverifiable-source MEDIUM and is NEVER silently clean.
+//
+// Doctrine (mirrors rules/residueMatchers.ts + artifacts/manifestDiff.ts):
+//   * regex/text extraction ONLY — no python/ruby/toml parsing, nothing is ever executed;
+//   * every rule id in RELEASE_COHERENCE_SEVERITIES is closed-table (no user-configurable
+//     patterns); severities fixed: drift CRITICAL, twin-drift CRITICAL, unverifiable MEDIUM;
+//   * findings flow through the native pipeline (residueFindings-style digest keying, then
+//     applyAllowList/report as for every other rule);
+//   * this file rides computeCheckRulesHash's fingerprint (RELEASE_FINGERPRINT_SOURCES in
+//     src/check/rulesHash.ts) so any edit here rotates rulesHash and invalidates proofs,
+//     exactly like the residue sources.
+import { spawnSync } from "node:child_process";
+import { basename, join } from "node:path";
+
+import { type Finding, type Severity } from "../findings.ts";
+import { type LedgerArtifact } from "../ledger/records.ts";
+import { redact, type TextSanitizer } from "../redact.ts";
+
+export const RELEASE_COHERENCE_DRIFT_RULE = "release-coherence-version-drift";
+export const RELEASE_COHERENCE_TWIN_RULE = "release-coherence-twin-drift";
+export const RELEASE_COHERENCE_UNVERIFIABLE_RULE = "release-coherence-unverifiable-source";
+
+/** Closed severity table — the ONLY rule ids this family may emit. */
+export const RELEASE_COHERENCE_SEVERITIES: Readonly<Record<string, Severity>> = {
+  [RELEASE_COHERENCE_DRIFT_RULE]: "CRITICAL",
+  [RELEASE_COHERENCE_TWIN_RULE]: "CRITICAL",
+  [RELEASE_COHERENCE_UNVERIFIABLE_RULE]: "MEDIUM",
+};
+
+const TARGET = "artifact";
+const ENGINE = "native";
+const FOUNDING = "version truth must AGREE across every source packed in the artifact (aihr: a wheel named 0.2.2 shipped __version__ 0.2.1)";
+
+// --------------------------------------------------------------- source probes (pure text)
+
+type Probe = { readonly status: "literal"; readonly value: string } | { readonly status: "dynamic"; readonly reason: string } | null;
+
+/** `__version__ = "X"` literal on its own line; ANY other assignment/import shape ⇒ dynamic. */
+export function probeDunderVersion(text: string): Probe {
+  for (const line of text.split(/\r?\n/)) {
+    const assign = /^\s*__version__\s*=\s*(.+?)\s*$/.exec(line);
+    if (assign?.[1] !== undefined) {
+      const lit = /^(['"])((?:(?!\1).)+)\1(?:\s*#.*)?$/.exec(assign[1]);
+      return lit?.[2] !== undefined ? { status: "literal", value: lit[2] } : { status: "dynamic", reason: `__version__ assigned a non-literal (${assign[1].slice(0, 60)})` };
+    }
+    if (/^\s*(?:from\s+\S+\s+)?import\b.*\b__version__\b/.test(line)) {
+      return { status: "dynamic", reason: "__version__ imported from another module" };
+    }
+  }
+  return null;
+}
+
+/** Core metadata `Version:` header (PKG-INFO / wheel METADATA). */
+export function probeHeaderVersion(text: string): Probe {
+  const m = /^Version:[ \t]*(.*?)[ \t]*$/m.exec(text);
+  if (m === null) return null;
+  return m[1] !== undefined && m[1] !== "" ? { status: "literal", value: m[1] } : { status: "dynamic", reason: "Version: header present but empty" };
+}
+
+/** pyproject `[project].version` literal; [project] absent ⇒ null (legacy setup.* project). */
+export function probePyprojectVersion(text: string): Probe {
+  const lines = text.split(/\r?\n/);
+  let inProject = false;
+  const slice: string[] = [];
+  for (const line of lines) {
+    if (/^\s*\[/.test(line)) {
+      if (inProject) break;
+      inProject = /^\s*\[project\]\s*$/.test(line);
+      continue;
+    }
+    if (inProject) slice.push(line);
+  }
+  if (!inProject && slice.length === 0 && !text.includes("[project]")) return null;
+  const body = slice.join("\n");
+  const lit = /^\s*version\s*=\s*(['"])((?:(?!\1).)+)\1\s*(?:#.*)?$/m.exec(body);
+  if (lit?.[2] !== undefined) return { status: "literal", value: lit[2] };
+  const dyn = /dynamic\s*=\s*\[([\s\S]*?)\]/.exec(`${body}\n]`);
+  if (dyn?.[1] !== undefined && /["']version["']/.test(dyn[1])) return { status: "dynamic", reason: 'project.version listed in dynamic = ["version"]' };
+  return { status: "dynamic", reason: "[project] declares no statically-readable version" };
+}
+
+/** setup.cfg `[metadata] version =` — bare scalars literal, attr:/interp ⇒ dynamic. */
+export function probeSetupCfgVersion(text: string): Probe {
+  // line-slice the [metadata] section (a lazy [\s\S] regex + /m $ would stop at the first
+  // newline and silently lose every later key — classic multiline-anchor trap)
+  const lines = text.split(/\r?\n/);
+  let inSection = false;
+  const slice: string[] = [];
+  for (const line of lines) {
+    if (/^\s*\[/.test(line)) {
+      if (inSection) break;
+      inSection = /^\s*\[metadata\]\s*$/.test(line);
+      continue;
+    }
+    if (inSection) slice.push(line);
+  }
+  const v = /^[ \t]*version[ \t]*=[ \t]*(.+?)[ \t]*$/m.exec(slice.join("\n"));
+  if (v?.[1] === undefined) return null;
+  return /^[\w.+-]+$/.test(v[1]) ? { status: "literal", value: v[1] } : { status: "dynamic", reason: `setup.cfg version = '${v[1].slice(0, 40)}' is not a bare literal` };
+}
+
+/** setup.py `version="X"` string-literal kwarg ONLY (never executed). */
+export function probeSetupPyVersion(text: string): Probe {
+  const lit = /(?:^|[,(]\s*)version\s*=\s*(['"])((?:(?!\1).)+)\1/.exec(text);
+  if (lit?.[2] !== undefined) return { status: "literal", value: lit[2] };
+  return /(?:^|[,(]\s*)version\s*=/.test(text) ? { status: "dynamic", reason: "setup.py version= is not a string literal" } : null;
+}
+
+/** Wheel filename `name-version-py-abi-plat.whl` ⇒ version segment (legacy dash form). */
+export function parseWheelFilenameVersion(fileName: string): { name: string; version: string } | null {
+  const base = basename(fileName).replace(/\.whl$/i, "");
+  const parts = base.split("-");
+  if (parts.length < 5) return null;
+  const name = parts[0] as string;
+  const version = parts[1] as string;
+  return name !== "" && version !== "" ? { name, version } : null;
+}
+
+/** `pkg-0.2.2.dist-info` directory segment ⇒ version (text after the last dash). */
+export function parseDistInfoDirVersion(relPath: string): string | null {
+  const dir = /(?:^|\/)([^/]+\.dist-info)\//.exec(relPath)?.[1];
+  if (dir === undefined) return null;
+  const stem = dir.slice(0, -".dist-info".length);
+  const idx = stem.lastIndexOf("-");
+  return idx >= 0 ? stem.slice(idx + 1) : null;
+}
+
+/** PEP 503 name canonicalization for cross-artifact matching. */
+const normName = (s: string): string => s.toLowerCase().replace(/[-_.]+/g, "_");
+
+// --------------------------------------------------------------- hit → Finding plumbing
+
+type Hit = { readonly rule: string; readonly message: string; readonly path: string; readonly disc: string };
+
+function toFindings(hits: readonly Hit[], identity: string, sanitizer?: TextSanitizer): Finding[] {
+  return hits.map((hit) => {
+    // digest key mirrors residueFindings: identity:family:rule:disc keeps two independent
+    // drift rows on one (rule, file) pair separately allow-listable.
+    const { valueDigest, snippet } = redact(`${identity}:release-coherence:${hit.rule}:${hit.disc}`);
+    return {
+      rule: hit.rule,
+      severity: RELEASE_COHERENCE_SEVERITIES[hit.rule] as Severity,
+      target: TARGET,
+      path: hit.path,
+      engine: ENGINE,
+      message: sanitizer?.sanitize(hit.message) ?? hit.message,
+      valueDigest,
+      snippet,
+    };
+  });
+}
+
+/** One collected version declaration inside an artifact. */
+type Src = { readonly label: string; readonly path: string; readonly probe: Probe };
+
+/** Primary = first LITERAL source in ecosystem priority order; every other literal is compared
+ *  to it (one CRITICAL per disagreeing source); every dynamic source ⇒ one MEDIUM row. */
+function analyze(sources: readonly Src[], pathPrefix: string, hits: Hit[]): void {
+  const primary = sources.find((s) => s.probe?.status === "literal");
+  for (const s of sources) {
+    if (s.probe === null) continue;
+    if (s.probe.status === "dynamic") {
+      hits.push({
+        rule: RELEASE_COHERENCE_UNVERIFIABLE_RULE,
+        message: `release coherence: ${s.label} (${s.path}) carries a version that cannot be verified statically — ${s.probe.reason}; surfaced, never silent-clean`,
+        path: `${pathPrefix}${s.path}`,
+        disc: `${s.path}:unverifiable`,
+      });
+      continue;
+    }
+    if (primary === undefined || s === primary) continue;
+    if (s.probe.value !== (primary.probe as { value: string }).value) {
+      hits.push({
+        rule: RELEASE_COHERENCE_DRIFT_RULE,
+        message: `release coherence: ${primary.label} '${(primary.probe as { value: string }).value}' disagrees with ${s.label} '${s.probe.value}' — ${FOUNDING}`,
+        path: `${pathPrefix}${s.path}`,
+        disc: `${s.path}:vs:${primary.label}`,
+      });
+    }
+  }
+}
+
+// --------------------------------------------------------------- npm
+
+/** package.json vs package-lock.json root + packages[""] — ONLY when the lock is packed.
+ *  lockText null ⇒ absent source ⇒ zero rows (see boundary note at the header). */
+export function npmPackCoherenceFindings(o: {
+  packedVersion: string | null;
+  lockText: string | null;
+  lockRelPath: string;
+  identity: string;
+  sanitizer?: TextSanitizer;
+}): Finding[] {
+  if (o.lockText === null || o.packedVersion === null) return [];
+  let lock: Record<string, unknown>;
+  try {
+    lock = JSON.parse(o.lockText) as Record<string, unknown>;
+  } catch {
+    return toFindings([{ rule: RELEASE_COHERENCE_UNVERIFIABLE_RULE, message: `release coherence: ${o.lockRelPath} is packed but not parseable JSON — cannot verify, never silent-clean`, path: o.lockRelPath, disc: "malformed" }], o.identity, o.sanitizer);
+  }
+  const hits: Hit[] = [];
+  const rootVer = typeof lock["version"] === "string" ? (lock["version"] as string) : null;
+  const pkgs = lock["packages"];
+  const rootPkg = typeof pkgs === "object" && pkgs !== null ? (pkgs as Record<string, unknown>)[""] : undefined;
+  const pkgEmptyVer = typeof rootPkg === "object" && rootPkg !== null ? ((rootPkg as Record<string, unknown>)["version"]) : null;
+  const cmp = (label: string, value: string | null, disc: string): void => {
+    if (value !== null && value !== o.packedVersion) {
+      hits.push({ rule: RELEASE_COHERENCE_DRIFT_RULE, message: `release coherence: packed package.json version '${String(o.packedVersion)}' disagrees with ${label} '${value}' — ${FOUNDING}`, path: o.lockRelPath, disc });
+    }
+  };
+  cmp("package-lock.json root version", rootVer, "root");
+  cmp('package-lock.json packages[""] version', typeof pkgEmptyVer === "string" ? pkgEmptyVer : null, "packages-empty");
+  return toFindings(hits, o.identity, o.sanitizer);
+}
+
+// --------------------------------------------------------------- pypi (wheel + sdist)
+
+export function pypiArtifactCoherenceFindings(o: {
+  kind: "wheel" | "sdist";
+  archiveName: string;
+  files: readonly string[];
+  read: (rel: string) => string | null;
+  identity: string;
+  sanitizer?: TextSanitizer;
+}): Finding[] {
+  const sources: Src[] = [];
+  const inTree = (rel: string): boolean => o.files.includes(rel);
+  const textOf = (rel: string): string | null => (inTree(rel) ? o.read(rel) : null);
+
+  if (o.kind === "wheel") {
+    const metaRel = o.files.find((f) => /\.dist-info\/METADATA$/.test(f));
+    if (metaRel !== undefined) {
+      const body = o.read(metaRel);
+      sources.push({ label: "wheel METADATA Version:", path: metaRel, probe: body === null ? null : probeHeaderVersion(body) ?? { status: "dynamic", reason: "METADATA has no Version: header" } });
+      const dirVer = parseDistInfoDirVersion(metaRel);
+      if (dirVer !== null) sources.push({ label: "wheel .dist-info directory name", path: metaRel, probe: { status: "literal", value: dirVer } });
+    }
+    const fn = parseWheelFilenameVersion(o.archiveName);
+    if (fn !== null) sources.push({ label: "wheel filename", path: metaRel ?? o.archiveName, probe: { status: "literal", value: fn.version } });
+  } else {
+    const pyproject = textOf("pyproject.toml");
+    if (pyproject !== null) sources.push({ label: "pyproject [project].version", path: "pyproject.toml", probe: probePyprojectVersion(pyproject) });
+    const cfg = textOf("setup.cfg");
+    if (cfg !== null) sources.push({ label: "setup.cfg [metadata] version", path: "setup.cfg", probe: probeSetupCfgVersion(cfg) });
+    const py = textOf("setup.py");
+    if (py !== null) sources.push({ label: "setup.py version literal", path: "setup.py", probe: probeSetupPyVersion(py) });
+    const pkgInfoRel = o.files.find((f) => f === "PKG-INFO" || f.endsWith(".egg-info/PKG-INFO"));
+    if (pkgInfoRel !== undefined) {
+      const body = o.read(pkgInfoRel);
+      if (body !== null) sources.push({ label: "PKG-INFO Version:", path: pkgInfoRel, probe: probeHeaderVersion(body) ?? { status: "dynamic", reason: "PKG-INFO has no Version: header" } });
+    }
+  }
+  for (const initRel of o.files.filter((f) => /(?:^|\/)__init__\.py$/.test(f)).sort()) {
+    const body = o.read(initRel);
+    if (body === null) continue;
+    const probe = probeDunderVersion(body);
+    if (probe !== null) sources.push({ label: `__version__ literal in ${initRel}`, path: initRel, probe });
+  }
+
+  const hits: Hit[] = [];
+  analyze(sources, `${o.archiveName}!`, hits);
+  return toFindings(hits, o.identity, o.sanitizer);
+}
+
+// --------------------------------------------------------------- crates
+
+export function cratesCoherenceFindings(o: {
+  name: string;
+  version: string;
+  lockText: string | null;
+  lockRelPath: string;
+  identity: string;
+  sanitizer?: TextSanitizer;
+}): Finding[] {
+  if (o.lockText === null) return []; // Cargo.lock not packed ⇒ absent source, not drift.
+  const entries = o.lockText
+    .split(/^\[\[package\]\][ \t]*$/m)
+    .map((block) => ({ name: /^\s*name\s*=\s*"([^"]*)"/m.exec(block)?.[1], version: /^\s*version\s*=\s*"([^"]*)"/m.exec(block)?.[1] }))
+    .filter((e): e is { name: string; version: string } => e.name !== undefined && e.version !== undefined)
+    .filter((e) => e.name === o.name);
+  if (entries.length === 0) {
+    return toFindings([{ rule: RELEASE_COHERENCE_UNVERIFIABLE_RULE, message: `release coherence: ${o.lockRelPath} is packed but names no [[package]] '${o.name}' — cannot verify, never silent-clean`, path: o.lockRelPath, disc: "no-entry" }], o.identity, o.sanitizer);
+  }
+  const hits: Hit[] = [];
+  for (const v of [...new Set(entries.map((e) => e.version))].sort()) {
+    if (v !== o.version) {
+      hits.push({ rule: RELEASE_COHERENCE_DRIFT_RULE, message: `release coherence: Cargo.toml [package].version '${o.version}' disagrees with Cargo.lock entry '${o.name}' version '${v}' — ${FOUNDING}`, path: o.lockRelPath, disc: v });
+    }
+  }
+  return toFindings(hits, o.identity, o.sanitizer);
+}
+
+// --------------------------------------------------------------- rubygems
+
+/**
+ * The .gem FORMAT derives the registry name-version from the spec itself, so for a
+ * conventionally-built gem filename↔metadata drift looks vacuous — but it is REACHABLE
+ * through border's own identity seam: channels/gemspec.ts GEMSPEC_VERSION (no /m flag)
+ * takes the FIRST literal `s.version = "..."`, while Ruby evaluates assignments in order
+ * (the LAST wins). A gemspec with two literal s.version assignments therefore produces a
+ * border-guessed `.gem` filename disagreeing with metadata.gz — the shipped bytes' own
+ * claim. metadata.gz is authoritative; this closes exactly that divergence.
+ */
+export function gemCoherenceFindings(o: {
+  specName: string;
+  specVersion: string;
+  metadataText: string | null;
+  identity: string;
+  sanitizer?: TextSanitizer;
+}): Finding[] {
+  if (o.metadataText === null) return []; // non-gem container layout ⇒ absent source, not drift.
+  const name = /^name:[ \t]*(\S+)[ \t]*$/m.exec(o.metadataText)?.[1];
+  const version = /^version:[ \t]*!ruby\/object:Gem::Version[ \t]*\n[ \t]+version:[ \t]*(\S+)[ \t]*$/m.exec(o.metadataText)?.[1];
+  if (name === undefined || version === undefined) {
+    return toFindings([{ rule: RELEASE_COHERENCE_UNVERIFIABLE_RULE, message: "release coherence: metadata.gz is present but its Gem::Specification name/version could not be read statically — cannot verify, never silent-clean", path: "metadata.gz", disc: "unparseable" }], o.identity, o.sanitizer);
+  }
+  const hits: Hit[] = [];
+  if (name !== o.specName) hits.push({ rule: RELEASE_COHERENCE_DRIFT_RULE, message: `release coherence: built gem '${o.identity}' names '${o.specName}' but metadata.gz Gem::Specification name is '${name}' — ${FOUNDING}`, path: "metadata.gz", disc: "name" });
+  if (version !== o.specVersion) hits.push({ rule: RELEASE_COHERENCE_DRIFT_RULE, message: `release coherence: built gem '${o.identity}' names version '${o.specVersion}' but metadata.gz Gem::Version is '${version}' — ${FOUNDING}`, path: "metadata.gz", disc: "version" });
+  return toFindings(hits, o.identity, o.sanitizer);
+}
+
+// --------------------------------------------------------------- release.twin (cross-manager)
+
+export type TwinPair = { readonly pypi: string; readonly npm: string };
+
+/** Read a packed tgz's package.json name+version straight from the STAGED BYTES (tar -xzO;
+ *  no extraction, nothing executed). Returns null when the member/JSON is unreadable. */
+function packedNpmIdentity(archiveAbs: string, env?: Readonly<Record<string, string | undefined>>): { name: string; version: string } | null {
+  const opts = { encoding: "utf8" as const, timeout: 30_000, ...(env !== undefined ? { env: env as NodeJS.ProcessEnv } : {}) };
+  const listing = spawnSync("tar", ["-tzf", archiveAbs], opts);
+  if (listing.status !== 0) return null;
+  const members = (listing.stdout ?? "").split("\n").filter((l) => /^[^/]+\/package\.json$/.test(l));
+  const member = members.includes("package/package.json") ? "package/package.json" : members.length === 1 ? members[0] : undefined;
+  if (member === undefined) return null;
+  const body = spawnSync("tar", ["-xzOf", archiveAbs, member], opts);
+  if (body.status !== 0) return null;
+  try {
+    const pkg = JSON.parse(body.stdout as string) as Record<string, unknown>;
+    return typeof pkg["name"] === "string" && typeof pkg["version"] === "string" ? { name: pkg["name"], version: pkg["version"] } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * release.twin: the ONE place a cross-manager version claim is statically enforceable
+ * (plan W4.1) — when a project declares {pypi, npm} twins, the wheel's version and the npm
+ * twin's PACKED package.json version must be string-equal. Wheels are read by filename
+ * (rule-3 already reconciled filename↔METADATA↔__version__ in the same run); the npm side
+ * is read from the staged tarball bytes. Either side missing/unreadable ⇒ MEDIUM — a
+ * declared obligation that cannot be proven is never silent-clean.
+ */
+export async function twinCoherenceFindings(o: {
+  pairs: readonly TwinPair[];
+  artifacts: readonly LedgerArtifact[];
+  repoDir: string;
+  env?: Readonly<Record<string, string | undefined>>;
+  sanitizer?: TextSanitizer;
+}): Promise<Finding[]> {
+  const wheels = o.artifacts.filter((a) => a.file.endsWith(".whl")).sort((a, b) => a.file.localeCompare(b.file));
+  const tgzs = o.artifacts.filter((a) => a.file.endsWith(".tgz")).sort((a, b) => a.file.localeCompare(b.file));
+  const hits: Hit[] = [];
+  for (const pair of o.pairs) {
+    const wh = wheels.find((a) => {
+      const parsed = parseWheelFilenameVersion(basename(a.file));
+      return parsed !== null && normName(parsed.name) === normName(pair.pypi);
+    });
+    if (wh === undefined) {
+      hits.push({ rule: RELEASE_COHERENCE_UNVERIFIABLE_RULE, message: `release coherence: release.twin pair '${pair.pypi}'/'${pair.npm}' — no staged wheel for '${pair.pypi}' in this run, so the declared cross-manager equality cannot be verified`, path: `${pair.pypi}(missing).whl`, disc: `twin:${pair.pypi}:no-wheel` });
+      continue;
+    }
+    const wheelVersion = (parseWheelFilenameVersion(basename(wh.file)) as { version: string }).version;
+    let npmSide: { file: string; version: string } | null = null;
+    let npmUnreadable = false;
+    for (const t of tgzs) {
+      const id = packedNpmIdentity(join(o.repoDir, t.file), o.env);
+      if (id === null) {
+        npmUnreadable = true;
+        continue;
+      }
+      if (id.name === pair.npm) {
+        npmSide = { file: t.file, version: id.version };
+        break;
+      }
+    }
+    if (npmSide === null) {
+      hits.push({
+        rule: RELEASE_COHERENCE_UNVERIFIABLE_RULE,
+        message: `release coherence: release.twin pair '${pair.pypi}'/'${pair.npm}' — ${npmUnreadable ? `npm twin '${pair.npm}' is staged but its package.json could not be read from the tarball bytes` : `no staged npm artifact for twin '${pair.npm}' in this run`}, so the declared cross-manager equality cannot be verified`,
+        path: basename(wh.file),
+        disc: `twin:${pair.pypi}:no-npm`,
+      });
+      continue;
+    }
+    if (wheelVersion !== npmSide.version) {
+      hits.push({
+        rule: RELEASE_COHERENCE_TWIN_RULE,
+        message: `release coherence: release.twin pair '${pair.pypi}'/'${pair.npm}' — wheel '${basename(wh.file)}' says version '${wheelVersion}' but npm twin '${basename(npmSide.file)}' packed package.json says '${npmSide.version}' — ${FOUNDING}`,
+        path: basename(wh.file),
+        disc: `twin:${pair.pypi}:${basename(npmSide.file)}`,
+      });
+    }
+  }
+  return toFindings(hits, "release.twin", o.sanitizer);
+}

package/dist/assets/residue-src/crates.ts

@@ -24,6 +24,7 @@ import { BORDER_STATE_DIR, ensureStateDir } from "../check/lock.ts";
 import { extractArchive, removeSandbox } from "./extract.ts";
 import { residueFindings } from "./residue.ts";
 import { residueCratesHits } from "./residueRust.ts";
+import { cratesCoherenceFindings } from "../rules/releaseCoherence.ts";
 import { scanTree } from "../engines/gitleaks.ts";
 import { scanPaths, type SecretlintMode } from "../engines/secretlint.ts";
 import { EngineMissingError, EngineRunError, type EngineOptions } from "../engines/support.ts";
@@ -214,6 +215,18 @@ export async function runCargoArtifactStage(o: CrateStageOptions): Promise<Crate
         identity: crateName,
         ...(o.sanitizer !== undefined ? { sanitizer: o.sanitizer } : {}),
       }));
+      // W4.1 release coherence: Cargo.toml [package].version ↔ the packed Cargo.lock's
+      // [[package]] entry for this crate. cargo only ships Cargo.lock when packed —
+      // ABSENT-SOURCE BOUNDARY: unpacked lock is not drift, never a finding.
+      const lockRel = `${identity.name}-${identity.version}/Cargo.lock`;
+      findings.push(...cratesCoherenceFindings({
+        name: identity.name,
+        version: identity.version,
+        lockText: relPaths.includes(lockRel) ? readFileSync(join(extractDir, lockRel), "utf8") : null,
+        lockRelPath: lockRel,
+        identity: crateName,
+        ...(o.sanitizer !== undefined ? { sanitizer: o.sanitizer } : {}),
+      }));
     } finally {
       removeSandbox(extractDir);
     }