skill-family-harness-node 0.2.1 → 0.3.0

package/CHANGELOG.md

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

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,26 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.3.0 locale=zh-CN baseline=sha256:b635e4170d3f7ac634e59f612939683ab04727f87101790d9a9f5613ea38fcfe -->
+## [0.3.0] - 2026-08-12
+
+本源码候选版把 Quickstart Profile Harness 更新为 v2 Task/Result 交换校验，同时不接管消费者语义。
+
+### 新增
+
+- 对 path-backed output 与 evidence 重算真实字节摘要，并拒绝 observation、output、evidence 之间重复的 Resource id。
+- 逐项复验 operation 身份、Task digest、run/stage/attempt 字段和 evidence 精确绑定集合。
+
+### 变更
+
+- 替换与 0.2.1 不兼容的 candidate 面；仍依赖 v1 的消费者必须继续精确锁定 0.2.1。
+- 方法选择、重试策略与领域结果解释继续归消费者所有。
+
+### 升级说明
+
+0.3.0 当前只是本地、未发布的源码候选。candidate 子路径必须精确锁定包版本，采用前需更新 v1 交换生产方。
+<!-- release-skill:changelog:end version=0.3.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.2.1 locale=zh-CN baseline=sha256:2f2c74ab9dcf0f1a84872743bf203eb43d15c5e722e823e670e8d81ca5f7de65 -->
 ## [0.2.1] - 2026-08-10
 

package/README.md

@@ -4,28 +4,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.2.1 -->
+<!-- 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.
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.2.1** (2026-08-10)
+**0.3.0** (2026-08-12)
 
-This release adds candidate Quickstart Profile exchange helpers and makes the package release documentation available in English and Simplified Chinese.
+This source candidate updates the Quickstart Profile harness to verify v2 Task and Result exchanges without taking ownership of consumer semantics.
 
 **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.
+- 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**
 
-- 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.
+- 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**
 
-The candidate helpers do not alter the stable Harness API or add lifecycle, retry, orchestration, model-call, network, or Git-write semantics.
+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 -->
 
 ## Problem It Solves
@@ -39,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.2.1
+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
-// Run from an empty directory: npm install skill-family-harness-node@0.2.1
+// Run from an empty directory: npm install skill-family-harness-node@0.3.0
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {
@@ -78,7 +78,9 @@ import {
 } from "skill-family-harness-node/candidate/quickstart-profile";
 ```
 
-This mechanism is intended for early integration trials of the candidate Contracts profile. It does not perform a domain audit, choose a method, retry work, or own lifecycle state. The subpath is public but **not stable** and may change or be removed in a later minor release; pin the exact package version and do not expose it through a stable consumer API.
+The v2 mechanism recomputes the bytes of every path-backed output and evidence Resource. It also rejects duplicate Resource ids, correlation drift, a changed Task digest, and incomplete or mismatched evidence bindings. It does not perform a domain audit, choose a method, retry work, or own lifecycle state.
+
+The subpath is public but **not stable** and may change or be removed in a later minor release. Pin exactly `0.3.0` for v2; integrations that still produce candidate v1 exchanges must stay pinned to exactly `0.2.1`.
 
 ## Typical Use Cases
 

package/README.zh-CN.md

@@ -5,28 +5,28 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.2.1 -->
+<!-- release-skill:release-version: 0.3.0 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.2.1** (2026-08-10)
+**0.3.0** (2026-08-12)
 
-本版新增 Quickstart Profile 候选交换辅助函数，并为包发布文档提供完整英文版与简体中文版。
+本源码候选版把 Quickstart Profile Harness 更新为 v2 Task/Result 交换校验，同时不接管消费者语义。
 
 **新增**
 
-- 新增候选辅助函数，用于创建并复验 observation Resource、构造 Task、封装 Result，并在 Result 未精确绑定 Task 与关联字段时失败关闭。
-- 新增完整的英文与简体中文包文档，并补充智能体快速参考章节。
+- 对 path-backed output 与 evidence 重算真实字节摘要，并拒绝 observation、output、evidence 之间重复的 Resource id。
+- 逐项复验 operation 身份、Task digest、run/stage/attempt 字段和 evidence 精确绑定集合。
 
 **变更**
 
-- 使用同一份双语版本化说明源管理当前 README 与 CHANGELOG 的发布区域。
-- 项目 NOTICE 与 Apache-2.0 LICENSE 分开分发。
+- 替换与 0.2.1 不兼容的 candidate 面；仍依赖 v1 的消费者必须继续精确锁定 0.2.1。
+- 方法选择、重试策略与领域结果解释继续归消费者所有。
 
 **升级说明**
 
-候选辅助函数不改变稳定 Harness API，也不引入生命周期、重试、编排、模型调用、网络或 Git 写入语义。
+0.3.0 当前只是本地、未发布的源码候选。candidate 子路径必须精确锁定包版本，采用前需更新 v1 交换生产方。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -40,14 +40,14 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 ## 安装和最小示例
 
 ```sh
-npm install skill-family-harness-node@0.2.1
+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.2.1
+// 从空目录运行：npm install skill-family-harness-node@0.3.0
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {
@@ -79,7 +79,9 @@ import {
 } from "skill-family-harness-node/candidate/quickstart-profile";
 ```
 
-以上机制用于 candidate Contracts Profile 的早期接入试验。它不执行领域审计，不选择 method，不编排重试，也不拥有生命周期状态。该子路径公开但**不稳定**，后续小版本可以修改或移除；调用方需要锁定精确包版本，并避免通过自身稳定 API 再导出。
+v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字节摘要，并拒绝重复 Resource id、correlation 漂移、Task digest 变化，以及缺失或错配的 evidence binding。它不执行领域审计，不选择 method，不编排重试，也不拥有生命周期状态。
+
+该子路径公开但**不稳定**，后续小版本可以修改或移除。使用 v2 时应精确锁定 `0.3.0`；仍生产 candidate v1 交换的接入必须继续精确锁定 `0.2.1`。
 
 ## 典型使用场景
 

package/candidate/quickstart-profile.mjs

@@ -1,16 +1,31 @@
-import { canonicalJson, digestDocument } from "skill-family-contracts";
+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, mechanismError } from "../src/errors.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`,
-    { profileKind: kind, findings: outcome.errors },
+    { category: "profile", profileKind: kind, findings: outcome.errors },
   );
 }
 
@@ -20,12 +35,28 @@ function assertProfile(kind, document) {
   return outcome.data;
 }
 
-function resourcePath(resource) {
+/**
+ * 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 observation Resource must use a contained relative path",
+      `the quickstart ${roleDescription} Resource must use a contained relative path`,
+      { category: "resource-location", resourceId: resource?.id },
     );
   }
   return relPath;
@@ -49,31 +80,54 @@ export async function createObservationResource({ root, path, id = "observation"
   return assertProfile("resource", resource);
 }
 
-/** Recompute and verify the single observation Resource digest. */
-export async function verifyObservationResource({ root, 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);
-  if (normalized.role !== "observation") {
-    throw mechanismError(
-      HARNESS_ERROR_KINDS.INVALID_RESULT,
-      "quickstart task input must have the observation role",
-    );
+  const relPath = normalized.location.path;
+  if (typeof relPath !== "string") {
+    return { resource: normalized, byteDigest: null };
   }
   const closure = await computeResourceClosure({
     root,
-    resources: [{ path: resourcePath(normalized), role: "input" }],
+    resources: [{ path: relPath, role: "input" }],
   });
   const actual = closure.resources[0].sha256;
   if (actual !== normalized.digest.value) {
     throw mechanismError(
       HARNESS_ERROR_KINDS.INVALID_RESULT,
-      "observation Resource digest does not match its current bytes",
-      { resourceId: normalized.id, expected: normalized.digest.value, actual },
+      `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, closureDigest: closure.digest };
+  return { resource: normalized, byteDigest: actual };
 }
 
-/** Build a candidate Task inside the existing operation-request envelope. */
+/** 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,
@@ -85,6 +139,7 @@ export async function createQuickstartTask({
   stage,
   attempt,
 } = {}) {
+  assertJsonValue("createQuickstartTask", "parameters", parameters);
   const observation = await createObservationResource({
     root,
     path: observationPath,
@@ -95,7 +150,7 @@ export async function createQuickstartTask({
     kind: "skill-family.operation-request",
     protocol: { ...QUICKSTART_PROTOCOL },
     operationId,
-    operation: "audit",
+    operation: QUICKSTART_OPERATION,
     params: {
       method,
       parameters: structuredClone(parameters),
@@ -106,7 +161,54 @@ export async function createQuickstartTask({
   return assertProfile("task", task);
 }
 
-/** Wrap a domain result inside the existing terminal operation-result envelope. */
+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",
@@ -114,94 +216,266 @@ export function wrapQuickstartResult({
   outputs = [],
   evidence = [],
   domainResult,
-  errors = [],
+  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 result = {
+  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: structuredClone(evidence),
+      evidence: normalizedEvidence,
       domainResult: structuredClone(domainResult),
       taskBinding: {
         operationId: normalizedTask.operationId,
         taskDigest: digestDocument(normalizedTask),
         observationId: observation.id,
         observationDigest: observation.digest.value,
-        correlation: structuredClone(normalizedTask.params.correlation),
+        correlation,
+        evidenceBindings: normalizedEvidence.map((resource) => ({
+          resourceId: resource?.id,
+          operationId: normalizedTask.operationId,
+          observationId: observation.id,
+          correlation: structuredClone(correlation),
+        })),
       },
     },
-    errors: structuredClone(errors),
-  };
-  return assertProfile("result", result);
+    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,
- * recomputes the observation, and proves the result echoes and binds the
- * exact Task/correlation fields. No retry or lifecycle state is introduced.
+ * 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 observation = normalizedTask.params.inputs[0];
-  await verifyObservationResource({ root, resource: observation });
 
   const mismatches = [];
   if (canonicalJson(normalizedResult.protocol) !== canonicalJson(normalizedTask.protocol)) {
     mismatches.push("protocol");
   }
-  if (normalizedResult.operationId !== normalizedTask.operationId) mismatches.push("operationId");
   if (normalizedResult.operation !== normalizedTask.operation) mismatches.push("operation");
+  if (normalizedResult.operationId !== normalizedTask.operationId) mismatches.push("operationId");
 
-  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");
+  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);
     }
-    if (
-      canonicalJson(binding.correlation) !==
-      canonicalJson(normalizedTask.params.correlation)
-    ) {
-      mismatches.push("binding.correlation");
+
+    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(", ")}`,
-      { mismatches },
+      { 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. */
+/**
+ * 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: cause?.code ?? "SFC2004",
-      message: cause?.message ?? String(cause),
-      details: cause?.details,
+      code: "SFC2004",
+      message,
+      details: {
+        kind: HARNESS_ERROR_KINDS.INVALID_RESULT,
+        category: "unexpected-failure",
+      },
     };
   }
 }

package/package.json

@@ -5,11 +5,12 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node/issues"
   },
   "dependencies": {
-    "skill-family-contracts": "0.2.1"
+    "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",
@@ -37,7 +38,7 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node.git"
   },
   "type": "module",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "scripts": {
     "check": "node --test",
     "test": "node --test"

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 交换生产方。