skill-family-harness-node 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.8.3 locale=en baseline=sha256:449943bedf3698888fec4dcb09a0460f337b9406d5258946a3d3ffcd23143b8d -->
+## [0.8.3] - 2026-08-23
+
+Path containment now tolerates one exact anchor-removal race while preserving fail-closed escape checks.
+
+### Changed
+
+- A second ENOENT and every non-ENOENT failure remain closed; symlink swaps, out-of-root targets, and all existing containment checks remain rejected.
+- Keeps the hook private to the paths module test surface and adds no public export, general retry policy, lock layer, ledger, or runner.
+- Moves the package version to 0.8.3 together with Contracts and Engineering Kit.
+
+### Fixed
+
+- When realpath of the selected existing anchor fails with ENOENT because another process removed it, resolveContained recomputes the deepest existing ancestor exactly once.
+
+### Upgrade Notes
+
+Consumers must pin all three Foundation packages to exactly 0.8.3. Concurrent lock acquisition can now survive the current owner removing the selected lock-file anchor; no Harness API migration is required.
+<!-- release-skill:changelog:end version=0.8.3 locale=en -->
+
+
+<!-- release-skill:changelog:start version=0.8.2 locale=en baseline=sha256:af051a6925c7d1f46bef6fbe367aceea8685b4a916629af4e69334e73014e3a7 -->
+## [0.8.2] - 2026-08-23
+
+The fixed candidate mechanism bridge now exposes the existing strict reader through read-file-strict.
+
+### Added
+
+- Adds read-file-strict to invokeFoundationMechanism with closed root, path, encoding, and expectedSha256 parameters.
+- Returns UTF-8 content as a string and binary content in the standard JSON-safe Buffer shape.
+
+### Changed
+
+- Delegates containment, file reading, digest verification, and failure classification directly to readFileStrict; no second read algorithm is introduced.
+- Moves the package version to 0.8.2 together with Contracts and Engineering Kit.
+
+### Upgrade Notes
+
+Candidate consumers must pin all three Foundation packages to exactly 0.8.2 and rebuild their managed Bundle. Direct calls retain SFC2004 details.kind failures; the JSON CLI continues to promise only exit code 0 for success and 2 for rejection.
+<!-- release-skill:changelog:end version=0.8.2 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.8.1 locale=en baseline=sha256:4cd9f23da3561184cef4ebadb7e758a22d377d069742bbe7c77166d6c1b3bd14 -->
 ## [0.8.1] - 2026-08-22
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,47 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.8.3 locale=zh-CN baseline=sha256:b84695a286aca7c1a9f90844f8682cde07d32276cebc11583568bc5ef11753fc -->
+## [0.8.3] - 2026-08-23
+
+路径收容现在可处理一次精确的锚点并发删除，同时保持越界检查失败关闭。
+
+### 变更
+
+- 第二次 ENOENT 与所有非 ENOENT 错误仍失败关闭；符号链接替换、根目录外目标和既有收容检查仍全部拒绝。
+- 测试钩子只留在 paths 模块的测试表面，不新增公共导出、通用重试策略、锁层、账本或 runner。
+- 包版本与 Contracts、Engineering Kit 一同升至 0.8.3。
+
+### 修复
+
+- 当另一进程删除已选锚点，导致该锚点的 realpath 返回 ENOENT 时，resolveContained 仅重新计算一次最深既存祖先。
+
+### 升级说明
+
+消费者必须把三个 Foundation 包精确锁定到 0.8.3。并发获取锁时，即使当前持有者删除已选锁文件锚点，也能完成一次安全重求；Harness API 无需迁移。
+<!-- release-skill:changelog:end version=0.8.3 locale=zh-CN -->
+
+
+<!-- release-skill:changelog:start version=0.8.2 locale=zh-CN baseline=sha256:748d79d51dcabe6193332e60ec69a6eb26fd914ad3555f6e924b78db71016192 -->
+## [0.8.2] - 2026-08-23
+
+固定的候选机制桥接新增 read-file-strict，直接公开既有严格读取机制。
+
+### 新增
+
+- invokeFoundationMechanism 新增 read-file-strict；参数闭合为 root、path、encoding 和 expectedSha256。
+- UTF-8 内容返回字符串，二进制内容返回标准的 JSON 安全 Buffer 形态。
+
+### 变更
+
+- 路径收容、文件读取、摘要复验和失败分类全部转发给 readFileStrict，不新增第二套读取算法。
+- 包版本与 Contracts、Engineering Kit 一同升至 0.8.2。
+
+### 升级说明
+
+候选消费者必须把三个 Foundation 包精确锁定到 0.8.2，再重建受管 Bundle。直接调用继续返回 SFC2004 与 details.kind；JSON CLI 只承诺成功退出码 0 和拒绝退出码 2。
+<!-- release-skill:changelog:end version=0.8.2 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.8.1 locale=zh-CN baseline=sha256:904de77446dbc69ef7e70cdda0020fd98632a6e704754f6ed57e136764e3112e -->
 ## [0.8.1] - 2026-08-22
 

package/README.md

@@ -4,28 +4,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.8.1 -->
+<!-- release-skill:release-version: 0.8.3 -->
 
 The **single default Node implementation** of the Contracts mechanism protocol. This is a thin runtime: it only implements the mechanism protocol, introduces no business semantics, and does not provide a second-language implementation.
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.8.1** (2026-08-22)
+**0.8.3** (2026-08-23)
 
-Harness now preserves its own report renderer version when a host bundles it into a single-file adapter.
+Path containment now tolerates one exact anchor-removal race while preserving fail-closed escape checks.
 
 **Changed**
 
-- Moves the package version to 0.8.1 together with Contracts and Engineering Kit.
-- Keeps all 21 Harness capabilities, report contracts, and public exports unchanged.
+- A second ENOENT and every non-ENOENT failure remain closed; symlink swaps, out-of-root targets, and all existing containment checks remain rejected.
+- Keeps the hook private to the paths module test surface and adds no public export, general retry policy, lock layer, ledger, or runner.
+- Moves the package version to 0.8.3 together with Contracts and Engineering Kit.
 
 **Fixed**
 
-- Replaces the report renderer's runtime import.meta.url package-manifest lookup with a static JSON import, so esbuild inlines the Harness version instead of resolving the host adapter's package metadata.
-- Adds source and third-party single-file bundle regression tests for REPORT_RENDERER_VERSION.
+- When realpath of the selected existing anchor fails with ENOENT because another process removed it, resolveContained recomputes the deepest existing ancestor exactly once.
 
 **Upgrade Notes**
 
-Host adapters that bundle the report renderer must pin Harness 0.8.1. The report API and renderer identity remain unchanged, so no API migration is required from 0.8.0.
+Consumers must pin all three Foundation packages to exactly 0.8.3. Concurrent lock acquisition can now survive the current owner removing the selected lock-file anchor; no Harness API migration is required.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -39,14 +39,14 @@ The Harness consumes `skill-family-contracts` (a workspace dependency), reusing
 ## Installation and Minimal Example
 
 ```sh
-npm install skill-family-harness-node@0.8.1
+npm install skill-family-harness-node@0.8.3
 npm info skill-family-harness-node --help
 ```
 
 The minimal example shows validating a contract document inside Node:
 
 ```js
-// Run from an empty directory: npm install skill-family-harness-node@0.8.1
+// Run from an empty directory: npm install skill-family-harness-node@0.8.3
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {

package/README.zh-CN.md

@@ -5,28 +5,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.8.1 -->
+<!-- release-skill:release-version: 0.8.3 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.8.1** (2026-08-22)
+**0.8.3** (2026-08-23)
 
-宿主把 Harness 打包进单文件适配器后，报告渲染器仍能保留 Harness 自身的包版本。
+路径收容现在可处理一次精确的锚点并发删除，同时保持越界检查失败关闭。
 
 **变更**
 
-- 包版本与 Contracts、Engineering Kit 一同升至 0.8.1。
-- Harness 的 21 项能力、报告合同和公共导出均保持不变。
+- 第二次 ENOENT 与所有非 ENOENT 错误仍失败关闭；符号链接替换、根目录外目标和既有收容检查仍全部拒绝。
+- 测试钩子只留在 paths 模块的测试表面，不新增公共导出、通用重试策略、锁层、账本或 runner。
+- 包版本与 Contracts、Engineering Kit 一同升至 0.8.3。
 
 **修复**
 
-- 用静态 JSON import 替换报告渲染器运行时基于 import.meta.url 的包清单查找，使 esbuild 内联 Harness 版本，不再读取宿主适配器的包元数据。
-- 为 REPORT_RENDERER_VERSION 新增源码运行与第三方单文件 bundle 回归测试。
+- 当另一进程删除已选锚点，导致该锚点的 realpath 返回 ENOENT 时，resolveContained 仅重新计算一次最深既存祖先。
 
 **升级说明**
 
-把报告渲染器打包进宿主适配器的消费者必须精确锁定 Harness 0.8.1；报告 API 与渲染器身份保持不变，从 0.8.0 升级不需要迁移 API。
+消费者必须把三个 Foundation 包精确锁定到 0.8.3。并发获取锁时，即使当前持有者删除已选锁文件锚点，也能完成一次安全重求；Harness API 无需迁移。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -40,14 +40,14 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 ## 安装和最小示例
 
 ```sh
-npm install skill-family-harness-node@0.8.1
+npm install skill-family-harness-node@0.8.3
 npm info skill-family-harness-node --help
 ```
 
 最小示例演示在 Node 内校验一份契约文档：
 
 ```js
-// 从空目录运行：npm install skill-family-harness-node@0.8.1
+// 从空目录运行：npm install skill-family-harness-node@0.8.3
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {

package/candidate/quickstart-profile.mjs

@@ -13,6 +13,7 @@ import { fileURLToPath } from "node:url";
 import { computeResourceClosure, digestBytes } from "../src/closure.mjs";
 import { HARNESS_ERROR_KINDS, HarnessError, mechanismError } from "../src/errors.mjs";
 import { resolveContained } from "../src/paths.mjs";
+import { readFileStrict } from "../src/strict-read.mjs";
 
 /**
  * Candidate quickstart profile v2 mechanisms (unstable).
@@ -455,6 +456,7 @@ const FOUNDATION_MECHANISM_OPERATIONS = Object.freeze([
   "digest-document",
   "resource-closure",
   "resolve-contained",
+  "read-file-strict",
   "create-task",
   "wrap-result",
   "verify-exchange",
@@ -483,6 +485,34 @@ function findUnsafeInteger(value, instancePath = "") {
   return null;
 }
 
+function assertReadFileStrictParams(params) {
+  const allowedKeys = new Set(["root", "path", "encoding", "expectedSha256"]);
+  const unknownKey = Object.keys(params).find((key) => !allowedKeys.has(key));
+  if (unknownKey !== undefined) {
+    throw new TypeError(`invokeFoundationMechanism: read-file-strict unknown param: ${unknownKey}`);
+  }
+  for (const key of ["root", "path"]) {
+    if (!Object.hasOwn(params, key) || typeof params[key] !== "string" || params[key].length === 0) {
+      throw new TypeError(`invokeFoundationMechanism: read-file-strict ${key} must be a non-empty string`);
+    }
+  }
+  if (Object.hasOwn(params, "encoding") && params.encoding !== "utf8") {
+    throw new TypeError('invokeFoundationMechanism: read-file-strict encoding must be "utf8" or omitted');
+  }
+}
+
+async function invokeReadFileStrict(params) {
+  assertReadFileStrictParams(params);
+  const receipt = await readFileStrict(params.root, params.path, {
+    ...(Object.hasOwn(params, "encoding") ? { encoding: params.encoding } : {}),
+    ...(Object.hasOwn(params, "expectedSha256") ? { expectedSha256: params.expectedSha256 } : {}),
+  });
+  return {
+    ...receipt,
+    content: Buffer.isBuffer(receipt.content) ? receipt.content.toJSON() : receipt.content,
+  };
+}
+
 /**
  * Fixed, business-neutral mechanism bridge for consumers that cannot import
  * several Foundation modules directly. validateBySchemaId is injected only
@@ -525,6 +555,9 @@ export async function invokeFoundationMechanism(request, { validateBySchemaId }
   if (operation === "resource-closure") {
     return computeResourceClosure({ root: params.root, resources: params.resources });
   }
+  if (operation === "read-file-strict") {
+    return invokeReadFileStrict(params);
+  }
   if (operation === "create-task") {
     return createQuickstartTask(params);
   }

package/package.json

@@ -10,7 +10,7 @@
   "dependencies": {
     "@pnpm/lockfile.fs": "1001.1.35",
     "ipaddr.js": "2.5.0",
-    "skill-family-contracts": "0.8.1",
+    "skill-family-contracts": "0.8.3",
     "yaml": "2.9.0"
   },
   "description": "Thin Node.js mechanism runtime for Skill Family engineering contracts.",
@@ -45,7 +45,7 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node.git"
   },
   "type": "module",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "scripts": {
     "check": "node --test",
     "test": "node --test"

package/release-notes/0.8.2.yaml

@@ -0,0 +1,23 @@
+version: 0.8.2
+date: 2026-08-23
+locales:
+  en:
+    summary: The fixed candidate mechanism bridge now exposes the existing strict reader through read-file-strict.
+    changes:
+      added:
+        - Adds read-file-strict to invokeFoundationMechanism with closed root, path, encoding, and expectedSha256 parameters.
+        - Returns UTF-8 content as a string and binary content in the standard JSON-safe Buffer shape.
+      changed:
+        - Delegates containment, file reading, digest verification, and failure classification directly to readFileStrict; no second read algorithm is introduced.
+        - Moves the package version to 0.8.2 together with Contracts and Engineering Kit.
+    upgradeNotes: Candidate consumers must pin all three Foundation packages to exactly 0.8.2 and rebuild their managed Bundle. Direct calls retain SFC2004 details.kind failures; the JSON CLI continues to promise only exit code 0 for success and 2 for rejection.
+  zh-CN:
+    summary: 固定的候选机制桥接新增 read-file-strict，直接公开既有严格读取机制。
+    changes:
+      added:
+        - invokeFoundationMechanism 新增 read-file-strict；参数闭合为 root、path、encoding 和 expectedSha256。
+        - UTF-8 内容返回字符串，二进制内容返回标准的 JSON 安全 Buffer 形态。
+      changed:
+        - 路径收容、文件读取、摘要复验和失败分类全部转发给 readFileStrict，不新增第二套读取算法。
+        - 包版本与 Contracts、Engineering Kit 一同升至 0.8.2。
+    upgradeNotes: 候选消费者必须把三个 Foundation 包精确锁定到 0.8.2，再重建受管 Bundle。直接调用继续返回 SFC2004 与 details.kind；JSON CLI 只承诺成功退出码 0 和拒绝退出码 2。

package/release-notes/0.8.3.yaml

@@ -0,0 +1,23 @@
+version: 0.8.3
+date: 2026-08-23
+locales:
+  en:
+    summary: Path containment now tolerates one exact anchor-removal race while preserving fail-closed escape checks.
+    changes:
+      fixed:
+        - When realpath of the selected existing anchor fails with ENOENT because another process removed it, resolveContained recomputes the deepest existing ancestor exactly once.
+      changed:
+        - A second ENOENT and every non-ENOENT failure remain closed; symlink swaps, out-of-root targets, and all existing containment checks remain rejected.
+        - Keeps the hook private to the paths module test surface and adds no public export, general retry policy, lock layer, ledger, or runner.
+        - Moves the package version to 0.8.3 together with Contracts and Engineering Kit.
+    upgradeNotes: Consumers must pin all three Foundation packages to exactly 0.8.3. Concurrent lock acquisition can now survive the current owner removing the selected lock-file anchor; no Harness API migration is required.
+  zh-CN:
+    summary: 路径收容现在可处理一次精确的锚点并发删除，同时保持越界检查失败关闭。
+    changes:
+      fixed:
+        - 当另一进程删除已选锚点，导致该锚点的 realpath 返回 ENOENT 时，resolveContained 仅重新计算一次最深既存祖先。
+      changed:
+        - 第二次 ENOENT 与所有非 ENOENT 错误仍失败关闭；符号链接替换、根目录外目标和既有收容检查仍全部拒绝。
+        - 测试钩子只留在 paths 模块的测试表面，不新增公共导出、通用重试策略、锁层、账本或 runner。
+        - 包版本与 Contracts、Engineering Kit 一同升至 0.8.3。
+    upgradeNotes: 消费者必须把三个 Foundation 包精确锁定到 0.8.3。并发获取锁时，即使当前持有者删除已选锁文件锚点，也能完成一次安全重求；Harness API 无需迁移。

package/src/paths.mjs

@@ -32,6 +32,13 @@ import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
 const WINDOWS_DRIVE_PATTERN = /^[A-Za-z]:/;
 const WINDOWS_UNC_PATTERN = /^\\\\/;
 const POSIX_UNC_PATTERN = /^\/\//;
+const ANCHOR_REALPATH_ATTEMPTS = 2;
+
+let testHooks = null;
+
+async function runTestHook(name, context) {
+  if (typeof testHooks?.[name] === "function") await testHooks[name](context);
+}
 
 /**
  * Classifies one candidate relative path without touching the filesystem.
@@ -143,7 +150,13 @@ async function deepestExistingAncestor(rootReal, absPath) {
     try {
       await lstat(current);
       return { anchor: current, missing };
-    } catch {
+    } catch (cause) {
+      if (cause?.code !== "ENOENT" && cause?.code !== "ENOTDIR") {
+        throw mechanismError(
+          HARNESS_ERROR_KINDS.READ_FAILED,
+          `path ancestor cannot be inspected: ${cause?.code ?? "unknown"}`,
+        );
+      }
       missing.unshift(path.basename(current));
       const parent = path.dirname(current);
       if (parent === current) break;
@@ -158,6 +171,31 @@ async function deepestExistingAncestor(rootReal, absPath) {
   );
 }
 
+async function canonicalAnchor(rootReal, resolved, relPath) {
+  for (let attempt = 0; attempt < ANCHOR_REALPATH_ATTEMPTS; attempt += 1) {
+    const { anchor, missing } = await deepestExistingAncestor(rootReal, resolved);
+    await runTestHook("beforeAnchorRealpath", { anchor, attempt });
+    try {
+      return { anchorReal: await realpath(anchor), missing };
+    } catch (cause) {
+      // An existing lock or staging file can be removed by its owner between
+      // lstat() and realpath(). Recompute the ancestor once for that exact
+      // disappearance race; every other error remains fail-closed.
+      if (cause?.code === "ENOENT" && attempt + 1 < ANCHOR_REALPATH_ATTEMPTS) continue;
+      throw mechanismError(
+        HARNESS_ERROR_KINDS.REALPATH_ESCAPE,
+        "anchor directory vanished during canonical resolution",
+        { input: relPath, code: cause?.code },
+      );
+    }
+  }
+  throw mechanismError(
+    HARNESS_ERROR_KINDS.REALPATH_ESCAPE,
+    "anchor directory vanished during canonical resolution",
+    { input: relPath },
+  );
+}
+
 /**
  * Resolves `relPath` against `root` and proves the target stays inside.
  * Returns the absolute, lexically resolved path (strictly inside the root).
@@ -221,17 +259,7 @@ export async function resolveContained(root, relPath) {
 
   // Escape class 3: canonical resolution (any intermediate symlink chain)
   // must stay inside the canonical root.
-  const { anchor, missing } = await deepestExistingAncestor(rootReal, resolved);
-  let anchorReal;
-  try {
-    anchorReal = await realpath(anchor);
-  } catch {
-    throw mechanismError(
-      HARNESS_ERROR_KINDS.REALPATH_ESCAPE,
-      "anchor directory vanished during canonical resolution",
-      { input: relPath },
-    );
-  }
+  const { anchorReal, missing } = await canonicalAnchor(rootReal, resolved, relPath);
   if (!insideOrEqualRoot(rootReal, anchorReal)) {
     throw mechanismError(
       HARNESS_ERROR_KINDS.REALPATH_ESCAPE,
@@ -250,6 +278,14 @@ export async function resolveContained(root, relPath) {
   return resolved;
 }
 
+/** Test-only hooks. Deliberately not re-exported from the package index. */
+export function __setPathsTestHooks(hooks) {
+  if (hooks !== null && (!hooks || typeof hooks !== "object" || Array.isArray(hooks))) {
+    throw new TypeError("paths test hooks must be an object or null");
+  }
+  testHooks = hooks;
+}
+
 /**
  * Contained read. Returns the file content as a Buffer (utf8 string when
  * encoding is "utf8"). Missing resources surface as SFC2004 with the stable