skill-family-harness-node 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.18.0 locale=en baseline=sha256:ca3679574ea53013c830563ae818326062794aec1f486e6953e89fa8937be644 -->
+## [0.18.0] - 2026-09-05
+
+Harness 0.18.0 adds the stable replaceFixedSetAtomic operation for replacing one existing fixed-set directory with one complete staged sibling.
+
+### Added
+
+- Adds replaceFixedSetAtomic to the package root and fixed-set-publication subpath. Source and target must be real sibling directories under the same canonical parent.
+- Uses one Darwin RENAME_SWAP or Linux RENAME_EXCHANGE commit. On success, the complete new set occupies the target and the displaced old target remains at sourceRoot.
+
+### Changed
+
+- Reports pre-commit, post-commit, publication, verification, commit, and durability state through the existing SFC2004 mechanism-error surface when replacement cannot return a verified success.
+
+### Upgrade Notes
+
+Pin all three Foundation packages to exactly 0.18.0. replaceFixedSetAtomic is not idempotent: calling it again with the same paths exchanges the directories back. Never retry blindly after success or a post-commit or indeterminate error. The caller owns cleanup of the displaced target after a verified success.
+<!-- release-skill:changelog:end version=0.18.0 locale=en -->
+
+
+<!-- release-skill:changelog:start version=0.17.0 locale=en baseline=sha256:5c685956ff1920dccdd91198687dbc1414bfef474a0d297bbcb7704014c549bd -->
+## [0.17.0] - 2026-09-01
+
+Harness 0.17.0 is a lockstep version update with no new mechanism, native source change, or public API.
+
+### Changed
+
+- Moves the package version to 0.17.0 together with Contracts and Engineering Kit while preserving the existing Harness capability and native prebuild surfaces.
+
+### Upgrade Notes
+
+Pin all three Foundation packages to exactly 0.17.0. Engineering-baseline validation and structural comparison belong to Contracts and Engineering Kit; no Harness migration is required.
+<!-- release-skill:changelog:end version=0.17.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.16.0 locale=en baseline=sha256:27fd0f5623d5c93b3076af93231101956233f179dd0cab3d1c74dae891668ea8 -->
 ## [0.16.0] - 2026-08-31
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,40 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.18.0 locale=zh-CN baseline=sha256:ba40c3c901c8f717b18d131344fe94a470c149ddb1d0f96e5611d38bf1c70d3d -->
+## [0.18.0] - 2026-09-05
+
+Harness 0.18.0 新增稳定的 replaceFixedSetAtomic，用一个完整暂存目录替换一个既有固定集合目录。
+
+### 新增
+
+- 包根与 fixed-set-publication 子路径新增 replaceFixedSetAtomic。源目录和目标目录必须是同一规范父目录下的真实兄弟目录。
+- 提交只执行一次 Darwin RENAME_SWAP 或 Linux RENAME_EXCHANGE。成功后，新集合完整位于目标路径，被置换的旧目标留在 sourceRoot。
+
+### 变更
+
+- 替换无法返回已验证成功时，沿用 SFC2004 机制错误表面，报告提交前后、发布、验证、提交和持久化状态。
+
+### 升级说明
+
+三个 Foundation 包须一起精确锁定到 0.18.0。replaceFixedSetAtomic 不是幂等操作：相同路径再次调用会把两个目录交换回去。成功后，或收到提交后及不确定错误时，均不得盲目重试。调用方只在确认成功后负责清理被置换的旧目标。
+<!-- release-skill:changelog:end version=0.18.0 locale=zh-CN -->
+
+
+<!-- release-skill:changelog:start version=0.17.0 locale=zh-CN baseline=sha256:fc1c5f48463b2d62363952f566011600a8a84b11456519507c8dc03bf58756d5 -->
+## [0.17.0] - 2026-09-01
+
+Harness 0.17.0 随 Foundation 锁步升版，不新增机制，不修改原生源码或公共 API。
+
+### 变更
+
+- 包版本与 Contracts、Engineering Kit 一同升至 0.17.0，既有 Harness 能力和原生预构建表面保持不变。
+
+### 升级说明
+
+三个 Foundation 包须一起精确锁定到 0.17.0。工程基线校验与结构比较分别归 Contracts 和 Engineering Kit 负责，无需迁移 Harness API。
+<!-- release-skill:changelog:end version=0.17.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.16.0 locale=zh-CN baseline=sha256:31d28348db231171b1ea5754c514d7fe3cc336c1063026af8763d92553d225de -->
 ## [0.16.0] - 2026-08-31
 

package/README.md

@@ -4,23 +4,27 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.16.0 -->
+<!-- release-skill:release-version: 0.18.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.16.0** (2026-08-31)
+**0.18.0** (2026-09-05)
 
-Harness 0.16.0 clarifies the existing rawSink boundary and keeps output redaction outside Foundation.
+Harness 0.18.0 adds the stable replaceFixedSetAtomic operation for replacing one existing fixed-set directory with one complete staged sibling.
+
+**Added**
+
+- Adds replaceFixedSetAtomic to the package root and fixed-set-publication subpath. Source and target must be real sibling directories under the same canonical parent.
+- Uses one Darwin RENAME_SWAP or Linux RENAME_EXCHANGE commit. On success, the complete new set occupies the target and the displaced old target remains at sourceRoot.
 
 **Changed**
 
-- Documents rawSink as a protected 0600 raw stdout/stderr sink in a fresh canonical temporary root, not a redaction API.
-- Explicitly rejects rawStreamSink, transform sinks, generic sanitizers, second runners, and new stdout callbacks for a single-consumer redaction request.
+- Reports pre-commit, post-commit, publication, verification, commit, and durability state through the existing SFC2004 mechanism-error surface when replacement cannot return a verified success.
 
 **Upgrade Notes**
 
-Consumers that require zero plaintext on the filesystem must own the threat model and implementation; this release adds no redaction or zero-plaintext guarantee.
+Pin all three Foundation packages to exactly 0.18.0. replaceFixedSetAtomic is not idempotent: calling it again with the same paths exchanges the directories back. Never retry blindly after success or a post-commit or indeterminate error. The caller owns cleanup of the displaced target after a verified success.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -33,7 +37,7 @@ The Harness consumes `skill-family-contracts` (a workspace dependency), reusing
 
 ## Installation and Minimal Example
 
-Version 0.16.0 is a local candidate. Build all three tarballs into one temporary directory and install those exact files for a candidate check:
+Version 0.18.0 is a local candidate. Build all three tarballs into one temporary directory and install those exact files for a candidate check:
 
 ```sh
 pack_dir="$(mktemp -d)"
@@ -41,13 +45,13 @@ pack_dir="$(mktemp -d)"
 (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.16.0.tgz" "$pack_dir/skill-family-harness-node-0.16.0.tgz" "$pack_dir/skill-family-engineering-kit-0.16.0.tgz")
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.18.0.tgz" "$pack_dir/skill-family-harness-node-0.18.0.tgz" "$pack_dir/skill-family-engineering-kit-0.18.0.tgz")
 ```
 
 After publication, use the registry coordinate:
 
 ```sh
-npm install skill-family-harness-node@0.16.0
+npm install skill-family-harness-node@0.18.0
 npm info skill-family-harness-node --help
 ```
 
@@ -119,6 +123,7 @@ The capability remains **candidate**. Pin all three Foundation packages exactly
 | `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. |
+| `createFixedSetPublicationManifest` / `publishFixedSet` / `replaceFixedSetAtomic` | Publish a complete fixed set without replacement, or atomically exchange a complete staged sibling with one existing target. |
 | `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. |
@@ -127,6 +132,12 @@ The capability remains **candidate**. Pin all three Foundation packages exactly
 | `readSnapshot` / `writeSnapshot` / `rebuildSnapshot` | Atomic derived snapshots and full-event rebuild; a bad event cannot be masked by an old snapshot, and a bad snapshot can be ignored by rebuild. |
 | `inspectStateStoreLock` / `recoverStateStoreLock` | Read-only lock diagnostics and explicit recovery; recovery must precisely match the observed owner + fencing. |
 
+## Replacing an Existing Fixed Set
+
+`replaceFixedSetAtomic({ sourceRoot, targetParent, targetSegment })` requires `sourceRoot` and the existing target to be real sibling directories under the same canonical parent. It verifies both complete trees, then commits one Darwin `RENAME_SWAP` or Linux `RENAME_EXCHANGE`. A verified success leaves the new set at the target and the displaced old target at `sourceRoot`; Foundation does not delete either directory.
+
+The operation is not idempotent: a second call with the same paths exchanges the directories back. Do not retry blindly after a verified success or an error whose state is post-commit or indeterminate. Mechanism failures use `SFC2004` with `details.kind: "atomic-replace-failed"` and include the phase, publication, commit, verification, and durability state needed for caller-controlled recovery.
+
 ## State Store Lock and Recovery Boundaries
 
 - The lock uses exclusive create; a second writer immediately receives `store-locked`; it does not queue, nor steals the lock by time, PID, or lease expiry.
@@ -249,4 +260,4 @@ When the actual threat includes malicious concurrency, return a minimal upstream
 
 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.16.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.
+Version 0.18.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,23 +5,27 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.16.0 -->
+<!-- release-skill:release-version: 0.18.0 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.16.0** (2026-08-31)
+**0.18.0** (2026-09-05)
 
-Harness 0.16.0 澄清现有 rawSink 边界，将输出脱敏留在 Foundation 之外。
+Harness 0.18.0 新增稳定的 replaceFixedSetAtomic，用一个完整暂存目录替换一个既有固定集合目录。
+
+**新增**
+
+- 包根与 fixed-set-publication 子路径新增 replaceFixedSetAtomic。源目录和目标目录必须是同一规范父目录下的真实兄弟目录。
+- 提交只执行一次 Darwin RENAME_SWAP 或 Linux RENAME_EXCHANGE。成功后，新集合完整位于目标路径，被置换的旧目标留在 sourceRoot。
 
 **变更**
 
-- 明确 rawSink 只适用于在 fresh canonical 临时根中以 0600 保存 stdout/stderr 原始文件的场景，不是脱敏接口。
-- 明确拒绝为单一消费者脱敏需求新增 rawStreamSink、transform sink、通用 sanitizer、第二个 runner 或新的 stdout 回调。
+- 替换无法返回已验证成功时，沿用 SFC2004 机制错误表面，报告提交前后、发布、验证、提交和持久化状态。
 
 **升级说明**
 
-需要硬性保证文件系统中不出现明文的消费者，应自行定义威胁模型并实现；本版本不增加脱敏或零明文保证。
+三个 Foundation 包须一起精确锁定到 0.18.0。replaceFixedSetAtomic 不是幂等操作：相同路径再次调用会把两个目录交换回去。成功后，或收到提交后及不确定错误时，均不得盲目重试。调用方只在确认成功后负责清理被置换的旧目标。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -34,7 +38,7 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 
 ## 安装和最小示例
 
-0.16.0 是本地候选版本。候选验证先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
+0.18.0 是本地候选版本。候选验证先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
 
 ```sh
 pack_dir="$(mktemp -d)"
@@ -42,13 +46,13 @@ pack_dir="$(mktemp -d)"
 (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.16.0.tgz" "$pack_dir/skill-family-harness-node-0.16.0.tgz" "$pack_dir/skill-family-engineering-kit-0.16.0.tgz")
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.18.0.tgz" "$pack_dir/skill-family-harness-node-0.18.0.tgz" "$pack_dir/skill-family-engineering-kit-0.18.0.tgz")
 ```
 
 发布后再使用 registry 坐标：
 
 ```sh
-npm install skill-family-harness-node@0.16.0
+npm install skill-family-harness-node@0.18.0
 npm info skill-family-harness-node --help
 ```
 
@@ -120,6 +124,7 @@ v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字
 | `superviseProcess` / `validateTimeoutPolicy` | 唯一的受约束子进程监督器。0.11.0 的 `rawSink` 只向 fresh canonical 私有根写原始 stdout/stderr 字节，并等待子进程、流、排队写入、fsync 与句柄全部关闭。调用方必须在整个调用期间独占 sink 命名空间；句柄保护不证明 pathname 或根目录身份始终不变。 |
 | `observeFilesystemTree` | 观察完整绑定树。默认/reject 保留既有 UTF-16 成员顺序；record 使用码点顺序，记录 symlink target bytes 且不跟随目标。 |
 | `observeExecutableIdentity` | 观察调用方绑定的可执行入口、符号链接链、启动字节和脚本解释器链，供每次 spawn 前紧邻重观察。 |
+| `createFixedSetPublicationManifest` / `publishFixedSet` / `replaceFixedSetAtomic` | 发布不替换的完整固定集合，或把完整暂存兄弟目录与一个既有目标原子交换。 |
 | `parseRequest` / `processRequest` | 解析 `operation-request`，输出终态 `operation-result`。 |
 | `validateReportModel` / `renderReportMarkdown` / `buildBinding` / `checkReport` | 消费经 Contracts 验证的 report model，确定性渲染中性 Markdown 并校验来源/结果/报告绑定；不解释业务输出。 |
 | `normalizeAdapterSource` / `buildAdapterClosure` / `verifyAdapterBuildManifest` / `materializeAdapterBuild` | 通用文本 source closure、manifest 全摘要复验和目标集合原子落盘；具体 Profile/driver 不在 Harness。 |
@@ -128,6 +133,12 @@ v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字
 | `readSnapshot` / `writeSnapshot` / `rebuildSnapshot` | 原子派生快照与完整事件重建；坏事件不能被旧快照掩盖，坏快照可被重建忽略。 |
 | `inspectStateStoreLock` / `recoverStateStoreLock` | 只读锁诊断与显式恢复；恢复必须对观测到的 owner + fencing 做精确匹配。 |
 
+## 替换既有固定集合
+
+`replaceFixedSetAtomic({ sourceRoot, targetParent, targetSegment })` 要求 `sourceRoot` 与既有目标是同一规范父目录下的真实兄弟目录。它先复验两棵完整目录树，再执行一次 Darwin `RENAME_SWAP` 或 Linux `RENAME_EXCHANGE`。确认成功后，新集合位于目标路径，被置换的旧目标留在 `sourceRoot`；Foundation 不删除任一目录。
+
+该操作不是幂等操作：相同路径再次调用会把两个目录交换回去。确认成功后，或错误状态为提交后及不确定时，不得盲目重试。机制失败使用 `SFC2004` 与 `details.kind: "atomic-replace-failed"`，并给出提交阶段、发布、提交、验证和持久化状态，供调用方自行恢复。
+
 ## 状态存储的锁与恢复边界
 
 - 锁使用 exclusive create，第二写者立即收到 `store-locked`；不排队，也不按时间、PID 或租约过期偷锁。
@@ -249,4 +260,4 @@ v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字
 
 另一个独立候选 `observeExecutableIdentity({ boundRoots, lookup, interpreterPolicy? })` 只对调用方显式提供的根和查找路径做逐次只读观察，供正式启动前紧邻重观察。`/usr/bin/env` shebang 通过显式 `pathEntries` 找到解释器时，结果保留解释器候选的完整 symlink chain，不折叠成最终文件。它不属于 `host-adapter`，也不证明 wrapper 控制流、ambient `PATH`、fd-exec/内核映像、签名信任、跨调用缓存、宿主支持/生命周期或领域接受；这些语义仍由调用方负责。候选入口存在不等于宿主已获资格。
 
-0.16.0 为本地源码候选，尚未发布。消费本地已验证的三包 tarball；版本标记、单元测试或安装成功都不等于契约接入完成、迁移完成或真实宿主资格。
+0.18.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.16.0",
+    "skill-family-contracts": "0.18.0",
     "yaml": "2.9.0"
   },
   "description": "Thin Node.js mechanism runtime for Skill Family engineering contracts.",
@@ -49,7 +49,7 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node.git"
   },
   "type": "module",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "scripts": {
     "check": "node --test",
     "test": "node --test"

package/release-notes/0.17.0.yaml

@@ -0,0 +1,15 @@
+version: 0.17.0
+date: 2026-09-01
+locales:
+  en:
+    summary: Harness 0.17.0 is a lockstep version update with no new mechanism, native source change, or public API.
+    changes:
+      changed:
+        - Moves the package version to 0.17.0 together with Contracts and Engineering Kit while preserving the existing Harness capability and native prebuild surfaces.
+    upgradeNotes: Pin all three Foundation packages to exactly 0.17.0. Engineering-baseline validation and structural comparison belong to Contracts and Engineering Kit; no Harness migration is required.
+  zh-CN:
+    summary: Harness 0.17.0 随 Foundation 锁步升版，不新增机制，不修改原生源码或公共 API。
+    changes:
+      changed:
+        - 包版本与 Contracts、Engineering Kit 一同升至 0.17.0，既有 Harness 能力和原生预构建表面保持不变。
+    upgradeNotes: 三个 Foundation 包须一起精确锁定到 0.17.0。工程基线校验与结构比较分别归 Contracts 和 Engineering Kit 负责，无需迁移 Harness API。

package/release-notes/0.18.0.yaml

@@ -0,0 +1,21 @@
+version: 0.18.0
+date: 2026-09-05
+locales:
+  en:
+    summary: Harness 0.18.0 adds the stable replaceFixedSetAtomic operation for replacing one existing fixed-set directory with one complete staged sibling.
+    changes:
+      added:
+        - Adds replaceFixedSetAtomic to the package root and fixed-set-publication subpath. Source and target must be real sibling directories under the same canonical parent.
+        - Uses one Darwin RENAME_SWAP or Linux RENAME_EXCHANGE commit. On success, the complete new set occupies the target and the displaced old target remains at sourceRoot.
+      changed:
+        - Reports pre-commit, post-commit, publication, verification, commit, and durability state through the existing SFC2004 mechanism-error surface when replacement cannot return a verified success.
+    upgradeNotes: "Pin all three Foundation packages to exactly 0.18.0. replaceFixedSetAtomic is not idempotent: calling it again with the same paths exchanges the directories back. Never retry blindly after success or a post-commit or indeterminate error. The caller owns cleanup of the displaced target after a verified success."
+  zh-CN:
+    summary: Harness 0.18.0 新增稳定的 replaceFixedSetAtomic，用一个完整暂存目录替换一个既有固定集合目录。
+    changes:
+      added:
+        - 包根与 fixed-set-publication 子路径新增 replaceFixedSetAtomic。源目录和目标目录必须是同一规范父目录下的真实兄弟目录。
+        - 提交只执行一次 Darwin RENAME_SWAP 或 Linux RENAME_EXCHANGE。成功后，新集合完整位于目标路径，被置换的旧目标留在 sourceRoot。
+      changed:
+        - 替换无法返回已验证成功时，沿用 SFC2004 机制错误表面，报告提交前后、发布、验证、提交和持久化状态。
+    upgradeNotes: 三个 Foundation 包须一起精确锁定到 0.18.0。replaceFixedSetAtomic 不是幂等操作：相同路径再次调用会把两个目录交换回去。成功后，或收到提交后及不确定错误时，均不得盲目重试。调用方只在确认成功后负责清理被置换的旧目标。

package/src/fixed-set-publication-loader.mjs

@@ -1,5 +1,7 @@
-import { loadNativeBoundReadAddon } from "./native/loader.mjs";
+import { loadNativeBoundReadAddon, stableNativePlatformKey } from "./native/loader.mjs";
 
 export async function loadNativeAddon() {
   return loadNativeBoundReadAddon();
 }
+
+export { stableNativePlatformKey };

package/src/fixed-set-publication.mjs

@@ -3,7 +3,8 @@ import { constants as FS_CONSTANTS } from "node:fs";
 import { lstat, open, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 import { canonicalJson, digestDocument } from "skill-family-contracts";
-import { loadNativeAddon } from "./fixed-set-publication-loader.mjs";
+import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
+import { loadNativeAddon, stableNativePlatformKey } from "./fixed-set-publication-loader.mjs";
 
 const MANIFEST_KIND = "skill-family.fixed-set-publication-manifest";
 const RECEIPT_KIND = "skill-family.fixed-set-publication-receipt";
@@ -47,10 +48,15 @@ function directoryIdentity(stats) {
   };
 }
 
-async function canonicalDirectory(input, label) {
+function assertNormalizedAbsolutePath(input, label) {
   if (typeof input !== "string" || !path.isAbsolute(input) || input.includes("\0") || path.normalize(input) !== input) {
     throw new TypeError(`${label} must be a normalized absolute path`);
   }
+  return input;
+}
+
+async function canonicalDirectory(input, label) {
+  assertNormalizedAbsolutePath(input, label);
   const before = await lstat(input, { bigint: true });
   if (before.isSymbolicLink() || !before.isDirectory()) throw new TypeError(`${label} must be a real directory`);
   const canonical = await realpath(input);
@@ -69,7 +75,7 @@ function assertSegment(value, label) {
   return value;
 }
 
-async function scanDirectory(root) {
+async function scanDirectory(root, { requireMember = true } = {}) {
   if (FS_CONSTANTS.O_NOFOLLOW === undefined) throw new Error("O_NOFOLLOW is required");
   const directories = [];
   const members = [];
@@ -109,7 +115,7 @@ async function scanDirectory(root) {
     }
   }
   await walk("");
-  if (members.length === 0) throw new TypeError("fixed-set source must contain at least one regular file");
+  if (requireMember && members.length === 0) throw new TypeError("fixed-set source must contain at least one regular file");
   return { directories, members };
 }
 
@@ -125,6 +131,137 @@ async function describeSource(sourceRoot) {
   return { root, source, members: closure.members };
 }
 
+async function describeTree(rootPath, label, { requireMember = true } = {}) {
+  const root = await canonicalDirectory(rootPath, label);
+  const closure = await scanDirectory(root.path, { requireMember });
+  return {
+    root,
+    snapshot: {
+      root: root.identity,
+      directories: closure.directories,
+      members: closure.members,
+      closureDigest: digestDocument({
+        root: root.identity,
+        directories: closure.directories,
+        members: closure.members,
+      }),
+    },
+  };
+}
+
+function sameIdentity(left, right) {
+  return left?.type === "directory" && right?.type === "directory" &&
+    left.device === right.device && left.inode === right.inode && left.mode === right.mode;
+}
+
+function sameSnapshot(left, right) {
+  return left?.closureDigest === right?.closureDigest && canonicalJson(left) === canonicalJson(right);
+}
+
+function replacementTuple({
+  phase,
+  publicationState,
+  commitState,
+  verification,
+  durability,
+}) {
+  return { phase, publicationState, commitState, verification, durability };
+}
+
+const PRE_COMMIT_NOT_RUN = Object.freeze(replacementTuple({
+  phase: "pre-commit",
+  publicationState: "not-published",
+  commitState: "not-committed",
+  verification: "not-run",
+  durability: "not-requested",
+}));
+
+const PRE_COMMIT_VERIFIED = Object.freeze(replacementTuple({
+  phase: "pre-commit",
+  publicationState: "not-published",
+  commitState: "not-committed",
+  verification: "original-mapping-verified",
+  durability: "not-requested",
+}));
+
+const POST_COMMIT_PUBLISHED = Object.freeze(replacementTuple({
+  phase: "post-commit",
+  publicationState: "published",
+  commitState: "exchange-committed",
+  verification: "verified",
+  durability: "indeterminate",
+}));
+
+const POST_COMMIT_INDETERMINATE = Object.freeze(replacementTuple({
+  phase: "post-commit",
+  publicationState: "indeterminate",
+  commitState: "indeterminate",
+  verification: "failed",
+  durability: "indeterminate",
+}));
+
+function replacementError(message, tuple, cause, kind = HARNESS_ERROR_KINDS.ATOMIC_REPLACE_FAILED) {
+  const diagnostic = cause?.code ?? cause?.message;
+  return mechanismError(
+    kind,
+    diagnostic ? `${message}: ${diagnostic}` : message,
+    { ...tuple },
+  );
+}
+
+async function observeReplacementMapping({ sourceRoot, targetPath, targetParent, parent, source, target }) {
+  try {
+    const liveParent = await canonicalDirectory(targetParent, "targetParent");
+    if (!sameIdentity(liveParent.identity, parent.identity)) return "other";
+    const liveSource = await describeTree(sourceRoot, "sourceRoot", { requireMember: false });
+    const liveTarget = await describeTree(targetPath, "target", { requireMember: false });
+    if (sameSnapshot(liveSource.snapshot, source.snapshot) && sameSnapshot(liveTarget.snapshot, target.snapshot)) {
+      return "original";
+    }
+    if (sameSnapshot(liveSource.snapshot, target.snapshot) && sameSnapshot(liveTarget.snapshot, source.snapshot)) {
+      return "exchanged";
+    }
+  } catch {
+    // An unobservable side is neither a proved original nor exchanged mapping.
+  }
+  return "other";
+}
+
+async function syncDirectoryBound(directory, expectedIdentity) {
+  if (FS_CONSTANTS.O_NOFOLLOW === undefined || FS_CONSTANTS.O_DIRECTORY === undefined) {
+    throw new Error("O_NOFOLLOW and O_DIRECTORY are required for directory synchronization");
+  }
+  const handle = await open(
+    directory,
+    FS_CONSTANTS.O_RDONLY | FS_CONSTANTS.O_DIRECTORY | FS_CONSTANTS.O_NOFOLLOW,
+  );
+  try {
+    const current = await handle.stat({ bigint: true });
+    if (!current.isDirectory() || !sameIdentity(directoryIdentity(current), expectedIdentity)) {
+      throw new Error("directory identity changed before synchronization");
+    }
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+function trustedNativeResult(value, expectedPlatform) {
+  if (!value || typeof value !== "object" || Array.isArray(value) ||
+      !Number.isInteger(value.status) || typeof value.committed !== "boolean" ||
+      value.platform !== expectedPlatform) {
+    return null;
+  }
+  const keys = Object.keys(value).sort().join(",");
+  if (value.status === 0) {
+    if (value.committed !== true || keys !== "committed,platform,status") return null;
+  } else if (keys !== "committed,error,platform,status" ||
+      typeof value.error !== "string" || value.error.length === 0) {
+    return null;
+  }
+  return value;
+}
+
 /** Mechanically freezes one sibling-directory publication manifest. */
 export async function createFixedSetPublicationManifest({ sourceRoot, targetParent, targetSegment } = {}) {
   const segment = assertSegment(targetSegment, "targetSegment");
@@ -287,3 +424,144 @@ export async function publishFixedSet({ sourceRoot, targetParent, targetSegment,
     memberCount: manifest.members.length,
   });
 }
+
+/**
+ * Atomically exchanges one complete staged fixed set with one existing target.
+ * A successful call leaves the displaced target at sourceRoot. This operation
+ * never deletes either side, retries the exchange, or attempts rollback.
+ */
+export async function replaceFixedSetAtomic({ sourceRoot, targetParent, targetSegment } = {}) {
+  assertNormalizedAbsolutePath(sourceRoot, "sourceRoot");
+  assertNormalizedAbsolutePath(targetParent, "targetParent");
+  const segment = assertSegment(targetSegment, "targetSegment");
+
+  let parent;
+  let sourceRootIdentity;
+  try {
+    parent = await canonicalDirectory(targetParent, "targetParent");
+    sourceRootIdentity = await canonicalDirectory(sourceRoot, "sourceRoot");
+  } catch (cause) {
+    throw replacementError("fixed-set replacement input cannot be observed", PRE_COMMIT_NOT_RUN, cause);
+  }
+  if (path.dirname(sourceRootIdentity.path) !== parent.path) {
+    throw new TypeError("sourceRoot and target must share the same canonical parent");
+  }
+  const sourceSegment = path.basename(sourceRootIdentity.path);
+  if (sourceSegment === segment) throw new TypeError("source and target segments must differ");
+  const targetPath = path.join(parent.path, segment);
+
+  let source;
+  let target;
+  try {
+    source = await describeTree(sourceRootIdentity.path, "sourceRoot");
+    target = await describeTree(targetPath, "target", { requireMember: false });
+  } catch (cause) {
+    throw replacementError("fixed-set replacement trees are unsafe", PRE_COMMIT_NOT_RUN, cause);
+  }
+  const context = {
+    sourceRoot: sourceRootIdentity.path,
+    targetPath,
+    targetParent: parent.path,
+    parent,
+    source,
+    target,
+  };
+
+  const runtimePlatform = stableNativePlatformKey();
+  if (runtimePlatform === null) {
+    throw replacementError(
+      "fixed-set replacement is unsupported on this runtime",
+      PRE_COMMIT_NOT_RUN,
+      null,
+      HARNESS_ERROR_KINDS.UNSUPPORTED_PLATFORM,
+    );
+  }
+
+  let loaded;
+  try {
+    loaded = await loadNativeAddon();
+    if (loaded?.platform !== runtimePlatform) {
+      throw new Error("stable native closure platform does not match the runtime");
+    }
+  } catch (cause) {
+    throw replacementError("stable native closure cannot be loaded", PRE_COMMIT_NOT_RUN, cause);
+  }
+
+  if ((await observeReplacementMapping(context)) !== "original") {
+    throw replacementError("fixed-set replacement input drifted before commit", PRE_COMMIT_NOT_RUN);
+  }
+
+  const addon = loaded?.addon;
+  let parentHandle = null;
+  let nativeResult;
+  let exchangeFailure = null;
+  let closeFailure = null;
+  try {
+    if (!addon || typeof addon.openParentDirectory !== "function" ||
+        typeof addon.closeParentDirectory !== "function" ||
+        typeof addon.exchangeDirectories !== "function") {
+      throw new Error("stable native addon does not expose the directory exchange closure");
+    }
+    parentHandle = addon.openParentDirectory(parent.path);
+    if (parentHandle?.status) {
+      throw new Error(parentHandle.error ?? "parent directory could not be opened");
+    }
+    nativeResult = addon.exchangeDirectories(
+      parentHandle,
+      sourceSegment,
+      segment,
+      parent.identity,
+      source.snapshot.root,
+      target.snapshot.root,
+    );
+  } catch (cause) {
+    exchangeFailure = cause;
+  } finally {
+    if (parentHandle && !parentHandle.status && typeof addon?.closeParentDirectory === "function") {
+      try {
+        const closed = addon.closeParentDirectory(parentHandle);
+        if (closed !== true) throw new Error(closed?.error ?? "parent directory handle did not close cleanly");
+      } catch (cause) {
+        closeFailure = cause;
+      }
+    }
+  }
+
+  const trusted = exchangeFailure === null
+    ? trustedNativeResult(nativeResult, runtimePlatform.startsWith("darwin-") ? "darwin" : "linux")
+    : null;
+  const mapping = await observeReplacementMapping(context);
+  const successfulExchange = closeFailure === null && trusted?.status === 0 &&
+    trusted.committed === true && mapping === "exchanged";
+
+  if (!successfulExchange) {
+    const cause = exchangeFailure ?? closeFailure ??
+      new Error(trusted?.error ?? "native directory exchange result is not trustworthy");
+    if (mapping === "original" && trusted?.committed !== true) {
+      throw replacementError("directory exchange did not commit", PRE_COMMIT_VERIFIED, cause);
+    }
+    if (mapping === "exchanged") {
+      throw replacementError("directory exchange committed without a trustworthy success result", POST_COMMIT_PUBLISHED, cause);
+    }
+    throw replacementError("directory exchange state is indeterminate", POST_COMMIT_INDETERMINATE, cause);
+  }
+
+  try {
+    await syncDirectoryBound(targetPath, source.snapshot.root);
+    await syncDirectoryBound(sourceRootIdentity.path, target.snapshot.root);
+    await syncDirectoryBound(parent.path, parent.identity);
+  } catch (cause) {
+    throw replacementError("directory exchange synchronization failed", POST_COMMIT_PUBLISHED, cause);
+  }
+
+  return Object.freeze({
+    path: targetPath,
+    displacedTargetPath: sourceRootIdentity.path,
+    publicationState: "published",
+    commitState: "exchange-committed",
+    verification: "verified",
+    durability: "namespace-synced",
+    publishedClosureDigest: source.snapshot.closureDigest,
+    displacedClosureDigest: target.snapshot.closureDigest,
+  });
+}

package/src/index.mjs

@@ -199,4 +199,4 @@ export {
   close,
 } from "./state-store.mjs";
 export { createFilesystemRootBinding, readFileBound } from "./bound-read.mjs";
-export { createFixedSetPublicationManifest, publishFixedSet } from "./fixed-set-publication.mjs";
+export { createFixedSetPublicationManifest, publishFixedSet, replaceFixedSetAtomic } from "./fixed-set-publication.mjs";

package/src/native/assemble-stable-prebuild.mjs

@@ -16,7 +16,7 @@ const PLATFORMS = Object.freeze({
   "linux-arm64-gnu": { os: "linux", arch: "arm64", libc: "glibc" },
   "linux-x64-gnu": { os: "linux", arch: "x64", libc: "glibc" },
 });
-const EXPORTS = Object.freeze(["closeParentDirectory", "observeFilesystemTreeNative", "openParentDirectory", "platform", "readFileBoundNative", "renameDirectoryNoReplace"]);
+const EXPORTS = Object.freeze(["closeParentDirectory", "exchangeDirectories", "observeFilesystemTreeNative", "openParentDirectory", "platform", "readFileBoundNative", "renameDirectoryNoReplace"]);
 const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
 const bindingGypSha256 = sha256(readFileSync(BINDING_GYP));
 

package/src/native/bound_read.c

@@ -19,6 +19,9 @@
 #ifndef RENAME_EXCL
 #error "RENAME_EXCL is unavailable"
 #endif
+#ifndef RENAME_SWAP
+#error "RENAME_SWAP is unavailable"
+#endif
 #define PLATFORM_NAME "darwin"
 #elif defined(__linux__)
 #include <linux/fs.h>
@@ -26,6 +29,9 @@
 #ifndef RENAME_NOREPLACE
 #error "RENAME_NOREPLACE is unavailable"
 #endif
+#ifndef RENAME_EXCHANGE
+#error "RENAME_EXCHANGE is unavailable"
+#endif
 #ifndef SYS_renameat2
 #error "SYS_renameat2 is unavailable"
 #endif
@@ -331,6 +337,38 @@ static int read_decimal_property(napi_env env, napi_value object, const char *na
   return 1;
 }
 
+static int read_directory_identity(napi_env env, napi_value object, uint64_t *device,
+                                   uint64_t *inode, int32_t *mode) {
+  napi_value value;
+  if (!read_decimal_property(env, object, "device", device) ||
+      !read_decimal_property(env, object, "inode", inode) ||
+      napi_get_named_property(env, object, "mode", &value) != napi_ok ||
+      napi_get_value_int32(env, value, mode) != napi_ok || *mode < 0 || *mode > 0777) {
+    napi_throw_type_error(env, NULL, "expected directory identity requires device, inode, and mode");
+    return 0;
+  }
+  return 1;
+}
+
+static int matches_directory_identity(const struct stat *actual, uint64_t device,
+                                      uint64_t inode, int32_t mode) {
+  return S_ISDIR(actual->st_mode) && (uint64_t)actual->st_dev == device &&
+    (uint64_t)actual->st_ino == inode &&
+    (actual->st_mode & 0777) == (mode_t)mode;
+}
+
+static napi_value rename_success_result(napi_env env) {
+  napi_value result, value;
+  NAPI_OK(napi_create_object(env, &result), "cannot create native result");
+  NAPI_OK(napi_create_int32(env, 0, &value), "cannot encode native status");
+  NAPI_OK(napi_set_named_property(env, result, "status", value), "cannot set native status");
+  NAPI_OK(napi_get_boolean(env, true, &value), "cannot encode commit state");
+  NAPI_OK(napi_set_named_property(env, result, "committed", value), "cannot set commit state");
+  NAPI_OK(napi_create_string_utf8(env, PLATFORM_NAME, NAPI_AUTO_LENGTH, &value), "cannot encode platform");
+  NAPI_OK(napi_set_named_property(env, result, "platform", value), "cannot set platform");
+  return result;
+}
+
 static int unwrap_parent(napi_env env, napi_value value, parent_handle **output) {
   bool tagged = false;
   if (napi_check_object_type_tag(env, value, &PARENT_HANDLE_TAG, &tagged) != napi_ok || !tagged ||
@@ -356,8 +394,13 @@ static napi_value OpenParentDirectory(napi_env env, napi_callback_info info) {
   parent_handle *handle = calloc(1, sizeof(*handle));
   if (handle == NULL) { close(fd); return throw_last(env, "cannot allocate parent directory handle"); }
   handle->fd = fd;
-  if (napi_create_object(env, &result) != napi_ok || napi_wrap(env, result, handle, finalize_parent, NULL, NULL) != napi_ok ||
-      napi_type_tag_object(env, result, &PARENT_HANDLE_TAG) != napi_ok) {
+  if (napi_create_object(env, &result) != napi_ok) {
+    close(fd); free(handle); return throw_last(env, "cannot create parent directory handle");
+  }
+  if (napi_type_tag_object(env, result, &PARENT_HANDLE_TAG) != napi_ok) {
+    close(fd); free(handle); return throw_last(env, "cannot tag parent directory handle");
+  }
+  if (napi_wrap(env, result, handle, finalize_parent, NULL, NULL) != napi_ok) {
     close(fd); free(handle); return throw_last(env, "cannot create parent directory handle");
   }
   return result;
@@ -369,15 +412,17 @@ static napi_value CloseParentDirectory(napi_env env, napi_callback_info info) {
   parent_handle *handle = NULL;
   NAPI_OK(napi_get_cb_info(env, info, &argc, argv, NULL, NULL), "cannot read arguments");
   if (argc != 1 || !unwrap_parent(env, argv[0], &handle)) return NULL;
-  if (close(handle->fd) != 0) return rename_errno_result(env, errno, 0, strerror(errno));
+  int fd = handle->fd;
   handle->closed = 1;
+  handle->fd = -1;
+  if (close(fd) != 0) return rename_errno_result(env, errno, 0, strerror(errno));
   NAPI_OK(napi_get_boolean(env, true, &result), "cannot encode close result");
   return result;
 }
 
 static napi_value RenameDirectoryNoReplace(napi_env env, napi_callback_info info) {
   size_t argc = 4;
-  napi_value argv[4], value, result;
+  napi_value argv[4], value;
   parent_handle *parent = NULL;
   char source[NAME_MAX + 1], target[NAME_MAX + 1];
   uint64_t expected_device = 0, expected_inode = 0;
@@ -411,14 +456,63 @@ static napi_value RenameDirectoryNoReplace(napi_env env, napi_callback_info info
   if (fstatat(parent->fd, target, &target_after, AT_SYMLINK_NOFOLLOW) != 0 || !S_ISDIR(target_after.st_mode) ||
       target_after.st_dev != source_stat.st_dev || target_after.st_ino != source_stat.st_ino ||
       (target_after.st_mode & 0777) != (source_stat.st_mode & 0777)) return rename_errno_result(env, EIO, 1, "target identity mismatch after committed rename");
-  NAPI_OK(napi_create_object(env, &result), "cannot create native result");
-  NAPI_OK(napi_create_int32(env, 0, &value), "cannot encode native status");
-  NAPI_OK(napi_set_named_property(env, result, "status", value), "cannot set native status");
-  NAPI_OK(napi_get_boolean(env, true, &value), "cannot encode commit state");
-  NAPI_OK(napi_set_named_property(env, result, "committed", value), "cannot set commit state");
-  NAPI_OK(napi_create_string_utf8(env, PLATFORM_NAME, NAPI_AUTO_LENGTH, &value), "cannot encode platform");
-  NAPI_OK(napi_set_named_property(env, result, "platform", value), "cannot set platform");
-  return result;
+  return rename_success_result(env);
+}
+
+static napi_value ExchangeDirectories(napi_env env, napi_callback_info info) {
+  size_t argc = 6;
+  napi_value argv[6];
+  parent_handle *parent = NULL;
+  char source[NAME_MAX + 1], target[NAME_MAX + 1];
+  uint64_t parent_device = 0, parent_inode = 0;
+  uint64_t source_device = 0, source_inode = 0;
+  uint64_t target_device = 0, target_inode = 0;
+  int32_t parent_mode = 0, source_mode = 0, target_mode = 0;
+  NAPI_OK(napi_get_cb_info(env, info, &argc, argv, NULL, NULL), "cannot read arguments");
+  if (argc != 6 || !unwrap_parent(env, argv[0], &parent) ||
+      !read_parent_segment(env, argv[1], source) ||
+      !read_parent_segment(env, argv[2], target)) return NULL;
+  if (strcmp(source, target) == 0) return throw_last(env, "sourceSegment and targetSegment must differ");
+  if (!read_directory_identity(env, argv[3], &parent_device, &parent_inode, &parent_mode) ||
+      !read_directory_identity(env, argv[4], &source_device, &source_inode, &source_mode) ||
+      !read_directory_identity(env, argv[5], &target_device, &target_inode, &target_mode)) return NULL;
+
+  struct stat parent_stat, source_stat, target_stat;
+  if (fstat(parent->fd, &parent_stat) != 0) return rename_errno_result(env, errno, 0, strerror(errno));
+  if (!matches_directory_identity(&parent_stat, parent_device, parent_inode, parent_mode)) {
+    return rename_errno_result(env, EPROTO, 0, "parent identity changed before exchange");
+  }
+  if (fstatat(parent->fd, source, &source_stat, AT_SYMLINK_NOFOLLOW) != 0) {
+    return rename_errno_result(env, errno, 0, strerror(errno));
+  }
+  if (!matches_directory_identity(&source_stat, source_device, source_inode, source_mode)) {
+    return rename_errno_result(env, EPROTO, 0, "source identity changed before exchange");
+  }
+  if (fstatat(parent->fd, target, &target_stat, AT_SYMLINK_NOFOLLOW) != 0) {
+    return rename_errno_result(env, errno, 0, strerror(errno));
+  }
+  if (!matches_directory_identity(&target_stat, target_device, target_inode, target_mode)) {
+    return rename_errno_result(env, EPROTO, 0, "target identity changed before exchange");
+  }
+
+  int rc;
+#if defined(__APPLE__)
+  rc = renameatx_np(parent->fd, source, parent->fd, target, RENAME_SWAP);
+#else
+  rc = (int)syscall(SYS_renameat2, parent->fd, source, parent->fd, target, RENAME_EXCHANGE);
+#endif
+  if (rc != 0) return rename_errno_result(env, errno, 0, strerror(errno));
+
+  struct stat source_after, target_after;
+  if (fstatat(parent->fd, source, &source_after, AT_SYMLINK_NOFOLLOW) != 0 ||
+      !matches_directory_identity(&source_after, target_device, target_inode, target_mode)) {
+    return rename_errno_result(env, EIO, 1, "source identity mismatch after committed exchange");
+  }
+  if (fstatat(parent->fd, target, &target_after, AT_SYMLINK_NOFOLLOW) != 0 ||
+      !matches_directory_identity(&target_after, source_device, source_inode, source_mode)) {
+    return rename_errno_result(env, EIO, 1, "target identity mismatch after committed exchange");
+  }
+  return rename_success_result(env);
 }
 
 /* A complete bound-tree observation is deliberately implemented beside the
@@ -570,6 +664,8 @@ static napi_value Init(napi_env env, napi_value exports) {
   NAPI_OK(napi_set_named_property(env, exports, "openParentDirectory", value), "cannot export openParentDirectory");
   NAPI_OK(napi_create_function(env, "closeParentDirectory", NAPI_AUTO_LENGTH, CloseParentDirectory, NULL, &value), "cannot export closeParentDirectory");
   NAPI_OK(napi_set_named_property(env, exports, "closeParentDirectory", value), "cannot export closeParentDirectory");
+  NAPI_OK(napi_create_function(env, "exchangeDirectories", NAPI_AUTO_LENGTH, ExchangeDirectories, NULL, &value), "cannot export exchangeDirectories");
+  NAPI_OK(napi_set_named_property(env, exports, "exchangeDirectories", value), "cannot export exchangeDirectories");
   NAPI_OK(napi_create_function(env, "renameDirectoryNoReplace", NAPI_AUTO_LENGTH, RenameDirectoryNoReplace, NULL, &value), "cannot export renameDirectoryNoReplace");
   NAPI_OK(napi_set_named_property(env, exports, "renameDirectoryNoReplace", value), "cannot export renameDirectoryNoReplace");
   NAPI_OK(napi_create_string_utf8(env, PLATFORM_NAME, NAPI_AUTO_LENGTH, &value), "cannot encode platform");

package/src/native/loader.mjs

@@ -9,7 +9,7 @@ import { fileURLToPath } from "node:url";
 const PACKAGE_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const MANIFEST_PATH = path.join(PACKAGE_ROOT, "prebuild-manifest.json");
 const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
-const EXPECTED_EXPORTS = Object.freeze(["closeParentDirectory", "observeFilesystemTreeNative", "openParentDirectory", "platform", "readFileBoundNative", "renameDirectoryNoReplace"]);
+const EXPECTED_EXPORTS = Object.freeze(["closeParentDirectory", "exchangeDirectories", "observeFilesystemTreeNative", "openParentDirectory", "platform", "readFileBoundNative", "renameDirectoryNoReplace"]);
 const PLATFORM_KEYS = Object.freeze(["darwin-arm64", "darwin-x64", "linux-arm64-gnu", "linux-x64-gnu"]);
 
 function fail(message) {
@@ -20,11 +20,15 @@ function digest(bytes) {
   return createHash("sha256").update(bytes).digest("hex");
 }
 
-function platformKey() {
-  if (process.platform === "darwin" && ["arm64", "x64"].includes(process.arch)) return `darwin-${process.arch}`;
-  if (process.platform === "linux" && ["arm64", "x64"].includes(process.arch) &&
-      typeof process.report?.getReport?.()?.header?.glibcVersionRuntime === "string") {
-    return `linux-${process.arch}-gnu`;
+export function stableNativePlatformKey({
+  platform = process.platform,
+  arch = process.arch,
+  glibcVersionRuntime = process.report?.getReport?.()?.header?.glibcVersionRuntime,
+} = {}) {
+  if (platform === "darwin" && ["arm64", "x64"].includes(arch)) return `darwin-${arch}`;
+  if (platform === "linux" && ["arm64", "x64"].includes(arch) &&
+      typeof glibcVersionRuntime === "string") {
+    return `linux-${arch}-gnu`;
   }
   return null;
 }
@@ -65,7 +69,7 @@ export async function loadNativeBoundReadAddon() {
   if (FS_CONSTANTS.O_NOFOLLOW === undefined || FS_CONSTANTS.O_DIRECTORY === undefined) fail("required no-follow flags are unavailable");
   const entries = await parseManifest();
   await verifyClosure(entries);
-  const key = platformKey();
+  const key = stableNativePlatformKey();
   const entry = entries.find((candidate) => candidate.platformKey === key);
   if (!entry) fail(`UNSUPPORTED: fixed platform matrix has no runtime ${process.platform}-${process.arch}`);
   const binaryPath = path.join(PACKAGE_ROOT, entry.binary);
@@ -84,7 +88,8 @@ export async function loadNativeBoundReadAddon() {
   try { addon = createRequire(import.meta.url)(binaryReal); } catch (cause) { throw new Error(`filesystemBoundRead: native load failed: ${cause?.message ?? "unknown"}`, { cause }); }
   if (JSON.stringify(Object.keys(addon).sort()) !== JSON.stringify([...EXPECTED_EXPORTS].sort()) || addon.platform !== entry.os ||
       typeof addon.readFileBoundNative !== "function" || typeof addon.openParentDirectory !== "function" ||
-      typeof addon.closeParentDirectory !== "function" || typeof addon.renameDirectoryNoReplace !== "function") {
+      typeof addon.closeParentDirectory !== "function" || typeof addon.exchangeDirectories !== "function" ||
+      typeof addon.renameDirectoryNoReplace !== "function") {
     fail("native exports do not match the fixed manifest");
   }
   const after = await lstat(binaryPath);

package/src/native/prebuild-manifest.json

@@ -10,10 +10,11 @@
       "libc": "none",
       "binary": "prebuilds/darwin-arm64/bound_read.darwin-arm64.node",
       "mode": 420,
-      "sha256": "19ce71026b737ba6b56da78ffabca4bb25f21249c30b545d68633d4b77547fde",
+      "sha256": "afcda237922692e147a800d7d291496d7055e5054bf09ba2e3d2f1ac5d1e445d",
       "napi": 10,
       "exports": [
         "closeParentDirectory",
+        "exchangeDirectories",
         "observeFilesystemTreeNative",
         "openParentDirectory",
         "platform",
@@ -28,10 +29,11 @@
       "libc": "none",
       "binary": "prebuilds/darwin-x64/bound_read.darwin-x64.node",
       "mode": 420,
-      "sha256": "e01e4a1df3554da857189f483174d0480eb36063ce17b5857a23fa8a02f4a664",
+      "sha256": "d3316e4d9dfb8f99ec64b0e495760bb12e4ce95f8522d9779971a82d5ee0c7fb",
       "napi": 10,
       "exports": [
         "closeParentDirectory",
+        "exchangeDirectories",
         "observeFilesystemTreeNative",
         "openParentDirectory",
         "platform",
@@ -46,10 +48,11 @@
       "libc": "glibc",
       "binary": "prebuilds/linux-arm64-gnu/bound_read.linux-arm64-gnu.node",
       "mode": 420,
-      "sha256": "7b7fd1188d2bbf356fe8c44690fd80bc7fb02e9f6f9dc7ee1c10834bf1c519b1",
+      "sha256": "748f6154d01b8873100f288dafba1b6bc542596951ab7978231e67daa9122e5b",
       "napi": 10,
       "exports": [
         "closeParentDirectory",
+        "exchangeDirectories",
         "observeFilesystemTreeNative",
         "openParentDirectory",
         "platform",
@@ -64,10 +67,11 @@
       "libc": "glibc",
       "binary": "prebuilds/linux-x64-gnu/bound_read.linux-x64-gnu.node",
       "mode": 420,
-      "sha256": "749b69ba1b7da3496e59f92f2ca8d04800031b2479c13b3ca63555ee69671acc",
+      "sha256": "ec40dc02bb666ccae585c78f59211951dcc2001bf71c828a59b0d5b821ebfae0",
       "napi": 10,
       "exports": [
         "closeParentDirectory",
+        "exchangeDirectories",
         "observeFilesystemTreeNative",
         "openParentDirectory",
         "platform",

package/src/native/prebuild-release-receipt.json

@@ -8,33 +8,33 @@
   },
   "source": {
     "path": "packages/skill-family-harness-node/src/native/bound_read.c",
-    "sha256": "10cfc3ff44343a532629879841f9ae7a12b78d818d596f85af3915cea9832c15"
+    "sha256": "367b21caadcf3c4d0f13c11fdc90efcfa2603bb5396298cf4a5b7d3c597f1e0b"
   },
   "buildRecipe": {
     "path": "packages/skill-family-harness-node/src/native/binding.gyp",
     "sha256": "1631420afe903b1978a856dbeadd37a655a704cd7ded9d1ab6696f87e1116d7f"
   },
-  "manifestSha256": "76a1e6f99ef5980043df4f328bbe9623dfc8cbba6655e008a8bb1d53d9e49ace",
+  "manifestSha256": "a730d45fab7a61eb5d39f898684d55ace6fc01ea149e4b0f101985b0726c4a41",
   "inputs": [
     {
       "platformKey": "darwin-arm64",
-      "platformReceiptSha256": "eff6c0350d7cb7f949346593af1b65f5791b5545e67eba192ef66bd7af7db93d",
-      "binarySha256": "19ce71026b737ba6b56da78ffabca4bb25f21249c30b545d68633d4b77547fde"
+      "platformReceiptSha256": "243a29778b3430f3c895871e88fcbe6f19f8786f02679d4a03611bfd6220848d",
+      "binarySha256": "afcda237922692e147a800d7d291496d7055e5054bf09ba2e3d2f1ac5d1e445d"
     },
     {
       "platformKey": "darwin-x64",
-      "platformReceiptSha256": "55254e51f14fbe7fa5e6d5a64bf23db3926a49758fbe6afb20bc4c8dbc8b30bb",
-      "binarySha256": "e01e4a1df3554da857189f483174d0480eb36063ce17b5857a23fa8a02f4a664"
+      "platformReceiptSha256": "c7b95b77003d1ef8b299f17bda96d65e034237c8f61bc2a1033e99b8c5760954",
+      "binarySha256": "d3316e4d9dfb8f99ec64b0e495760bb12e4ce95f8522d9779971a82d5ee0c7fb"
     },
     {
       "platformKey": "linux-arm64-gnu",
-      "platformReceiptSha256": "3e4df89d8b211d0700f436314ec6302999e086602bf26d68797d285d40ab7941",
-      "binarySha256": "7b7fd1188d2bbf356fe8c44690fd80bc7fb02e9f6f9dc7ee1c10834bf1c519b1"
+      "platformReceiptSha256": "9ed354775568eea2c954440c501dfeb5404e84e9381afa34e2f8ff0c1fa082b1",
+      "binarySha256": "748f6154d01b8873100f288dafba1b6bc542596951ab7978231e67daa9122e5b"
     },
     {
       "platformKey": "linux-x64-gnu",
-      "platformReceiptSha256": "672d066df845073da0999f69659e772dec3cf0d6b3e34bf74907a5e7fd5190c9",
-      "binarySha256": "749b69ba1b7da3496e59f92f2ca8d04800031b2479c13b3ca63555ee69671acc"
+      "platformReceiptSha256": "5e8cf755503058e7164ae36652df811d7c16c47ab5c65fe9a4748486574b2b0e",
+      "binarySha256": "ec40dc02bb666ccae585c78f59211951dcc2001bf71c828a59b0d5b821ebfae0"
     }
   ]
 }

package/src/native/prebuild-sbom.json

@@ -4,7 +4,7 @@
   "status": "stable",
   "source": {
     "path": "packages/skill-family-harness-node/src/native/bound_read.c",
-    "sha256": "10cfc3ff44343a532629879841f9ae7a12b78d818d596f85af3915cea9832c15"
+    "sha256": "367b21caadcf3c4d0f13c11fdc90efcfa2603bb5396298cf4a5b7d3c597f1e0b"
   },
   "buildRecipe": {
     "path": "packages/skill-family-harness-node/src/native/binding.gyp",
@@ -14,25 +14,25 @@
     {
       "platformKey": "darwin-arm64",
       "binary": "prebuilds/darwin-arm64/bound_read.darwin-arm64.node",
-      "sha256": "19ce71026b737ba6b56da78ffabca4bb25f21249c30b545d68633d4b77547fde",
+      "sha256": "afcda237922692e147a800d7d291496d7055e5054bf09ba2e3d2f1ac5d1e445d",
       "license": "Apache-2.0"
     },
     {
       "platformKey": "darwin-x64",
       "binary": "prebuilds/darwin-x64/bound_read.darwin-x64.node",
-      "sha256": "e01e4a1df3554da857189f483174d0480eb36063ce17b5857a23fa8a02f4a664",
+      "sha256": "d3316e4d9dfb8f99ec64b0e495760bb12e4ce95f8522d9779971a82d5ee0c7fb",
       "license": "Apache-2.0"
     },
     {
       "platformKey": "linux-arm64-gnu",
       "binary": "prebuilds/linux-arm64-gnu/bound_read.linux-arm64-gnu.node",
-      "sha256": "7b7fd1188d2bbf356fe8c44690fd80bc7fb02e9f6f9dc7ee1c10834bf1c519b1",
+      "sha256": "748f6154d01b8873100f288dafba1b6bc542596951ab7978231e67daa9122e5b",
       "license": "Apache-2.0"
     },
     {
       "platformKey": "linux-x64-gnu",
       "binary": "prebuilds/linux-x64-gnu/bound_read.linux-x64-gnu.node",
-      "sha256": "749b69ba1b7da3496e59f92f2ca8d04800031b2479c13b3ca63555ee69671acc",
+      "sha256": "ec40dc02bb666ccae585c78f59211951dcc2001bf71c828a59b0d5b821ebfae0",
       "license": "Apache-2.0"
     }
   ]

package/src/version.mjs

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