skill-family-harness-node 0.1.2 → 0.2.0

package/CONTRIBUTING.md

@@ -1,79 +1,25 @@
-# 贡献指南（Contributing）
+# 贡献指南（skill-family-harness-node）
 
-感谢关注 `skill-family-foundation-workspace`。本文件说明本地开发环境、
-验证流程与 PR 规则。行为准则见 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)，
-Git 写操作的授权边界见仓库内文档站的生命周期指南（`docs/git-lifecycle.md`）。
+本仓是 `skill-family-harness-node` 的公开发布镜像，只承载版本化发布物。开发在私有工作区进行，不在本仓公开。
 
-拓扑说明：本工作区仓永久 private，是唯一开发真源；三个 public 仓
-（`skill-family-contracts`、`skill-family-harness-node`、
-`skill-family-engineering-kit`）是版本化发布镜像，不承载完整开发历史与
-测试。本指南描述的是私有工作区内经授权的开发流程；消费坐标与发布状态
-唯一见 `docs/status/current.md`。
+## 问题报告
 
-## Bug 报告与 Issue
+Bug 报告请在本仓 GitHub Issues 提交：https://github.com/ifoohoo/skill-family-harness-node/issues
 
-普通 bug 报告欢迎通过各 public 发布镜像仓的 GitHub Issues 提交（例如
-`https://github.com/ifoohoo/skill-family-engineering-kit/issues`）。提交
-bug 报告时请尽量提供：受影响包与版本、最小复现步骤、预期与实际行为。
+提交时请尽量提供：受影响版本、最小复现步骤、预期与实际行为。
 
-**未经事先讨论的 Pull Request 不予接受。** 如果你希望贡献代码，请先
-通过 Issue 讨论变更的动机与范围，获得维护者确认后再提交 PR。这是为了
-避免重复劳动、确保变更与本项目的架构裁决和发布合同一致。
+## 代码贡献
 
-## 本地安装
+未经事先讨论的 Pull Request 不予接受。请先通过 Issue 讨论变更的动机与范围，获得维护者确认后再提交 PR。
 
-必需工具（精确版本见仓库内 `docs/setup.md` 的安装合同）：
+## 行为准则
 
-- Node.js：`>=22.22.2 <23`（版本取自 `.node-version`）
-- pnpm：10.30.0（`packageManager` 精确锁定）
-- Python：3.10 或更高（仅文档站构建需要）
+互动请遵守本仓 CODE_OF_CONDUCT.md。
 
-```bash
-pnpm install
-pnpm synth
-pnpm check
-```
-
-- `pnpm synth` 再生成 projen 受管文件。受管文件只能通过修改
-  `.projenrc.js` 间接变更；手写源码、文档和 fixture 不会被 synth 覆盖。
-- `pnpm check` 是统一根门禁：10 个稳定门禁 ID 按固定顺序串联执行，
-  任一步骤非 0 即整体失败。
-
-## 提交 PR 前必须做到
-
-1. 只修改当前任务授权的文件，不顺手改动无关文件；
-2. 修改 `.projenrc.js` 后运行 `pnpm synth`，并保证连续两次 synth 零漂移；
-3. 本地完整通过根门禁：
-
-   ```bash
-   pnpm check
-   ```
-
-4. 涉及文档时额外运行文档事实与链接检查：
-
-   ```bash
-   node scripts/docs/fact-check.mjs
-   node scripts/docs/link-check.mjs
-   ```
-
-5. 涉及三个叶子包时，确认发布字节合同仍然成立：
-
-   ```bash
-   pnpm run release-artifacts:build -- --output .artifacts/publish-candidates
-   pnpm run release-artifacts:verify -- --root .artifacts/publish-candidates --manifest .artifacts/publish-candidates/release-artifacts.manifest.json
-   ```
-
-## PR 规则
+## 安全报告
 
-- PR 描述须包含：动机、变更面、本地门禁结果（退出码）与剩余风险；
-- 不得为转绿而弱化任何产品门禁、Action pin、权限、泄漏策略或 tarball 合同；
-- 不新增运行时依赖，除非先经评审并显式修订泄漏策略中的公开依赖清单；
-- 不提交生成物与本地状态：`node_modules`、`site/`、`.artifacts/`、缓存、
-  日志、凭据或本机绝对路径一律不进入提交；
-- 受管投影必须与产生它的源变更在同一 PR 内提交，禁止手改受管文件；
-- 动态状态（实时发布状态、远端对象状态）不写入版本化文档，唯一产品状态
-  口径见 `docs/status/current.md`。
+漏洞报告渠道见本仓 SECURITY.md。请走 Private vulnerability reporting，不要以公开 Issue 提交漏洞。
 
-## 安全报告
+## 许可证
 
-漏洞报告渠道与支持版本见 [SECURITY.md](SECURITY.md)。
+贡献内容默认按 Apache-2.0 授权，与本包许可证一致。

package/README.md

@@ -8,7 +8,7 @@ Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时
 ## 边界
 
 - 消费 `skill-family-contracts`（工作区依赖），复用其方言路由的 Ajv validator、Kernel Protocol、冻结错误码与 fixture；不复制协议定义，不重新解释 Schema。
-- 只实现机制：Schema 校验、原子写、路径收容、临时工作区、资源闭包、operation-request → operation-result 管道。
+- 只实现机制：Schema 校验、原子写、路径收容、临时工作区、资源闭包、operation-request → operation-result 管道、业务中立的事件日志与派生快照。
 - 明确排除：业务语义、任务编排、Git 写入、模型调用、远程网络、发布状态。见 `HARNESS_EXCLUSIONS`。
 
 ## 公共 API
@@ -23,6 +23,22 @@ Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时
 | `TemporaryWorkspace` / `createTemporaryWorkspace` / `withTemporaryWorkspace` | 自动清理的临时工作区，异常路径也清理。 |
 | `digestBytes` / `computeResourceClosure` / `closureContains` | 资源闭包与确定性 sha256 摘要。 |
 | `parseRequest` / `processRequest` | 解析 `operation-request`，输出终态 `operation-result`。 |
+| `validateReportModel` / `renderReportMarkdown` / `buildBinding` / `checkReport` | 消费经 Contracts 验证的 report model，确定性渲染中性 Markdown 并校验来源/结果/报告绑定；不解释业务输出。 |
+| `normalizeAdapterSource` / `buildAdapterClosure` / `verifyAdapterBuildManifest` / `materializeAdapterBuild` | 通用文本 source closure、manifest 全摘要复验和目标集合原子落盘；具体 Profile/driver 不在 Harness。 |
+| `probeVersionVector` | 默认禁用 spawn 的版本探测机制；显式启用时只执行绝对、无 symlink 的受审计向量，不使用 PATH/shell。 |
+| `openStateStore` / `appendEvent` / `readEvents` / `verifyStateStore` / `closeStateStore` | 严格单写者的 append-only 事件存储；事件目录是唯一状态权威，`chain-head.json` 只是缓存。 |
+| `readSnapshot` / `writeSnapshot` / `rebuildSnapshot` | 原子派生快照与完整事件重建；坏事件不能被旧快照掩盖，坏快照可被重建忽略。 |
+| `inspectStateStoreLock` / `recoverStateStoreLock` | 只读锁诊断与显式恢复；恢复必须对观测到的 owner + fencing 做精确匹配。 |
+
+## 状态存储的锁与恢复边界
+
+- 锁使用 exclusive create，第二写者立即收到 `store-locked`；不排队，也不按时间、PID 或租约过期偷锁。
+- `inspectStateStoreLock` 不创建任何文件，只返回 `owner`、单调 `fencing`、`ageMs` 和恢复中标记。`ageMs` 仅供诊断，从不参与正确性判断。
+- 崩溃遗留锁只能由调用方在 Foundation 之外确认旧写者已经终止后，调用 `recoverStateStoreLock`，同时提交精确匹配的 `expectedOwner`、`expectedFencing` 与 `confirmOwnerTerminated: true`。不匹配或缺少确认均失败关闭。
+- 恢复产生更大的 fencing。旧 handle 每次 append 都重新核对 owner、fencing 和 acquisition id；事件最终发布使用同目录临时普通文件、fsync 和 exclusive link，绝不覆盖既有 sequence。
+- append、snapshot、close 与 recovery 由短期 `writer-mutation.lock` 串行化；恢复不能越过已经持有 mutation guard 的权威写入。
+- 如果恢复进程自身在持有 `writer-recovery.lock` 时崩溃，系统保持可诊断的锁死状态，不自动删除该 guard。它需要新的外部取证与人工处置；当前 API 不声称解决不可信调用方谎报“旧写者已终止”的场景。
+- state root、`events/`、`snapshots/`、事件和快照拒绝 symlink、硬链接、FIFO、设备与其它非普通条目。payload 必须是纯 JSON，且 `eventType + payloadSchemaVersion` 必须命中调用方在 open/recover 时冻结的 Schema 对。
 
 ## 稳定错误码
 
@@ -43,19 +59,19 @@ Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时
 
 ## 测试
 
-`node --test` 覆盖：Contracts fixture 全量回放、安全反例（三类逃逸均被拦截且零越界写）、原子性失败路径无残留、临时工作区异常清理、闭包确定性、Windows 路径/整数/正则/`format` 边界。
+`node --test` 覆盖：Contracts fixture 全量回放、安全反例、原子性失败路径、临时工作区、闭包确定性、报告事实绑定与 Markdown 注入、宿主 manifest/路径/命令信任，以及状态存储的崩溃、并发、损坏、fencing、显式恢复、symlink、硬链接与 FIFO 反例。
 
 ## 安装
 
 ```sh
-npm install skill-family-harness-node
+npm install skill-family-harness-node@0.2.0
 npm info skill-family-harness-node --help
 ```
 
 ## 最小示例
 
 ```js
-// 从空目录运行：npm install skill-family-harness-node
+// 从空目录运行：npm install skill-family-harness-node@0.2.0
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {

package/SECURITY.md

@@ -12,15 +12,10 @@
 ## 报告漏洞
 
 请勿通过公开 issue 直接披露未修复的安全漏洞。private workspace 仓永久
-private，不是公开报告渠道；请通过以下渠道私下报告：
-
-1. **首选**：通过任一 public 发布镜像仓（例如
-   `https://github.com/ifoohoo/skill-family-engineering-kit`）在 GitHub 上使用
-   **Private vulnerability reporting**（仓库 Security 页签的
-   "Report a vulnerability"）；
-2. **备选**：如上述通道不可用，请通过邮件联系仓库维护者
-   （`ifoohoo` GitHub 组织的 `security` 团队，或仓库 `README.md` 中列出的
-   维护者邮箱）。
+private，不是公开报告渠道；请通过任一 public 发布镜像仓（例如
+`https://github.com/ifoohoo/skill-family-engineering-kit`）在 GitHub 上使用
+**Private vulnerability reporting**（仓库 Security 页签的
+"Report a vulnerability"）私下报告。
 
 报告时请尽量提供：
 

package/package.json

@@ -5,7 +5,7 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node/issues"
   },
   "dependencies": {
-    "skill-family-contracts": "0.1.2"
+    "skill-family-contracts": "0.2.0"
   },
   "description": "Thin Node.js mechanism runtime for Skill Family engineering contracts.",
   "engines": {
@@ -27,9 +27,9 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node.git"
   },
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "scripts": {
-    "check": "node --input-type=module -e \"import('./src/index.mjs').then(() => console.log('smoke ok')).catch(e => { console.error(e); process.exit(1) })\"",
-    "test": "node --input-type=module -e \"import('./src/index.mjs').then(() => console.log('smoke ok')).catch(e => { console.error(e); process.exit(1) })\""
+    "check": "node --test",
+    "test": "node --test"
   }
 }

package/src/errors.mjs

@@ -41,6 +41,22 @@ export const HARNESS_ERROR_KINDS = Object.freeze({
   UNSUPPORTED_POLICY: "unsupported-policy",
   EXECUTION_FAILED: "execution-failed",
   INVALID_RESULT: "invalid-result",
+  STORE_CLOSED: "store-closed",
+  STORE_LOCKED: "store-locked",
+  LOCK_CORRUPT: "lock-corrupt",
+  LOCK_RECOVERY_REFUSED: "lock-recovery-refused",
+  UNSAFE_STATE_ENTRY: "unsafe-state-entry",
+  EVENT_SCHEMA_INVALID: "event-schema-invalid",
+  DUPLICATE_SEQUENCE: "duplicate-sequence",
+  IDEMPOTENCY_CONFLICT: "idempotency-conflict",
+  CHAIN_BROKEN: "chain-broken",
+  SNAPSHOT_MISMATCH: "snapshot-mismatch",
+  HOST_CONTRACT_INVALID: "host-contract-invalid",
+  HOST_BUILD_FAILED: "host-build-failed",
+  HOST_PROBE_FAILED: "host-probe-failed",
+  UNTRUSTED_EXECUTABLE: "untrusted-executable",
+  PORTABLE_PATH_COLLISION: "portable-path-collision",
+  MANIFEST_MISMATCH: "manifest-mismatch",
 });
 
 /**

package/src/host.mjs

@@ -0,0 +1,245 @@
+import { constants } from "node:fs";
+import { access, lstat, mkdtemp, readFile, realpath, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { canonicalJson, digestDocument, validateDocument } from "skill-family-contracts";
+import { writeFileAtomic } from "./atomic.mjs";
+import { digestBytes } from "./closure.mjs";
+import { HARNESS_ERROR_KINDS, HarnessError, mechanismError } from "./errors.mjs";
+import { classifyPathInput } from "./paths.mjs";
+
+const SCHEMAS = Object.freeze({
+  adapterSource: "https://contracts.skill-family.example/v1/adapter-source.json",
+  buildManifest: "https://contracts.skill-family.example/v1/adapter-build-manifest.json",
+  capabilityFact: "https://contracts.skill-family.example/v1/host-capability-fact.json",
+});
+
+function invalidParams(message, details) {
+  return new HarnessError("SFC2003", message, { ...(details ?? {}), kind: "invalid-params" });
+}
+
+function validateContract(document, schemaId, message) {
+  const result = validateDocument(document, { schemaId, dialect: "2020-12", policy: "strict" });
+  if (!result.valid) throw mechanismError(HARNESS_ERROR_KINDS.HOST_CONTRACT_INVALID, message, { errors: result.errors });
+  return result.data;
+}
+
+function assertRelative(relPath, label) {
+  const classified = classifyPathInput(relPath);
+  const normalized = typeof relPath === "string" ? path.posix.normalize(relPath) : "";
+  if (!classified.ok || normalized !== relPath || normalized === "." || normalized.startsWith("../")) {
+    throw invalidParams(`${label} must be a normalized contained relative path`, { path: relPath, pathKind: classified.kind ?? "non-normalized" });
+  }
+  return relPath;
+}
+
+function portablePathKey(value) {
+  return value.normalize("NFC").toLocaleLowerCase("en-US");
+}
+
+function assertUniquePortablePaths(paths, label) {
+  const seen = new Map();
+  for (const value of paths) {
+    const key = portablePathKey(value);
+    if (seen.has(key)) {
+      throw mechanismError(HARNESS_ERROR_KINDS.PORTABLE_PATH_COLLISION, `${label} contains a portable path collision`, { first: seen.get(key), second: value });
+    }
+    seen.set(key, value);
+  }
+}
+
+/** Validates and deterministically normalizes an adapter source closure. */
+export function normalizeAdapterSource(input) {
+  const source = validateContract(input, SCHEMAS.adapterSource, "adapter source fails its registered contract");
+  const skillIds = source.skills.map((skill) => skill.id);
+  if (new Set(skillIds).size !== skillIds.length) throw mechanismError(HARNESS_ERROR_KINDS.HOST_CONTRACT_INVALID, "adapter source contains a duplicate skill id");
+  assertUniquePortablePaths(skillIds, "adapter skill ids");
+
+  const sources = [];
+  for (const skill of source.skills) {
+    const filePaths = skill.files.map((file) => assertRelative(file.path, "adapter source file path"));
+    if (!filePaths.includes("SKILL.md")) throw invalidParams(`skill ${skill.id} is missing SKILL.md`);
+    if (new Set(filePaths).size !== filePaths.length) throw invalidParams(`skill ${skill.id} contains a duplicate path`);
+    assertUniquePortablePaths(filePaths, `skill ${skill.id}`);
+    for (const file of skill.files) {
+      const bytes = Buffer.from(file.content, "utf8");
+      sources.push({
+        sourcePath: `${skill.id}/${file.path}`,
+        skillId: skill.id,
+        filePath: file.path,
+        content: file.content,
+        bytes,
+        sha256: digestBytes(bytes),
+      });
+    }
+  }
+  assertUniquePortablePaths(sources.map((entry) => entry.sourcePath), "adapter source closure");
+  sources.sort((left, right) => left.sourcePath.localeCompare(right.sourcePath));
+  return sources;
+}
+
+/** Pure adapter build mechanism. Host-specific path categories are injected. */
+export function buildAdapterClosure({ hostId, pathCategory, input } = {}) {
+  if (!hostId || !pathCategory) throw invalidParams("buildAdapterClosure requires hostId and pathCategory");
+  const sources = normalizeAdapterSource(input);
+  const sourceMembers = sources.map(({ sourcePath, sha256, bytes }) => ({ sourcePath, sha256, bytes: bytes.length }));
+  const sourceClosure = { digest: digestDocument(sourceMembers), members: sourceMembers };
+  const files = sources.map((source) => ({
+    sourcePath: source.sourcePath,
+    target: `${pathCategory.relPath}/${source.sourcePath}`,
+    content: source.content,
+    sha256: source.sha256,
+    bytes: source.bytes.length,
+  }));
+  assertUniquePortablePaths(files.map((entry) => entry.target), "adapter target closure");
+  const manifestBase = {
+    schemaVersion: 1,
+    kind: "skill-family.adapter-build-manifest",
+    hostId,
+    pathCategory,
+    sourceClosure,
+    members: files.map(({ sourcePath, target, sha256, bytes }) => ({ sourcePath, target, sha256, bytes })),
+  };
+  const manifest = validateContract({ ...manifestBase, digest: digestDocument(manifestBase) }, SCHEMAS.buildManifest, "adapter build manifest fails its registered contract");
+  verifyAdapterBuildManifest(manifest, { hostId, pathCategory });
+  return { status: "built", manifest, files };
+}
+
+/** Recomputes every digest and source-to-target binding before consumption. */
+export function verifyAdapterBuildManifest(manifestInput, { hostId, pathCategory } = {}) {
+  const manifest = validateContract(manifestInput, SCHEMAS.buildManifest, "adapter build manifest fails its registered contract");
+  const { digest, ...base } = manifest;
+  if (digestDocument(base) !== digest) throw mechanismError(HARNESS_ERROR_KINDS.MANIFEST_MISMATCH, "adapter manifest digest does not match its content");
+  if (digestDocument(manifest.sourceClosure.members) !== manifest.sourceClosure.digest) {
+    throw mechanismError(HARNESS_ERROR_KINDS.MANIFEST_MISMATCH, "adapter source closure digest does not match its members");
+  }
+  if (hostId !== undefined && manifest.hostId !== hostId) throw mechanismError(HARNESS_ERROR_KINDS.MANIFEST_MISMATCH, "adapter manifest host does not match the requested host");
+  if (pathCategory !== undefined && canonicalJson(manifest.pathCategory) !== canonicalJson(pathCategory)) {
+    throw mechanismError(HARNESS_ERROR_KINDS.MANIFEST_MISMATCH, "adapter manifest category does not match the requested category");
+  }
+
+  const sourcePaths = manifest.sourceClosure.members.map((entry) => entry.sourcePath);
+  const targetPaths = manifest.members.map((entry) => entry.target);
+  assertUniquePortablePaths(sourcePaths, "manifest source closure");
+  assertUniquePortablePaths(targetPaths, "manifest target closure");
+  if (new Set(sourcePaths).size !== sourcePaths.length || new Set(targetPaths).size !== targetPaths.length) {
+    throw mechanismError(HARNESS_ERROR_KINDS.MANIFEST_MISMATCH, "adapter manifest contains duplicate members");
+  }
+  const sortedSources = [...sourcePaths].sort((left, right) => left.localeCompare(right));
+  const outputSources = manifest.members.map((entry) => entry.sourcePath);
+  if (canonicalJson(sourcePaths) !== canonicalJson(sortedSources) || canonicalJson(outputSources) !== canonicalJson(sortedSources)) {
+    throw mechanismError(HARNESS_ERROR_KINDS.MANIFEST_MISMATCH, "adapter manifest members are not the canonical complete source set");
+  }
+  const bySource = new Map(manifest.sourceClosure.members.map((entry) => [entry.sourcePath, entry]));
+  for (const member of manifest.members) {
+    assertRelative(member.sourcePath, "manifest source path");
+    assertRelative(member.target, "manifest target path");
+    const source = bySource.get(member.sourcePath);
+    const expectedTarget = `${manifest.pathCategory.relPath}/${member.sourcePath}`;
+    if (!source || source.sha256 !== member.sha256 || source.bytes !== member.bytes || member.target !== expectedTarget) {
+      throw mechanismError(HARNESS_ERROR_KINDS.MANIFEST_MISMATCH, "adapter manifest member is not bound to its declared source/category", { sourcePath: member.sourcePath, target: member.target });
+    }
+  }
+  return manifest;
+}
+
+/** Atomically publishes one complete, reverified build set. */
+export async function materializeAdapterBuild({ targetRoot, build, writer = writeFileAtomic } = {}) {
+  if (!path.isAbsolute(targetRoot ?? "")) throw invalidParams("materializeAdapterBuild requires an absolute targetRoot");
+  if (!build || build.status !== "built" || !Array.isArray(build.files)) throw invalidParams("materializeAdapterBuild requires a completed in-memory build");
+  const manifest = verifyAdapterBuildManifest(build.manifest);
+  if (build.files.length !== manifest.members.length) throw mechanismError(HARNESS_ERROR_KINDS.MANIFEST_MISMATCH, "in-memory build is not the manifest's complete target set");
+  for (let index = 0; index < manifest.members.length; index += 1) {
+    const member = manifest.members[index];
+    const file = build.files[index];
+    const content = Buffer.from(file?.content ?? "", "utf8");
+    if (file?.sourcePath !== member.sourcePath || file?.target !== member.target || digestBytes(content) !== member.sha256 || content.length !== member.bytes) {
+      throw mechanismError(HARNESS_ERROR_KINDS.MANIFEST_MISMATCH, "in-memory build bytes do not match the manifest", { index });
+    }
+  }
+
+  const parent = path.dirname(targetRoot);
+  const baseName = path.basename(targetRoot);
+  const parentStat = await lstat(parent).catch(() => null);
+  if (!parentStat?.isDirectory() || parentStat.isSymbolicLink()) throw mechanismError(HARNESS_ERROR_KINDS.HOST_BUILD_FAILED, "build target parent must be an existing plain directory");
+  const resolvedParent = await realpath(parent);
+  if (resolvedParent !== path.resolve(parent)) throw mechanismError(HARNESS_ERROR_KINDS.HOST_BUILD_FAILED, "build target parent path cannot contain a symlink ancestor");
+  if (await lstat(targetRoot).then(() => true, () => false)) throw mechanismError(HARNESS_ERROR_KINDS.HOST_BUILD_FAILED, "host build target must be absent; no bytes were written");
+  const staging = await mkdtemp(path.join(parent, `.${baseName}.host-build-`));
+  try {
+    for (const file of build.files) await writer(staging, file.target, file.content);
+    await writer(staging, "adapter-build-manifest.json", `${JSON.stringify(manifest, null, 2)}\n`);
+    for (const member of manifest.members) {
+      const bytes = await readFile(path.join(staging, member.target));
+      if (digestBytes(bytes) !== member.sha256 || bytes.length !== member.bytes) throw mechanismError(HARNESS_ERROR_KINDS.HOST_BUILD_FAILED, "staged adapter bytes do not match the manifest");
+    }
+    if (await lstat(targetRoot).then(() => true, () => false)) throw mechanismError(HARNESS_ERROR_KINDS.HOST_BUILD_FAILED, "host build target appeared during staging; staged bytes were discarded");
+    // Staging is a sibling of targetRoot, so rename is same-filesystem and
+    // publishes the verified member set as one namespace operation.
+    await rename(staging, targetRoot);
+    return { targetRoot, manifest };
+  } catch (cause) {
+    await rm(staging, { recursive: true, force: true });
+    if (cause?.code?.startsWith?.("SFC")) throw cause;
+    throw mechanismError(HARNESS_ERROR_KINDS.HOST_BUILD_FAILED, "atomic host build failed; no target was published", { causeCode: cause?.code ?? "unknown" });
+  }
+}
+
+function fact(hostId, capability, state, evidence, extra = {}) {
+  return validateContract({ schemaVersion: 1, kind: "skill-family.host-capability-fact", hostId, capability, state, evidence, ...extra }, SCHEMAS.capabilityFact, "probe emitted an invalid capability fact");
+}
+
+function unknownFact(hostId, capability, unknownReason, evidence, manualStep) {
+  return fact(hostId, capability, "unknown", [evidence], { unknownReason, manualSteps: [manualStep] });
+}
+
+function fillLimited(hostId, capabilities, firstFacts) {
+  return [...firstFacts, ...capabilities.slice(2).map((capability) => unknownFact(hostId, capability, "driver-limited", `The frozen version-only driver does not inspect ${capability}.`, `Verify ${capability} manually using the host's documented read-only interface.`))];
+}
+
+function parseVersion(output) {
+  const match = String(output ?? "").match(/(?:^|[^0-9])v?((?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)(?=$|[^0-9A-Za-z.+-])/);
+  return match?.[1] ?? null;
+}
+
+async function verifyExecutable(executable) {
+  if (typeof executable !== "string" || !path.isAbsolute(executable)) throw mechanismError(HARNESS_ERROR_KINDS.UNTRUSTED_EXECUTABLE, "host probe spawn requires an explicit absolute executable path");
+  const stat = await lstat(executable).catch(() => null);
+  if (!stat?.isFile() || stat.isSymbolicLink()) throw mechanismError(HARNESS_ERROR_KINDS.UNTRUSTED_EXECUTABLE, "host probe executable must be an existing plain file");
+  const resolved = await realpath(executable);
+  if (resolved !== path.resolve(executable)) throw mechanismError(HARNESS_ERROR_KINDS.UNTRUSTED_EXECUTABLE, "host probe executable path cannot contain symlinks");
+  await access(executable, constants.X_OK).catch(() => { throw mechanismError(HARNESS_ERROR_KINDS.UNTRUSTED_EXECUTABLE, "host probe executable is not executable"); });
+  return resolved;
+}
+
+/** Runs an audited vector; spawn is disabled by default and never uses PATH. */
+export async function probeVersionVector({ hostId, capabilities, executable, argv, allowSpawn = false, timeoutMs = 5000, runner = spawnSync } = {}) {
+  if (!Array.isArray(capabilities) || capabilities.length < 2 || capabilities[0] !== "cli" || capabilities[1] !== "version") throw invalidParams("probe capabilities must begin with cli and version");
+  if (!Array.isArray(argv) || argv.some((value) => typeof value !== "string")) throw invalidParams("probe argv must be a frozen string array");
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw invalidParams("timeoutMs must be an integer from 1 to 30000");
+  if (!allowSpawn) return capabilities.map((capability) => unknownFact(hostId, capability, "spawn-restricted", "Process spawning is disabled by default; no host command ran.", "Provide an audited absolute executable and explicitly opt in to the frozen non-interactive version probe."));
+  const trustedExecutable = await verifyExecutable(executable);
+  let result;
+  try {
+    result = runner(trustedExecutable, [...argv], {
+      cwd: process.cwd(), env: {}, encoding: "utf8", shell: false,
+      windowsHide: true, timeout: timeoutMs, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (cause) {
+    return fillLimited(hostId, capabilities, [fact(hostId, "cli", "error", [`Version probe runner threw ${cause?.name ?? "Error"}.`]), fact(hostId, "version", "error", ["No version output was produced because the probe runner threw."])]);
+  }
+  if (result?.error) {
+    const code = result.error.code ?? "unknown";
+    if (code === "ENOENT") return fillLimited(hostId, capabilities, [fact(hostId, "cli", "unavailable", ["The explicitly bound executable was not found."]), fact(hostId, "version", "unavailable", ["A version cannot be observed because the CLI is unavailable."])]);
+    const reason = code === "ETIMEDOUT" ? "timeout" : code === "EACCES" || code === "EPERM" ? "permission-denied" : null;
+    if (reason) {
+      const step = reason === "timeout" ? "Run the same frozen version command manually and inspect whether it completes without interaction." : "Run the same frozen version command in a context with read/execute permission.";
+      return fillLimited(hostId, capabilities, [unknownFact(hostId, "cli", reason, `The frozen version probe ended with ${code}.`, step), unknownFact(hostId, "version", reason, "No trustworthy version was observed.", step)]);
+    }
+    return fillLimited(hostId, capabilities, [fact(hostId, "cli", "error", [`The process API reported spawn error ${code}.`]), fact(hostId, "version", "error", ["No trustworthy version was observed after the spawn error."])]);
+  }
+  if (result?.status !== 0) return fillLimited(hostId, capabilities, [fact(hostId, "cli", "available", ["The explicitly bound executable started without a spawn error."]), fact(hostId, "version", "error", [`The version command exited with status ${String(result?.status)}.`])]);
+  const observedVersion = parseVersion(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
+  if (!observedVersion) return fillLimited(hostId, capabilities, [fact(hostId, "cli", "available", ["The explicitly bound executable completed successfully."]), fact(hostId, "version", "error", ["Successful output did not contain a parseable semantic version."])]);
+  return fillLimited(hostId, capabilities, [fact(hostId, "cli", "available", ["The explicitly bound executable completed successfully."]), fact(hostId, "version", "available", ["A semantic version was parsed from the frozen version output."], { observedVersion })]);
+}

package/src/index.mjs

@@ -17,6 +17,9 @@ export const HARNESS_CAPABILITIES = Object.freeze([
   "temporary-workspace",
   "resource-closure",
   "operation-envelope",
+  "host-adapter-mechanism",
+  "report-rendering",
+  "durable-state-store",
 ]);
 
 export const HARNESS_EXCLUSIONS = Object.freeze([
@@ -50,3 +53,51 @@ export {
 } from "./validation.mjs";
 
 export { parseRequest, processRequest } from "./request.mjs";
+
+// Generic host mechanism. Concrete host profiles and audited driver vectors
+// are injected by downstream orchestration; the harness never imports them.
+export {
+  normalizeAdapterSource,
+  buildAdapterClosure,
+  verifyAdapterBuildManifest,
+  materializeAdapterBuild,
+  probeVersionVector,
+} from "./host.mjs";
+
+// Deterministic report layer (FND-ADR-005): validate -> render -> bind -> check.
+// Pure functions only: no clock, no environment, no network, no model calls.
+export {
+  REPORT_RENDERER_NAME,
+  REPORT_RENDERER_VERSION,
+  SUPPORTED_REPORT_LOCALES,
+  EXECUTION_STATUSES,
+  RESULT_STATE_EXECUTION_STATUSES,
+  REPORT_AUDIENCES,
+  REPORT_STYLE_RULES,
+  validateReportModel,
+  renderReportMarkdown,
+  computeResultDigest,
+  computeModelDigest,
+  digestReport,
+  buildBinding,
+  verifyBinding,
+  checkReport,
+  collectStyleWarnings,
+} from "./report.mjs";
+
+// Durable state mechanism only. Event meaning and reducer transitions remain
+// consumer-owned; the harness owns ordering, integrity, fencing and recovery.
+export {
+  STATE_GENESIS_DIGEST,
+  openStateStore,
+  inspectStateStoreLock,
+  recoverStateStoreLock,
+  appendEvent,
+  readEvents,
+  readSnapshot,
+  writeSnapshot,
+  verifyStateStore,
+  rebuildSnapshot,
+  closeStateStore,
+  close,
+} from "./state-store.mjs";