skill-family-harness-node 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+<!-- 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
+
+This release adds candidate Quickstart Profile exchange helpers and makes the package release documentation available in English and Simplified Chinese.
+
+### 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.
+
+### 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.
+
+### Upgrade Notes
+
+The candidate helpers do not alter the stable Harness API or add lifecycle, retry, orchestration, model-call, network, or Git-write semantics.
+<!-- release-skill:changelog:end version=0.2.1 locale=en -->

package/CHANGELOG.zh-CN.md

@@ -0,0 +1,42 @@
+# 变更日志
+
+<!-- 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
+
+本版新增 Quickstart Profile 候选交换辅助函数，并为包发布文档提供完整英文版与简体中文版。
+
+### 新增
+
+- 新增候选辅助函数，用于创建并复验 observation Resource、构造 Task、封装 Result，并在 Result 未精确绑定 Task 与关联字段时失败关闭。
+- 新增完整的英文与简体中文包文档，并补充智能体快速参考章节。
+
+### 变更
+
+- 使用同一份双语版本化说明源管理当前 README 与 CHANGELOG 的发布区域。
+- 项目 NOTICE 与 Apache-2.0 LICENSE 分开分发。
+
+### 升级说明
+
+候选辅助函数不改变稳定 Harness API，也不引入生命周期、重试、编排、模型调用、网络或 Git 写入语义。
+<!-- release-skill:changelog:end version=0.2.1 locale=zh-CN -->

package/NOTICE

@@ -0,0 +1,10 @@
+Skill Family Foundation
+=======================
+
+Copyright 2026 广州市风荷科技有限公司
+
+Licensed under the Apache License, Version 2.0.
+
+This NOTICE contains project attribution for Skill Family Foundation. Third-party
+attribution and license texts distributed with skill-family-engineering-kit are
+recorded separately in THIRD_PARTY_NOTICES and the corresponding license files.

package/README.md

@@ -1,77 +1,52 @@
 <!-- release-skill:safe-first-command -->
 <!-- release-skill:external-write-boundary -->
+> 简体中文版：[README.zh-CN.md](./README.zh-CN.md)
 
 # skill-family-harness-node
 
-Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
+<!-- release-skill:release-version: 0.3.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.
 
-- 消费 `skill-family-contracts`（工作区依赖），复用其方言路由的 Ajv validator、Kernel Protocol、冻结错误码与 fixture；不复制协议定义，不重新解释 Schema。
-- 只实现机制：Schema 校验、原子写、路径收容、临时工作区、资源闭包、operation-request → operation-result 管道、业务中立的事件日志与派生快照。
-- 明确排除：业务语义、任务编排、Git 写入、模型调用、远程网络、发布状态。见 `HARNESS_EXCLUSIONS`。
+<!-- release-skill:managed:start id=latest-release -->
+**0.3.0** (2026-08-12)
 
-## 公共 API
+This source candidate updates the Quickstart Profile harness to verify v2 Task and Result exchanges without taking ownership of consumer semantics.
 
-| 导出 | 职责 |
-| --- | --- |
-| `HARNESS_CAPABILITIES` / `HARNESS_EXCLUSIONS` | 能力与排除清单（冻结常量）。 |
-| `HarnessError` / `HARNESS_ERROR_KINDS` / `mechanismError` | 机制失败统一携带注册错误码 `SFC2004`，`details.kind` 给出稳定细分。 |
-| `validateContractDocument` / `getValidator` / `resolveSchemaContext` / `validatorCacheSize` | 按 Schema 方言路由并缓存 validator；复用 Contracts 的 Ajv 实例与 dialect/policy 语义。 |
-| `classifyPathInput` / `resolveContained` / `readFileContained` | 路径收容：拦截路径越界、符号链接逃逸、真实路径逃逸。 |
-| `writeFileAtomic` | 原子写：失败不留半成品（临时文件 + fsync + rename）。 |
-| `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 做精确匹配。 |
-
-## 状态存储的锁与恢复边界
+**Added**
 
-- 锁使用 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 对。
+- 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**
 
-全部复用 Contracts 冻结登记表，不新增未登记码。机制失败统一为 `SFC2004`（EXECUTION_FAILED），`details.kind` 取 `HARNESS_ERROR_KINDS` 中的稳定值，例如 `path-traversal`、`symlink-escape`、`realpath-escape`、`atomic-write-failed`、`missing-resource`、`workspace-disposed`。
+- 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.
 
-新增一个全新的 SFC 码属于 Contracts 变更（登记表在 contracts 包内），超出本包写集；因此用「`SFC2004` + 稳定 `details.kind`」组合保持对外语义稳定。
+**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:managed:end id=latest-release -->
 
-`resolveContained(root, rel)` 是所有文件系统访问的唯一入口，按序拒绝：
+## Problem It Solves
 
-1. 输入分级（`classifyPathInput`，纯函数可测）：拒绝绝对路径、Windows 盘符/UNC 路径、POSIX 上的反斜杠路径、空输入、NUL 字节。
-2. 词法收容：`path.resolve` 后离开根 → `path-traversal`。
-3. 符号链接逃逸：末位组件是指向根外的符号链接（或断链）→ `symlink-escape`。
-4. 真实路径逃逸：任一中间符号链接链的规范化结果离开根 → `realpath-escape`。
+Contracts defines "what should be", and the Harness turns that into "can be safely reused" mechanisms at the Node runtime. If multiple skill-family projects each implement path containment, atomic writes, resource closure, report rendering, host integration, and the state base independently, you get inconsistent security boundaries and behavioral drift. The Harness consolidates these business-neutral mechanisms into one default implementation, which callers pick up as needed.
 
-比较是基于 `realpath` 之后的规范根，避免 macOS `/var → /private/var` 一类系统级符号链接造成误判。
+## Core Mental Model
 
-## 测试
+The Harness consumes `skill-family-contracts` (a workspace dependency), reusing its dialect-routed Ajv validator, Kernel Protocol, frozen error codes, and fixtures; it does not copy protocol definitions or re-interpret the Schema. It only implements mechanisms: Schema validation, atomic writes, path containment, temporary workspaces, resource closure, the operation-request → operation-result pipeline, and business-neutral event logging with derived snapshots. Explicitly excluded: business semantics, task orchestration, Git writes, model calls, remote networking, and publish state. See `HARNESS_EXCLUSIONS`.
 
-`node --test` 覆盖：Contracts fixture 全量回放、安全反例、原子性失败路径、临时工作区、闭包确定性、报告事实绑定与 Markdown 注入、宿主 manifest/路径/命令信任，以及状态存储的崩溃、并发、损坏、fencing、显式恢复、symlink、硬链接与 FIFO 反例。
-
-## 安装
+## Installation and Minimal Example
 
 ```sh
-npm install skill-family-harness-node@0.2.0
+npm install skill-family-harness-node@0.3.0
 npm info skill-family-harness-node --help
 ```
 
-## 最小示例
+The minimal example shows validating a contract document inside Node:
 
 ```js
-// 从空目录运行：npm install skill-family-harness-node@0.2.0
+// Run from an empty directory: npm install skill-family-harness-node@0.3.0
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {
@@ -89,6 +64,160 @@ const result = validateContractDocument(document, {
 if (!result.valid) console.error(result.errorCode);
 ```
 
-## 故障诊断
+The code above shows the basic `validateContractDocument` call; it reuses the Contracts validator and caches instances keyed by schema, without recompiling.
+
+## Candidate Quickstart Profile
+
+Use the candidate subpath to construct an observation-backed Task, wrap its terminal Result, and verify that both documents bind the exact observation bytes and correlation fields:
+
+```js
+import {
+  createQuickstartTask,
+  wrapQuickstartResult,
+  verifyQuickstartExchange,
+} from "skill-family-harness-node/candidate/quickstart-profile";
+```
+
+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.3.0` for v2; integrations that still produce candidate v1 exchanges must stay pinned to exactly `0.2.1`.
+
+## Typical Use Cases
+
+- Need to safely read/write contained paths inside Node: use path containment and atomic write.
+- Need to normalize resources into a recomputable closure or generate a digest: use resource closure.
+- Need to generate a human report from a machine result: use report model/render/binding/check.
+- Need to persist an event log with derived snapshots: use state-store (event meaning is owned by the caller).
+
+## Boundaries
+
+- Consumes `skill-family-contracts`, reusing its dialect-routed Ajv validator, Kernel Protocol, frozen error codes, and fixtures; does not copy protocol definitions or re-interpret the Schema.
+- Only implements mechanisms: Schema validation, atomic writes, path containment, temporary workspaces, resource closure, the operation-request → operation-result pipeline, and business-neutral event logging with derived snapshots.
+- Explicitly excluded: business semantics, task orchestration, Git writes, model calls, remote networking, and publish state. See `HARNESS_EXCLUSIONS`.
+
+## Public API
+
+| Export | Responsibility |
+| --- | --- |
+| `HARNESS_CAPABILITIES` / `HARNESS_EXCLUSIONS` | Capability and exclusion lists (frozen constants). |
+| `HarnessError` / `HARNESS_ERROR_KINDS` / `mechanismError` | Mechanism failures uniformly carry the registered error code `SFC2004`; `details.kind` gives a stable subcategory. |
+| `validateContractDocument` / `getValidator` / `resolveSchemaContext` / `validatorCacheSize` | Routes and caches validators by Schema dialect; reuses Contracts' Ajv instances and dialect/policy semantics. |
+| `classifyPathInput` / `resolveContained` / `readFileContained` | Path containment: intercepts path overruns, symlink escapes, and realpath escapes. |
+| `writeFileAtomic` | Atomic write: leaves no half-written artifact on failure (temp file + fsync + rename). |
+| `TemporaryWorkspace` / `createTemporaryWorkspace` / `withTemporaryWorkspace` | Auto-cleanup temporary workspace, cleaned up even on exception paths. |
+| `digestBytes` / `computeResourceClosure` / `closureContains` | Resource closure and deterministic sha256 digest. |
+| `parseRequest` / `processRequest` | Parse `operation-request`, output terminal `operation-result`. |
+| `validateReportModel` / `renderReportMarkdown` / `buildBinding` / `checkReport` | Consume a Contracts-validated report model, deterministically render neutral Markdown, and verify source/result/report binding; does not interpret business output. |
+| `normalizeAdapterSource` / `buildAdapterClosure` / `verifyAdapterBuildManifest` / `materializeAdapterBuild` | Generic text-source closure, full-manifest digest re-verification, and atomic landing of the target set; specific Profile/driver is not in the Harness. |
+| `probeVersionVector` | A version-probe mechanism that disables spawn by default; when explicitly enabled, executes only absolute, symlink-free, audited vectors, using no PATH/shell. |
+| `openStateStore` / `appendEvent` / `readEvents` / `verifyStateStore` / `closeStateStore` | Strict single-writer append-only event store; the event directory is the sole state authority, `chain-head.json` is only a cache. |
+| `readSnapshot` / `writeSnapshot` / `rebuildSnapshot` | Atomic derived snapshots and full-event rebuild; a bad event cannot be masked by an old snapshot, and a bad snapshot can be ignored by rebuild. |
+| `inspectStateStoreLock` / `recoverStateStoreLock` | Read-only lock diagnostics and explicit recovery; recovery must precisely match the observed owner + fencing. |
+
+## State Store Lock and Recovery Boundaries
+
+- The lock uses exclusive create; a second writer immediately receives `store-locked`; it does not queue, nor steals the lock by time, PID, or lease expiry.
+- `inspectStateStoreLock` creates no file, only returns `owner`, monotonic `fencing`, `ageMs`, and an in-recovery flag. `ageMs` is for diagnostics only and never participates in correctness decisions.
+- A crash-left lock can only be recovered by the caller, after confirming outside Foundation that the old writer has terminated, by calling `recoverStateStoreLock` while submitting the precisely matching `expectedOwner`, `expectedFencing`, and `confirmOwnerTerminated: true`. A mismatch or missing confirmation fails closed.
+- Recovery produces a larger fencing. The old handle re-checks owner, fencing, and acquisition id on every append; final event publication uses a same-directory temporary regular file, fsync, and exclusive link, never overwriting an existing sequence.
+- Append, snapshot, close, and recovery are serialized by a short-lived `writer-mutation.lock`; recovery cannot cross an authoritative write that already holds the mutation guard.
+- If the recovering process itself crashes while holding `writer-recovery.lock`, the system stays in a diagnosable deadlock state and does not auto-delete that guard. It requires fresh external forensics and manual handling; the current API does not claim to solve the scenario where an untrusted caller falsely reports "old writer terminated".
+- The state root, `events/`, `snapshots/`, events, and snapshots reject symlinks, hard links, FIFOs, devices, and other non-regular entries. Payload must be pure JSON, and `eventType + payloadSchemaVersion` must hit the Schema pair frozen by the caller at open/recover.
+
+## Stable Error Codes
+
+All reuse the Contracts frozen registry; no unregistered codes are added. Mechanism failures are uniformly `SFC2004` (EXECUTION_FAILED), and `details.kind` takes a stable value from `HARNESS_ERROR_KINDS`, such as `path-traversal`, `symlink-escape`, `realpath-escape`, `atomic-write-failed`, `missing-resource`, `workspace-disposed`.
+
+Adding an entirely new SFC code is a Contracts change (the registry is inside the contracts package) and is outside this package's write set; therefore the combination "`SFC2004` + stable `details.kind`" keeps external semantics stable.
+
+## Path Containment Model
+
+`resolveContained(root, rel)` is the single entry point for all filesystem access, rejecting in order:
+
+1. Input classification (`classifyPathInput`, a pure testable function): rejects absolute paths, Windows drive/UNC paths, backslash paths on POSIX, empty input, and NUL bytes.
+2. Lexical containment: after `path.resolve`, leaving the root → `path-traversal`.
+3. Symlink escape: the final component is a symlink (or dangling link) pointing outside the root → `symlink-escape`.
+4. Realpath escape: any intermediate symlink chain's normalized result leaves the root → `realpath-escape`.
+
+Comparison is based on the canonical root after `realpath`, avoiding misjudgment from system-level symlinks such as macOS `/var → /private/var`.
+
+## Testing
+
+`node --test` covers: full Contracts fixture replay, security negative cases, atomic-failure paths, temporary workspaces, closure determinism, report fact binding and Markdown injection, host manifest/path/command trust, and state-store crashes, concurrency, corruption, fencing, explicit recovery, symlinks, hard links, and FIFO negative cases.
+
+## Troubleshooting
+
+Mechanism failures uniformly throw `SFC2004` (EXECUTION_FAILED), with `details.kind` giving a stable subcategory (e.g., `path-traversal`, `atomic-write-failed`). If it fails, check that the root path is correct and the target file is not locked.
+
+## Further Documentation
+
+- Architecture boundaries and routing: [Architecture](https://ifoohoo.github.io/skill-family-engineering-kit/architecture/), [Agent architecture routing](https://ifoohoo.github.io/skill-family-engineering-kit/agents/architecture-routing/)
+- Capability catalog: [capability-catalog.json](https://ifoohoo.github.io/skill-family-engineering-kit/agents/capability-catalog.json)
+- Side-effect matrix: [Failure and side-effect matrix](https://ifoohoo.github.io/skill-family-engineering-kit/reference/failure-and-side-effect-matrix/)
+
+<!-- agent-quick-reference:start -->
+## Agent Quick Reference
+
+### Use when
+
+- You need to validate contracts inside Node, safely read/write contained paths, compute resource closures, or render deterministic reports.
+- You need to persist an event log with derived snapshots, or normalize host adapter sources.
+- You need to trial the non-stable Quickstart exchange and verify its observation/task/result binding.
+
+### Do not use when
+
+- You need to put file-selection business rules into the Foundation (business rules are owned by the caller).
+- You need host apply/install/update/uninstall, a full Qoder driver, or binary adapter source (explicitly unsupported).
+- You need domain audit semantics, retry orchestration, or a compatibility-frozen Quickstart API.
+
+### Capability selection
+
+- `foundation.harness.contract-validation`: contract validation and validator caching inside Node.
+- `foundation.harness.path-containment`: path classification and contained resolution, rejecting the three escape types.
+- `foundation.harness.atomic-write`: atomic write within contained paths, rolling back on failure.
+- `foundation.harness.temporary-workspace`: auto-cleanup temporary workspace.
+- `foundation.harness.resource-closure`: deterministic resource closure and sha256 digest.
+- `foundation.harness.request-processing`: operation-request → terminal operation-result.
+- `foundation.harness.report`: report-model validation/render/binding/check.
+- `foundation.harness.host-adapter`: adapter source closure/build/materialize and version probe.
+- `foundation.harness.state-store`: append-only events, hash chain, snapshots, and lock recovery.
+- `foundation.harness.errors`: mechanism error types and stable error classes.
+- `foundation.harness.quickstart-profile-candidate`: exact-version observation/task/result construction and binding verification.
+
+### Required inputs
+
+- The contained root directory (the boundary for path containment).
+- The document, resource, or event payload to validate/write.
+
+### Outputs and evidence
+
+- Validation result, contained absolute path, atomically written file, closure digest, terminal result, report text, events/snapshots.
+- Evidence: `packages/skill-family-harness-node/test/validation.test.mjs`, `atomic.test.mjs`, `containment.test.mjs`, `closure.test.mjs`, `report.test.mjs`, `state-store.test.mjs`.
+
+### Side effects
+
+- Read-only filesystem access (path/atomic/workspace/state-store read and write within contained paths).
+- `HARNESS_EXCLUSIONS` explicitly excludes release-state, remote-network-access, business-semantics, workflow-orchestration, model-calls, git-writes.
+
+### Failure semantics
+
+- Mechanism failures are uniformly `SFC2004`, with `details.kind` as a stable subcategory (e.g., `path-traversal`, `atomic-write-failed`).
+- Residual state after failure: atomic write rolls back the temp file; a broken state-store hash chain throws, and old snapshots can be ignored by rebuild.
+
+### Architectural invariants
+
+- Event meaning and reducer transitions remain consumer-owned; state-store only provides the base.
+- Only text adapter source (utf8) is supported; binary projection is not supported.
+
+### Route elsewhere when
+
+- Business state machine / terminal states: route to loop-agent.
+- Host apply: explicitly unsupported.
+- Domain audit semantics: route to a standalone audit consumer.
+
+### Machine-readable sources
 
-机制失败统一抛出 `SFC2004`（EXECUTION_FAILED），`details.kind` 给出稳定细分（如 `path-traversal`、`atomic-write-failed`）。如失败，检查 root 路径是否正确且目标文件未被锁定。
+- Public capability catalog: [`capability-catalog.json`](https://ifoohoo.github.io/skill-family-engineering-kit/agents/capability-catalog.json) (`foundation.harness.*` entries).
+- Package-local source: `src/*.mjs`.
+- Package-local candidate source: `candidate/quickstart-profile.mjs`; public import: `skill-family-harness-node/candidate/quickstart-profile`.
+<!-- agent-quick-reference:end -->

package/README.zh-CN.md

@@ -0,0 +1,224 @@
+<!-- release-skill:safe-first-command -->
+<!-- release-skill:external-write-boundary -->
+
+> English version: [README.md](./README.md)
+
+# skill-family-harness-node
+
+<!-- release-skill:release-version: 0.3.0 -->
+
+Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
+
+<!-- release-skill:managed:start id=latest-release -->
+**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:managed:end id=latest-release -->
+
+## 解决的问题
+
+Contracts 定义了「应当如何」，Harness 把它在 Node 运行时变成「可以安全复用」的机制。多个技能族项目如果各自实现路径收容、原子写、资源闭包、报告渲染、宿主接入与状态底座，会出现安全边界不一致、行为漂移。Harness 把这些业务中立机制收口成一份默认实现，调用方按需取用。
+
+## 核心心智模型
+
+Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言路由的 Ajv validator、Kernel Protocol、冻结错误码与 fixture；不复制协议定义，不重新解释 Schema。它只实现机制：Schema 校验、原子写、路径收容、临时工作区、资源闭包、operation-request → operation-result 管道、业务中立的事件日志与派生快照。明确排除：业务语义、任务编排、Git 写入、模型调用、远程网络、发布状态。见 `HARNESS_EXCLUSIONS`。
+
+## 安装和最小示例
+
+```sh
+npm install skill-family-harness-node@0.3.0
+npm info skill-family-harness-node --help
+```
+
+最小示例演示在 Node 内校验一份契约文档：
+
+```js
+// 从空目录运行：npm install skill-family-harness-node@0.3.0
+import { validateContractDocument } from "skill-family-harness-node";
+
+const document = {
+  schemaVersion: 1,
+  kind: "skill-family.project-manifest",
+  project: { id: "my-project", name: "My Project", description: "Example" },
+  contracts: { version: "1.0.0", profile: "generic" },
+  managedFiles: ["package.json"],
+  updatedAt: "2026-01-01T00:00:00Z",
+};
+
+const result = validateContractDocument(document, {
+  schemaId: "https://contracts.skill-family.example/v1/project-manifest.json",
+});
+if (!result.valid) console.error(result.errorCode);
+```
+
+以上代码展示了 `validateContractDocument` 的基本调用；它复用 Contracts 的校验器并以 schema 为键缓存实例，不重新编译。
+
+## Candidate Quickstart Profile
+
+需要构造带 observation 绑定的 Task、封装终态 Result，并复验两个文档是否绑定精确 observation 字节与 correlation 字段时，使用 candidate 子路径：
+
+```js
+import {
+  createQuickstartTask,
+  wrapQuickstartResult,
+  verifyQuickstartExchange,
+} from "skill-family-harness-node/candidate/quickstart-profile";
+```
+
+v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字节摘要，并拒绝重复 Resource id、correlation 漂移、Task digest 变化，以及缺失或错配的 evidence binding。它不执行领域审计，不选择 method，不编排重试，也不拥有生命周期状态。
+
+该子路径公开但**不稳定**，后续小版本可以修改或移除。使用 v2 时应精确锁定 `0.3.0`；仍生产 candidate v1 交换的接入必须继续精确锁定 `0.2.1`。
+
+## 典型使用场景
+
+- 需要在 Node 内安全地读/写受收容路径：用 path containment 与 atomic write。
+- 需要把资源归一成可复算闭包或生成摘要：用 resource closure。
+- 需要从机器结果生成人类报告：用 report model/render/binding/check。
+- 需要持久化事件日志与派生快照：用 state-store（事件含义由调用方拥有）。
+
+## 边界
+
+- 消费 `skill-family-contracts`，复用其方言路由的 Ajv validator、Kernel Protocol、冻结错误码与 fixture；不复制协议定义，不重新解释 Schema。
+- 只实现机制：Schema 校验、原子写、路径收容、临时工作区、资源闭包、operation-request → operation-result 管道、业务中立的事件日志与派生快照。
+- 明确排除：业务语义、任务编排、Git 写入、模型调用、远程网络、发布状态。见 `HARNESS_EXCLUSIONS`。
+
+## 公共 API
+
+| 导出 | 职责 |
+| --- | --- |
+| `HARNESS_CAPABILITIES` / `HARNESS_EXCLUSIONS` | 能力与排除清单（冻结常量）。 |
+| `HarnessError` / `HARNESS_ERROR_KINDS` / `mechanismError` | 机制失败统一携带注册错误码 `SFC2004`，`details.kind` 给出稳定细分。 |
+| `validateContractDocument` / `getValidator` / `resolveSchemaContext` / `validatorCacheSize` | 按 Schema 方言路由并缓存 validator；复用 Contracts 的 Ajv 实例与 dialect/policy 语义。 |
+| `classifyPathInput` / `resolveContained` / `readFileContained` | 路径收容：拦截路径越界、符号链接逃逸、真实路径逃逸。 |
+| `writeFileAtomic` | 原子写：失败不留半成品（临时文件 + fsync + rename）。 |
+| `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 对。
+
+## 稳定错误码
+
+全部复用 Contracts 冻结登记表，不新增未登记码。机制失败统一为 `SFC2004`（EXECUTION_FAILED），`details.kind` 取 `HARNESS_ERROR_KINDS` 中的稳定值，例如 `path-traversal`、`symlink-escape`、`realpath-escape`、`atomic-write-failed`、`missing-resource`、`workspace-disposed`。
+
+新增一个全新的 SFC 码属于 Contracts 变更（登记表在 contracts 包内），超出本包写集；因此用「`SFC2004` + 稳定 `details.kind`」组合保持对外语义稳定。
+
+## 路径收容模型
+
+`resolveContained(root, rel)` 是所有文件系统访问的唯一入口，按序拒绝：
+
+1. 输入分级（`classifyPathInput`，纯函数可测）：拒绝绝对路径、Windows 盘符/UNC 路径、POSIX 上的反斜杠路径、空输入、NUL 字节。
+2. 词法收容：`path.resolve` 后离开根 → `path-traversal`。
+3. 符号链接逃逸：末位组件是指向根外的符号链接（或断链）→ `symlink-escape`。
+4. 真实路径逃逸：任一中间符号链接链的规范化结果离开根 → `realpath-escape`。
+
+比较是基于 `realpath` 之后的规范根，避免 macOS `/var → /private/var` 一类系统级符号链接造成误判。
+
+## 测试
+
+`node --test` 覆盖：Contracts fixture 全量回放、安全反例、原子性失败路径、临时工作区、闭包确定性、报告事实绑定与 Markdown 注入、宿主 manifest/路径/命令信任，以及状态存储的崩溃、并发、损坏、fencing、显式恢复、symlink、硬链接与 FIFO 反例。
+
+## 故障诊断
+
+机制失败统一抛出 `SFC2004`（EXECUTION_FAILED），`details.kind` 给出稳定细分（如 `path-traversal`、`atomic-write-failed`）。如失败，检查 root 路径是否正确且目标文件未被锁定。
+
+## 深入文档入口
+
+- 架构边界与路由：[架构说明](https://ifoohoo.github.io/skill-family-engineering-kit/architecture/)、[智能体架构路由](https://ifoohoo.github.io/skill-family-engineering-kit/agents/architecture-routing/)
+- 能力目录：[capability-catalog.json](https://ifoohoo.github.io/skill-family-engineering-kit/agents/capability-catalog.json)
+- 副作用矩阵：[失败与副作用矩阵](https://ifoohoo.github.io/skill-family-engineering-kit/reference/failure-and-side-effect-matrix/)
+
+<!-- agent-quick-reference:start -->
+## Agent Quick Reference
+
+### Use when
+
+- 需要在 Node 内校验契约、安全读写受收容路径、计算资源闭包、渲染确定性报告。
+- 需要持久化事件日志与派生快照，或归一化宿主适配源。
+- 需要试用非稳定 Quickstart 交换，并复验 observation/task/result 绑定。
+
+### Do not use when
+
+- 需要把文件选择的业务规则放入 Foundation（业务规则由调用方拥有）。
+- 需要 host apply/install/update/uninstall、Qoder 完整 driver 或二进制 adapter source（明确 unsupported）。
+- 需要领域审计语义、重试编排或兼容性已冻结的 Quickstart API。
+
+### Capability selection
+
+- `foundation.harness.contract-validation`：Node 内契约校验与校验器缓存。
+- `foundation.harness.path-containment`：路径分类与受收容解析，拒绝三类逃逸。
+- `foundation.harness.atomic-write`：受收容路径内原子写，失败回滚。
+- `foundation.harness.temporary-workspace`：自动清理的临时工作区。
+- `foundation.harness.resource-closure`：确定性资源闭包与 sha256 摘要。
+- `foundation.harness.request-processing`：operation-request → 终态 operation-result。
+- `foundation.harness.report`：report-model 校验/渲染/绑定/检查。
+- `foundation.harness.host-adapter`：adapter source closure/build/materialize 与版本探测。
+- `foundation.harness.state-store`：append-only 事件、hash chain、快照与锁恢复。
+- `foundation.harness.errors`：机制错误类型与稳定错误类。
+- `foundation.harness.quickstart-profile-candidate`：锁定精确版本后构造 observation/task/result 并复验绑定。
+
+### Required inputs
+
+- 受收容根目录（路径收容的边界）。
+- 待校验/待写入的文档、资源或事件负载。
+
+### Outputs and evidence
+
+- 校验结果、受收容绝对路径、原子写文件、闭包摘要、终态结果、报告文本、事件/快照。
+- 证据：`packages/skill-family-harness-node/test/validation.test.mjs`、`atomic.test.mjs`、`containment.test.mjs`、`closure.test.mjs`、`report.test.mjs`、`state-store.test.mjs`。
+
+### Side effects
+
+- 只读文件系统访问（path/atomic/workspace/state-store 在受收容路径内读写）。
+- `HARNESS_EXCLUSIONS` 明确排除 release-state、remote-network-access、business-semantics、workflow-orchestration、model-calls、git-writes。
+
+### Failure semantics
+
+- 机制失败统一 `SFC2004`，`details.kind` 为稳定细分（如 `path-traversal`、`atomic-write-failed`）。
+- 失败后残余状态：原子写回滚临时文件；状态存储链断裂抛错，旧快照可被重建忽略。
+
+### Architectural invariants
+
+- Event meaning and reducer transitions remain consumer-owned；state-store 只提供底座。
+- 仅支持文本 adapter source（utf8），不支持二进制投影。
+
+### Route elsewhere when
+
+- 业务状态机/终态：转 loop-agent。
+- 宿主 apply：明确 unsupported。
+- 领域审计语义：转独立审计消费者。
+
+### Machine-readable sources
+
+- 公开能力目录：[`capability-catalog.json`](https://ifoohoo.github.io/skill-family-engineering-kit/agents/capability-catalog.json)（`foundation.harness.*` 条目）。
+- 包内源：`src/*.mjs`。
+- 包内 Candidate 源：`candidate/quickstart-profile.mjs`；公共导入：`skill-family-harness-node/candidate/quickstart-profile`。
+<!-- agent-quick-reference:end -->

package/candidate/mechanisms-cli.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { stdin, stdout, stderr } from "node:process";
+import {
+  canonicalJson,
+  computeResourceClosure,
+  digestDocument,
+} from "./quickstart-profile.mjs";
+
+async function readRequest() {
+  const chunks = [];
+  for await (const chunk of stdin) chunks.push(chunk);
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+export async function runMechanismCli() {
+  try {
+    const request = await readRequest();
+    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,
+      });
+    } else {
+      throw new TypeError(`unknown Foundation mechanism: ${String(request.operation)}`);
+    }
+    stdout.write(`${JSON.stringify(result)}\n`);
+    return 0;
+  } catch (cause) {
+    stderr.write(`${cause?.message ?? String(cause)}\n`);
+    return 2;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exitCode = await runMechanismCli();
+}

package/candidate/quickstart-profile.mjs

@@ -0,0 +1,485 @@
+import { canonicalJson, digestDocument, isRegisteredErrorCode } from "skill-family-contracts";
+import {
+  QUICKSTART_PROTOCOL,
+  findNonJsonValue,
+  validateQuickstartProfileDocument,
+} from "skill-family-contracts/candidate/quickstart-profile";
+import { computeResourceClosure, digestBytes } from "../src/closure.mjs";
+import { HARNESS_ERROR_KINDS, HarnessError, mechanismError } from "../src/errors.mjs";
+
+/**
+ * Candidate quickstart profile v2 mechanisms (unstable).
+ *
+ * The harness only interprets mechanism constraints: contained reads, real
+ * byte digests, profile validation, and per-field Task/Result binding. The
+ * single operation is the business-neutral execute-method; params.method,
+ * params.parameters, and domainResult are caller-owned and never read here.
+ */
+
+const QUICKSTART_OPERATION = "execute-method";
+const RESULT_STATES = Object.freeze(["succeeded", "failed", "rejected"]);
+const CORRELATION_FIELDS = Object.freeze(["run", "stage", "attempt"]);
+const ERROR_ENTRY_FIELDS = new Set(["code", "message", "path", "details"]);
+
+function invalidProfile(kind, outcome) {
+  return mechanismError(
+    HARNESS_ERROR_KINDS.INVALID_RESULT,
+    `quickstart ${kind} violates the Foundation candidate profile`,
+    { category: "profile", profileKind: kind, findings: outcome.errors },
+  );
+}
+
+function assertProfile(kind, document) {
+  const outcome = validateQuickstartProfileDocument(kind, document);
+  if (!outcome.valid) throw invalidProfile(kind, outcome);
+  return outcome.data;
+}
+
+/**
+ * Caller-owned values must be pure JSON before they enter any Task or
+ * Result: this refuses BigInt and friends before structuredClone,
+ * digestDocument, or JSON.stringify could throw or silently drift.
+ */
+function assertJsonValue(caller, label, value) {
+  const issue = findNonJsonValue(value);
+  if (issue) {
+    throw new TypeError(
+      `${caller}: ${label} must be a JSON value; found ${issue.reason}` +
+        (issue.instancePath ? ` at ${issue.instancePath}` : ""),
+    );
+  }
+}
+
+function containedPath(resource, roleDescription) {
+  const relPath = resource?.location?.path;
+  if (typeof relPath !== "string") {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.INVALID_RESULT,
+      `the quickstart ${roleDescription} Resource must use a contained relative path`,
+      { category: "resource-location", resourceId: resource?.id },
+    );
+  }
+  return relPath;
+}
+
+/** Create one observation Resource from the actual contained file bytes. */
+export async function createObservationResource({ root, path, id = "observation" } = {}) {
+  const closure = await computeResourceClosure({
+    root,
+    resources: [{ path, role: "input" }],
+  });
+  const record = closure.resources[0];
+  const resource = {
+    schemaVersion: 1,
+    kind: "skill-family.resource",
+    id,
+    location: { path: record.path },
+    role: "observation",
+    digest: { algorithm: "sha256", value: record.sha256 },
+  };
+  return assertProfile("resource", resource);
+}
+
+/**
+ * Recomputes the real byte digest of one path-backed Resource and compares it
+ * with the declared digest. URI-backed Resources are structurally checked
+ * only: Foundation never fetches URIs.
+ */
+export async function verifyResourceBytes({ root, resource } = {}) {
+  const normalized = assertProfile("resource", resource);
+  const relPath = normalized.location.path;
+  if (typeof relPath !== "string") {
+    return { resource: normalized, byteDigest: null };
+  }
+  const closure = await computeResourceClosure({
+    root,
+    resources: [{ path: relPath, role: "input" }],
+  });
+  const actual = closure.resources[0].sha256;
+  if (actual !== normalized.digest.value) {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.INVALID_RESULT,
+      `quickstart ${normalized.role} Resource digest does not match its current bytes`,
+      {
+        category: "resource-bytes",
+        role: normalized.role,
+        resourceId: normalized.id,
+        expected: normalized.digest.value,
+        actual,
+      },
+    );
+  }
+  return { resource: normalized, byteDigest: actual };
+}
+
+/** Verify the single observation Resource: role, path-backed location, bytes. */
+export async function verifyObservationResource({ root, resource } = {}) {
+  const normalized = assertProfile("resource", resource);
+  if (normalized.role !== "observation") {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.INVALID_RESULT,
+      "quickstart task input must have the observation role",
+      { category: "resource-role", resourceId: normalized.id, role: normalized.role },
+    );
+  }
+  containedPath(normalized, "observation");
+  const { byteDigest } = await verifyResourceBytes({ root, resource: normalized });
+  return { resource: normalized, byteDigest };
+}
+
+/** Build a candidate v2 Task inside the stable operation-request envelope. */
+export async function createQuickstartTask({
+  root,
+  observationPath,
+  observationId = "observation",
+  operationId,
+  method,
+  parameters = {},
+  run,
+  stage,
+  attempt,
+} = {}) {
+  assertJsonValue("createQuickstartTask", "parameters", parameters);
+  const observation = await createObservationResource({
+    root,
+    path: observationPath,
+    id: observationId,
+  });
+  const task = {
+    schemaVersion: 1,
+    kind: "skill-family.operation-request",
+    protocol: { ...QUICKSTART_PROTOCOL },
+    operationId,
+    operation: QUICKSTART_OPERATION,
+    params: {
+      method,
+      parameters: structuredClone(parameters),
+      inputs: [observation],
+      correlation: { run, stage, attempt },
+    },
+  };
+  return assertProfile("task", task);
+}
+
+function normalizeErrorEntries(errors) {
+  if (!Array.isArray(errors) || errors.length === 0) {
+    throw new TypeError(
+      "wrapQuickstartResult: failed and rejected results require at least one error entry",
+    );
+  }
+  assertJsonValue("wrapQuickstartResult", "errors", errors);
+  return errors.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new TypeError(`wrapQuickstartResult: error entry ${index} must be an object`);
+    }
+    const extraField = Object.keys(entry).find((field) => !ERROR_ENTRY_FIELDS.has(field));
+    if (extraField !== undefined) {
+      throw new TypeError(
+        `wrapQuickstartResult: error entry ${index} has unsupported field ${extraField}`,
+      );
+    }
+    const { code, message, path, details } = entry;
+    if (typeof code !== "string" || !isRegisteredErrorCode(code)) {
+      throw new TypeError(
+        `wrapQuickstartResult: error entry ${index} code must be registered in the frozen contracts error registry`,
+      );
+    }
+    if (typeof message !== "string" || message.length === 0) {
+      throw new TypeError(
+        `wrapQuickstartResult: error entry ${index} must carry a non-empty message`,
+      );
+    }
+    if (path !== undefined) {
+      assertJsonValue("wrapQuickstartResult", `error entry ${index} path`, path);
+    }
+    if (details !== undefined) {
+      assertJsonValue("wrapQuickstartResult", `error entry ${index} details`, details);
+    }
+    const normalized = { code, message };
+    if (path !== undefined) normalized.path = path;
+    if (details !== undefined) normalized.details = structuredClone(details);
+    return normalized;
+  });
+}
+
+/**
+ * Wrap one terminal Result for the candidate protocol. succeeded builds the
+ * full outputs envelope (summary, outputs, evidence, domainResult,
+ * taskBinding with exactly one evidenceBindings entry per evidence
+ * Resource); failed and rejected always carry null outputs and at least one
+ * registry-registered error.
+ */
+export function wrapQuickstartResult({
+  task,
+  state = "succeeded",
+  summary,
+  outputs = [],
+  evidence = [],
+  domainResult,
+  errors,
+} = {}) {
+  const normalizedTask = assertProfile("task", task);
+  if (!RESULT_STATES.includes(state)) {
+    throw new TypeError(
+      `wrapQuickstartResult: state must be one of ${RESULT_STATES.join(", ")}`,
+    );
+  }
+  const observation = normalizedTask.params.inputs[0];
+  const base = {
+    schemaVersion: 1,
+    kind: "skill-family.operation-result",
+    protocol: structuredClone(normalizedTask.protocol),
+    operationId: normalizedTask.operationId,
+    operation: normalizedTask.operation,
+    state,
+  };
+  if (state !== "succeeded") {
+    for (const [name, value] of [
+      ["summary", summary],
+      ["outputs", outputs],
+      ["evidence", evidence],
+      ["domainResult", domainResult],
+    ]) {
+      const untouched =
+        (name === "outputs" || name === "evidence") && Array.isArray(value) && value.length === 0;
+      if (!untouched && value !== undefined) {
+        throw new TypeError(
+          `wrapQuickstartResult: ${state} results never carry ${name}; outputs must be null`,
+        );
+      }
+    }
+    return assertProfile("result", {
+      ...base,
+      outputs: null,
+      errors: normalizeErrorEntries(errors),
+    });
+  }
+  if (typeof summary !== "string" || summary.length === 0) {
+    throw new TypeError("wrapQuickstartResult: succeeded results require a non-empty summary");
+  }
+  assertJsonValue("wrapQuickstartResult", "outputs", outputs);
+  assertJsonValue("wrapQuickstartResult", "evidence", evidence);
+  assertJsonValue("wrapQuickstartResult", "domainResult", domainResult);
+  const normalizedEvidence = structuredClone(evidence);
+  const correlation = structuredClone(normalizedTask.params.correlation);
+  return assertProfile("result", {
+    ...base,
+    outputs: {
+      summary,
+      outputs: structuredClone(outputs),
+      evidence: normalizedEvidence,
+      domainResult: structuredClone(domainResult),
+      taskBinding: {
+        operationId: normalizedTask.operationId,
+        taskDigest: digestDocument(normalizedTask),
+        observationId: observation.id,
+        observationDigest: observation.digest.value,
+        correlation,
+        evidenceBindings: normalizedEvidence.map((resource) => ({
+          resourceId: resource?.id,
+          operationId: normalizedTask.operationId,
+          observationId: observation.id,
+          correlation: structuredClone(correlation),
+        })),
+      },
+    },
+    errors: [],
+  });
+}
+
+/**
+ * Per-field correlation comparison: run, stage, and attempt mismatches are
+ * reported as distinguishable paths instead of one opaque binding mismatch.
+ */
+function correlationMismatches(actual, expected, prefix) {
+  const mismatches = [];
+  for (const field of CORRELATION_FIELDS) {
+    if (actual[field] !== expected[field]) mismatches.push(`${prefix}.${field}`);
+  }
+  return mismatches;
+}
+
+/**
+ * Cross-checks taskBinding.evidenceBindings against the declared evidence
+ * Resources: exactly one entry per evidence Resource id, each echoing the
+ * exact operationId, observationId, and run/stage/attempt of this Task.
+ */
+function evidenceBindingMismatches(bindings, evidenceResources, normalizedTask, observation) {
+  const mismatches = [];
+  const evidenceIds = new Set(evidenceResources.map((resource) => resource.id));
+  const bound = new Set();
+  bindings.forEach((entry, index) => {
+    const { resourceId } = entry;
+    if (!evidenceIds.has(resourceId)) {
+      mismatches.push(`binding.evidenceBindings.extra:${resourceId}`);
+      return;
+    }
+    if (bound.has(resourceId)) {
+      mismatches.push(`binding.evidenceBindings.duplicate:${resourceId}`);
+      return;
+    }
+    bound.add(resourceId);
+    const prefix = `binding.evidenceBindings[${index}]`;
+    if (entry.operationId !== normalizedTask.operationId) {
+      mismatches.push(`${prefix}.operationId`);
+    }
+    if (entry.observationId !== observation.id) {
+      mismatches.push(`${prefix}.observationId`);
+    }
+    mismatches.push(
+      ...correlationMismatches(entry.correlation, normalizedTask.params.correlation, `${prefix}.correlation`),
+    );
+  });
+  for (const resourceId of [...evidenceIds].filter((id) => !bound.has(id)).sort()) {
+    mismatches.push(`binding.evidenceBindings.missing:${resourceId}`);
+  }
+  return mismatches;
+}
+
+/**
+ * Fail-closed exchange assertion. It validates both candidate profiles,
+ * refuses duplicate Resource ids across the Task observation and all
+ * output/evidence Resources, recomputes the real bytes of every path-backed
+ * Resource, and proves the result echoes and binds the exact
+ * protocol/operation/operationId/Task-digest/observation/correlation fields
+ * plus one evidenceBindings entry per evidence Resource. No retry or
+ * lifecycle state is introduced and no Result file is written.
+ */
+export async function assertQuickstartExchange({ root, task, result } = {}) {
+  const normalizedTask = assertProfile("task", task);
+  const normalizedResult = assertProfile("result", result);
+
+  const mismatches = [];
+  if (canonicalJson(normalizedResult.protocol) !== canonicalJson(normalizedTask.protocol)) {
+    mismatches.push("protocol");
+  }
+  if (normalizedResult.operation !== normalizedTask.operation) mismatches.push("operation");
+  if (normalizedResult.operationId !== normalizedTask.operationId) mismatches.push("operationId");
+
+  const observation = normalizedTask.params.inputs[0];
+  if (normalizedResult.state === "succeeded") {
+    const declared = [
+      observation,
+      ...normalizedResult.outputs.outputs,
+      ...normalizedResult.outputs.evidence,
+    ];
+    const seen = new Set();
+    for (const resource of declared) {
+      if (seen.has(resource.id)) {
+        throw mechanismError(
+          HARNESS_ERROR_KINDS.INVALID_RESULT,
+          `quickstart result declares a duplicate Resource id: ${resource.id}`,
+          { category: "duplicate-resource-id", resourceId: resource.id },
+        );
+      }
+      seen.add(resource.id);
+    }
+
+    const binding = normalizedResult.outputs?.taskBinding;
+    if (!binding) {
+      mismatches.push("taskBinding");
+    } else {
+      if (binding.operationId !== normalizedTask.operationId) {
+        mismatches.push("binding.operationId");
+      }
+      if (binding.taskDigest !== digestDocument(normalizedTask)) {
+        mismatches.push("binding.taskDigest");
+      }
+      if (binding.observationId !== observation.id) mismatches.push("binding.observationId");
+      if (binding.observationDigest !== observation.digest.value) {
+        mismatches.push("binding.observationDigest");
+      }
+      mismatches.push(
+        ...correlationMismatches(
+          binding.correlation,
+          normalizedTask.params.correlation,
+          "binding.correlation",
+        ),
+      );
+      mismatches.push(
+        ...evidenceBindingMismatches(
+          binding.evidenceBindings,
+          normalizedResult.outputs.evidence,
+          normalizedTask,
+          observation,
+        ),
+      );
+    }
+  }
+  if (mismatches.length > 0) {
+    throw mechanismError(
+      HARNESS_ERROR_KINDS.INVALID_RESULT,
+      `quickstart result does not bind the exact task: ${mismatches.join(", ")}`,
+      { category: "binding", mismatches },
+    );
+  }
+
+  await verifyObservationResource({ root, resource: observation });
+
+  if (normalizedResult.state === "succeeded") {
+    const declared = [
+      ...normalizedResult.outputs.outputs,
+      ...normalizedResult.outputs.evidence,
+    ];
+    for (const resource of declared) {
+      await verifyResourceBytes({ root, resource });
+    }
+  }
+
+  return {
+    valid: true,
+    state: normalizedResult.state,
+    taskDigest: digestDocument(normalizedTask),
+    observationDigest: observation.digest.value,
+  };
+}
+
+/**
+ * Non-throwing form for callers that need a structured finding. Every
+ * failure resolves to code SFC2004 with a deterministic string details.kind
+ * and details.category: HarnessError paths from the closure and containment
+ * machinery (missing-resource, path, symlink escapes) keep their stable kind
+ * and every useful detail field, ordinary TypeErrors and omitted inputs fall
+ * back to the invalid-result/unexpected-failure pair.
+ */
+export async function verifyQuickstartExchange(input) {
+  try {
+    return await assertQuickstartExchange(input);
+  } catch (cause) {
+    const message =
+      cause instanceof Error && typeof cause.message === "string" && cause.message.length > 0
+        ? cause.message
+        : String(cause);
+    if (cause instanceof HarnessError) {
+      const rawDetails =
+        cause.details && typeof cause.details === "object" ? cause.details : {};
+      const kind =
+        typeof rawDetails.kind === "string" && rawDetails.kind.length > 0
+          ? rawDetails.kind
+          : HARNESS_ERROR_KINDS.EXECUTION_FAILED;
+      const category =
+        typeof rawDetails.category === "string" && rawDetails.category.length > 0
+          ? rawDetails.category
+          : "resource-closure";
+      return {
+        valid: false,
+        code: "SFC2004",
+        message,
+        details: { ...rawDetails, kind, category },
+      };
+    }
+    return {
+      valid: false,
+      code: "SFC2004",
+      message,
+      details: {
+        kind: HARNESS_ERROR_KINDS.INVALID_RESULT,
+        category: "unexpected-failure",
+      },
+    };
+  }
+}
+
+// Candidate consumers may use these generic Foundation mechanisms directly.
+// They are thin exports of the stable implementations, not parallel algorithms.
+export { canonicalJson, computeResourceClosure, digestBytes, digestDocument };

package/package.json

@@ -5,15 +5,26 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node/issues"
   },
   "dependencies": {
-    "skill-family-contracts": "0.2.0"
+    "skill-family-contracts": "0.3.0"
   },
   "description": "Thin Node.js mechanism runtime for Skill Family engineering contracts.",
   "engines": {
-    "node": ">=22.22.2 <23"
+    "node": ">=22.22.2 <23",
+    "pnpm": "10.30.0"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./candidate/quickstart-profile": "./candidate/quickstart-profile.mjs"
   },
-  "exports": "./src/index.mjs",
   "files": [
     "src",
+    "candidate",
+    "release-notes",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "CHANGELOG.zh-CN.md",
+    "NOTICE",
     "SECURITY.md",
     "CONTRIBUTING.md",
     "CODE_OF_CONDUCT.md"
@@ -27,7 +38,7 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node.git"
   },
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "scripts": {
     "check": "node --test",
     "test": "node --test"

package/release-notes/0.2.1.yaml

@@ -0,0 +1,23 @@
+version: 0.2.1
+date: 2026-08-10
+locales:
+  en:
+    summary: This release adds candidate Quickstart Profile exchange helpers and makes the package release documentation available in English and Simplified Chinese.
+    changes:
+      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.
+      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.
+    upgradeNotes: The candidate helpers do not alter the stable Harness API or add lifecycle, retry, orchestration, model-call, network, or Git-write semantics.
+  zh-CN:
+    summary: 本版新增 Quickstart Profile 候选交换辅助函数，并为包发布文档提供完整英文版与简体中文版。
+    changes:
+      added:
+        - 新增候选辅助函数，用于创建并复验 observation Resource、构造 Task、封装 Result，并在 Result 未精确绑定 Task 与关联字段时失败关闭。
+        - 新增完整的英文与简体中文包文档，并补充智能体快速参考章节。
+      changed:
+        - 使用同一份双语版本化说明源管理当前 README 与 CHANGELOG 的发布区域。
+        - 项目 NOTICE 与 Apache-2.0 LICENSE 分开分发。
+    upgradeNotes: 候选辅助函数不改变稳定 Harness API，也不引入生命周期、重试、编排、模型调用、网络或 Git 写入语义。

package/release-notes/0.3.0.yaml

@@ -0,0 +1,23 @@
+version: 0.3.0
+date: 2026-08-12
+locales:
+  en:
+    summary: This source candidate updates the Quickstart Profile harness to verify v2 Task and Result exchanges without taking ownership of consumer semantics.
+    changes:
+      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.
+    upgradeNotes: 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.
+  zh-CN:
+    summary: 本源码候选版把 Quickstart Profile Harness 更新为 v2 Task/Result 交换校验，同时不接管消费者语义。
+    changes:
+      added:
+        - 对 path-backed output 与 evidence 重算真实字节摘要，并拒绝 observation、output、evidence 之间重复的 Resource id。
+        - 逐项复验 operation 身份、Task digest、run/stage/attempt 字段和 evidence 精确绑定集合。
+      changed:
+        - 替换与 0.2.1 不兼容的 candidate 面；仍依赖 v1 的消费者必须继续精确锁定 0.2.1。
+        - 方法选择、重试策略与领域结果解释继续归消费者所有。
+    upgradeNotes: 0.3.0 当前只是本地、未发布的源码候选。candidate 子路径必须精确锁定包版本，采用前需更新 v1 交换生产方。