skill-family-harness-node 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.15.0 locale=en baseline=sha256:8c81395a147ed1e995e21ae0074f66d434b87070ea33350fa3e97cbcb5f2fa8e -->
+## [0.15.0] - 2026-08-29
+
+Harness 0.15.0 adds executable identity observation and a best-effort Node tree record mode.
+
+### Added
+
+- Records symlink target bytes without following links on a stable isolated tree.
+- Rechecks the original script after observing its interpreter and orders paths by Unicode code point.
+
+### Changed
+
+- Keeps omitted and reject symlink policy on the 0.14 native path.
+
+### Upgrade Notes
+
+Record mode is candidate best effort; it does not provide a transaction snapshot or hostile concurrent-writer safety.
+<!-- release-skill:changelog:end version=0.15.0 locale=en -->
+
+
+<!-- release-skill:changelog:start version=0.14.0 locale=en baseline=sha256:23ac2de57433409f1dafac90d7bdd130fd10bd399fd188d7d848a49320b86f30 -->
+## [0.14.0] - 2026-08-28
+
+Harness 0.14.0 adds an official atomic-write fake, a synchronized package version export, and canonical temporary workspace roots for safe raw sinks.
+
+### Added
+
+- Adds createAtomicWriteFake({ vector }) with deterministic write, replace, and observation facts and no filesystem side effects.
+- Exposes FOUNDATION_PACKAGE_VERSION for lockstep consumers.
+- Returns canonical realpaths from TemporaryWorkspace.create() and fromBaseline(). A root returned by create() can be passed directly to superviseProcess rawSink while it remains fresh and empty. A materialized non-empty baseline root is rejected by rawSink freshness validation.
+
+### Changed
+
+- Documents that the fake verifies adapter wiring, not the domain guarantee or real-host qualification.
+
+### Upgrade Notes
+
+Pin Contracts, Harness, and Engineering Kit to 0.14.0 together. Use the official fake with the Contracts vectors; retain real filesystem and domain tests for production guarantees. Temporary workspace roots are canonical. A root returned by create() can be passed directly to superviseProcess rawSink while it remains fresh and empty. A materialized non-empty baseline root is rejected by rawSink freshness validation.
+<!-- release-skill:changelog:end version=0.14.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.13.0 locale=en baseline=sha256:ba0667eb4b4805aafc2423cd79c04df3c835b8ae9bb07391867175f6ad96c36b -->
 ## [0.13.0] - 2026-08-26
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,46 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.15.0 locale=zh-CN baseline=sha256:945e9d06ed1cc8178ac13f3ec27ee753ec129d2f54ae59b59c6d8f4ec137d821 -->
+## [0.15.0] - 2026-08-29
+
+Harness 0.15.0 增加可执行文件身份观察与 Node 树 best-effort 记录模式。
+
+### 新增
+
+- 在稳定隔离树上记录 symlink 自身与原始 target bytes，不跟随链接。
+- 观察解释器后重查原脚本，并按 Unicode code point 排序路径。
+
+### 变更
+
+- 省略或 reject symlinkPolicy 时继续使用 0.14 native 路径。
+
+### 升级说明
+
+record 模式仍为 candidate best-effort，不提供事务快照或恶意并发写者安全保证。
+<!-- release-skill:changelog:end version=0.15.0 locale=zh-CN -->
+
+
+<!-- release-skill:changelog:start version=0.14.0 locale=zh-CN baseline=sha256:11857b4e61d5111fab3dbc5eb1afcf99fd8fd6fd41f190bad5a5e16c09633e25 -->
+## [0.14.0] - 2026-08-28
+
+Harness 0.14.0 增加消费者契约测试用正式 atomic-write 测试替身（`fake`）、同步公开包版本导出，并让临时工作区根目录返回 canonical realpath。
+
+### 新增
+
+- 新增 `createAtomicWriteFake({ vector })`，提供确定性的写入、替换和观察事实且不触碰文件系统。
+- 公开 `FOUNDATION_PACKAGE_VERSION`，供锁步消费者使用。
+- `TemporaryWorkspace.create()` 与 `fromBaseline()` 返回 canonical realpath。`create()` 返回的根目录在保持 fresh 且为空时，可以直接传给 `superviseProcess` 的 `rawSink`。物化后的非空 baseline 根目录会被 `rawSink` 的 freshness 校验拒绝。
+
+### 变更
+
+- 明确测试替身用于验证适配器接线，不代表领域保证或真实宿主资格。
+
+### 升级说明
+
+Contracts、Harness 与 Engineering Kit 须一起精确锁定到 0.14.0。用正式测试替身配合 Contracts 向量；生产保证仍须由真实文件系统和领域测试覆盖。临时工作区根目录已经 canonical。`create()` 返回的根目录在保持 fresh 且为空时，可以直接传给 `superviseProcess` 的 `rawSink`。物化后的非空 baseline 根目录会被 `rawSink` 的 freshness 校验拒绝。
+<!-- release-skill:changelog:end version=0.14.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.13.0 locale=zh-CN baseline=sha256:1356b2ecff87da4a8bbe5bc04980b125ddf181873ff2b536be87a2e246b59609 -->
 ## [0.13.0] - 2026-08-26
 

package/README.md

@@ -4,26 +4,27 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.13.0 -->
+<!-- release-skill:release-version: 0.15.0 -->
 
 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.13.0** (2026-08-26)
+**0.15.0** (2026-08-29)
 
-Harness 0.13.0 is a source candidate for complete bound-tree observations and optional subprocess output limits.
+Harness 0.15.0 adds executable identity observation and a best-effort Node tree record mode.
 
 **Added**
 
-- Adds observeFilesystemTree({ root, rootBinding }) as a public candidate entry for fresh private tree facts, including file bytes and POSIX mode observations.
+- Records symlink target bytes without following links on a stable isolated tree.
+- Rechecks the original script after observing its interpreter and orders paths by Unicode code point.
 
 **Changed**
 
-- Extends superviseProcess with independent stdout/stderr byte limits using the existing termination path. Equal-to-limit output is allowed; uncapped behavior remains compatible.
+- Keeps omitted and reject symlink policy on the 0.14 native path.
 
 **Upgrade Notes**
 
-Pin Contracts and Harness together. Tree observation does not apply payload acceptance policy or promise a transaction snapshot. Candidate preparation is not publication.
+Record mode is candidate best effort; it does not provide a transaction snapshot or hostile concurrent-writer safety.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -36,17 +37,28 @@ The Harness consumes `skill-family-contracts` (a workspace dependency), reusing
 
 ## Installation and Minimal Example
 
-Version 0.13.0 is not published. The registry command below is for use after publication; this iteration installs the three local candidate tarballs in an isolated directory.
+Version 0.15.0 is a local candidate. Build all three tarballs into one temporary directory and install those exact files for a candidate check:
 
 ```sh
-npm install skill-family-harness-node@0.13.0
+pack_dir="$(mktemp -d)"
+(cd packages/skill-family-contracts && pnpm pack --pack-destination "$pack_dir")
+(cd packages/skill-family-harness-node && pnpm pack --pack-destination "$pack_dir")
+(cd packages/skill-family-engineering-kit && pnpm pack --pack-destination "$pack_dir")
+mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.15.0.tgz" "$pack_dir/skill-family-harness-node-0.15.0.tgz" "$pack_dir/skill-family-engineering-kit-0.15.0.tgz")
+```
+
+After publication, use the registry coordinate:
+
+```sh
+npm install skill-family-harness-node@0.15.0
 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.13.0
+// Run from an installed consumer directory after publication.
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {
@@ -100,13 +112,17 @@ The capability remains **candidate**. Pin all three Foundation packages exactly
 | Export | Responsibility |
 | --- | --- |
 | `HARNESS_CAPABILITIES` / `HARNESS_EXCLUSIONS` | Capability and exclusion lists (frozen constants). |
+| `FOUNDATION_PACKAGE_VERSION` | Exact Foundation package version used for lockstep checks. |
 | `HarnessError` / `HARNESS_ERROR_KINDS` / `mechanismError` | Mechanism failures uniformly carry the registered error code `SFC2004`; `details.kind` gives a stable subcategory. |
 | `validateContractDocument` / `getValidator` / `resolveSchemaContext` / `validatorCacheSize` | Routes and caches validators by Schema dialect; reuses Contracts' Ajv instances and dialect/policy semantics. |
 | `classifyPathInput` / `resolveContained` / `readFileContained` | Path containment: intercepts path overruns, symlink escapes, and realpath escapes. |
 | `writeFileAtomic` | Atomic write: leaves no half-written artifact on failure (temp file + fsync + rename). |
+| `createAtomicWriteFake({ vector })` | Official no-filesystem fake for consumer contract tests; emits deterministic write/replace/observation facts. |
 | `TemporaryWorkspace` / `createTemporaryWorkspace` / `withTemporaryWorkspace` | Auto-cleanup temporary workspace, cleaned up even on exception paths. |
 | `digestBytes` / `computeResourceClosure` / `closureContains` | Resource closure and deterministic sha256 digest. |
 | `superviseProcess` / `validateTimeoutPolicy` | The single bounded subprocess supervisor. Its 0.11.0 `rawSink` option writes raw stdout/stderr bytes only to a fresh canonical private root, then waits for child/stream close, queued writes, fsync, and handle close. The caller must exclusively control the sink namespace for the entire call; handle protection does not prove stable pathname/root identity. |
+| `observeFilesystemTree` | Observe a complete bound tree. Default/reject preserves the existing UTF-16 member order; record uses code-point order and records symlink target bytes without following them. |
+| `observeExecutableIdentity` | Observe a caller-bound executable, its symlink chain, launch bytes, and any script interpreter chain for immediate pre-spawn re-observation. |
 | `parseRequest` / `processRequest` | Parse `operation-request`, output terminal `operation-result`. |
 | `validateReportModel` / `renderReportMarkdown` / `buildBinding` / `checkReport` | Consume a Contracts-validated report model, deterministically render neutral Markdown, and verify source/result/report binding; does not interpret business output. |
 | `normalizeAdapterSource` / `buildAdapterClosure` / `verifyAdapterBuildManifest` / `materializeAdapterBuild` | Generic text-source closure, full-manifest digest re-verification, and atomic landing of the target set; specific Profile/driver is not in the Harness. |
@@ -168,7 +184,7 @@ Mechanism failures uniformly throw `SFC2004` (EXECUTION_FAILED), with `details.k
 ### Do not use when
 
 - You need to put file-selection business rules into the Foundation (business rules are owned by the caller).
-- You need host identity policy, host drivers, remote publication, uninstall deletion, a full Qoder driver, or binary adapter source (explicitly unsupported).
+- You need host identity policy, host-specific lifecycle plans, remote publication, deleting uninstall, or binary adapter source. Host policy and lifecycle plans belong to Engineering Kit.
 - You need domain audit semantics, retry orchestration, or a compatibility-frozen Quickstart API.
 
 ### Capability selection
@@ -229,4 +245,12 @@ Mechanism failures uniformly throw `SFC2004` (EXECUTION_FAILED), with `details.k
 
 The candidate observeFilesystemTree({ root, rootBinding }) reads complete tree facts. Existing superviseProcess accepts optional per-stream raw-byte caps. Observing a payload does not accept it.
 
-Version 0.13.0 is a local source candidate and is not published. Consume the three locally verified tarballs; a version marker, unit test or successful install is not complete host qualification or release approval.
+`observeFilesystemTree({ root, rootBinding, symlinkPolicy: { mode: "record" } })` is for a stable installation, cache, or projection tree after the host command has completed, with caller isolation and no concurrent namespace writer during the scan. It records each symlink itself as `targetBase64`, `bytes`, and `statMode`, reads only the raw target bytes, and never follows the target; regular files continue to reuse `readFileBound`. Record is a Node/JS best-effort candidate: observed drift fails closed, but the mode does not provide a transaction snapshot, same-UID malicious-concurrency, or ABA guarantee. A stable-tree result remains a normal usable result. Consumers such as release-skill own invocation timing and domain acceptance rules such as npm `.bin`.
+
+Member ordering is mode-specific for compatibility: omitted/reject mode retains the 0.14 UTF-16 relational order, while record mode uses Unicode code-point order. The selected order is also the order used to derive `membersDigest`.
+
+When the actual threat includes malicious concurrency, return a minimal upstream capability gap to Foundation for a decision. Do not copy a generic walker, native addon, Harness, schema, Registry, runner, or receipt chain into a skill family, and do not independently upgrade ordinary consumers to a four-platform native implementation.
+
+The separate candidate `observeExecutableIdentity({ boundRoots, lookup, interpreterPolicy? })` provides a read-only point-in-time observation of only the caller-explicit roots and lookup paths, for an immediate re-observation before launch. When an `/usr/bin/env` shebang resolves an interpreter through explicit `pathEntries`, the observation preserves the interpreter candidate's complete symlink chain rather than collapsing it to the final file. It is not part of `host-adapter` and does not prove wrapper control flow, ambient `PATH`, fd-exec/kernel image, signature trust, cross-call caching, host support/lifecycle, or domain acceptance; the caller owns those semantics. The candidate entry alone does not qualify a host.
+
+Version 0.15.0 is a local source candidate and is not published. Consume the three locally verified tarballs; a version marker, unit test or successful install is not complete contract integration, migration completion, or real-host qualification.

package/README.zh-CN.md

@@ -5,26 +5,27 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.13.0 -->
+<!-- release-skill:release-version: 0.15.0 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.13.0** (2026-08-26)
+**0.15.0** (2026-08-29)
 
-Harness 0.13.0 源码候选增加完整绑定树观察与可选子进程输出上限。
+Harness 0.15.0 增加可执行文件身份观察与 Node 树 best-effort 记录模式。
 
 **新增**
 
-- 新增公开候选入口 observeFilesystemTree({ root, rootBinding })，每次读取私有树事实，包含文件字节与 POSIX 模式观察。
+- 在稳定隔离树上记录 symlink 自身与原始 target bytes，不跟随链接。
+- 观察解释器后重查原脚本，并按 Unicode code point 排序路径。
 
 **变更**
 
-- 为 superviseProcess 增加 stdout/stderr 独立字节上限，复用既有终止路径；等于上限允许，未设置上限保持旧行为。
+- 省略或 reject symlinkPolicy 时继续使用 0.14 native 路径。
 
 **升级说明**
 
-Contracts 与 Harness 须精确锁步。树观察不执行载荷接受政策，也不承诺事务快照。候选准备不代表发布完成。
+record 模式仍为 candidate best-effort，不提供事务快照或恶意并发写者安全保证。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -37,17 +38,28 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 
 ## 安装和最小示例
 
-0.13.0 尚未发布。下面的 registry 安装命令供发布后使用；本轮验证应在隔离目录安装三个本地候选 tarball。
+0.15.0 是本地候选版本。候选验证先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
 
 ```sh
-npm install skill-family-harness-node@0.13.0
+pack_dir="$(mktemp -d)"
+(cd packages/skill-family-contracts && pnpm pack --pack-destination "$pack_dir")
+(cd packages/skill-family-harness-node && pnpm pack --pack-destination "$pack_dir")
+(cd packages/skill-family-engineering-kit && pnpm pack --pack-destination "$pack_dir")
+mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.15.0.tgz" "$pack_dir/skill-family-harness-node-0.15.0.tgz" "$pack_dir/skill-family-engineering-kit-0.15.0.tgz")
+```
+
+发布后再使用 registry 坐标：
+
+```sh
+npm install skill-family-harness-node@0.15.0
 npm info skill-family-harness-node --help
 ```
 
 最小示例演示在 Node 内校验一份契约文档：
 
 ```js
-// 从空目录运行：npm install skill-family-harness-node@0.13.0
+// 发布后从已安装的消费者目录运行。
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {
@@ -101,13 +113,17 @@ v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字
 | 导出 | 职责 |
 | --- | --- |
 | `HARNESS_CAPABILITIES` / `HARNESS_EXCLUSIONS` | 能力与排除清单（冻结常量）。 |
+| `FOUNDATION_PACKAGE_VERSION` | 供锁步检查使用的精确 Foundation 包版本。 |
 | `HarnessError` / `HARNESS_ERROR_KINDS` / `mechanismError` | 机制失败统一携带注册错误码 `SFC2004`，`details.kind` 给出稳定细分。 |
 | `validateContractDocument` / `getValidator` / `resolveSchemaContext` / `validatorCacheSize` | 按 Schema 方言路由并缓存 validator；复用 Contracts 的 Ajv 实例与 dialect/policy 语义。 |
 | `classifyPathInput` / `resolveContained` / `readFileContained` | 路径收容：拦截路径越界、符号链接逃逸、真实路径逃逸。 |
 | `writeFileAtomic` | 原子写：失败不留半成品（临时文件 + fsync + rename）。 |
+| `createAtomicWriteFake({ vector })` | 消费者契约测试用正式无文件系统测试替身；产生确定性的写入/替换/观察事实。 |
 | `TemporaryWorkspace` / `createTemporaryWorkspace` / `withTemporaryWorkspace` | 自动清理的临时工作区，异常路径也清理。 |
 | `digestBytes` / `computeResourceClosure` / `closureContains` | 资源闭包与确定性 sha256 摘要。 |
 | `superviseProcess` / `validateTimeoutPolicy` | 唯一的受约束子进程监督器。0.11.0 的 `rawSink` 只向 fresh canonical 私有根写原始 stdout/stderr 字节，并等待子进程、流、排队写入、fsync 与句柄全部关闭。调用方必须在整个调用期间独占 sink 命名空间；句柄保护不证明 pathname 或根目录身份始终不变。 |
+| `observeFilesystemTree` | 观察完整绑定树。默认/reject 保留既有 UTF-16 成员顺序；record 使用码点顺序，记录 symlink target bytes 且不跟随目标。 |
+| `observeExecutableIdentity` | 观察调用方绑定的可执行入口、符号链接链、启动字节和脚本解释器链，供每次 spawn 前紧邻重观察。 |
 | `parseRequest` / `processRequest` | 解析 `operation-request`，输出终态 `operation-result`。 |
 | `validateReportModel` / `renderReportMarkdown` / `buildBinding` / `checkReport` | 消费经 Contracts 验证的 report model，确定性渲染中性 Markdown 并校验来源/结果/报告绑定；不解释业务输出。 |
 | `normalizeAdapterSource` / `buildAdapterClosure` / `verifyAdapterBuildManifest` / `materializeAdapterBuild` | 通用文本 source closure、manifest 全摘要复验和目标集合原子落盘；具体 Profile/driver 不在 Harness。 |
@@ -169,7 +185,7 @@ v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字
 ### Do not use when
 
 - 需要把文件选择的业务规则放入 Foundation（业务规则由调用方拥有）。
-- 需要宿主身份策略、宿主 driver、远端发布、删除式 uninstall、Qoder 完整 driver 或二进制 adapter source（明确 unsupported）。
+- 需要宿主身份策略、宿主专属生命周期计划、远端发布、删除式 uninstall 或二进制 adapter source。宿主策略与生命周期计划归 Engineering Kit。
 - 需要领域审计语义、重试编排或兼容性已冻结的 Quickstart API。
 
 ### Capability selection
@@ -229,4 +245,12 @@ v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字
 
 新增候选 observeFilesystemTree({ root, rootBinding }) 读取完整树事实；既有 superviseProcess 支持可选每流原始字节上限。观察完成不等于接受载荷。
 
-0.13.0 为本地源码候选，尚未发布。消费本地已验证的三包 tarball，不能把版本标记、单元测试或安装成功当作完整宿主资格与发布批准。
+`observeFilesystemTree({ root, rootBinding, symlinkPolicy: { mode: "record" } })` 适用于宿主命令完成后、调用方已隔离且扫描期间没有并发 namespace writer 的稳定安装树、缓存树或投影树。它记录 symlink 自身的 `targetBase64`、`bytes` 和 `statMode`，只读取原始 target bytes，绝不跟随 target；普通文件仍复用 `readFileBound`。record 是 Node/JS best-effort candidate：发现扫描期间的漂移会失败关闭，但不提供事务快照、同 UID 恶意并发或 ABA 保证，这不改变稳定树结果的正常使用语义。release-skill 等消费者负责调用时机，并继续负责 npm `.bin` 等领域接受规则。
+
+成员排序按模式区分，以保留兼容性：省略策略或使用 reject 时沿用 0.14 的 UTF-16 关系顺序，record 使用 Unicode 码点顺序；`membersDigest` 也按对应顺序推导。
+
+真实威胁包含恶意并发时，应形成最小上游能力缺口并交回 Foundation 裁决；不要在技能族内复制通用 walker、native addon、Harness、schema、Registry、runner 或 receipt 链，也不要自行升级为四平台原生实现。
+
+另一个独立候选 `observeExecutableIdentity({ boundRoots, lookup, interpreterPolicy? })` 只对调用方显式提供的根和查找路径做逐次只读观察，供正式启动前紧邻重观察。`/usr/bin/env` shebang 通过显式 `pathEntries` 找到解释器时，结果保留解释器候选的完整 symlink chain，不折叠成最终文件。它不属于 `host-adapter`，也不证明 wrapper 控制流、ambient `PATH`、fd-exec/内核映像、签名信任、跨调用缓存、宿主支持/生命周期或领域接受；这些语义仍由调用方负责。候选入口存在不等于宿主已获资格。
+
+0.15.0 为本地源码候选，尚未发布。消费本地已验证的三包 tarball；版本标记、单元测试或安装成功都不等于契约接入完成、迁移完成或真实宿主资格。

package/package.json

@@ -10,7 +10,7 @@
   "dependencies": {
     "@pnpm/lockfile.fs": "1001.1.35",
     "ipaddr.js": "2.5.0",
-    "skill-family-contracts": "0.13.0",
+    "skill-family-contracts": "0.15.0",
     "yaml": "2.9.0"
   },
   "description": "Thin Node.js mechanism runtime for Skill Family engineering contracts.",
@@ -22,6 +22,7 @@
     ".": "./src/index.mjs",
     "./candidate/quickstart-profile": "./candidate/quickstart-profile.mjs",
     "./candidate/rename-directory-no-replace": "./candidate/rename-directory-no-replace/rename-directory-no-replace.mjs",
+    "./contract-testing": "./src/contract-testing.mjs",
     "./fixed-set-publication": "./src/fixed-set-publication.mjs",
     "./quickstart-profile": "./candidate/quickstart-profile.mjs",
     "./rename-directory-no-replace": "./candidate/rename-directory-no-replace/rename-directory-no-replace.mjs"
@@ -48,7 +49,7 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node.git"
   },
   "type": "module",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "scripts": {
     "check": "node --test",
     "test": "node --test"

package/release-notes/0.14.0.yaml

@@ -0,0 +1,23 @@
+version: 0.14.0
+date: 2026-08-28
+locales:
+  en:
+    summary: Harness 0.14.0 adds an official atomic-write fake, a synchronized package version export, and canonical temporary workspace roots for safe raw sinks.
+    changes:
+      added:
+        - Adds createAtomicWriteFake({ vector }) with deterministic write, replace, and observation facts and no filesystem side effects.
+        - Exposes FOUNDATION_PACKAGE_VERSION for lockstep consumers.
+        - Returns canonical realpaths from TemporaryWorkspace.create() and fromBaseline(). A root returned by create() can be passed directly to superviseProcess rawSink while it remains fresh and empty. A materialized non-empty baseline root is rejected by rawSink freshness validation.
+      changed:
+        - Documents that the fake verifies adapter wiring, not the domain guarantee or real-host qualification.
+    upgradeNotes: Pin Contracts, Harness, and Engineering Kit to 0.14.0 together. Use the official fake with the Contracts vectors; retain real filesystem and domain tests for production guarantees. Temporary workspace roots are canonical. A root returned by create() can be passed directly to superviseProcess rawSink while it remains fresh and empty. A materialized non-empty baseline root is rejected by rawSink freshness validation.
+  zh-CN:
+    summary: 'Harness 0.14.0 增加消费者契约测试用正式 atomic-write 测试替身（`fake`）、同步公开包版本导出，并让临时工作区根目录返回 canonical realpath。'
+    changes:
+      added:
+        - 新增 `createAtomicWriteFake({ vector })`，提供确定性的写入、替换和观察事实且不触碰文件系统。
+        - 公开 `FOUNDATION_PACKAGE_VERSION`，供锁步消费者使用。
+        - '`TemporaryWorkspace.create()` 与 `fromBaseline()` 返回 canonical realpath。`create()` 返回的根目录在保持 fresh 且为空时，可以直接传给 `superviseProcess` 的 `rawSink`。物化后的非空 baseline 根目录会被 `rawSink` 的 freshness 校验拒绝。'
+      changed:
+        - 明确测试替身用于验证适配器接线，不代表领域保证或真实宿主资格。
+    upgradeNotes: 'Contracts、Harness 与 Engineering Kit 须一起精确锁定到 0.14.0。用正式测试替身配合 Contracts 向量；生产保证仍须由真实文件系统和领域测试覆盖。临时工作区根目录已经 canonical。`create()` 返回的根目录在保持 fresh 且为空时，可以直接传给 `superviseProcess` 的 `rawSink`。物化后的非空 baseline 根目录会被 `rawSink` 的 freshness 校验拒绝。'

package/release-notes/0.15.0.yaml

@@ -0,0 +1,21 @@
+version: 0.15.0
+date: 2026-08-29
+locales:
+  en:
+    summary: Harness 0.15.0 adds executable identity observation and a best-effort Node tree record mode.
+    changes:
+      added:
+        - Records symlink target bytes without following links on a stable isolated tree.
+        - Rechecks the original script after observing its interpreter and orders paths by Unicode code point.
+      changed:
+        - Keeps omitted and reject symlink policy on the 0.14 native path.
+    upgradeNotes: Record mode is candidate best effort; it does not provide a transaction snapshot or hostile concurrent-writer safety.
+  zh-CN:
+    summary: Harness 0.15.0 增加可执行文件身份观察与 Node 树 best-effort 记录模式。
+    changes:
+      added:
+        - 在稳定隔离树上记录 symlink 自身与原始 target bytes，不跟随链接。
+        - 观察解释器后重查原脚本，并按 Unicode code point 排序路径。
+      changed:
+        - 省略或 reject symlinkPolicy 时继续使用 0.14 native 路径。
+    upgradeNotes: record 模式仍为 candidate best-effort，不提供事务快照或恶意并发写者安全保证。

package/src/contract-testing.mjs

@@ -0,0 +1,173 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import {
+  ContractsError,
+  assertRegisteredErrorCode,
+  verifyConsumerContractVector,
+} from "skill-family-contracts";
+import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
+import { FOUNDATION_PACKAGE_VERSION } from "./version.mjs";
+
+const ATOMIC_WRITE_CAPABILITY = "foundation.harness.atomic-write";
+const ATOMIC_WRITE_VECTOR_SET = "foundation.harness.atomic-write.consumer-v1";
+const ATOMIC_WRITE_CONTRACT = "skill-family-harness-node:writeFileAtomic";
+
+function deepFreeze(value, seen = new Set()) {
+  if (value === null || typeof value !== "object" || seen.has(value)) return value;
+  seen.add(value);
+  for (const child of Object.values(value)) deepFreeze(child, seen);
+  return Object.freeze(value);
+}
+
+function sameValue(left, right, seen = new Set()) {
+  if (Object.is(left, right)) return true;
+  if (left === null || right === null || typeof left !== typeof right) return false;
+  if (typeof left !== "object") return false;
+  if (Buffer.isBuffer(left) || Buffer.isBuffer(right)) {
+    return Buffer.isBuffer(left) && Buffer.isBuffer(right) && left.equals(right);
+  }
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return Array.isArray(left) && Array.isArray(right) && left.length === right.length &&
+      left.every((value, index) => sameValue(value, right[index], seen));
+  }
+  if (seen.has(left)) return true;
+  seen.add(left);
+  const leftKeys = Object.keys(left).sort();
+  const rightKeys = Object.keys(right).sort();
+  return leftKeys.length === rightKeys.length &&
+    leftKeys.every((key, index) => key === rightKeys[index] && sameValue(left[key], right[key], seen));
+}
+
+function dataSummary(data) {
+  if (typeof data === "string") return data;
+  if (Buffer.isBuffer(data)) {
+    return {
+      kind: "Buffer",
+      bytes: data.byteLength,
+      sha256: createHash("sha256").update(data).digest("hex"),
+    };
+  }
+  if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
+    const bytes = data instanceof ArrayBuffer
+      ? Buffer.from(data)
+      : Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    return {
+      kind: data.constructor?.name ?? "ArrayBufferView",
+      bytes: bytes.byteLength,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+    };
+  }
+  return undefined;
+}
+
+function cloneForObservation(value, seen = new Map()) {
+  if (value === null || typeof value !== "object") return value;
+  if (Buffer.isBuffer(value)) return dataSummary(value);
+  if (seen.has(value)) return "[Circular]";
+  seen.set(value, true);
+  if (Array.isArray(value)) return value.map((child) => cloneForObservation(child, seen));
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, cloneForObservation(value[key], seen)]));
+}
+
+function contractMismatch(validation) {
+  const code = validation?.mismatchCode ?? "SFC1001";
+  return new ContractsError(code, "atomic-write fake requires an official verified consumer contract vector", {
+    vectorId: validation?.vectorId ?? null,
+    observed: validation,
+  });
+}
+
+function invalidRequest(message, details) {
+  return mechanismError(HARNESS_ERROR_KINDS.ATOMIC_WRITE_FAILED, message, details);
+}
+
+function requestMatches(vector, root, relPath, data, mode) {
+  const expected = vector.request;
+  return typeof root === "string" && root.length > 0 && path.isAbsolute(root) &&
+    path.normalize(root) === root &&
+    relPath === expected.relPath && sameValue(data, expected.data) &&
+    sameValue({ mode }, expected.options);
+}
+
+/**
+ * Creates the atomic-write fake published for the exact Foundation vector set.
+ * The fake is deliberately single-use and performs no filesystem operation.
+ */
+export function createAtomicWriteFake({ vector } = {}) {
+  let vectorSnapshot;
+  try {
+    vectorSnapshot = structuredClone(vector);
+  } catch (cause) {
+    throw new ContractsError("SFC1001", "atomic-write fake requires a structured consumer contract vector", {
+      cause: cause?.name ?? "DataCloneError",
+    });
+  }
+  const validation = verifyConsumerContractVector(vectorSnapshot, {
+    capabilityId: ATOMIC_WRITE_CAPABILITY,
+    foundationVersion: FOUNDATION_PACKAGE_VERSION,
+    vectorSetId: ATOMIC_WRITE_VECTOR_SET,
+  });
+  if (!validation.ok) throw contractMismatch(validation);
+  if (vectorSnapshot.contractId !== ATOMIC_WRITE_CONTRACT || vectorSnapshot.strategy !== "official-fake") {
+    throw contractMismatch({ ...validation, mismatchCode: "SFC1013" });
+  }
+  deepFreeze(vectorSnapshot);
+
+  const identity = deepFreeze({
+    capabilityId: ATOMIC_WRITE_CAPABILITY,
+    vectorSetId: ATOMIC_WRITE_VECTOR_SET,
+    foundationVersion: FOUNDATION_PACKAGE_VERSION,
+  });
+  let consumed = false;
+  let state = { callCount: 0, request: null, outcome: "indeterminate" };
+
+  function observation() {
+    return deepFreeze(cloneForObservation(state));
+  }
+
+  async function writeFileAtomic(root, relPath, data, { mode = 0o644 } = {}) {
+    if (consumed) {
+      throw invalidRequest("atomic-write fake vector was already consumed", { vectorId: vectorSnapshot.vectorId });
+    }
+    if (!requestMatches(vectorSnapshot, root, relPath, data, mode)) {
+      throw invalidRequest("atomic-write fake received a request different from its verified vector", {
+        vectorId: vectorSnapshot.vectorId,
+      });
+    }
+    consumed = true;
+    state = {
+      callCount: 1,
+      request: {
+        root: cloneForObservation(root),
+        relPath: cloneForObservation(relPath),
+        data: cloneForObservation(data),
+        options: cloneForObservation({ mode }),
+      },
+      outcome: vectorSnapshot.expected.outcome,
+    };
+
+    if (vectorSnapshot.expected.outcome === "return" || vectorSnapshot.expected.outcome === "indeterminate") {
+      const value = path.join(root, vectorSnapshot.request.relPath);
+      if (!path.isAbsolute(value) || value === root) {
+        state = { ...state, outcome: "throw", errorCode: "SFC2004" };
+        throw invalidRequest("atomic-write fake could not project an absolute target", { vectorId: vectorSnapshot.vectorId });
+      }
+      state = { ...state, outcome: "return", value };
+      return value;
+    }
+
+    const errorCode = vectorSnapshot.expected.errorCode ?? "SFC2004";
+    const errorKind = vectorSnapshot.expected.errorKind;
+    assertRegisteredErrorCode(errorCode);
+    state = { ...state, errorCode, errorKind };
+    if (errorCode === "SFC2004") {
+      if (errorKind === HARNESS_ERROR_KINDS.PATH_TRAVERSAL) {
+        throw mechanismError(errorKind, "atomic-write fake projected the vector failure", { vectorId: vectorSnapshot.vectorId });
+      }
+      throw invalidRequest("atomic-write fake projected the vector failure", { vectorId: vectorSnapshot.vectorId });
+    }
+    throw new ContractsError(errorCode, "atomic-write fake projected the vector failure", { vectorId: vectorSnapshot.vectorId });
+  }
+
+  return Object.freeze({ identity, writeFileAtomic, observation });
+}

package/src/errors.mjs

@@ -59,6 +59,8 @@ export const HARNESS_ERROR_KINDS = Object.freeze({
   HOST_BUILD_FAILED: "host-build-failed",
   HOST_PROBE_FAILED: "host-probe-failed",
   UNTRUSTED_EXECUTABLE: "untrusted-executable",
+  EXECUTABLE_NOT_FOUND: "executable-not-found",
+  UNSUPPORTED_INTERPRETER: "unsupported-interpreter",
   PORTABLE_PATH_COLLISION: "portable-path-collision",
   MANIFEST_MISMATCH: "manifest-mismatch",
   BASELINE_MISMATCH: "baseline-mismatch",