skill-family-harness-node 0.18.0 → 0.19.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.19.1 locale=en baseline=sha256:76ded57ddca31105929a12a1b198bd6da407090e353dbf90096c17da5532a3ea -->
+## [0.19.1] - 2026-09-08
+
+Harness 0.19.1 makes the candidate mechanism-batch entry point settle on the current transfer's actual completion or failure while preserving caller ownership of programmatic streams.
+
+### Fixed
+
+- Waits for the current write callback, handles premature input and output closure, and removes only listeners installed by the batch helper.
+- Stops the library helper's own reading and releases its buffer after input overflow without destroying a caller-owned stream.
+- Releases CLI-owned standard input after an oversized request is reported, allowing the process to exit 2 while the upstream pipe remains open.
+
+### Upgrade Notes
+
+Pin all three Foundation packages to exactly 0.19.1. The batch operation, capacity policy, per-item order, and single-request CLI remain unchanged. This entry is candidate and requires re-verification after an upgrade.
+<!-- release-skill:changelog:end version=0.19.1 locale=en -->
+
+
+<!-- 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
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,43 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.19.1 locale=zh-CN baseline=sha256:398aacf147e429237ff5b72fa1d22652afb76eb49da388eeb333d073bbd0a032 -->
+## [0.19.1] - 2026-09-08
+
+Harness 0.19.1 让候选机制批量入口等待本次传输真正完成或失败，同时保留程序化入口中调用方对流的所有权。
+
+### 修复
+
+- 等待本次写入回调，处理输入与输出提前关闭，并且只移除批量辅助函数自己安装的监听器。
+- 输入超限后停止库辅助函数自己的读取并释放缓存，不销毁调用方拥有的流。
+- 超限错误写出后释放 CLI 自己拥有的标准输入，使上游管道保持打开时进程仍能自行退出 2。
+
+### 升级说明
+
+三个 Foundation 包须一起精确锁定到 0.19.1。批量操作、容量政策、逐项顺序和旧单请求 CLI 保持不变。该入口仍是候选能力，升级后须重新验证。
+<!-- release-skill:changelog:end version=0.19.1 locale=zh-CN -->
+
+
+<!-- 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
 

package/README.md

@@ -4,27 +4,24 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.18.0 -->
+<!-- release-skill:release-version: 0.19.1 -->
 
 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.18.0** (2026-09-05)
+**0.19.1** (2026-09-08)
 
-Harness 0.18.0 adds the stable replaceFixedSetAtomic operation for replacing one existing fixed-set directory with one complete staged sibling.
+Harness 0.19.1 makes the candidate mechanism-batch entry point settle on the current transfer's actual completion or failure while preserving caller ownership of programmatic streams.
 
-**Added**
+**Fixed**
 
-- 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.
+- Waits for the current write callback, handles premature input and output closure, and removes only listeners installed by the batch helper.
+- Stops the library helper's own reading and releases its buffer after input overflow without destroying a caller-owned stream.
+- Releases CLI-owned standard input after an oversized request is reported, allowing the process to exit 2 while the upstream pipe remains open.
 
 **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.
+Pin all three Foundation packages to exactly 0.19.1. The batch operation, capacity policy, per-item order, and single-request CLI remain unchanged. This entry is candidate and requires re-verification after an upgrade.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -37,7 +34,7 @@ The Harness consumes `skill-family-contracts` (a workspace dependency), reusing
 
 ## Installation and Minimal Example
 
-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:
+Version 0.19.1 is the local source candidate. Build all three tarballs into one temporary directory and install those exact files for a candidate check:
 
 ```sh
 pack_dir="$(mktemp -d)"
@@ -45,13 +42,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.18.0.tgz" "$pack_dir/skill-family-harness-node-0.18.0.tgz" "$pack_dir/skill-family-engineering-kit-0.18.0.tgz")
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.19.1.tgz" "$pack_dir/skill-family-harness-node-0.19.1.tgz" "$pack_dir/skill-family-engineering-kit-0.19.1.tgz")
 ```
 
 After publication, use the registry coordinate:
 
 ```sh
-npm install skill-family-harness-node@0.18.0
+npm install skill-family-harness-node@0.19.1
 npm info skill-family-harness-node --help
 ```
 
@@ -260,4 +257,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.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.
+Version 0.19.1 is the local source candidate. Remote availability must be established by the corresponding release-skill post-release evidence. Consume the three locally verified tarballs for candidate checks; 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,27 +5,24 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.18.0 -->
+<!-- release-skill:release-version: 0.19.1 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.18.0** (2026-09-05)
+**0.19.1** (2026-09-08)
 
-Harness 0.18.0 新增稳定的 replaceFixedSetAtomic，用一个完整暂存目录替换一个既有固定集合目录。
+Harness 0.19.1 让候选机制批量入口等待本次传输真正完成或失败，同时保留程序化入口中调用方对流的所有权。
 
-**新增**
+**修复**
 
-- 包根与 fixed-set-publication 子路径新增 replaceFixedSetAtomic。源目录和目标目录必须是同一规范父目录下的真实兄弟目录。
-- 提交只执行一次 Darwin RENAME_SWAP 或 Linux RENAME_EXCHANGE。成功后，新集合完整位于目标路径，被置换的旧目标留在 sourceRoot。
-
-**变更**
-
-- 替换无法返回已验证成功时，沿用 SFC2004 机制错误表面，报告提交前后、发布、验证、提交和持久化状态。
+- 等待本次写入回调，处理输入与输出提前关闭，并且只移除批量辅助函数自己安装的监听器。
+- 输入超限后停止库辅助函数自己的读取并释放缓存，不销毁调用方拥有的流。
+- 超限错误写出后释放 CLI 自己拥有的标准输入，使上游管道保持打开时进程仍能自行退出 2。
 
 **升级说明**
 
-三个 Foundation 包须一起精确锁定到 0.18.0。replaceFixedSetAtomic 不是幂等操作：相同路径再次调用会把两个目录交换回去。成功后，或收到提交后及不确定错误时，均不得盲目重试。调用方只在确认成功后负责清理被置换的旧目标。
+三个 Foundation 包须一起精确锁定到 0.19.1。批量操作、容量政策、逐项顺序和旧单请求 CLI 保持不变。该入口仍是候选能力，升级后须重新验证。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -38,7 +35,7 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 
 ## 安装和最小示例
 
-0.18.0 是本地候选版本。候选验证先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
+0.19.1 是本地源码候选。候选验证先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
 
 ```sh
 pack_dir="$(mktemp -d)"
@@ -46,13 +43,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.18.0.tgz" "$pack_dir/skill-family-harness-node-0.18.0.tgz" "$pack_dir/skill-family-engineering-kit-0.18.0.tgz")
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.19.1.tgz" "$pack_dir/skill-family-harness-node-0.19.1.tgz" "$pack_dir/skill-family-engineering-kit-0.19.1.tgz")
 ```
 
 发布后再使用 registry 坐标：
 
 ```sh
-npm install skill-family-harness-node@0.18.0
+npm install skill-family-harness-node@0.19.1
 npm info skill-family-harness-node --help
 ```
 
@@ -260,4 +257,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.18.0 为本地源码候选，尚未发布。消费本地已验证的三包 tarball；版本标记、单元测试或安装成功都不等于契约接入完成、迁移完成或真实宿主资格。
+0.19.1 是本地源码候选，远端可用性须由对应的 release-skill 发布后证据证明。候选检查使用本地已验证的三包 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,379 @@ 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, outputWatch) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let received = 0;
+    let settled = false;
+    let preexistingErrorFallback;
+    let deferredFailure;
+    let stopWatchingOutput = () => {};
+    const startedFlowing = input.readableFlowing !== true && input.listenerCount("data") === 0;
+    const cleanup = () => {
+      input.removeListener("data", onData);
+      input.removeListener("end", onEnd);
+      input.removeListener("error", onError);
+      input.removeListener("close", onClose);
+      stopWatchingOutput();
+      if (preexistingErrorFallback !== undefined) {
+        clearImmediate(preexistingErrorFallback);
+        preexistingErrorFallback = undefined;
+      }
+    };
+    const rejectRead = (cause) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      chunks.length = 0;
+      if (
+        startedFlowing &&
+        input.readableFlowing === true &&
+        input.listenerCount("data") === 0
+      ) {
+        input.pause();
+      }
+      reject(cause);
+    };
+    const onData = (chunk) => {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const next = received + bytes.length;
+      if (next > byteLimit) {
+        rejectRead(
+          batchRefusal(
+            "batch-input-limit",
+            `mechanism batch input exceeds ${byteLimit} raw UTF-8 bytes`,
+          ),
+        );
+        return;
+      }
+      received = next;
+      chunks.push(bytes);
+    };
+    const onEnd = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      const bytes = Buffer.concat(chunks, received);
+      chunks.length = 0;
+      resolve(bytes);
+    };
+    const onError = (cause) => {
+      rejectRead(deferredFailure ?? cause);
+    };
+    const onClose = () => {
+      rejectRead(
+        deferredFailure ?? input.errored ?? new Error("mechanism batch input closed before the request ended"),
+      );
+    };
+    const onOutputFailure = (cause) => {
+      if (input.errored) {
+        deferredFailure ??= cause;
+        if (preexistingErrorFallback === undefined) {
+          preexistingErrorFallback = setImmediate(() => rejectRead(deferredFailure));
+        }
+        return;
+      }
+      rejectRead(cause);
+    };
+    input.on("data", onData);
+    input.on("end", onEnd);
+    input.on("error", onError);
+    input.on("close", onClose);
+    // A destroy(error) may have set `closed` while its public error event is
+    // still queued. Keep our listener through that event; the immediate also
+    // handles a stream whose error event had already been observed by callers.
+    if (input.errored) {
+      preexistingErrorFallback = setImmediate(() => rejectRead(deferredFailure ?? input.errored));
+    } else if (input.closed || input.readableEnded || input.destroyed) {
+      onClose();
+    }
+    stopWatchingOutput = outputWatch.onFailure(onOutputFailure);
+    if (settled) stopWatchingOutput();
+  });
+}
+
+/**
+ * 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",
+      );
+    }
+  }
+}
+
+// Keeps only the batch call's short-lived listeners active before the actual
+// write begins. This closes the gap where an already-destroyed Writable still
+// owes its public error event, without ending or otherwise managing the stream.
+function watchBatchWritable(stream, channelName) {
+  let failure = stream.errored;
+  let failureListener;
+  let pendingErrorFallback;
+  let resolvePendingError;
+  const pendingError = failure
+    ? new Promise((resolve) => {
+      resolvePendingError = resolve;
+      pendingErrorFallback = setImmediate(resolve);
+    })
+    : undefined;
+  const onError = (cause) => {
+    failure ??= cause;
+    failureListener?.(failure);
+    if (resolvePendingError) {
+      clearImmediate(pendingErrorFallback);
+      pendingErrorFallback = undefined;
+      const resolve = resolvePendingError;
+      resolvePendingError = undefined;
+      resolve();
+    }
+  };
+  const onClose = () => {
+    failure ??= stream.errored ?? new Error(
+      `mechanism batch ${channelName} closed before its write completed`,
+    );
+    failureListener?.(failure);
+  };
+  stream.on("error", onError);
+  stream.on("close", onClose);
+  if (!failure && (stream.closed || stream.writableEnded || stream.destroyed)) onClose();
+  return {
+    pendingError,
+    failure: () => failure,
+    onFailure(listener) {
+      failureListener = listener;
+      if (failure) listener(failure);
+      return () => {
+        if (failureListener === listener) failureListener = undefined;
+      };
+    },
+    release() {
+      failureListener = undefined;
+      stream.removeListener("error", onError);
+      stream.removeListener("close", onClose);
+      if (pendingErrorFallback !== undefined) clearImmediate(pendingErrorFallback);
+    },
+  };
+}
+
+/**
+ * Waits for this write's callback rather than treating the writable's buffer
+ * signal as delivery completion. The caller retains ownership of the stream,
+ * so completion neither ends it nor waits for the whole stream to finish.
+ */
+function writeAll(stream, text, channelName) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let callbackFailureFallback;
+    const cleanup = () => {
+      stream.removeListener("error", onError);
+      stream.removeListener("close", onClose);
+      if (callbackFailureFallback !== undefined) {
+        clearImmediate(callbackFailureFallback);
+        callbackFailureFallback = undefined;
+      }
+    };
+    const rejectWrite = (cause) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(cause);
+    };
+    const onError = (cause) => {
+      rejectWrite(cause);
+    };
+    const onClose = () => {
+      rejectWrite(
+        stream.errored ?? new Error(`mechanism batch ${channelName} closed before its write completed`),
+      );
+    };
+    const onWrite = (cause) => {
+      if (settled) return;
+      if (cause) {
+        // A standard Writable emits its matching error just after invoking the
+        // write callback. Keep our listener through that event so the failure
+        // cannot become an unhandled error; the immediate is a fallback for a
+        // writable-like caller that reports only through the callback.
+        callbackFailureFallback = setImmediate(() => rejectWrite(cause));
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve();
+    };
+    stream.on("error", onError);
+    stream.on("close", onClose);
+    // As with input, an errored destroy may still owe its public error event.
+    // Waiting for that event preserves the cause and prevents it from becoming
+    // unhandled after an eager preflight rejection.
+    if (stream.errored) {
+      callbackFailureFallback = setImmediate(() => rejectWrite(stream.errored));
+      return;
+    }
+    if (stream.closed || stream.writableEnded || stream.destroyed) {
+      onClose();
+      return;
+    }
+    try {
+      stream.write(text, onWrite);
+    } catch (cause) {
+      rejectWrite(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,
+} = {}) {
+  const outputWatch = watchBatchWritable(output, "output");
+  const errorWatch = watchBatchWritable(error, "error output");
+  try {
+    // Start the input read synchronously so a queued input error is covered
+    // before any output preflight can await or fail this batch.
+    const bytes = await readBoundedBatchInput(
+      input,
+      MECHANISM_BATCH_POLICY.inputByteLimit,
+      outputWatch,
+    );
+    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;
+    }
+    const outputFailure = outputWatch.failure();
+    outputWatch.release();
+    if (outputFailure) throw outputFailure;
+    await writeAll(
+      output,
+      `${BATCH_OUTPUT_PREFIX}${fragments.join(",")}${BATCH_OUTPUT_SUFFIX}`,
+      "output",
+    );
+    if (errorWatch.pendingError) await errorWatch.pendingError;
+    errorWatch.release();
+    return anyItemFailure ? 2 : 0;
+  } catch (cause) {
+    const pendingErrors = [outputWatch.pendingError, errorWatch.pendingError].filter(Boolean);
+    if (pendingErrors.length > 0) await Promise.all(pendingErrors);
+    outputWatch.release();
+    const errorFailure = errorWatch.failure();
+    errorWatch.release();
+    if (!errorFailure) {
+      try {
+        await writeAll(error, `${JSON.stringify(errorResponse(cause))}\n`, "error output");
+      } catch {
+        // The error channel itself failed; the batch still exits failed.
+      }
+    }
+    return 2;
+  } finally {
+    outputWatch.release();
+    errorWatch.release();
+  }
+}
+
 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 {
+      const exitCode = await runMechanismCliBatch();
+      if (exitCode === 2 && !stdin.destroyed) stdin.destroy();
+      process.exitCode = exitCode;
+    }
+  } 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.18.0",
+    "skill-family-contracts": "0.19.1",
     "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.18.0",
+  "version": "0.19.1",
   "scripts": {
     "check": "node --test",
     "test": "node --test"

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

@@ -0,0 +1,19 @@
+version: 0.19.1
+date: 2026-09-08
+locales:
+  en:
+    summary: Harness 0.19.1 makes the candidate mechanism-batch entry point settle on the current transfer's actual completion or failure while preserving caller ownership of programmatic streams.
+    changes:
+      fixed:
+        - Waits for the current write callback, handles premature input and output closure, and removes only listeners installed by the batch helper.
+        - Stops the library helper's own reading and releases its buffer after input overflow without destroying a caller-owned stream.
+        - Releases CLI-owned standard input after an oversized request is reported, allowing the process to exit 2 while the upstream pipe remains open.
+    upgradeNotes: Pin all three Foundation packages to exactly 0.19.1. The batch operation, capacity policy, per-item order, and single-request CLI remain unchanged. This entry is candidate and requires re-verification after an upgrade.
+  zh-CN:
+    summary: Harness 0.19.1 让候选机制批量入口等待本次传输真正完成或失败，同时保留程序化入口中调用方对流的所有权。
+    changes:
+      fixed:
+        - 等待本次写入回调，处理输入与输出提前关闭，并且只移除批量辅助函数自己安装的监听器。
+        - 输入超限后停止库辅助函数自己的读取并释放缓存，不销毁调用方拥有的流。
+        - 超限错误写出后释放 CLI 自己拥有的标准输入，使上游管道保持打开时进程仍能自行退出 2。
+    upgradeNotes: 三个 Foundation 包须一起精确锁定到 0.19.1。批量操作、容量政策、逐项顺序和旧单请求 CLI 保持不变。该入口仍是候选能力，升级后须重新验证。

package/src/version.mjs

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