skill-family-harness-node 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.19.0 locale=en baseline=sha256:c3b3a06b509cc53719c2de75d1edacd22c1711c99c5f7687ad91f350976262e3 -->
+## [0.19.0] - 2026-09-07
+
+Harness 0.19.0 adds runMechanismCliBatch and the explicit --batch CLI mode for bounded, ordered, same-operation batch transport, with canonical-json as the first operation.
+
+### Added
+
+- Adds runMechanismCliBatch({input, output, error}) on the existing fixed mechanism CLI, reading one batch request and returning per-item results with inputIndex, exitCode, and the original single-request response.
+- Adds the explicit --batch mode to the official Bundle-projected mechanisms-cli.mjs. Without --batch the old single-request path is unchanged.
+
+### Changed
+
+- Batch structure and capacity refusals use TypeError with error.details.kind from the closed set batch-structure-invalid, batch-item-limit, batch-input-limit, and batch-output-limit.
+- A single item's mechanism failure is recorded in its result position and sibling items continue; the whole batch exits 2 when any item failed.
+
+### Upgrade Notes
+
+Pin all three Foundation packages to exactly 0.19.0. The fixed capacity policy is 256 items, 16 MiB input bytes, and 32 MiB output bytes; consumers own grouping independent requests and splitting oversized batches. This entry is candidate: re-verify after upgrading. The old single-request CLI keeps its previous contract.
+<!-- release-skill:changelog:end version=0.19.0 locale=en -->
+
+
+<!-- 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
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,46 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.19.0 locale=zh-CN baseline=sha256:e0a716c69bbc9033af79ab9b1d1b607ba997b5324bb8301dfc8e0b7f4072dab2 -->
+## [0.19.0] - 2026-09-07
+
+Harness 0.19.0 在既有固定机制 CLI 上新增 runMechanismCliBatch 与显式 --batch 模式，提供有界、有序、同操作批量传输，首批操作 canonical-json。
+
+### 新增
+
+- 新增 runMechanismCliBatch({input, output, error})：读入一个批量请求，逐项返回 inputIndex、exitCode 与原单请求响应。
+- 官方 Bundle 投影的 mechanisms-cli.mjs 新增显式 --batch 模式。不带 --batch 时旧单请求路径不变。
+
+### 变更
+
+- 批量结构与容量拒绝使用 TypeError，error.details.kind 封闭为 batch-structure-invalid、batch-item-limit、batch-input-limit、batch-output-limit。
+- 单项机制失败写入该项结果位置，其余项继续执行；任一机制项失败时整批退出码为 2。
+
+### 升级说明
+
+三个 Foundation 包须一起精确锁定到 0.19.0。固定容量政策为 256 项、16 MiB 输入字节、32 MiB 输出字节；相互独立请求的分组与超限切分由消费者负责。该入口为候选能力，升级后须重新验证。旧单请求 CLI 合同保持不变。
+<!-- release-skill:changelog:end version=0.19.0 locale=zh-CN -->
+
+
+<!-- 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
 

package/README.md

@@ -4,22 +4,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.17.0 -->
+<!-- release-skill:release-version: 0.19.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.17.0** (2026-09-01)
+**0.19.0** (2026-09-07)
 
-Harness 0.17.0 is a lockstep version update with no new mechanism, native source change, or public API.
+Harness 0.19.0 adds runMechanismCliBatch and the explicit --batch CLI mode for bounded, ordered, same-operation batch transport, with canonical-json as the first operation.
+
+**Added**
+
+- Adds runMechanismCliBatch({input, output, error}) on the existing fixed mechanism CLI, reading one batch request and returning per-item results with inputIndex, exitCode, and the original single-request response.
+- Adds the explicit --batch mode to the official Bundle-projected mechanisms-cli.mjs. Without --batch the old single-request path is unchanged.
 
 **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.
+- Batch structure and capacity refusals use TypeError with error.details.kind from the closed set batch-structure-invalid, batch-item-limit, batch-input-limit, and batch-output-limit.
+- A single item's mechanism failure is recorded in its result position and sibling items continue; the whole batch exits 2 when any item failed.
 
 **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.
+Pin all three Foundation packages to exactly 0.19.0. The fixed capacity policy is 256 items, 16 MiB input bytes, and 32 MiB output bytes; consumers own grouping independent requests and splitting oversized batches. This entry is candidate: re-verify after upgrading. The old single-request CLI keeps its previous contract.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -32,7 +38,7 @@ The Harness consumes `skill-family-contracts` (a workspace dependency), reusing
 
 ## Installation and Minimal Example
 
-Version 0.17.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)"
@@ -40,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.17.0.tgz" "$pack_dir/skill-family-harness-node-0.17.0.tgz" "$pack_dir/skill-family-engineering-kit-0.17.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.17.0
+npm install skill-family-harness-node@0.19.0
 npm info skill-family-harness-node --help
 ```
 
@@ -118,6 +124,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. |
@@ -126,6 +133,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.
@@ -248,4 +261,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.17.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,22 +5,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.17.0 -->
+<!-- release-skill:release-version: 0.19.0 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.17.0** (2026-09-01)
+**0.19.0** (2026-09-07)
 
-Harness 0.17.0 随 Foundation 锁步升版，不新增机制，不修改原生源码或公共 API。
+Harness 0.19.0 在既有固定机制 CLI 上新增 runMechanismCliBatch 与显式 --batch 模式，提供有界、有序、同操作批量传输，首批操作 canonical-json。
+
+**新增**
+
+- 新增 runMechanismCliBatch({input, output, error})：读入一个批量请求，逐项返回 inputIndex、exitCode 与原单请求响应。
+- 官方 Bundle 投影的 mechanisms-cli.mjs 新增显式 --batch 模式。不带 --batch 时旧单请求路径不变。
 
 **变更**
 
-- 包版本与 Contracts、Engineering Kit 一同升至 0.17.0，既有 Harness 能力和原生预构建表面保持不变。
+- 批量结构与容量拒绝使用 TypeError，error.details.kind 封闭为 batch-structure-invalid、batch-item-limit、batch-input-limit、batch-output-limit。
+- 单项机制失败写入该项结果位置，其余项继续执行；任一机制项失败时整批退出码为 2。
 
 **升级说明**
 
-三个 Foundation 包须一起精确锁定到 0.17.0。工程基线校验与结构比较分别归 Contracts 和 Engineering Kit 负责，无需迁移 Harness API。
+三个 Foundation 包须一起精确锁定到 0.19.0。固定容量政策为 256 项、16 MiB 输入字节、32 MiB 输出字节；相互独立请求的分组与超限切分由消费者负责。该入口为候选能力，升级后须重新验证。旧单请求 CLI 合同保持不变。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -33,7 +39,7 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 
 ## 安装和最小示例
 
-0.17.0 是本地候选版本。候选验证先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
+0.18.0 是本地候选版本。候选验证先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
 
 ```sh
 pack_dir="$(mktemp -d)"
@@ -41,13 +47,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.17.0.tgz" "$pack_dir/skill-family-harness-node-0.17.0.tgz" "$pack_dir/skill-family-engineering-kit-0.17.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.17.0
+npm install skill-family-harness-node@0.19.0
 npm info skill-family-harness-node --help
 ```
 
@@ -119,6 +125,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。 |
@@ -127,6 +134,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 或租约过期偷锁。
@@ -248,4 +261,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.17.0 为本地源码候选，尚未发布。消费本地已验证的三包 tarball；版本标记、单元测试或安装成功都不等于契约接入完成、迁移完成或真实宿主资格。
+0.18.0 为本地源码候选，尚未发布。消费本地已验证的三包 tarball；版本标记、单元测试或安装成功都不等于契约接入完成、迁移完成或真实宿主资格。

package/candidate/mechanisms-cli.mjs

@@ -6,9 +6,17 @@ import {
   invokeFoundationMechanism,
   verifyManagedBundleIdentity,
 } from "./quickstart-profile.mjs";
+import { loadMechanismBatchPolicy } from "skill-family-contracts/quickstart-profile";
 
 const CLI_NAME = "mechanisms-cli.mjs";
 
+// Fixed capacity authority and serialization envelope for the bounded
+// mechanism batch transport (FND-DES-022); both derive from the single
+// Contracts authority rather than a second copy.
+const MECHANISM_BATCH_POLICY = loadMechanismBatchPolicy();
+const BATCH_OUTPUT_PREFIX = '{"results":[';
+const BATCH_OUTPUT_SUFFIX = "]}\n";
+
 async function readRequest(input) {
   const chunks = [];
   for await (const chunk of input) chunks.push(Buffer.from(chunk));
@@ -154,6 +162,210 @@ async function runSelfCheck(request) {
   return verifyManagedBundleIdentity({ cliUrl: import.meta.url, cliName: CLI_NAME });
 }
 
+function batchRefusal(kind, message) {
+  const cause = new TypeError(message);
+  cause.details = { kind };
+  return cause;
+}
+
+/**
+ * Bounded raw-byte read through explicit listeners (never `for await`, whose
+ * early break would destroy the caller stream). The current chunk is kept only
+ * after the running total plus its bytes is confirmed within the limit, so an
+ * over-limit chunk is never copied into the accumulation cache. Every exit
+ * path releases this function's listeners; refusal never terminates the
+ * caller process.
+ */
+function readBoundedBatchInput(input, byteLimit) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let received = 0;
+    const cleanup = () => {
+      input.removeListener("data", onData);
+      input.removeListener("end", onEnd);
+      input.removeListener("error", onError);
+    };
+    const onData = (chunk) => {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const next = received + bytes.length;
+      if (next > byteLimit) {
+        cleanup();
+        reject(
+          batchRefusal(
+            "batch-input-limit",
+            `mechanism batch input exceeds ${byteLimit} raw UTF-8 bytes`,
+          ),
+        );
+        return;
+      }
+      received = next;
+      chunks.push(bytes);
+    };
+    const onEnd = () => {
+      cleanup();
+      resolve(Buffer.concat(chunks));
+    };
+    const onError = (cause) => {
+      cleanup();
+      reject(cause);
+    };
+    input.on("data", onData);
+    input.on("end", onEnd);
+    input.on("error", onError);
+  });
+}
+
+/**
+ * Whole-batch shape precheck (FND-DES-022 section 3): the outer layer of every
+ * item is checked before the first item executes. Structure failures never
+ * reach the mechanism dispatcher and never fabricate per-item results.
+ */
+function assertMechanismBatchShape(request) {
+  if (
+    request === null ||
+    typeof request !== "object" ||
+    Array.isArray(request) ||
+    Object.keys(request).sort().join(",") !== "inputs,operation" ||
+    request.operation !== "canonical-json" ||
+    !Array.isArray(request.inputs) ||
+    request.inputs.length === 0
+  ) {
+    throw batchRefusal(
+      "batch-structure-invalid",
+      "mechanism batch request must carry exactly operation canonical-json and a non-empty inputs array",
+    );
+  }
+  for (const item of request.inputs) {
+    if (
+      item === null ||
+      typeof item !== "object" ||
+      Array.isArray(item) ||
+      Object.keys(item).sort().join(",") !== "document"
+    ) {
+      throw batchRefusal(
+        "batch-structure-invalid",
+        "each mechanism batch input must be an object carrying exactly document",
+      );
+    }
+  }
+}
+
+/**
+ * Waits until the writable accepted the whole payload, propagating both
+ * synchronous write throws and asynchronous stream errors.
+ */
+function writeAll(stream, text) {
+  return new Promise((resolve, reject) => {
+    const onError = (cause) => {
+      stream.removeListener("drain", onDrain);
+      reject(cause);
+    };
+    const onDrain = () => {
+      stream.removeListener("error", onError);
+      resolve();
+    };
+    stream.on("error", onError);
+    try {
+      if (stream.write(text)) {
+        stream.removeListener("error", onError);
+        resolve();
+        return;
+      }
+      stream.once("drain", onDrain);
+    } catch (cause) {
+      stream.removeListener("error", onError);
+      reject(cause);
+    }
+  });
+}
+
+/**
+ * Bounded, same-operation, ordered mechanism batch transport (FND-DES-022).
+ *
+ * The request stream is read once under the raw-byte budget, strictly decoded
+ * as UTF-8, parsed once, shape-prechecked, then executed item by item through
+ * the fixed single-request dispatcher — no second algorithm is introduced.
+ * Every item's serialized response bytes are accumulated with the envelope
+ * commas, prefix, and mandatory closing newline; nothing is written to the
+ * output until the complete response is confirmed within the output budget.
+ * Item failures follow the original CLI error projection into that item's
+ * `response` and continue; whole-batch refusals and transport failures write
+ * one batch error object to the error channel and never touch the output.
+ */
+export async function runMechanismCliBatch({
+  input = stdin,
+  output = stdout,
+  error = stderr,
+  invoke = invokeFoundationMechanism,
+} = {}) {
+  try {
+    const bytes = await readBoundedBatchInput(input, MECHANISM_BATCH_POLICY.inputByteLimit);
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    const request = JSON.parse(text);
+    assertMechanismBatchShape(request);
+    const inputs = request.inputs;
+    if (inputs.length > MECHANISM_BATCH_POLICY.itemLimit) {
+      throw batchRefusal(
+        "batch-item-limit",
+        `mechanism batch exceeds the ${MECHANISM_BATCH_POLICY.itemLimit} item limit`,
+      );
+    }
+    const fragments = [];
+    let outputBytes = Buffer.byteLength(BATCH_OUTPUT_PREFIX, "utf8");
+    let anyItemFailure = false;
+    for (let inputIndex = 0; inputIndex < inputs.length; inputIndex += 1) {
+      const item = inputs[inputIndex];
+      let exitCode = 0;
+      let response;
+      try {
+        response = await invoke({ operation: "canonical-json", params: item });
+      } catch (cause) {
+        response = errorResponse(cause);
+        exitCode = 2;
+      }
+      const fragment = JSON.stringify({ inputIndex, exitCode, response });
+      if (inputIndex > 0) outputBytes += 1; // separating comma between items
+      outputBytes += Buffer.byteLength(fragment, "utf8");
+      // The closing bytes are mandatory, so the check includes them before the
+      // next item may execute; an overrun never delivers a partial result.
+      if (outputBytes + Buffer.byteLength(BATCH_OUTPUT_SUFFIX, "utf8") > MECHANISM_BATCH_POLICY.outputByteLimit) {
+        throw batchRefusal(
+          "batch-output-limit",
+          `mechanism batch response exceeds the ${MECHANISM_BATCH_POLICY.outputByteLimit} byte limit`,
+        );
+      }
+      fragments.push(fragment);
+      if (exitCode === 2) anyItemFailure = true;
+    }
+    await writeAll(
+      output,
+      `${BATCH_OUTPUT_PREFIX}${fragments.join(",")}${BATCH_OUTPUT_SUFFIX}`,
+    );
+    return anyItemFailure ? 2 : 0;
+  } catch (cause) {
+    try {
+      await writeAll(error, `${JSON.stringify(errorResponse(cause))}\n`);
+    } catch {
+      // The error channel itself failed; the batch still exits failed.
+    }
+    return 2;
+  }
+}
+
 if (process.argv[1] && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
-  process.exitCode = await runMechanismCli();
+  const args = process.argv.slice(2);
+  if (args[0] === "--batch") {
+    if (args.length > 1) {
+      // Refuse before reading any input: the batch mode takes no positional
+      // arguments, and the old single-request entry must stay unchanged.
+      stderr.write(
+        `${JSON.stringify(errorResponse(new TypeError("mechanisms CLI --batch accepts no additional arguments")))}\n`,
+      );
+      process.exitCode = 2;
+    } else {
+      process.exitCode = await runMechanismCliBatch();
+    }
+  } else {
+    process.exitCode = await runMechanismCli();
+  }
 }

package/package.json

@@ -10,7 +10,7 @@
   "dependencies": {
     "@pnpm/lockfile.fs": "1001.1.35",
     "ipaddr.js": "2.5.0",
-    "skill-family-contracts": "0.17.0",
+    "skill-family-contracts": "0.19.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.17.0",
+  "version": "0.19.0",
   "scripts": {
     "check": "node --test",
     "test": "node --test"

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/release-notes/0.19.0.yaml

@@ -0,0 +1,23 @@
+version: 0.19.0
+date: 2026-09-07
+locales:
+  en:
+    summary: Harness 0.19.0 adds runMechanismCliBatch and the explicit --batch CLI mode for bounded, ordered, same-operation batch transport, with canonical-json as the first operation.
+    changes:
+      added:
+        - Adds runMechanismCliBatch({input, output, error}) on the existing fixed mechanism CLI, reading one batch request and returning per-item results with inputIndex, exitCode, and the original single-request response.
+        - Adds the explicit --batch mode to the official Bundle-projected mechanisms-cli.mjs. Without --batch the old single-request path is unchanged.
+      changed:
+        - Batch structure and capacity refusals use TypeError with error.details.kind from the closed set batch-structure-invalid, batch-item-limit, batch-input-limit, and batch-output-limit.
+        - A single item's mechanism failure is recorded in its result position and sibling items continue; the whole batch exits 2 when any item failed.
+    upgradeNotes: "Pin all three Foundation packages to exactly 0.19.0. The fixed capacity policy is 256 items, 16 MiB input bytes, and 32 MiB output bytes; consumers own grouping independent requests and splitting oversized batches. This entry is candidate: re-verify after upgrading. The old single-request CLI keeps its previous contract."
+  zh-CN:
+    summary: Harness 0.19.0 在既有固定机制 CLI 上新增 runMechanismCliBatch 与显式 --batch 模式，提供有界、有序、同操作批量传输，首批操作 canonical-json。
+    changes:
+      added:
+        - 新增 runMechanismCliBatch({input, output, error})：读入一个批量请求，逐项返回 inputIndex、exitCode 与原单请求响应。
+        - 官方 Bundle 投影的 mechanisms-cli.mjs 新增显式 --batch 模式。不带 --batch 时旧单请求路径不变。
+      changed:
+        - 批量结构与容量拒绝使用 TypeError，error.details.kind 封闭为 batch-structure-invalid、batch-item-limit、batch-input-limit、batch-output-limit。
+        - 单项机制失败写入该项结果位置，其余项继续执行；任一机制项失败时整批退出码为 2。
+    upgradeNotes: 三个 Foundation 包须一起精确锁定到 0.19.0。固定容量政策为 256 项、16 MiB 输入字节、32 MiB 输出字节；相互独立请求的分组与超限切分由消费者负责。该入口为候选能力，升级后须重新验证。旧单请求 CLI 合同保持不变。

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 };