border-customs 0.3.1 → 0.4.0

package/README.md

@@ -214,6 +214,45 @@ restate. The empirical roundtrip (install → snapshot → uninstall → rc-delt
 valve. **border is NOT a malware sandbox**: it never executes, intercepts, or sandboxes the
 code it reads; it matches text and blocks the push.
 
+#### Proof valve: `residue.requireProof` (0.4.0)
+
+Static analysis stops at capability. `residue: { requireProof: true }` (strict; default **off**)
+raises the bar for publish channels: when the residue scan flags a blocking-capable finding on a
+staged artifact, `border check` can no longer PASS that channel on signatures alone — the
+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
+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
+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.
+
+- Missing proof ⇒ new native CRITICAL `roundtrip-proof-missing`; proof whose `rulesHash` no
+  longer matches (classifier, engine, or config changed — including the flag flip itself) ⇒
+  `roundtrip-proof-stale`. Freshness is exactly the fingerprint pattern: rotating the policy
+  invalidates cached verdicts, PASSes included.
+- `border roundtrip` records by default (`--record` is the default; opt out with `--no-record`).
+- Both new rules are ordinary findings: the allow-list can waive them and every waiver is
+  enumerated in `allowHits` — no hidden channel.
+
+### 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:
+
+- 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).
+- 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.
+- A `clean` verdict is proof-of-fact about one artifact version on one machine class, not a
+  security guarantee.
+
 ## Architecture: `border push`
 
 `border push` is a state machine over per-target states, recomputed from live git queries,
@@ -375,6 +414,39 @@ dropped file to stderr with the sha256 of its original bytes
 (`border scan: crates envelope normalized: <file> sha256=<hex>`); the rebuild regenerates
 them from the normalized manifest, so no scanned byte is silently lost.
 
+### Engines in consumer installs
+
+`dist/index.js` is one self-contained esbuild bundle and every runtime asset (vendored
+gitleaks rules, prompt template, the secretlint fingerprint snapshot) ships inside `dist/`,
+so after `npm i -D border-customs` (or `-g`) the engine surface is:
+
+- **publint** — installed automatically: it is an exact-pinned runtime dependency of the
+  package, invoked via bin resolution (package-local `node_modules/.bin`, the hoisted
+  project-level `node_modules/.bin`, then `PATH`, then `~/.local/bin`). The
+  `publint-fail` leg of the npm artifact stage works out of the box in a consumer install.
+- **secretlint** — no consumer action, ever: the default lint runs **in-process** with the
+  `@secretlint/*` rule modules already declared as border's own runtime dependencies
+  (`src/engines/secretlint.ts` header). The `mode: "cli"` fallback that spawns a
+  `secretlint` binary is border-internal (test transport); it is not reachable from
+  `border.yaml` or any flag, so installing `secretlint` into your project changes nothing
+  for border. If the engine probe cannot read the bundled lock snapshot
+  (`dist/assets/package-lock.json`), the run fails closed as `DEGRADED-ENGINE` exit 2 —
+  never a silent pass.
+- **gitleaks** — stays external, same posture as `git`: border vendors the 8.30.1 rule
+  config but the binary is yours (on `PATH` or `~/.local/bin/gitleaks`; see the
+  requirements paragraph at the top and `src/engines/ADAPTER-CONTRACT.md`). Missing
+  gitleaks means `border check` records a CRITICAL `DEGRADED-ENGINE` finding and exits 2,
+  and `border scan` exits 2 with `engine binary 'gitleaks' not found; border fails
+  closed`. Neither command degrades to a skip.
+- **trufflehog** — optional third engine, external binary, same posture as gitleaks once
+  enabled: `engines.trufflehog: true` puts it in the required set, and an absent binary
+  degrades the run to exit 2 exactly like a missing gitleaks.
+
+There is no "engine absent ⇒ leg silently skipped" state anywhere: missing required
+engines are exit 2 (`2` = the gate could not answer, see
+[Exit codes](#exit-codes-the-contract)), and the ledger refuses to write a PASS for a
+degraded run.
+
 ## Configuration
 
 Everything border can be told lives in `border.yaml` at the repo root. Unknown keys are
@@ -541,6 +613,30 @@ same one that wrote the commit) how to run the five subcommands, how to produce
 
 ## Changelog
 
+### 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
+  and after uninstall, and reports exactly what the uninstaller left behind. Persistence
+  surfaces (rc/profile mutations) => CRITICAL; orphan files => HIGH. Verdicts record to
+  the ledger by default (`--no-record` opts out); Docker absent => fail-closed, never clean.
+- Add: `residue.requireProof` — when on, a residue-capable artifact only passes `border
+  check` with a fresh recorded roundtrip proof (bound to rulesHash; flipping the config
+  invalidates cached verdicts). Missing proof => CRITICAL `roundtrip-proof-missing`.
+- Opt-in test legs: BORDER_ROUNDTRIP_DOCKER=1 (8 real container legs, 4 ecosystems).
+
+### 0.3.2 (2026-09-10)
+- Fix: CLI invoked through the npm `.bin` shim silently exited 0 without running
+  (entrypoint detection now realpath-canonicalizes both sides). Regression-locked by a
+  pack -> install -> shim-invocation test (`BORDER_PACK_TEST=1`, wired into CI).
+- Fix: `publint` is an exact-pinned runtime dependency, so `border scan`/npm checks work
+  out of the box in consumer installs; README documents the engine posture truthfully.
+- Add: release-coherence seed test pinning the scan User-Agent version to package.json.
+
+### 0.3.1 (2026-09-10)
+- Add: `border scan [ecosystem:]name@version` — static residue inspection of third-party
+  registry packages (npm/PyPI/crates.io/RubyGems), ledger-free by design.
+- Docs: README scan section; crates envelope normalization now logs scrubbed-file hashes.
+
 ### 0.3.0 (2026-09-09)
 
 - **Residue gate (artifact stage).** The blanket install-hook CRITICAL becomes a classified
@@ -584,4 +680,14 @@ 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 不是恶意软件沙箱,从不执行被读代码。可选 LLM 层 border 自身从不调用模型 API:`llm-request` 导出掩码审阅包,`llm-ingest` 严格校验 agent 结论并重算裁决。退出码即合同:0 通过、1 拦截、2 门禁无法作答,任何"工具不健康"都不可能被误读为干净。MIT 许可,无遥测,除你配置的注册表预检外不联网。
+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
+两种裁决都算"事实已在";缺记录判 `roundtrip-proof-missing`、rulesHash 过期判
+`roundtrip-proof-stale`(均 CRITICAL/native,与普通发现同受白名单管辖并在 allowHits 枚举),翻转
+该配置即轮换 rulesHash,所有缓存 PASS 自动失效。`border roundtrip` 本身保真边界:Docker 必需、
+缺失即 exit 2 绝不假装干净;pypi 通道会把 pip 遗留的传递依赖如实报成孤儿行(收窄到目标包自身是
+已知后续项);只有包管理器生命周期触发的写入被观测,显式调用的 bin 自写配置不在射程——W2.3 在
+自家 registrar 链上实测到该盲区并留下了 `{"plugin": []}` 残留证据。clean 是"某一版本构件在某类
+机器上"的事实证明,不是安全担保。可选 LLM 层 border 自身从不调用模型 API:`llm-request` 导出掩码审阅包,`llm-ingest` 严格校验 agent 结论并重算裁决。退出码即合同:0 通过、1 拦截、2 门禁无法作答,任何"工具不健康"都不可能被误读为干净。MIT 许可,无遥测,除你配置的注册表预检外不联网。

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "border-customs",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "border",
-      "version": "0.1.0",
+      "name": "border-customs",
+      "version": "0.3.1",
       "license": "MIT",
       "dependencies": {
         "@secretlint/core": "13.0.5",
@@ -14,6 +14,7 @@
         "@secretlint/secretlint-rule-no-homedir": "13.0.5",
         "@secretlint/secretlint-rule-pattern": "13.0.5",
         "@secretlint/secretlint-rule-preset-recommend": "13.0.5",
+        "publint": "0.3.24",
         "yaml": "2.9.0",
         "zod": "4.5.4"
       },
@@ -23,7 +24,6 @@
       "devDependencies": {
         "@types/node": "22.19.0",
         "esbuild": "0.25.12",
-        "publint": "0.3.24",
         "secretlint": "13.0.5",
         "typescript": "5.9.3",
         "verdaccio": "6.10.2"
@@ -601,7 +601,6 @@
       "version": "0.1.7",
       "resolved": "https://registry.npmjs.org/@publint/pack/-/pack-0.1.7.tgz",
       "integrity": "sha512-4EDEmvxWtgsCnnVeBvtFIFZtUhPPt1+bA9JrSwU4Sa//6oKtzCSlGGXYJr44OD9aGISymbieJ4mCKHUygUDU+g==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "tinyexec": "^1.3.0"
@@ -3821,7 +3820,6 @@
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/mri/-/mri-1.2.0.tgz",
       "integrity": "sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=4"
@@ -3982,7 +3980,6 @@
       "version": "1.8.0",
       "resolved": "https://registry.npmjs.org/package-manager-detector/-/package-manager-detector-1.8.0.tgz",
       "integrity": "sha512-yQA4H19AmPEoMUeavPMDIe1higySl/gH/yaQrkT/s07Qp+7pp2hYz30N3z2l5BkjVkF9Ow6o0wjJamm2y7Sn0A==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/pako": {
@@ -4073,7 +4070,6 @@
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
       "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
-      "dev": true,
       "license": "ISC"
     },
     "node_modules/picomatch": {
@@ -4255,7 +4251,6 @@
       "version": "0.3.24",
       "resolved": "https://registry.npmjs.org/publint/-/publint-0.3.24.tgz",
       "integrity": "sha512-9zS56KrKBoqi5Qt8h92uMP8TTM9AYZSgnmCo4u2priMqkOZvQnTsziZ2p5LJ2ywbYkAjoCDp2jda9u4cgFefIw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@publint/pack": "^0.1.7",
@@ -4551,7 +4546,6 @@
       "version": "1.8.1",
       "resolved": "https://registry.npmjs.org/sade/-/sade-1.8.1.tgz",
       "integrity": "sha512-xal3CZX1Xlo/k4ApwCFrHVACi9fBqJ7V+mwhBsuf/1IOKbBy098Fex+Wa/5QMubw09pSZ/u8EY8PWgevJsXp1A==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "mri": "^1.1.0"
@@ -5231,7 +5225,6 @@
       "version": "1.3.1",
       "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.1.tgz",
       "integrity": "sha512-GCvB3aoys96IuDFBMcTB46JOR6mdMtAToqwiW8JlWhsoh1mhHi/xn9ss/Dg7N555GiJyEt2qzoG/NHCwM6h1EA==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=18"

package/dist/index.js

@@ -13028,7 +13028,8 @@ var require_micromatch = __commonJS({
 });
 
 // src/index.ts
-import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+import { fileURLToPath as fileURLToPath5, pathToFileURL } from "node:url";
 
 // src/cli.ts
 import { parseArgs } from "node:util";
@@ -37896,10 +37897,14 @@ var NPM_TARGET_LABEL = "artifact";
 var DEFAULT_TOOL_TIMEOUT_MS = 12e4;
 var MESSAGE_TAIL_CHARS = 600;
 var HERE = dirname3(fileURLToPath3(import.meta.url));
-var PUBLINT_LOCAL_BINS = [
-  join6(HERE, "..", "node_modules", ".bin", "publint"),
-  join6(HERE, "..", "..", "node_modules", ".bin", "publint")
-];
+function publintLocalBins(here) {
+  return [
+    join6(here, "..", "node_modules", ".bin", "publint"),
+    join6(here, "..", "..", "node_modules", ".bin", "publint"),
+    join6(here, "..", "..", ".bin", "publint")
+  ];
+}
+var PUBLINT_LOCAL_BINS = publintLocalBins(HERE);
 function tail(text) {
   const trimmed = text.trim();
   return trimmed.length > MESSAGE_TAIL_CHARS ? `${trimmed.slice(-MESSAGE_TAIL_CHARS)}\u2026` : trimmed;
@@ -39839,6 +39844,20 @@ function buildPushRecord(i) {
     ts: i.ts ?? (/* @__PURE__ */ new Date()).toISOString()
   };
 }
+function buildRoundtripRecord(i) {
+  if (!HEX64.test(i.artifactSha256)) bad("artifactSha256 is not hex-shaped");
+  if (!HEX64.test(i.rulesHash)) bad("rulesHash is not hex-shaped");
+  if (i.verdict !== "clean" && i.verdict !== "residue") bad(`verdict must be clean or residue, got '${i.verdict}'`);
+  if (!Number.isInteger(i.rows) || i.rows < 0) bad("rows must be a non-negative integer");
+  return {
+    t: "roundtrip",
+    artifactSha256: i.artifactSha256,
+    verdict: i.verdict,
+    rulesHash: i.rulesHash,
+    rows: i.rows,
+    ts: i.ts ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
 function bad(msg) {
   throw new Error(msg);
 }
@@ -39929,6 +39948,20 @@ function parseLedgerRecord(value) {
       ts: needString(o, "ts")
     };
   }
+  if (t === "roundtrip") {
+    const verdict = needString(o, "verdict");
+    if (verdict !== "clean" && verdict !== "residue") bad(`verdict must be clean or residue, got '${verdict}'`);
+    const rows = o.rows;
+    if (typeof rows !== "number" || !Number.isInteger(rows) || rows < 0) bad("rows must be a non-negative integer");
+    return {
+      t: "roundtrip",
+      artifactSha256: needHex(o, "artifactSha256", HEX64),
+      verdict,
+      rulesHash: needHex(o, "rulesHash", HEX64),
+      rows,
+      ts: needString(o, "ts")
+    };
+  }
   return bad(`unknown record type ${JSON.stringify(t)}`);
 }
 function codeOf2(err) {
@@ -39981,6 +40014,13 @@ function latestPassCoveringTargets(records, key, targets) {
 function pushRecords(records, key) {
   return records.filter((r) => r.t === "push" && (key === void 0 || r.key === key));
 }
+function latestRoundtripForSha(records, artifactSha256) {
+  for (let i = records.length - 1; i >= 0; i -= 1) {
+    const r = records[i];
+    if (r !== void 0 && r.t === "roundtrip" && r.artifactSha256 === artifactSha256) return r;
+  }
+  return null;
+}
 
 // src/ledger/retention.ts
 import { existsSync as existsSync9, mkdirSync as mkdirSync6, readdirSync as readdirSync5, rmSync as rmSync6 } from "node:fs";
@@ -41950,8 +41990,17 @@ function buildBorderConfigSchema() {
     // of the residue scan is this toggle; a scan that cannot RUN is a FAIL
     // (fail-closed doctrine), and the digest seam keeps every cached PASS
     // honest about the residue sources it was certified against.
+    // W2.2 (border-inspect-roadmap): requireProof arms the PROOF VALVE — a
+    // blocking residue-* row on a staged artifact then additionally demands a
+    // fresh `t:"roundtrip"` ledger record for that artifact's sha256 before
+    // the channel may PASS. Default FALSE (0.3.x behavior byte-identical);
+    // the valve reads `residue?.requireProof === true`, so absence IS the
+    // false default — same construction contract as the outer key. The flag
+    // rides the whole-object configDigest (stableStringify), so flipping it
+    // rotates the check rulesHash and the ledger refuses every cached PASS.
     residue: external_exports.object({
-      enabled: external_exports.boolean().default(true)
+      enabled: external_exports.boolean().default(true),
+      requireProof: external_exports.boolean().default(false)
     }).strict().optional()
   }).strict();
 }
@@ -42402,6 +42451,44 @@ function applyAllowList(findings, allow, repoDir) {
   return { kept, allowHits: [...hits.values()] };
 }
 
+// src/check/proofValve.ts
+var ROUNDTRIP_PROOF_MISSING_RULE = "roundtrip-proof-missing";
+var ROUNDTRIP_PROOF_STALE_RULE = "roundtrip-proof-stale";
+var RESIDUE_RULE_IDS = new Set(Object.keys(RESIDUE_SEVERITIES));
+function hasBlockingResidueCapability(findings) {
+  return findings.some((f) => RESIDUE_RULE_IDS.has(f.rule) && isBlocking(f.severity));
+}
+function proofFinding(rule, art, cause) {
+  return {
+    rule,
+    severity: "CRITICAL",
+    target: "artifact",
+    path: art.file,
+    engine: "native",
+    message: `${art.file} (sha256 ${art.sha256.slice(0, 12)}\u2026) tripped the residue scan while residue.requireProof is on, but ${cause}. Run 'border roundtrip <spec>' for exactly these bytes to mint the ledger proof.`,
+    ...redact(`${art.sha256}:${cause}`),
+    snippet: `${art.file} ${art.sha256.slice(0, 12)}`
+  };
+}
+function proofFindings(o) {
+  const out = [];
+  for (const art of o.artifacts) {
+    const rec = latestRoundtripForSha(o.records, art.sha256);
+    if (rec === null) {
+      out.push(proofFinding(ROUNDTRIP_PROOF_MISSING_RULE, art, "no roundtrip proof record exists for its digest"));
+    } else if (rec.rulesHash !== o.rulesHash) {
+      out.push(
+        proofFinding(
+          ROUNDTRIP_PROOF_STALE_RULE,
+          art,
+          `its proof record predates the current rules policy (recorded ${rec.rulesHash.slice(0, 12)}\u2026, required ${o.rulesHash.slice(0, 12)}\u2026)`
+        )
+      );
+    }
+  }
+  return out;
+}
+
 // src/check/tagScan.ts
 import { spawnSync as spawnSync12 } from "node:child_process";
 import { mkdtempSync as mkdtempSync3, rmSync as rmSync10, writeFileSync as writeFileSync4 } from "node:fs";
@@ -42518,7 +42605,6 @@ function scanTagMessages(o) {
 
 // src/check.ts
 var TRACKED_BORDER_RULE = "repo-tracks-border-state";
-var RESIDUE_RULE_IDS = new Set(Object.keys(RESIDUE_SEVERITIES));
 var GUARD_PATH_CAP = 50;
 function trackedBorderStateFinding(repoDir, headSha, env2) {
   const listing = runGitChecked(repoDir, ["ls-files", "--", `${BORDER_STATE_DIR}/`], { ...env2 !== void 0 ? { env: env2 } : {} }).split("\n").filter((p) => p !== "");
@@ -42607,13 +42693,16 @@ async function runPipeline(o, ctx, lockWarning) {
       if (f !== void 0 && RESIDUE_RULE_IDS.has(f.rule)) findings.splice(i, 1);
     }
   }
-  const exposure = [...exposureSet(o.cfg, { cwd: repoDir })];
-  const allow = applyAllowList(findings, o.cfg.allow, repoDir);
   const rulesHash = await computeCheckRulesHash({
     engineVersions: probe.engineVersions,
     configDigest: o.configDigest,
     ...o.env !== void 0 ? { env: o.env } : {}
   });
+  if (o.cfg.residue?.requireProof === true && ledgerArtifacts.length > 0 && hasBlockingResidueCapability(findings)) {
+    findings.push(...proofFindings({ artifacts: ledgerArtifacts, records: readLedger(repoDir).records, rulesHash }));
+  }
+  const exposure = [...exposureSet(o.cfg, { cwd: repoDir })];
+  const allow = applyAllowList(findings, o.cfg.allow, repoDir);
   const report = {
     schemaVersion: 1,
     key: computeCheckKey({
@@ -43431,41 +43520,18 @@ async function executeYesPush(ctx, loaded) {
   return EXIT_PASS;
 }
 
-// src/scan/scan.ts
-import { mkdtempSync as mkdtempSync5 } from "node:fs";
+// src/roundtrip/orchestrate.ts
+import { mkdtempSync as mkdtempSync5, rmSync as rmSync12, writeFileSync as writeFileSync7 } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { tmpdir as tmpdir3 } from "node:os";
-import { join as join26 } from "node:path";
-
-// src/scan/config.ts
-function buildScanConfigYaml(eco) {
-  return [
-    "version: 1",
-    "targets:",
-    "  git:",
-    "    remotes: []",
-    `  ${eco}: {}`,
-    "rules:",
-    "  authors:",
-    "    emails: []",
-    "    names: []",
-    "  hosts: []",
-    "  ips: []",
-    "  pathPatterns: []",
-    "residue:",
-    "  enabled: true",
-    ""
-  ].join("\n");
-}
-function synthesizeScanConfig(eco) {
-  return parseConfig(buildScanConfigYaml(eco), "<border scan>");
-}
+import { join as join25 } from "node:path";
 
 // src/scan/fetch.ts
 import { createHash as createHash15 } from "node:crypto";
 import { basename as basename4 } from "node:path";
 var SCAN_MAX_ARTIFACT_BYTES = 200 * 1024 * 1024;
 var SCAN_REQUEST_TIMEOUT_MS = 6e4;
-var SCAN_USER_AGENT = "border-customs/0.3.0 (+https://github.com/sumteclab/border; border scan)";
+var SCAN_USER_AGENT = "border-customs/0.4.0 (+https://github.com/sumteclab/border; border scan)";
 var CRATES_DOWNLOAD_HOST = "https://static.crates.io";
 var defaultScanFetcher = async (url2, init) => {
   if (!/^https?:\/\//.test(url2)) throw new EngineRunError(`border scan refuses non-http(s) URL: ${url2}`, null);
@@ -43594,9 +43660,402 @@ function sha256Hex(data) {
   return createHash15("sha256").update(data).digest("hex");
 }
 
+// src/scan/spec.ts
+var ECOSYSTEMS = ["npm", "pypi", "crates", "rubygems"];
+var SCAN_SPEC_USAGE = "usage: border scan <[ecosystem:]name@version> \u2014 e.g. border scan puppeteer@23.11.1 | pypi:requests@2.32.3 | crates:serde@1.0.219 | rubygems:rails@7.1.1";
+var PLAIN_NAME = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+var SCOPED_NAME = /^@[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+var VERSION = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+var bad2 = (why) => {
+  throw new UnknownArgError(`${why}; ${SCAN_SPEC_USAGE}`);
+};
+function parseScanSpec(raw) {
+  const text = raw.trim();
+  if (text.length === 0) return bad2("empty spec");
+  let ecosystem = "npm";
+  let rest = text;
+  const colon = text.indexOf(":");
+  if (colon >= 0) {
+    const prefix = text.slice(0, colon);
+    const found = ECOSYSTEMS.find((e) => e === prefix);
+    if (found === void 0) {
+      return bad2(`unknown ecosystem '${prefix}' \u2014 expected one of: ${ECOSYSTEMS.join(", ")}`);
+    }
+    ecosystem = found;
+    rest = text.slice(colon + 1);
+    if (rest.length === 0) return bad2("missing package name after the ecosystem prefix");
+  }
+  const scoped = rest.startsWith("@");
+  const at = rest.lastIndexOf("@");
+  if (at <= 0) return bad2(`spec '${raw}' is missing '@version'`);
+  const name = rest.slice(0, at);
+  const version2 = rest.slice(at + 1);
+  if (!(scoped ? SCOPED_NAME : PLAIN_NAME).test(name)) {
+    return bad2(`invalid package name '${name}'`);
+  }
+  if (!VERSION.test(version2)) {
+    return bad2(`invalid version '${version2}' in spec '${raw}'`);
+  }
+  return { ecosystem, name, version: version2 };
+}
+
+// src/roundtrip/docker.ts
+var DOCKER_PROBE_TIMEOUT_MS = 15e3;
+var DOCKER_RUN_TIMEOUT_MS = 12e4;
+var DOCKER_CP_TIMEOUT_MS = 12e4;
+var SNAPSHOT_TIMEOUT_MS = 12e4;
+var PHASE_TIMEOUT_MS = 6e5;
+var DOCKER_RM_TIMEOUT_MS = 6e4;
+var CONTAINER_TTL_SEC = 900;
+var BASE_EXCLUDES = [
+  "/proc",
+  "/sys",
+  "/dev",
+  "/root/.npm",
+  "/tmp/node-compile-cache",
+  "/etc/hostname",
+  "/etc/resolv.conf",
+  "/etc/hosts"
+];
+var PYTHON_EXCLUDES = ["/root/.cache", "/var/log", "/var/lib/apt/lists", "*/__pycache__"];
+var CARGO_EXCLUDES = ["/root/.cargo", "/usr/local/cargo", "/usr/local/.crates2.json", "/usr/local/.crates.toml"];
+function snapshotScript(excludes) {
+  const prune = `"(" ${excludes.map((p) => `-path "${p}"`).join(" -o ")} ")" -prune -o`;
+  return [
+    "set -e",
+    'T=/dev/shm/rt-snap.$$; mkdir -p "$T"',
+    `find / -xdev ${prune} -type f -print0 > "$T/f0"`,
+    // || true: a file can vanish between find passes (package managers churn
+    // temp state); the missing row is consistent noise, not a false residue.
+    `xargs -0 -r sha256sum < "$T/f0" 2>/dev/null > "$T/hashes" || true`,
+    // sha256sum text mode = 64 hex + 2 spaces + path; substr keeps spaced paths whole.
+    `awk '{ printf "F\\t%s\\t%s\\n", substr($0,67), substr($0,1,64) }' "$T/hashes" > "$T/files"`,
+    `find / -xdev ${prune} -type l -printf 'L\\t%p\\t%l\\n' > "$T/links"`,
+    `find / -xdev ${prune} -type d -printf 'D\\t%p\\t-\\n' > "$T/dirs"`,
+    'LC_ALL=C sort "$T/files" "$T/links" "$T/dirs"',
+    'rm -rf "$T"'
+  ].join("\n");
+}
+function realDockerExec() {
+  return (args, timeoutMs) => {
+    const r = spawnEngine(binaryCandidates("docker", {}), [...args], { timeoutMs });
+    return { status: r.status, stdout: r.stdout, stderr: r.stderr };
+  };
+}
+
+// src/roundtrip/manifest.ts
+import { createHash as createHash16 } from "node:crypto";
+var RT_ENGINE = "roundtrip";
+var RT_RESIDUE_RULE = "roundtrip-residue-file";
+var RT_MODIFY_RULE = "roundtrip-modified-file";
+var RT_PERSIST_RULE = "roundtrip-modified-persistence";
+var KEY_SEP = "";
+var keyOf = (kind, path4) => `${kind}${KEY_SEP}${path4}`;
+function parseManifest(text) {
+  const out = /* @__PURE__ */ new Map();
+  for (const line of text.split("\n")) {
+    if (line.length === 0) continue;
+    const parts = line.split("	");
+    if (parts.length < 3) continue;
+    const kind = parts[0];
+    const path4 = parts[1];
+    const value = parts.slice(2).join("	");
+    if (kind !== "F" && kind !== "L" && kind !== "D") continue;
+    out.set(keyOf(kind, path4), { kind, path: path4, value });
+  }
+  return out;
+}
+function diffManifests(before, after) {
+  const added = [];
+  const removed = [];
+  const modified = [];
+  for (const [key, entry] of after) {
+    const old = before.get(key);
+    if (old === void 0) added.push(entry);
+    else if (old.value !== entry.value) modified.push(entry);
+  }
+  for (const [key, entry] of before) {
+    if (!after.has(key)) removed.push(entry);
+  }
+  return { added, removed, modified };
+}
+var PERSISTENCE_PATTERNS = [
+  /(^|\/)\.(bashrc|bash_profile|bash_login|profile|zshrc|zprofile|zshenv|kshrc|cshrc|login\.sh)$/,
+  /^\/etc\/profile\.d\//,
+  /^\/etc\/(bash\.bashrc|profile|environment|zsh\/zshrc|inputrc)$/,
+  /^\/etc\/systemd\//,
+  /(^|\/)\.config\/systemd\//,
+  /(^|\/)systemd\/system\//,
+  /(^|\/)(cron|cron\.d|cron\.[0-9dhmwy]+|spool\/cron)\//,
+  /^\/etc\/crontab$/,
+  /(^|\/)\.config\/fish\//,
+  /^\/(usr\/)?(local\/)?(s?bin)\//,
+  /(^|\/)\.local\/bin\//
+];
+function isPersistenceSurface(path4) {
+  return PERSISTENCE_PATTERNS.some((re) => re.test(path4));
+}
+var digestOf = (what) => createHash16("sha256").update(what).digest("hex");
+function classifyResidue(label, diff) {
+  const findings = [];
+  for (const e of diff.added) {
+    findings.push({
+      rule: RT_RESIDUE_RULE,
+      severity: "HIGH",
+      target: label,
+      path: e.path,
+      engine: RT_ENGINE,
+      message: `installed file survived uninstall (ADDED in post-uninstall manifest)`,
+      valueDigest: digestOf(`ADDED:${e.path}:${e.value}`),
+      snippet: `residue: ${e.path}`
+    });
+  }
+  for (const e of diff.modified) {
+    const persist = isPersistenceSurface(e.path);
+    findings.push({
+      rule: persist ? RT_PERSIST_RULE : RT_MODIFY_RULE,
+      severity: persist ? "CRITICAL" : "HIGH",
+      target: label,
+      path: e.path,
+      engine: RT_ENGINE,
+      message: persist ? `uninstall mutated a persistence surface (rc/systemd/cron/PATH) \u2014 content differs pre-install vs post-uninstall` : `file content differs pre-install vs post-uninstall (MODIFIED, not reverted by uninstall)`,
+      valueDigest: digestOf(`MODIFIED:${e.path}:${e.value}`),
+      snippet: persist ? `persistence: ${e.path}` : `modified: ${e.path}`
+    });
+  }
+  return findings;
+}
+
+// src/roundtrip/orchestrate.ts
+function containerNameFor(label, rand = randomBytes(3).toString("hex")) {
+  return `rt-${sha256Hex(label).slice(0, 8)}-${rand}`;
+}
+var shArgv = (name) => {
+  if (!/^[A-Za-z0-9@._+/-]+$/.test(name)) {
+    throw new EngineRunError(`roundtrip: package name '${name}' rejected for shell composition`, null);
+  }
+  return [name];
+};
+var PROFILES = {
+  npm: {
+    image: "node:24-slim",
+    artifactPath: "/root/p.tgz",
+    excludes: BASE_EXCLUDES,
+    install: (p) => ["npm", "install", "-g", "--foreground-scripts", "--no-audit", "--no-fund", p],
+    uninstall: (s) => ["npm", "uninstall", "-g", shArgv(s.name)[0]]
+  },
+  pypi: {
+    image: "python:3.12-slim",
+    artifactPath: "/root/p.tar.gz",
+    excludes: [...BASE_EXCLUDES, ...PYTHON_EXCLUDES],
+    install: (p) => ["pip", "install", "--no-input", "--root-user-action=ignore", p],
+    uninstall: (s) => ["pip", "uninstall", "-y", shArgv(s.name)[0]]
+  },
+  rubygems: {
+    image: "ruby:3.4-slim",
+    artifactPath: "/root/p.gem",
+    excludes: BASE_EXCLUDES,
+    install: (p) => ["gem", "install", "--no-document", p],
+    uninstall: (s) => ["gem", "uninstall", shArgv(s.name)[0], "-x", "--force"]
+  },
+  crates: {
+    image: "rust:1-slim",
+    artifactPath: "/root/p.crate",
+    excludes: [...BASE_EXCLUDES, ...CARGO_EXCLUDES],
+    // W2.1 docker legs, verified on rust:1-slim / cargo 1.98: a bare positional
+    // is parsed as a CRATE@VER spec (a directory 400s on "invalid character `/`"),
+    // so the unpacked staging dir goes through --path; --no-track must NOT be
+    // used because it suppresses the $ROOT/.crates2.json install record, which is
+    // the only thing `cargo uninstall` reads (with it, every uninstall dies on
+    // "package ID specification did not match"); and border's own /opt/<dir>
+    // staging tree is never owned by cargo, so the chain that creates it removes
+    // it — after `cargo install` succeeded, keeping install failure fail-closed.
+    install: (p, s) => {
+      const name = shArgv(s.name)[0];
+      const dir = `${name}-${s.version}`;
+      return ["sh", "-c", `tar xf ${p} -C /opt && cargo install --root /usr/local --path "/opt/${dir}" && rm -rf "/opt/${dir}"`];
+    },
+    uninstall: (s) => ["cargo", "uninstall", "--root", "/usr/local", shArgv(s.name)[0]]
+  }
+};
+function profileFor(eco) {
+  return PROFILES[eco];
+}
+function execChecked(exec, args, timeoutMs, what) {
+  const r = exec(args, timeoutMs);
+  if (r.status !== 0) {
+    const tail3 = r.stderr.replace(/\s+/g, " ").slice(-240);
+    throw new EngineRunError(`roundtrip: ${what} failed (exit ${String(r.status)})${tail3 ? `: ${tail3}` : ""} \u2014 cannot verify (fail-closed)`, r.status);
+  }
+  return r;
+}
+function runPipeline2(exec, profile, spec, label, hostPath, container) {
+  execChecked(exec, ["run", "-d", "--name", container, profile.image, "sleep", String(CONTAINER_TTL_SEC)], DOCKER_RUN_TIMEOUT_MS, "container start");
+  try {
+    execChecked(exec, ["cp", hostPath, `${container}:${profile.artifactPath}`], DOCKER_CP_TIMEOUT_MS, "artifact copy");
+    const m1 = parseManifest(takeSnapshot(exec, container, profile.excludes));
+    execChecked(exec, ["exec", container, ...profile.install(profile.artifactPath, spec)], PHASE_TIMEOUT_MS, `install ${label}`);
+    const m2 = parseManifest(takeSnapshot(exec, container, profile.excludes));
+    const installDiff = diffManifests(m1, m2);
+    const installDelta = installDiff.added.length + installDiff.removed.length + installDiff.modified.length;
+    if (installDelta === 0) {
+      throw new EngineRunError(
+        `roundtrip: install of ${label} produced an empty filesystem delta \u2014 cannot verify it ran, refusing to grade a no-op`,
+        null
+      );
+    }
+    execChecked(exec, ["exec", container, ...profile.uninstall(spec)], PHASE_TIMEOUT_MS, `uninstall ${label}`);
+    const m3 = parseManifest(takeSnapshot(exec, container, profile.excludes));
+    return {
+      findings: classifyResidue(label, diffManifests(m1, m3)),
+      installDelta,
+      baselineDigest: sha256Hex([...m1.keys()].join("\n"))
+    };
+  } finally {
+    try {
+      exec(["rm", "-f", container], DOCKER_RM_TIMEOUT_MS);
+    } catch {
+    }
+  }
+}
+function takeSnapshot(exec, container, excludes) {
+  return execChecked(
+    exec,
+    ["exec", container, "sh", "-c", snapshotScript(excludes)],
+    SNAPSHOT_TIMEOUT_MS,
+    "manifest snapshot"
+  ).stdout;
+}
+async function runRoundtripCore(ctx, deps = {}) {
+  const raw = ctx.positionals[0];
+  if (ctx.positionals.length !== 1 || raw === void 0) {
+    throw new UnknownArgError(
+      `border roundtrip expects exactly one <spec> argument (got ${String(ctx.positionals.length)}); ${SCAN_SPEC_USAGE}`
+    );
+  }
+  const spec = parseScanSpec(raw);
+  const profile = profileFor(spec.ecosystem);
+  const label = `${spec.ecosystem}:${spec.name}@${spec.version}`;
+  const exec = deps.exec ?? realDockerExec();
+  if (!dockerAvailableGuard(exec)) {
+    ctx.stderr("roundtrip: docker unavailable \u2014 cannot verify");
+    return EXIT_ERROR;
+  }
+  const baseDir = mkdtempSync5(join25(tmpdir3(), "border-roundtrip-"));
+  try {
+    const { bytes } = await fetchArtifact(spec, { fetcher: deps.fetcher ?? defaultScanFetcher });
+    const hostPath = join25(baseDir, "artifact");
+    writeFileSync7(hostPath, bytes);
+    const container = containerNameFor(label);
+    const { findings, installDelta, baselineDigest } = runPipeline2(exec, profile, spec, label, hostPath, container);
+    const verdict = computeVerdict(findings);
+    const report = {
+      schemaVersion: 1,
+      key: sha256Hex(`roundtrip:${label}:${baselineDigest}:${verdict}`),
+      head: baselineDigest.slice(0, 40),
+      dirty: false,
+      exposureSet: [label],
+      refSet: [],
+      rulesHash: sha256Hex(`${profile.image}|${profile.install(profile.artifactPath, spec).join(" ")}|${profile.uninstall(spec).join(" ")}`),
+      verdict,
+      counts: countFindings(findings),
+      findings,
+      ts: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const sanitizer = new TextSanitizer();
+    const line = (text) => sanitizer.sanitize(text).replace(/\s+/g, " ").trim();
+    if (ctx.flags.json) {
+      ctx.stdout(renderReportJson(report));
+    } else {
+      for (const f of report.findings) {
+        ctx.stdout(line(`  ${f.severity} ${f.rule} [${f.engine}] ${f.path ?? f.target} ${f.message}`));
+      }
+      ctx.stdout(line(`roundtrip: ${String(report.findings.length)} residue row(s); install-delta ${String(installDelta)} files`));
+    }
+    if (ctx.flags.record !== false) {
+      await recordRoundtripProof(ctx, sha256Hex(bytes), report.findings.length, report.findings.length === 0 ? "clean" : "residue");
+    }
+    return exitCodeFromVerdict(verdict);
+  } finally {
+    rmSync12(baseDir, { recursive: true, force: true });
+  }
+}
+async function recordRoundtripProof(ctx, artifactSha256, rows, verdict) {
+  const notice = (msg) => ctx.stderr(`roundtrip: ${msg}`);
+  try {
+    const env2 = ctx.env;
+    const load = loadConfig({
+      cwd: ctx.cwd,
+      ...ctx.flags.config !== void 0 ? { configPath: ctx.flags.config } : {},
+      ...env2 !== void 0 ? { env: env2 } : {}
+    });
+    let effective = null;
+    if (load.kind === "loaded") effective = load;
+    else if (load.explicit !== void 0) effective = { kind: "loaded", config: load.explicit.config, warnings: [], source: load.explicit.source };
+    if (effective === null) {
+      notice("no border.yaml here \u2014 proof NOT recorded");
+      return;
+    }
+    const repoDir = resolveRepoDir(ctx.cwd, { ...env2 !== void 0 ? { env: env2 } : {} });
+    const probe = await probeEngines(effective.config, { ...env2 !== void 0 ? { env: env2 } : {} });
+    if (probe.degraded) {
+      notice("engine probe degraded \u2014 cannot mint the rulesHash this proof must match; proof NOT recorded");
+      return;
+    }
+    const rulesHash = await computeCheckRulesHash({
+      engineVersions: probe.engineVersions,
+      configDigest: computeConfigDigest(effective),
+      ...env2 !== void 0 ? { env: env2 } : {}
+    });
+    appendRecord(repoDir, buildRoundtripRecord({ artifactSha256, verdict, rulesHash, rows }));
+    notice(`proof recorded for ${artifactSha256.slice(0, 12)}\u2026 (verdict ${verdict}, ${String(rows)} residue row(s))`);
+  } catch (err) {
+    notice(`proof NOT recorded (${err instanceof Error ? err.message : String(err)}) \u2014 'border check' with residue.requireProof will treat this artifact as unproven`);
+  }
+}
+function dockerAvailableGuard(exec) {
+  try {
+    return exec(["--version"], DOCKER_PROBE_TIMEOUT_MS).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// src/commands/roundtrip.ts
+var runRoundtrip = (ctx) => runRoundtripCore(ctx);
+
+// src/scan/scan.ts
+import { mkdtempSync as mkdtempSync6 } from "node:fs";
+import { tmpdir as tmpdir4 } from "node:os";
+import { join as join27 } from "node:path";
+
+// src/scan/config.ts
+function buildScanConfigYaml(eco) {
+  return [
+    "version: 1",
+    "targets:",
+    "  git:",
+    "    remotes: []",
+    `  ${eco}: {}`,
+    "rules:",
+    "  authors:",
+    "    emails: []",
+    "    names: []",
+    "  hosts: []",
+    "  ips: []",
+    "  pathPatterns: []",
+    "residue:",
+    "  enabled: true",
+    ""
+  ].join("\n");
+}
+function synthesizeScanConfig(eco) {
+  return parseConfig(buildScanConfigYaml(eco), "<border scan>");
+}
+
 // src/scan/materialize.ts
-import { existsSync as existsSync17, mkdirSync as mkdirSync11, readdirSync as readdirSync10, readFileSync as readFileSync16, rmSync as rmSync12, writeFileSync as writeFileSync7 } from "node:fs";
-import { join as join25 } from "node:path";
+import { existsSync as existsSync17, mkdirSync as mkdirSync11, readdirSync as readdirSync10, readFileSync as readFileSync16, rmSync as rmSync13, writeFileSync as writeFileSync8 } from "node:fs";
+import { join as join26 } from "node:path";
 var CRATES_ENVELOPE_FILES = ["Cargo.toml.orig", ".cargo-ok", ".cargo_vcs_info.json"];
 var fail2 = (why) => {
   throw new Error(`border scan cannot materialize the artifact (${why}) \u2014 refusing to stage an unusable tree (fail-closed)`);
@@ -43613,12 +44072,12 @@ function unwrapSingleDir(dir) {
   const entries = readdirSync10(dir, { withFileTypes: true });
   const dirs = entries.filter((e) => e.isDirectory());
   if (entries.length === 1 && dirs.length === 1 && dirs[0] !== void 0) {
-    return join25(dir, dirs[0].name);
+    return join26(dir, dirs[0].name);
   }
   return dir;
 }
 function requireManifest(repoDir, ecosystem, candidates) {
-  if (!candidates.some((rel) => existsSync17(join25(repoDir, rel)))) {
+  if (!candidates.some((rel) => existsSync17(join26(repoDir, rel)))) {
     fail2(`${ecosystem} package tree has none of [${candidates.join(", ")}] at its root`);
   }
 }
@@ -43628,18 +44087,18 @@ function materializePackage(o) {
 `);
   });
   const safe = safeArtifactName(o.filename, `${o.ecosystem}-artifact`);
-  const archive = join25(o.baseDir, safe);
-  writeFileSync7(archive, o.bytes);
-  const extractDir = join25(o.baseDir, "extract");
+  const archive = join26(o.baseDir, safe);
+  writeFileSync8(archive, o.bytes);
+  const extractDir = join26(o.baseDir, "extract");
   mkdirSync11(extractDir, { recursive: true });
   extractFlat(archive, extractDir);
   let repoDir = unwrapSingleDir(extractDir);
   if (o.ecosystem === "rubygems") {
     const outer = repoDir;
     const dataCandidates = findNativeMissArchives(outer).filter((f) => f.endsWith("data.tar.gz"));
-    const inner = dataCandidates[0] ?? join25(outer, "data.tar.gz");
+    const inner = dataCandidates[0] ?? join26(outer, "data.tar.gz");
     if (!existsSync17(inner)) fail2(".gem archive contains no data.tar.gz");
-    const gemTree = join25(o.baseDir, "gem-tree");
+    const gemTree = join26(o.baseDir, "gem-tree");
     mkdirSync11(gemTree, { recursive: true });
     extractFlat(inner, gemTree);
     repoDir = unwrapSingleDir(gemTree);
@@ -43650,10 +44109,10 @@ function materializePackage(o) {
   } else {
     requireManifest(repoDir, o.ecosystem, ["Cargo.toml"]);
     for (const file2 of CRATES_ENVELOPE_FILES) {
-      const path4 = join25(repoDir, file2);
+      const path4 = join26(repoDir, file2);
       if (!existsSync17(path4)) continue;
       const original = readFileSync16(path4);
-      rmSync12(path4, { force: true });
+      rmSync13(path4, { force: true });
       note(`border scan: crates envelope normalized: ${file2} sha256=${sha256Hex(original)}`);
     }
   }
@@ -43665,45 +44124,6 @@ function materializePackage(o) {
   return repoDir;
 }
 
-// src/scan/spec.ts
-var ECOSYSTEMS = ["npm", "pypi", "crates", "rubygems"];
-var SCAN_SPEC_USAGE = "usage: border scan <[ecosystem:]name@version> \u2014 e.g. border scan puppeteer@23.11.1 | pypi:requests@2.32.3 | crates:serde@1.0.219 | rubygems:rails@7.1.1";
-var PLAIN_NAME = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
-var SCOPED_NAME = /^@[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
-var VERSION = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
-var bad2 = (why) => {
-  throw new UnknownArgError(`${why}; ${SCAN_SPEC_USAGE}`);
-};
-function parseScanSpec(raw) {
-  const text = raw.trim();
-  if (text.length === 0) return bad2("empty spec");
-  let ecosystem = "npm";
-  let rest = text;
-  const colon = text.indexOf(":");
-  if (colon >= 0) {
-    const prefix = text.slice(0, colon);
-    const found = ECOSYSTEMS.find((e) => e === prefix);
-    if (found === void 0) {
-      return bad2(`unknown ecosystem '${prefix}' \u2014 expected one of: ${ECOSYSTEMS.join(", ")}`);
-    }
-    ecosystem = found;
-    rest = text.slice(colon + 1);
-    if (rest.length === 0) return bad2("missing package name after the ecosystem prefix");
-  }
-  const scoped = rest.startsWith("@");
-  const at = rest.lastIndexOf("@");
-  if (at <= 0) return bad2(`spec '${raw}' is missing '@version'`);
-  const name = rest.slice(0, at);
-  const version2 = rest.slice(at + 1);
-  if (!(scoped ? SCOPED_NAME : PLAIN_NAME).test(name)) {
-    return bad2(`invalid package name '${name}'`);
-  }
-  if (!VERSION.test(version2)) {
-    return bad2(`invalid version '${version2}' in spec '${raw}'`);
-  }
-  return { ecosystem, name, version: version2 };
-}
-
 // src/scan/scan.ts
 async function runScanCore(ctx, deps = {}) {
   const raw = ctx.positionals[0];
@@ -43719,7 +44139,7 @@ async function runScanCore(ctx, deps = {}) {
   }
   const cfg = synthesizeScanConfig(spec.ecosystem);
   const fetcher = deps.fetcher ?? defaultScanFetcher;
-  const baseDir = mkdtempSync5(join26(tmpdir3(), "border-scan-"));
+  const baseDir = mkdtempSync6(join27(tmpdir4(), "border-scan-"));
   try {
     const { bytes, filename } = await fetchArtifact(spec, { fetcher });
     const env2 = { ...ctx.env };
@@ -43843,11 +44263,12 @@ var handlers = {
   status: runStatus,
   "llm-request": runLlmRequest,
   "llm-ingest": runLlmIngest,
-  scan: runScan2
+  scan: runScan2,
+  roundtrip: runRoundtrip
 };
 
 // src/cli/types.ts
-var SUBCOMMANDS = ["check", "push", "status", "llm-request", "llm-ingest", "scan"];
+var SUBCOMMANDS = ["check", "push", "status", "llm-request", "llm-ingest", "scan", "roundtrip"];
 
 // src/cli.ts
 var VALID_TARGETS = targetIds();
@@ -43864,6 +44285,7 @@ function usage() {
     "  llm-request    emit the provenance request for LLM-authored commits",
     "  llm-ingest     record provenance captured by the harness",
     "  scan           inspect a third-party package ([ecosystem:]name@version) for residue",
+    "  roundtrip      install+uninstall a package in a throwaway container, report uninstall residue",
     "",
     "flags:",
     "  --config <path>             config file (default: ./border.yaml, then git-remote fallback)",
@@ -43873,11 +44295,12 @@ function usage() {
     "  --require-engine <list>     comma-separated engines that must be healthy (else exit 2)",
     "  --llm                       include the optional LLM review layer",
     "  --json                      machine-readable report on stdout",
+    "  --record / --no-record      `border roundtrip` records a ledger proof by default; --no-record opts out",
     "  --help, -h                  this table",
     "",
     "exit codes: 0 pass (MEDIUM/INFO/LOW allowed) | 1 gate-blocked (CRITICAL/HIGH) or partial push | 2 config/tool error",
     "",
-    "subcommands: check, push, status, llm-request, llm-ingest, scan"
+    "subcommands: check, push, status, llm-request, llm-ingest, scan, roundtrip"
   ].join("\n");
 }
 function isSubcommand(value) {
@@ -43908,10 +44331,15 @@ function parseFlags(argv) {
         "require-engine": { type: "string" },
         llm: { type: "boolean" },
         json: { type: "boolean" },
+        record: { type: "boolean" },
+        "no-record": { type: "boolean" },
         help: { type: "boolean" }
       }
     });
     const { config: config2, targets, force, yes, llm, json: json2 } = values;
+    if (values.record === true && values["no-record"] === true) {
+      throw new UnknownArgError("--record and --no-record contradict each other");
+    }
     const requireEngine = values["require-engine"];
     const flags = {
       ...config2 !== void 0 ? { config: config2 } : {},
@@ -43920,7 +44348,8 @@ function parseFlags(argv) {
       yes: yes === true,
       ...requireEngine !== void 0 ? { requireEngine: splitList(requireEngine, { flag: "--require-engine", item: "engine" }) } : {},
       llm: llm === true,
-      json: json2 === true
+      json: json2 === true,
+      ...values["no-record"] === true ? { record: false } : values.record === true ? { record: true } : {}
     };
     return { flags, positionals, help: values.help === true };
   } catch (err) {
@@ -43986,11 +44415,18 @@ function run(argv, stdout = (line) => {
 }
 
 // src/index.ts
-function isMainModule() {
-  const entry = process.argv[1];
-  return entry !== void 0 && import.meta.url === pathToFileURL(entry).href;
+function isMainModule({ argv1, moduleUrl, realpath }) {
+  if (argv1 === void 0) return false;
+  const canonical = (p) => {
+    try {
+      return realpath(p);
+    } catch {
+      return p;
+    }
+  };
+  return pathToFileURL(canonical(argv1)).href === pathToFileURL(canonical(fileURLToPath5(moduleUrl))).href;
 }
-if (isMainModule()) {
+if (isMainModule({ argv1: process.argv[1], moduleUrl: import.meta.url, realpath: realpathSync.native })) {
   const outcome = run(process.argv.slice(2));
   process.exitCode = outcome instanceof Promise ? await outcome : outcome;
 }
@@ -43999,6 +44435,7 @@ export {
   EXIT_ERROR,
   EXIT_PASS,
   SUBCOMMANDS,
+  isMainModule,
   run,
   translateError,
   usage

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "border-customs",
-  "version": "0.3.1",
+  "version": "0.4.0",
+  "//": "publint is a runtime dep (exact pin): the npm-stage engine is invoked via bin resolution against the installed layout, so consumers get the publint-fail leg out of the box; the dev suite resolves the same node_modules/.bin/publint — no devDependencies entry is needed for it to stay green.",
   "description": "Fail-closed git push gate: secret scanning + supply-chain checks before any remote leaves the machine",
   "type": "module",
   "bin": {
@@ -30,13 +31,13 @@
     "@secretlint/secretlint-rule-no-homedir": "13.0.5",
     "@secretlint/secretlint-rule-pattern": "13.0.5",
     "@secretlint/secretlint-rule-preset-recommend": "13.0.5",
+    "publint": "0.3.24",
     "yaml": "2.9.0",
     "zod": "4.5.4"
   },
   "devDependencies": {
     "@types/node": "22.19.0",
     "esbuild": "0.25.12",
-    "publint": "0.3.24",
     "secretlint": "13.0.5",
     "typescript": "5.9.3",
     "verdaccio": "6.10.2"