skill-family-harness-node 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.4.0 locale=en baseline=sha256:72d3fe048ced8eb44a84fabe6f1fdd2eb0c938b4f6bb98740474f72aec04d873 -->
+## [0.4.0] - 2026-08-16
+
+This release adds five finite-closed-semantics mechanisms and a token-lock primitive to the stable Harness surface (FND-ADR-009), grows HARNESS_CAPABILITIES from 9 to 16 entries, and ships the rename-directory-no-replace native-prebuild candidate.
+
+### Added
+
+- Adds five finite-closed-semantics mechanisms (FND-ADR-009), namely frozen-baseline materialization with contentGuard, the generic read chokepoint, strategy-driven surface scanning, deterministic token upper-bound estimation, and the generic upper-bound guard.
+- Adds the token-lock primitive for exclusive token-file publication and digest verification.
+- Grows HARNESS_CAPABILITIES from 9 to 16 entries for the new mechanisms.
+- Adds the rename-directory-no-replace candidate, a native-prebuild addon proving no-replace directory renames on darwin-arm64, darwin-x64, linux-arm64-gnu, and linux-x64-gnu, with a release receipt and SBOM.
+
+### Changed
+
+- Keeps the Quickstart Profile v2 Task/Result exchange verification delivered in 0.3.0, including real-byte recomputation for path-backed outputs and evidence, duplicate Resource id rejection, and exact evidence binding verification.
+- Leaves method selection, retry policy, and domain result interpretation to the consumer.
+
+### Upgrade Notes
+
+Version 0.4.0 is released on npm and the public mirror. Pin the candidate subpath to exactly 0.4.0; mechanism imports use the stable capability names published in HARNESS_CAPABILITIES.
+<!-- release-skill:changelog:end version=0.4.0 locale=en -->
+
+
+<!-- release-skill:changelog:start version=0.3.0 locale=en baseline=sha256:7afef97792b4714abbd0412dcb7ea76ca66260ef9f8dd2191131b7c3f8539813 -->
+## [0.3.0] - 2026-08-12
+
+This source candidate updates the Quickstart Profile harness to verify v2 Task and Result exchanges without taking ownership of consumer semantics.
+
+### Added
+
+- Recomputes real bytes for path-backed outputs and evidence, and rejects duplicate Resource ids across observations, outputs, and evidence.
+- Verifies operation identity, Task digest, every run/stage/attempt field, and the exact evidence binding set.
+
+### Changed
+
+- Replaces the incompatible 0.2.1 candidate surface; consumers that still require v1 must remain pinned to exactly 0.2.1.
+- Leaves method selection, retry policy, and domain result interpretation to the consumer.
+
+### Upgrade Notes
+
+Version 0.3.0 is a local, unpublished source candidate. Pin the candidate subpath to an exact package version and update v1 exchange producers before adopting it.
+<!-- release-skill:changelog:end version=0.3.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.2.1 locale=en baseline=sha256:acd7d4e02eb309b149a31f4b88a8163c69ae094a53591f173c20c407e8ff4ed0 -->
 ## [0.2.1] - 2026-08-10
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,49 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.4.0 locale=zh-CN baseline=sha256:dafaa1100bf6163a28d53fc982a30e8325d8bd3cab43bbb6daf2e6002befa2c1 -->
+## [0.4.0] - 2026-08-16
+
+本版在稳定 Harness 面上新增五项有限封闭语义机制与 token-lock 原语（FND-ADR-009），HARNESS_CAPABILITIES 从 9 项增至 16 项，并随附 rename-directory-no-replace 原生预编译候选。
+
+### 新增
+
+- 新增五项有限封闭语义机制（FND-ADR-009）：冻结基线物化 + contentGuard、通用只读 chokepoint、策略化表面扫描、确定性 token 上界估算与通用上限守卫。
+- 新增 token-lock 原语：独占 token 文件发布与摘要复验。
+- HARNESS_CAPABILITIES 从 9 项增至 16 项，覆盖上述新机制。
+- 新增 rename-directory-no-replace 候选：覆盖 darwin-arm64、darwin-x64、linux-arm64-gnu、linux-x64-gnu 的原生预编译 no-replace 目录改名 addon，附带发布 receipt 与 SBOM。
+
+### 变更
+
+- 保持 0.3.0 交付的 Quickstart Profile v2 Task/Result 交换校验：path-backed output 与 evidence 重算真实字节、拒绝重复 Resource id、evidence 精确绑定逐项复验。
+- 方法选择、重试策略与领域结果解释继续归消费者所有。
+
+### 升级说明
+
+0.4.0 已发布到 npm 与 public 镜像仓。candidate 子路径必须精确锁定 0.4.0；机制导入使用 HARNESS_CAPABILITIES 公布的稳定能力名。
+<!-- release-skill:changelog:end version=0.4.0 locale=zh-CN -->
+
+
+<!-- release-skill:changelog:start version=0.3.0 locale=zh-CN baseline=sha256:b635e4170d3f7ac634e59f612939683ab04727f87101790d9a9f5613ea38fcfe -->
+## [0.3.0] - 2026-08-12
+
+本源码候选版把 Quickstart Profile Harness 更新为 v2 Task/Result 交换校验，同时不接管消费者语义。
+
+### 新增
+
+- 对 path-backed output 与 evidence 重算真实字节摘要，并拒绝 observation、output、evidence 之间重复的 Resource id。
+- 逐项复验 operation 身份、Task digest、run/stage/attempt 字段和 evidence 精确绑定集合。
+
+### 变更
+
+- 替换与 0.2.1 不兼容的 candidate 面；仍依赖 v1 的消费者必须继续精确锁定 0.2.1。
+- 方法选择、重试策略与领域结果解释继续归消费者所有。
+
+### 升级说明
+
+0.3.0 当前只是本地、未发布的源码候选。candidate 子路径必须精确锁定包版本，采用前需更新 v1 交换生产方。
+<!-- release-skill:changelog:end version=0.3.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.2.1 locale=zh-CN baseline=sha256:2f2c74ab9dcf0f1a84872743bf203eb43d15c5e722e823e670e8d81ca5f7de65 -->
 ## [0.2.1] - 2026-08-10
 

package/README.md

@@ -4,28 +4,30 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.2.1 -->
+<!-- release-skill:release-version: 0.4.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.2.1** (2026-08-10)
+**0.4.0** (2026-08-16)
 
-This release adds candidate Quickstart Profile exchange helpers and makes the package release documentation available in English and Simplified Chinese.
+This release adds five finite-closed-semantics mechanisms and a token-lock primitive to the stable Harness surface (FND-ADR-009), grows HARNESS_CAPABILITIES from 9 to 16 entries, and ships the rename-directory-no-replace native-prebuild candidate.
 
 **Added**
 
-- Adds candidate helpers that create and revalidate observation Resources, build Tasks, wrap Results, and fail closed when a Result does not bind the exact Task and correlation fields.
-- Adds complete English and Simplified Chinese package documentation, including an agent quick-reference section.
+- Adds five finite-closed-semantics mechanisms (FND-ADR-009), namely frozen-baseline materialization with contentGuard, the generic read chokepoint, strategy-driven surface scanning, deterministic token upper-bound estimation, and the generic upper-bound guard.
+- Adds the token-lock primitive for exclusive token-file publication and digest verification.
+- Grows HARNESS_CAPABILITIES from 9 to 16 entries for the new mechanisms.
+- Adds the rename-directory-no-replace candidate, a native-prebuild addon proving no-replace directory renames on darwin-arm64, darwin-x64, linux-arm64-gnu, and linux-x64-gnu, with a release receipt and SBOM.
 
 **Changed**
 
-- Manages the current README and CHANGELOG release sections from one bilingual, versioned notes source.
-- Distributes the project NOTICE separately from the Apache-2.0 LICENSE.
+- Keeps the Quickstart Profile v2 Task/Result exchange verification delivered in 0.3.0, including real-byte recomputation for path-backed outputs and evidence, duplicate Resource id rejection, and exact evidence binding verification.
+- Leaves method selection, retry policy, and domain result interpretation to the consumer.
 
 **Upgrade Notes**
 
-The candidate helpers do not alter the stable Harness API or add lifecycle, retry, orchestration, model-call, network, or Git-write semantics.
+Version 0.4.0 is released on npm and the public mirror. Pin the candidate subpath to exactly 0.4.0; mechanism imports use the stable capability names published in HARNESS_CAPABILITIES.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -39,14 +41,14 @@ The Harness consumes `skill-family-contracts` (a workspace dependency), reusing
 ## Installation and Minimal Example
 
 ```sh
-npm install skill-family-harness-node@0.2.1
+npm install skill-family-harness-node@0.4.0
 npm info skill-family-harness-node --help
 ```
 
 The minimal example shows validating a contract document inside Node:
 
 ```js
-// Run from an empty directory: npm install skill-family-harness-node@0.2.1
+// Run from an empty directory: npm install skill-family-harness-node@0.4.0
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {
@@ -78,7 +80,9 @@ import {
 } from "skill-family-harness-node/candidate/quickstart-profile";
 ```
 
-This mechanism is intended for early integration trials of the candidate Contracts profile. It does not perform a domain audit, choose a method, retry work, or own lifecycle state. The subpath is public but **not stable** and may change or be removed in a later minor release; pin the exact package version and do not expose it through a stable consumer API.
+The v2 mechanism recomputes the bytes of every path-backed output and evidence Resource. It also rejects duplicate Resource ids, correlation drift, a changed Task digest, and incomplete or mismatched evidence bindings. It does not perform a domain audit, choose a method, retry work, or own lifecycle state.
+
+The subpath is public but **not stable** and may change or be removed in a later minor release. Pin exactly `0.4.0` for v2; integrations that still produce candidate v1 exchanges must stay pinned to exactly `0.2.1`.
 
 ## Typical Use Cases
 

package/README.zh-CN.md

@@ -5,28 +5,30 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.2.1 -->
+<!-- release-skill:release-version: 0.4.0 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.2.1** (2026-08-10)
+**0.4.0** (2026-08-16)
 
-本版新增 Quickstart Profile 候选交换辅助函数，并为包发布文档提供完整英文版与简体中文版。
+本版在稳定 Harness 面上新增五项有限封闭语义机制与 token-lock 原语（FND-ADR-009），HARNESS_CAPABILITIES 从 9 项增至 16 项，并随附 rename-directory-no-replace 原生预编译候选。
 
 **新增**
 
-- 新增候选辅助函数，用于创建并复验 observation Resource、构造 Task、封装 Result，并在 Result 未精确绑定 Task 与关联字段时失败关闭。
-- 新增完整的英文与简体中文包文档，并补充智能体快速参考章节。
+- 新增五项有限封闭语义机制（FND-ADR-009）：冻结基线物化 + contentGuard、通用只读 chokepoint、策略化表面扫描、确定性 token 上界估算与通用上限守卫。
+- 新增 token-lock 原语：独占 token 文件发布与摘要复验。
+- HARNESS_CAPABILITIES 从 9 项增至 16 项，覆盖上述新机制。
+- 新增 rename-directory-no-replace 候选：覆盖 darwin-arm64、darwin-x64、linux-arm64-gnu、linux-x64-gnu 的原生预编译 no-replace 目录改名 addon，附带发布 receipt 与 SBOM。
 
 **变更**
 
-- 使用同一份双语版本化说明源管理当前 README 与 CHANGELOG 的发布区域。
-- 项目 NOTICE 与 Apache-2.0 LICENSE 分开分发。
+- 保持 0.3.0 交付的 Quickstart Profile v2 Task/Result 交换校验：path-backed output 与 evidence 重算真实字节、拒绝重复 Resource id、evidence 精确绑定逐项复验。
+- 方法选择、重试策略与领域结果解释继续归消费者所有。
 
 **升级说明**
 
-候选辅助函数不改变稳定 Harness API，也不引入生命周期、重试、编排、模型调用、网络或 Git 写入语义。
+0.4.0 已发布到 npm 与 public 镜像仓。candidate 子路径必须精确锁定 0.4.0；机制导入使用 HARNESS_CAPABILITIES 公布的稳定能力名。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -40,14 +42,14 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 ## 安装和最小示例
 
 ```sh
-npm install skill-family-harness-node@0.2.1
+npm install skill-family-harness-node@0.4.0
 npm info skill-family-harness-node --help
 ```
 
 最小示例演示在 Node 内校验一份契约文档：
 
 ```js
-// 从空目录运行：npm install skill-family-harness-node@0.2.1
+// 从空目录运行：npm install skill-family-harness-node@0.4.0
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {
@@ -79,7 +81,9 @@ import {
 } from "skill-family-harness-node/candidate/quickstart-profile";
 ```
 
-以上机制用于 candidate Contracts Profile 的早期接入试验。它不执行领域审计，不选择 method，不编排重试，也不拥有生命周期状态。该子路径公开但**不稳定**，后续小版本可以修改或移除；调用方需要锁定精确包版本，并避免通过自身稳定 API 再导出。
+v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字节摘要，并拒绝重复 Resource id、correlation 漂移、Task digest 变化，以及缺失或错配的 evidence binding。它不执行领域审计，不选择 method，不编排重试，也不拥有生命周期状态。
+
+该子路径公开但**不稳定**，后续小版本可以修改或移除。使用 v2 时应精确锁定 `0.4.0`；仍生产 candidate v1 交换的接入必须继续精确锁定 `0.2.1`。
 
 ## 典型使用场景
 

package/candidate/mechanisms-cli.mjs

@@ -1,41 +1,157 @@
 #!/usr/bin/env node
 import { stdin, stdout, stderr } from "node:process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import {
-  canonicalJson,
-  computeResourceClosure,
-  digestDocument,
+  invokeFoundationMechanism,
+  verifyManagedBundleIdentity,
 } from "./quickstart-profile.mjs";
 
-async function readRequest() {
+const CLI_NAME = "mechanisms-cli.mjs";
+
+async function readRequest(input) {
   const chunks = [];
-  for await (const chunk of stdin) chunks.push(chunk);
-  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  for await (const chunk of input) chunks.push(Buffer.from(chunk));
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+  return JSON.parse(text);
+}
+
+function errorResponse(cause) {
+  return {
+    ok: false,
+    error: {
+      name: typeof cause?.name === "string" ? cause.name : "Error",
+      message: cause?.message ?? String(cause),
+    },
+  };
 }
 
-export async function runMechanismCli() {
+/**
+ * Fixed dispatch for the publish-fixed-set operation.
+ *
+ * This operation is fail-closed: if the native addon is unavailable or the
+ * platform is unsupported, the operation returns a receipt with status=refused
+ * and error code UNSUPPORTED_PLATFORM. No JS rename fallback is attempted.
+ *
+ * The operation takes a frozen sibling-directory source/target tuple and
+ * returns a receipt. It does NOT
+ * expose any module/function/pathToFileURL call surface.
+ */
+async function runPublishFixedSet(params, invoke) {
+  if (
+    params === null ||
+    typeof params !== "object" ||
+    Array.isArray(params) ||
+    Object.keys(params).sort().join(",") !== "manifest,sourceRoot,targetParent,targetSegment" ||
+    typeof params.sourceRoot !== "string" ||
+    typeof params.targetParent !== "string" ||
+    typeof params.targetSegment !== "string" ||
+    params.manifest === null ||
+    typeof params.manifest !== "object"
+  ) {
+    throw new TypeError("publish-fixed-set requires exactly sourceRoot, targetParent, targetSegment, and manifest");
+  }
+
+  let publishFixedSet;
   try {
-    const request = await readRequest();
+    const mod = await import("./rename-directory-no-replace/rename-directory-no-replace.mjs");
+    publishFixedSet = mod.publishFixedSet;
+  } catch (cause) {
+    const manifestDigest = await invoke({ operation: "digest-document", params: { document: params.manifest } });
+    return {
+      schemaVersion: 1,
+      kind: "skill-family.fixed-set-publication-receipt",
+      manifestDigest: manifestDigest.digest,
+      targetRootBinding: params.manifest?.target?.rootBinding ?? {
+        kind: "trusted-filesystem-root-binding", digestAlgorithm: "sha256",
+        basis: "canonical-realpath-device-inode-type-mode-v1", digest: "0".repeat(64),
+      },
+      platform: "other",
+      primitive: "none",
+      status: "refused",
+      targetState: "absent",
+      commitState: "not-committed",
+      verification: "not-run",
+      durability: "not-attempted",
+      error: {
+        code: "UNSUPPORTED_PLATFORM",
+        message: `publish-fixed-set module unavailable: ${cause?.message ?? "unknown"}`.slice(0, 300),
+      },
+    };
+  }
+
+  return publishFixedSet(params);
+}
+
+/** Fixed manifest construction for the same receipt-bound publication mechanism. */
+async function runCreateFixedSetPublicationManifest(params) {
+  if (
+    params === null ||
+    typeof params !== "object" ||
+    Array.isArray(params) ||
+    Object.keys(params).sort().join(",") !== "sourceRoot,targetParent,targetSegment" ||
+    typeof params.sourceRoot !== "string" ||
+    typeof params.targetParent !== "string" ||
+    typeof params.targetSegment !== "string"
+  ) {
+    throw new TypeError(
+      "create-fixed-set-publication-manifest requires exactly sourceRoot, targetParent, and targetSegment",
+    );
+  }
+  const { createFixedSetPublicationManifest } = await import(
+    "./rename-directory-no-replace/rename-directory-no-replace.mjs"
+  );
+  return createFixedSetPublicationManifest(params);
+}
+
+/**
+ * One-request/one-response JSON transport for the fixed Foundation mechanism
+ * bridge. The offline Bundle rewrites the import above to its managed runner,
+ * which injects the Bundle-owned schema validator. No request can name a
+ * module, export, or arbitrary function.
+ */
+export async function runMechanismCli({
+  input = stdin,
+  output = stdout,
+  error = stderr,
+  invoke = invokeFoundationMechanism,
+} = {}) {
+  try {
+    const request = await readRequest(input);
     let result;
-    if (request.operation === "canonical-json") {
-      result = { text: canonicalJson(request.document) };
-    } else if (request.operation === "digest-document") {
-      result = { digest: digestDocument(request.document) };
-    } else if (request.operation === "resource-closure") {
-      result = await computeResourceClosure({
-        root: request.root,
-        resources: request.resources,
-      });
+    if (request?.operation === "self-check") {
+      result = await runSelfCheck(request);
+    } else if (request?.operation === "create-fixed-set-publication-manifest") {
+      result = await runCreateFixedSetPublicationManifest(request.params);
+    } else if (request?.operation === "publish-fixed-set") {
+      result = await runPublishFixedSet(request.params, invoke);
     } else {
-      throw new TypeError(`unknown Foundation mechanism: ${String(request.operation)}`);
+      result = await invoke(request);
     }
-    stdout.write(`${JSON.stringify(result)}\n`);
+    output.write(`${JSON.stringify(result)}\n`);
     return 0;
   } catch (cause) {
-    stderr.write(`${cause?.message ?? String(cause)}\n`);
+    error.write(`${JSON.stringify(errorResponse(cause))}\n`);
     return 2;
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+async function runSelfCheck(request) {
+  if (
+    request === null ||
+    typeof request !== "object" ||
+    Array.isArray(request) ||
+    Object.keys(request).sort().join(",") !== "operation,params" ||
+    request.params === null ||
+    typeof request.params !== "object" ||
+    Array.isArray(request.params) ||
+    Object.keys(request.params).length !== 0
+  ) {
+    throw new TypeError("mechanisms CLI self-check requires exactly operation and empty params");
+  }
+  return verifyManagedBundleIdentity({ cliUrl: import.meta.url, cliName: CLI_NAME });
+}
+
+if (process.argv[1] && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
   process.exitCode = await runMechanismCli();
 }