skill-family-harness-node 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+<!-- 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,26 @@
 # 变更日志
 
+<!-- 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,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.13.0 -->
+<!-- release-skill:release-version: 0.14.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.14.0** (2026-08-28)
 
-Harness 0.13.0 is a source candidate for complete bound-tree observations and optional subprocess output limits.
+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 observeFilesystemTree({ root, rootBinding }) as a public candidate entry for fresh private tree facts, including file bytes and POSIX mode observations.
+- 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**
 
-- Extends superviseProcess with independent stdout/stderr byte limits using the existing termination path. Equal-to-limit output is allowed; uncapped behavior remains compatible.
+- Documents that the fake verifies adapter wiring, not the domain guarantee or real-host qualification.
 
 **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.
+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:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -36,17 +38,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.14.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.14.0.tgz" "$pack_dir/skill-family-harness-node-0.14.0.tgz" "$pack_dir/skill-family-engineering-kit-0.14.0.tgz")
+```
+
+After publication, use the registry coordinate:
+
+```sh
+npm install skill-family-harness-node@0.14.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,10 +113,12 @@ 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. |
@@ -229,4 +244,4 @@ 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.
+Version 0.14.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,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.13.0 -->
+<!-- release-skill:release-version: 0.14.0 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.13.0** (2026-08-26)
+**0.14.0** (2026-08-28)
 
-Harness 0.13.0 源码候选增加完整绑定树观察与可选子进程输出上限。
+Harness 0.14.0 增加消费者契约测试用正式 atomic-write 测试替身（`fake`）、同步公开包版本导出，并让临时工作区根目录返回 canonical realpath。
 
 **新增**
 
-- 新增公开候选入口 observeFilesystemTree({ root, rootBinding })，每次读取私有树事实，包含文件字节与 POSIX 模式观察。
+- 新增 `createAtomicWriteFake({ vector })`，提供确定性的写入、替换和观察事实且不触碰文件系统。
+- 公开 `FOUNDATION_PACKAGE_VERSION`，供锁步消费者使用。
+- `TemporaryWorkspace.create()` 与 `fromBaseline()` 返回 canonical realpath。`create()` 返回的根目录在保持 fresh 且为空时，可以直接传给 `superviseProcess` 的 `rawSink`。物化后的非空 baseline 根目录会被 `rawSink` 的 freshness 校验拒绝。
 
 **变更**
 
-- 为 superviseProcess 增加 stdout/stderr 独立字节上限，复用既有终止路径；等于上限允许，未设置上限保持旧行为。
+- 明确测试替身用于验证适配器接线，不代表领域保证或真实宿主资格。
 
 **升级说明**
 
-Contracts 与 Harness 须精确锁步。树观察不执行载荷接受政策，也不承诺事务快照。候选准备不代表发布完成。
+Contracts、Harness 与 Engineering Kit 须一起精确锁定到 0.14.0。用正式测试替身配合 Contracts 向量；生产保证仍须由真实文件系统和领域测试覆盖。临时工作区根目录已经 canonical。`create()` 返回的根目录在保持 fresh 且为空时，可以直接传给 `superviseProcess` 的 `rawSink`。物化后的非空 baseline 根目录会被 `rawSink` 的 freshness 校验拒绝。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -37,17 +39,28 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 
 ## 安装和最小示例
 
-0.13.0 尚未发布。下面的 registry 安装命令供发布后使用；本轮验证应在隔离目录安装三个本地候选 tarball。
+0.14.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.14.0.tgz" "$pack_dir/skill-family-harness-node-0.14.0.tgz" "$pack_dir/skill-family-engineering-kit-0.14.0.tgz")
+```
+
+发布后再使用 registry 坐标：
+
+```sh
+npm install skill-family-harness-node@0.14.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,10 +114,12 @@ 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 或根目录身份始终不变。 |
@@ -229,4 +244,4 @@ v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字
 
 新增候选 observeFilesystemTree({ root, rootBinding }) 读取完整树事实；既有 superviseProcess 支持可选每流原始字节上限。观察完成不等于接受载荷。
 
-0.13.0 为本地源码候选，尚未发布。消费本地已验证的三包 tarball，不能把版本标记、单元测试或安装成功当作完整宿主资格与发布批准。
+0.14.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.14.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.14.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/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/index.mjs

@@ -36,6 +36,8 @@ export const HARNESS_CAPABILITIES = Object.freeze([
   "url-credential-redaction",
 ]);
 
+export { FOUNDATION_PACKAGE_VERSION } from "./version.mjs";
+
 export const HARNESS_EXCLUSIONS = Object.freeze([
   "business-semantics",
   "workflow-orchestration",

package/src/version.mjs

@@ -0,0 +1,2 @@
+/** Exact Foundation release coordinate shared by the public Harness exports. */
+export const FOUNDATION_PACKAGE_VERSION = "0.14.0";

package/src/workspace.mjs

@@ -1,4 +1,4 @@
-import { mkdtemp, rm } from "node:fs/promises";
+import fsPromises from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { materializeBaseline } from "./baseline.mjs";
@@ -6,6 +6,46 @@ import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
 import { readFileContained, resolveContained } from "./paths.mjs";
 import { writeFileAtomic } from "./atomic.mjs";
 
+const CLEANUP_OPTIONS = { recursive: true, force: true, maxRetries: 3 };
+
+async function canonicalizeCreatedRoot(root, label) {
+  try {
+    return await fsPromises.realpath(root);
+  } catch (cause) {
+    // The root was created/materialized before canonicalization failed. Keep
+    // the existing create-failed contract while reporting cleanup failure as
+    // part of the same mechanism error instead of hiding it.
+    let cleanupCode;
+    try {
+      await fsPromises.rm(root, CLEANUP_OPTIONS);
+    } catch (cleanupCause) {
+      cleanupCode = cleanupCause && cleanupCause.code ? cleanupCause.code : "unknown";
+    }
+    const code = cause && cause.code ? cause.code : "unknown";
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.WORKSPACE_CREATE_FAILED,
+      `cannot canonicalize ${label}: ${code}`,
+      {
+        code,
+        ...(cleanupCode ? { cleanup: { code: cleanupCode } } : {}),
+      },
+    );
+  }
+}
+
+async function createCanonicalTemporaryRoot(prefix, label) {
+  let root;
+  try {
+    root = await fsPromises.mkdtemp(path.join(os.tmpdir(), prefix));
+  } catch (cause) {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.WORKSPACE_CREATE_FAILED,
+      `cannot create ${label}: ${cause && cause.code ? cause.code : "unknown"}`,
+    );
+  }
+  return canonicalizeCreatedRoot(root, label);
+}
+
 /**
  * Auto-cleaning temporary workspaces.
  *
@@ -28,15 +68,8 @@ export class TemporaryWorkspace {
     if (typeof prefix !== "string" || prefix.length === 0 || prefix.includes("/") || prefix.includes("\0")) {
       throw new TypeError("TemporaryWorkspace.create: prefix must be a non-empty, separator-free string");
     }
-    try {
-      const root = await mkdtemp(path.join(os.tmpdir(), prefix));
-      return new TemporaryWorkspace(root);
-    } catch (cause) {
-      throw mechanismError(
-        HARNESS_ERROR_KINDS.WORKSPACE_CREATE_FAILED,
-        `cannot create temporary workspace: ${cause && cause.code ? cause.code : "unknown"}`,
-      );
-    }
+    const root = await createCanonicalTemporaryRoot(prefix, "temporary workspace");
+    return new TemporaryWorkspace(root);
   }
 
   /**
@@ -58,7 +91,8 @@ export class TemporaryWorkspace {
     if (contentGuard !== undefined && typeof contentGuard !== "function") {
       throw new TypeError("TemporaryWorkspace.fromBaseline: contentGuard must be a function or undefined");
     }
-    const root = await materializeBaseline({ baselineDir, baselineDigest, prefix });
+    const materializedRoot = await materializeBaseline({ baselineDir, baselineDigest, prefix });
+    const root = await canonicalizeCreatedRoot(materializedRoot, "baseline workspace");
     const workspace = new TemporaryWorkspace(root);
     if (contentGuard === undefined) return workspace;
     try {
@@ -119,7 +153,7 @@ export class TemporaryWorkspace {
     if (this.#disposed) return;
     this.#disposed = true;
     try {
-      await rm(this.#root, { recursive: true, force: true, maxRetries: 3 });
+      await fsPromises.rm(this.#root, { recursive: true, force: true, maxRetries: 3 });
     } catch (cause) {
       throw mechanismError(
         HARNESS_ERROR_KINDS.WORKSPACE_DISPOSE_FAILED,