skill-family-harness-node 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.8.2 locale=en baseline=sha256:af051a6925c7d1f46bef6fbe367aceea8685b4a916629af4e69334e73014e3a7 -->
+## [0.8.2] - 2026-08-23
+
+The fixed candidate mechanism bridge now exposes the existing strict reader through read-file-strict.
+
+### Added
+
+- Adds read-file-strict to invokeFoundationMechanism with closed root, path, encoding, and expectedSha256 parameters.
+- Returns UTF-8 content as a string and binary content in the standard JSON-safe Buffer shape.
+
+### Changed
+
+- Delegates containment, file reading, digest verification, and failure classification directly to readFileStrict; no second read algorithm is introduced.
+- Moves the package version to 0.8.2 together with Contracts and Engineering Kit.
+
+### Upgrade Notes
+
+Candidate consumers must pin all three Foundation packages to exactly 0.8.2 and rebuild their managed Bundle. Direct calls retain SFC2004 details.kind failures; the JSON CLI continues to promise only exit code 0 for success and 2 for rejection.
+<!-- release-skill:changelog:end version=0.8.2 locale=en -->
+
+
+<!-- release-skill:changelog:start version=0.8.1 locale=en baseline=sha256:4cd9f23da3561184cef4ebadb7e758a22d377d069742bbe7c77166d6c1b3bd14 -->
+## [0.8.1] - 2026-08-22
+
+Harness now preserves its own report renderer version when a host bundles it into a single-file adapter.
+
+### Changed
+
+- Moves the package version to 0.8.1 together with Contracts and Engineering Kit.
+- Keeps all 21 Harness capabilities, report contracts, and public exports unchanged.
+
+### Fixed
+
+- Replaces the report renderer's runtime import.meta.url package-manifest lookup with a static JSON import, so esbuild inlines the Harness version instead of resolving the host adapter's package metadata.
+- Adds source and third-party single-file bundle regression tests for REPORT_RENDERER_VERSION.
+
+### Upgrade Notes
+
+Host adapters that bundle the report renderer must pin Harness 0.8.1. The report API and renderer identity remain unchanged, so no API migration is required from 0.8.0.
+<!-- release-skill:changelog:end version=0.8.1 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.8.0 locale=en baseline=sha256:85322b5fb8d4e3a2177fbe9e37427235256d530bf604d0b5cdb95cf2ad11cc50 -->
 ## [0.8.0] - 2026-08-21
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,47 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.8.2 locale=zh-CN baseline=sha256:748d79d51dcabe6193332e60ec69a6eb26fd914ad3555f6e924b78db71016192 -->
+## [0.8.2] - 2026-08-23
+
+固定的候选机制桥接新增 read-file-strict，直接公开既有严格读取机制。
+
+### 新增
+
+- invokeFoundationMechanism 新增 read-file-strict；参数闭合为 root、path、encoding 和 expectedSha256。
+- UTF-8 内容返回字符串，二进制内容返回标准的 JSON 安全 Buffer 形态。
+
+### 变更
+
+- 路径收容、文件读取、摘要复验和失败分类全部转发给 readFileStrict，不新增第二套读取算法。
+- 包版本与 Contracts、Engineering Kit 一同升至 0.8.2。
+
+### 升级说明
+
+候选消费者必须把三个 Foundation 包精确锁定到 0.8.2，再重建受管 Bundle。直接调用继续返回 SFC2004 与 details.kind；JSON CLI 只承诺成功退出码 0 和拒绝退出码 2。
+<!-- release-skill:changelog:end version=0.8.2 locale=zh-CN -->
+
+
+<!-- release-skill:changelog:start version=0.8.1 locale=zh-CN baseline=sha256:904de77446dbc69ef7e70cdda0020fd98632a6e704754f6ed57e136764e3112e -->
+## [0.8.1] - 2026-08-22
+
+宿主把 Harness 打包进单文件适配器后，报告渲染器仍能保留 Harness 自身的包版本。
+
+### 变更
+
+- 包版本与 Contracts、Engineering Kit 一同升至 0.8.1。
+- Harness 的 21 项能力、报告合同和公共导出均保持不变。
+
+### 修复
+
+- 用静态 JSON import 替换报告渲染器运行时基于 import.meta.url 的包清单查找，使 esbuild 内联 Harness 版本，不再读取宿主适配器的包元数据。
+- 为 REPORT_RENDERER_VERSION 新增源码运行与第三方单文件 bundle 回归测试。
+
+### 升级说明
+
+把报告渲染器打包进宿主适配器的消费者必须精确锁定 Harness 0.8.1；报告 API 与渲染器身份保持不变，从 0.8.0 升级不需要迁移 API。
+<!-- release-skill:changelog:end version=0.8.1 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.8.0 locale=zh-CN baseline=sha256:83f13f0b9f624ee26865c5d1bb0295ecd8cbaa64c581f066b53012eadf1dc040 -->
 ## [0.8.0] - 2026-08-21
 

package/README.md

@@ -4,22 +4,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.8.0 -->
+<!-- release-skill:release-version: 0.8.2 -->
 
 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.8.0** (2026-08-21)
+**0.8.2** (2026-08-23)
 
-Lockstep version bump with Foundation 0.8.0; the Harness mechanism surface is unchanged.
+The fixed candidate mechanism bridge now exposes the existing strict reader through read-file-strict.
+
+**Added**
+
+- Adds read-file-strict to invokeFoundationMechanism with closed root, path, encoding, and expectedSha256 parameters.
+- Returns UTF-8 content as a string and binary content in the standard JSON-safe Buffer shape.
 
 **Changed**
 
-- Contracts 1.7.0 adds the Project Profile contract, but no Harness capability or exported mechanism changes.
+- Delegates containment, file reading, digest verification, and failure classification directly to readFileStrict; no second read algorithm is introduced.
+- Moves the package version to 0.8.2 together with Contracts and Engineering Kit.
 
 **Upgrade Notes**
 
-Consumers keep their Harness mechanism pins. Project Profile verification belongs to Engineering Kit/Profile SPI, not to a new Harness mechanism.
+Candidate consumers must pin all three Foundation packages to exactly 0.8.2 and rebuild their managed Bundle. Direct calls retain SFC2004 details.kind failures; the JSON CLI continues to promise only exit code 0 for success and 2 for rejection.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -33,14 +39,14 @@ The Harness consumes `skill-family-contracts` (a workspace dependency), reusing
 ## Installation and Minimal Example
 
 ```sh
-npm install skill-family-harness-node@0.8.0
+npm install skill-family-harness-node@0.8.2
 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.8.0
+// Run from an empty directory: npm install skill-family-harness-node@0.8.2
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {

package/README.zh-CN.md

@@ -5,22 +5,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.8.0 -->
+<!-- release-skill:release-version: 0.8.2 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.8.0** (2026-08-21)
+**0.8.2** (2026-08-23)
 
-随 Foundation 0.8.0 线锁步升版；Harness 机制表面不变。
+固定的候选机制桥接新增 read-file-strict，直接公开既有严格读取机制。
+
+**新增**
+
+- invokeFoundationMechanism 新增 read-file-strict；参数闭合为 root、path、encoding 和 expectedSha256。
+- UTF-8 内容返回字符串，二进制内容返回标准的 JSON 安全 Buffer 形态。
 
 **变更**
 
-- Contracts 1.7.0 新增 Project Profile 合同，但 Harness 能力和导出机制均不变。
+- 路径收容、文件读取、摘要复验和失败分类全部转发给 readFileStrict，不新增第二套读取算法。
+- 包版本与 Contracts、Engineering Kit 一同升至 0.8.2。
 
 **升级说明**
 
-消费者保持 Harness 机制锁定；Project Profile 校验归 Engineering Kit/Profile SPI 负责，不新增 Harness 机制。
+候选消费者必须把三个 Foundation 包精确锁定到 0.8.2，再重建受管 Bundle。直接调用继续返回 SFC2004 与 details.kind；JSON CLI 只承诺成功退出码 0 和拒绝退出码 2。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -34,14 +40,14 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 ## 安装和最小示例
 
 ```sh
-npm install skill-family-harness-node@0.8.0
+npm install skill-family-harness-node@0.8.2
 npm info skill-family-harness-node --help
 ```
 
 最小示例演示在 Node 内校验一份契约文档：
 
 ```js
-// 从空目录运行：npm install skill-family-harness-node@0.8.0
+// 从空目录运行：npm install skill-family-harness-node@0.8.2
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {

package/candidate/quickstart-profile.mjs

@@ -13,6 +13,7 @@ import { fileURLToPath } from "node:url";
 import { computeResourceClosure, digestBytes } from "../src/closure.mjs";
 import { HARNESS_ERROR_KINDS, HarnessError, mechanismError } from "../src/errors.mjs";
 import { resolveContained } from "../src/paths.mjs";
+import { readFileStrict } from "../src/strict-read.mjs";
 
 /**
  * Candidate quickstart profile v2 mechanisms (unstable).
@@ -455,6 +456,7 @@ const FOUNDATION_MECHANISM_OPERATIONS = Object.freeze([
   "digest-document",
   "resource-closure",
   "resolve-contained",
+  "read-file-strict",
   "create-task",
   "wrap-result",
   "verify-exchange",
@@ -483,6 +485,34 @@ function findUnsafeInteger(value, instancePath = "") {
   return null;
 }
 
+function assertReadFileStrictParams(params) {
+  const allowedKeys = new Set(["root", "path", "encoding", "expectedSha256"]);
+  const unknownKey = Object.keys(params).find((key) => !allowedKeys.has(key));
+  if (unknownKey !== undefined) {
+    throw new TypeError(`invokeFoundationMechanism: read-file-strict unknown param: ${unknownKey}`);
+  }
+  for (const key of ["root", "path"]) {
+    if (!Object.hasOwn(params, key) || typeof params[key] !== "string" || params[key].length === 0) {
+      throw new TypeError(`invokeFoundationMechanism: read-file-strict ${key} must be a non-empty string`);
+    }
+  }
+  if (Object.hasOwn(params, "encoding") && params.encoding !== "utf8") {
+    throw new TypeError('invokeFoundationMechanism: read-file-strict encoding must be "utf8" or omitted');
+  }
+}
+
+async function invokeReadFileStrict(params) {
+  assertReadFileStrictParams(params);
+  const receipt = await readFileStrict(params.root, params.path, {
+    ...(Object.hasOwn(params, "encoding") ? { encoding: params.encoding } : {}),
+    ...(Object.hasOwn(params, "expectedSha256") ? { expectedSha256: params.expectedSha256 } : {}),
+  });
+  return {
+    ...receipt,
+    content: Buffer.isBuffer(receipt.content) ? receipt.content.toJSON() : receipt.content,
+  };
+}
+
 /**
  * Fixed, business-neutral mechanism bridge for consumers that cannot import
  * several Foundation modules directly. validateBySchemaId is injected only
@@ -525,6 +555,9 @@ export async function invokeFoundationMechanism(request, { validateBySchemaId }
   if (operation === "resource-closure") {
     return computeResourceClosure({ root: params.root, resources: params.resources });
   }
+  if (operation === "read-file-strict") {
+    return invokeReadFileStrict(params);
+  }
   if (operation === "create-task") {
     return createQuickstartTask(params);
   }

package/package.json

@@ -10,7 +10,7 @@
   "dependencies": {
     "@pnpm/lockfile.fs": "1001.1.35",
     "ipaddr.js": "2.5.0",
-    "skill-family-contracts": "0.8.0",
+    "skill-family-contracts": "0.8.2",
     "yaml": "2.9.0"
   },
   "description": "Thin Node.js mechanism runtime for Skill Family engineering contracts.",
@@ -45,7 +45,7 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node.git"
   },
   "type": "module",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "scripts": {
     "check": "node --test",
     "test": "node --test"

package/release-notes/0.8.1.yaml

@@ -0,0 +1,23 @@
+version: 0.8.1
+date: 2026-08-22
+locales:
+  en:
+    summary: Harness now preserves its own report renderer version when a host bundles it into a single-file adapter.
+    changes:
+      fixed:
+        - Replaces the report renderer's runtime import.meta.url package-manifest lookup with a static JSON import, so esbuild inlines the Harness version instead of resolving the host adapter's package metadata.
+        - Adds source and third-party single-file bundle regression tests for REPORT_RENDERER_VERSION.
+      changed:
+        - Moves the package version to 0.8.1 together with Contracts and Engineering Kit.
+        - Keeps all 21 Harness capabilities, report contracts, and public exports unchanged.
+    upgradeNotes: Host adapters that bundle the report renderer must pin Harness 0.8.1. The report API and renderer identity remain unchanged, so no API migration is required from 0.8.0.
+  zh-CN:
+    summary: 宿主把 Harness 打包进单文件适配器后，报告渲染器仍能保留 Harness 自身的包版本。
+    changes:
+      fixed:
+        - 用静态 JSON import 替换报告渲染器运行时基于 import.meta.url 的包清单查找，使 esbuild 内联 Harness 版本，不再读取宿主适配器的包元数据。
+        - 为 REPORT_RENDERER_VERSION 新增源码运行与第三方单文件 bundle 回归测试。
+      changed:
+        - 包版本与 Contracts、Engineering Kit 一同升至 0.8.1。
+        - Harness 的 21 项能力、报告合同和公共导出均保持不变。
+    upgradeNotes: 把报告渲染器打包进宿主适配器的消费者必须精确锁定 Harness 0.8.1；报告 API 与渲染器身份保持不变，从 0.8.0 升级不需要迁移 API。

package/release-notes/0.8.2.yaml

@@ -0,0 +1,23 @@
+version: 0.8.2
+date: 2026-08-23
+locales:
+  en:
+    summary: The fixed candidate mechanism bridge now exposes the existing strict reader through read-file-strict.
+    changes:
+      added:
+        - Adds read-file-strict to invokeFoundationMechanism with closed root, path, encoding, and expectedSha256 parameters.
+        - Returns UTF-8 content as a string and binary content in the standard JSON-safe Buffer shape.
+      changed:
+        - Delegates containment, file reading, digest verification, and failure classification directly to readFileStrict; no second read algorithm is introduced.
+        - Moves the package version to 0.8.2 together with Contracts and Engineering Kit.
+    upgradeNotes: Candidate consumers must pin all three Foundation packages to exactly 0.8.2 and rebuild their managed Bundle. Direct calls retain SFC2004 details.kind failures; the JSON CLI continues to promise only exit code 0 for success and 2 for rejection.
+  zh-CN:
+    summary: 固定的候选机制桥接新增 read-file-strict，直接公开既有严格读取机制。
+    changes:
+      added:
+        - invokeFoundationMechanism 新增 read-file-strict；参数闭合为 root、path、encoding 和 expectedSha256。
+        - UTF-8 内容返回字符串，二进制内容返回标准的 JSON 安全 Buffer 形态。
+      changed:
+        - 路径收容、文件读取、摘要复验和失败分类全部转发给 readFileStrict，不新增第二套读取算法。
+        - 包版本与 Contracts、Engineering Kit 一同升至 0.8.2。
+    upgradeNotes: 候选消费者必须把三个 Foundation 包精确锁定到 0.8.2，再重建受管 Bundle。直接调用继续返回 SFC2004 与 details.kind；JSON CLI 只承诺成功退出码 0 和拒绝退出码 2。

package/src/report-version.mjs

@@ -0,0 +1,6 @@
+import harnessPackage from "../package.json" with { type: "json" };
+
+// The Harness package manifest is the report renderer version authority.
+// Bundlers inline this static JSON import, so a single-file host adapter keeps
+// the Harness version instead of resolving package.json beside the host file.
+export const REPORT_RENDERER_VERSION = harnessPackage.version;

package/src/report.mjs

@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 import {
   canonicalJson,
   digestDocument,
@@ -7,6 +6,7 @@ import {
 } from "skill-family-contracts";
 import { digestBytes } from "./closure.mjs";
 import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
+import { REPORT_RENDERER_VERSION } from "./report-version.mjs";
 import { validateContractDocument } from "./validation.mjs";
 
 /**
@@ -18,10 +18,8 @@ import { validateContractDocument } from "./validation.mjs";
  * operation's outputs, derives an execution status, or fills missing facts.
  */
 
-const PACKAGE_META = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-
 export const REPORT_RENDERER_NAME = "skill-family-harness-node/report";
-export const REPORT_RENDERER_VERSION = PACKAGE_META.version;
+export { REPORT_RENDERER_VERSION };
 export const SUPPORTED_REPORT_LOCALES = Object.freeze(["zh-CN", "en-US"]);
 export const EXECUTION_STATUSES = Object.freeze([
   "SUCCEEDED",