skill-family-harness-node 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 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
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,26 @@
 # 变更日志
 
+<!-- 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,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.18.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.18.0** (2026-09-05)
+**0.19.0** (2026-09-07)
 
-Harness 0.18.0 adds the stable replaceFixedSetAtomic operation for replacing one existing fixed-set directory with one complete staged sibling.
+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 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.
+- 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**
 
-- 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.
+- 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.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.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
@@ -51,7 +52,7 @@ mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
 After publication, use the registry coordinate:
 
 ```sh
-npm install skill-family-harness-node@0.18.0
+npm install skill-family-harness-node@0.19.0
 npm info skill-family-harness-node --help
 ```
 

package/README.zh-CN.md

@@ -5,27 +5,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.18.0 -->
+<!-- release-skill:release-version: 0.19.0 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.18.0** (2026-09-05)
+**0.19.0** (2026-09-07)
 
-Harness 0.18.0 新增稳定的 replaceFixedSetAtomic，用一个完整暂存目录替换一个既有固定集合目录。
+Harness 0.19.0 在既有固定机制 CLI 上新增 runMechanismCliBatch 与显式 --batch 模式，提供有界、有序、同操作批量传输，首批操作 canonical-json。
 
 **新增**
 
-- 包根与 fixed-set-publication 子路径新增 replaceFixedSetAtomic。源目录和目标目录必须是同一规范父目录下的真实兄弟目录。
-- 提交只执行一次 Darwin RENAME_SWAP 或 Linux RENAME_EXCHANGE。成功后，新集合完整位于目标路径，被置换的旧目标留在 sourceRoot。
+- 新增 runMechanismCliBatch({input, output, error})：读入一个批量请求，逐项返回 inputIndex、exitCode 与原单请求响应。
+- 官方 Bundle 投影的 mechanisms-cli.mjs 新增显式 --batch 模式。不带 --batch 时旧单请求路径不变。
 
 **变更**
 
-- 替换无法返回已验证成功时，沿用 SFC2004 机制错误表面，报告提交前后、发布、验证、提交和持久化状态。
+- 批量结构与容量拒绝使用 TypeError，error.details.kind 封闭为 batch-structure-invalid、batch-item-limit、batch-input-limit、batch-output-limit。
+- 单项机制失败写入该项结果位置，其余项继续执行；任一机制项失败时整批退出码为 2。
 
 **升级说明**
 
-三个 Foundation 包须一起精确锁定到 0.18.0。replaceFixedSetAtomic 不是幂等操作：相同路径再次调用会把两个目录交换回去。成功后，或收到提交后及不确定错误时，均不得盲目重试。调用方只在确认成功后负责清理被置换的旧目标。
+三个 Foundation 包须一起精确锁定到 0.19.0。固定容量政策为 256 项、16 MiB 输入字节、32 MiB 输出字节；相互独立请求的分组与超限切分由消费者负责。该入口为候选能力，升级后须重新验证。旧单请求 CLI 合同保持不变。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -52,7 +53,7 @@ mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
 发布后再使用 registry 坐标：
 
 ```sh
-npm install skill-family-harness-node@0.18.0
+npm install skill-family-harness-node@0.19.0
 npm info skill-family-harness-node --help
 ```
 

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.18.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.18.0",
+  "version": "0.19.0",
   "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/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.0";