skill-family-contracts 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:32a8df58662f9dbb64e142cb8a2b329556b4bd59872e48fcbc317cc971cbdd7c -->
+## [0.3.0] - 2026-08-12
+
+This source candidate replaces the Quickstart Profile candidate with v2 while preserving the stable Contracts registry and kernel protocol.
+
+### Added
+
+- Adds the v2 protocol definition with the business-neutral execute-method operation and a real $id-indexed Resource, Task, and Result schema collection.
+- Enforces JSON-safe Task and Result boundaries, one path-backed observation, terminal output shapes, and exact evidence bindings.
+
+### Changed
+
+- Replaces the incompatible 0.2.1 candidate surface; consumers that still require v1 must remain pinned to exactly 0.2.1.
+- Keeps method identifiers, parameter schemas, and domain result semantics under consumer ownership.
+
+### Upgrade Notes
+
+Version 0.3.0 is a local, unpublished source candidate. Pin all candidate imports to an exact package version and migrate v1 integrations before selecting this version.
+<!-- release-skill:changelog:end version=0.3.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.2.1 locale=en baseline=sha256:b759650e4d52969bd907bccea937c64622b00b0ff97851da9c6c4aee8adb4888 -->
 ## [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:5f1c4cf56cc336279cbc6f11bc6cf8ce0a7524f454ff6589e067e828707a7cc7 -->
+## [0.3.0] - 2026-08-12
+
+本源码候选版以 Quickstart Profile v2 替换原 candidate，同时保持稳定 Contracts 登记表和内核协议不变。
+
+### 新增
+
+- 新增 v2 协议定义，以业务中立的 execute-method 作为唯一操作，并按真实 $id 登记 Resource、Task、Result Schema 集合。
+- 收紧 Task 与 Result 的 JSON-safe 边界、单一 path-backed observation、终态输出形状及 evidence 精确回指。
+
+### 变更
+
+- 替换与 0.2.1 不兼容的 candidate 面；仍依赖 v1 的消费者必须继续精确锁定 0.2.1。
+- 方法标识、参数 Schema 与领域结果语义继续归消费者所有。
+
+### 升级说明
+
+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:1f9b53564843c024415fda87d41abf96bc22db2ec5b90d12d7a8cd7c897a24fc -->
 ## [0.2.1] - 2026-08-10
 

package/README.md

@@ -4,28 +4,28 @@
 
 # skill-family-contracts
 
-<!-- release-skill:release-version: 0.2.1 -->
+<!-- release-skill:release-version: 0.3.0 -->
 
 The single authoritative package of machine-executable engineering structure and mechanism protocols (Contracts 1.4.0, frozen).
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.2.1** (2026-08-10)
+**0.3.0** (2026-08-12)
 
-This release adds a candidate Quickstart Profile contract surface and makes the package release documentation available in English and Simplified Chinese.
+This source candidate replaces the Quickstart Profile candidate with v2 while preserving the stable Contracts registry and kernel protocol.
 
 **Added**
 
-- Adds candidate Resource, Task, and Result schemas with strict validation helpers. The candidate schemas remain outside the stable Contracts registry.
-- Adds complete English and Simplified Chinese package documentation, including an agent quick-reference section.
+- Adds the v2 protocol definition with the business-neutral execute-method operation and a real $id-indexed Resource, Task, and Result schema collection.
+- Enforces JSON-safe Task and Result boundaries, one path-backed observation, terminal output shapes, and exact evidence bindings.
 
 **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.
+- Keeps method identifiers, parameter schemas, and domain result semantics under consumer ownership.
 
 **Upgrade Notes**
 
-Stable registry consumers do not need to change. Import the Quickstart Profile only through its candidate subpath and do not treat it as a frozen Contracts object.
+Version 0.3.0 is a local, unpublished source candidate. Pin all candidate imports to an exact package version and migrate v1 integrations before selecting this version.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -41,14 +41,14 @@ Schema validation is based entirely on [Ajv](https://ajv.js.org/) (exact version
 ## Installation and Minimal Example
 
 ```sh
-npm install skill-family-contracts@0.2.1
+npm install skill-family-contracts@0.3.0
 npm info skill-family-contracts --help
 ```
 
 The minimal example starts from an empty directory and demonstrates how to validate a registered contract object:
 
 ```js
-// Run from an empty directory: npm install skill-family-contracts@0.2.1
+// Run from an empty directory: npm install skill-family-contracts@0.3.0
 import { validateDocument } from "skill-family-contracts";
 
 const document = {
@@ -81,7 +81,9 @@ import {
 } from "skill-family-contracts/candidate/quickstart-profile";
 ```
 
-The subpath is public but **not stable**. Its schemas are deliberately absent from `src/registry.json`, do not expand the eighteen stable object classes, and may change or be removed in a later minor release. Consumers should pin the exact package version and keep candidate imports outside their stable public API. Use the root package export for production contracts that require frozen registry and compatibility guarantees.
+Version 0.3.0 carries Quickstart Profile v2. Its protocol fixes the business-neutral operation to `execute-method`; Resource, Task, and Result schemas resolve one another through their real v2 `$id` values. Foundation validates the JSON-safe exchange shape, while the consumer owns method identifiers, parameter schemas, and domain results.
+
+The subpath is public but **not stable**. Its schemas remain absent from `src/registry.json`, do not expand the eighteen stable object classes, and may change or be removed in a later minor release. Pin exactly `0.3.0` when evaluating v2. Integrations that still require candidate v1 must stay pinned to exactly `0.2.1`.
 
 ## Typical Use Cases
 

package/README.zh-CN.md

@@ -5,28 +5,28 @@
 
 # skill-family-contracts
 
-<!-- release-skill:release-version: 0.2.1 -->
+<!-- release-skill:release-version: 0.3.0 -->
 
 机器可执行工程结构和机制协议的唯一权威包（Contracts 1.4.0，冻结）。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.2.1** (2026-08-10)
+**0.3.0** (2026-08-12)
 
-本版新增 Quickstart Profile 候选契约面，并为包发布文档提供完整英文版与简体中文版。
+本源码候选版以 Quickstart Profile v2 替换原 candidate，同时保持稳定 Contracts 登记表和内核协议不变。
 
 **新增**
 
-- 新增候选 Resource、Task、Result Schema 及其严格校验辅助函数。这组候选 Schema 不进入稳定 Contracts 登记表。
-- 新增完整的英文与简体中文包文档，并补充智能体快速参考章节。
+- 新增 v2 协议定义，以业务中立的 execute-method 作为唯一操作，并按真实 $id 登记 Resource、Task、Result Schema 集合。
+- 收紧 Task 与 Result 的 JSON-safe 边界、单一 path-backed observation、终态输出形状及 evidence 精确回指。
 
 **变更**
 
-- 使用同一份双语版本化说明源管理当前 README 与 CHANGELOG 的发布区域。
-- 项目 NOTICE 与 Apache-2.0 LICENSE 分开分发。
+- 替换与 0.2.1 不兼容的 candidate 面；仍依赖 v1 的消费者必须继续精确锁定 0.2.1。
+- 方法标识、参数 Schema 与领域结果语义继续归消费者所有。
 
 **升级说明**
 
-稳定登记表的消费者无需修改。Quickstart Profile 只能通过 candidate 子路径导入，不得把它当作已冻结的 Contracts 对象。
+0.3.0 当前只是本地、未发布的源码候选。candidate 导入必须精确锁定包版本，v1 接入完成迁移后才能选用本版本。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -42,14 +42,14 @@ Schema 验证完全基于 [Ajv](https://ajv.js.org/)（精确版本见 `package.
 ## 安装和最小示例
 
 ```sh
-npm install skill-family-contracts@0.2.1
+npm install skill-family-contracts@0.3.0
 npm info skill-family-contracts --help
 ```
 
 最小示例从空目录开始，演示如何校验一份已登记契约对象：
 
 ```js
-// 从空目录运行：npm install skill-family-contracts@0.2.1
+// 从空目录运行：npm install skill-family-contracts@0.3.0
 import { validateDocument } from "skill-family-contracts";
 
 const document = {
@@ -82,7 +82,9 @@ import {
 } from "skill-family-contracts/candidate/quickstart-profile";
 ```
 
-以上子路径公开但**不稳定**。这些 Schema 刻意不进入 `src/registry.json`，不扩张十八类稳定对象，后续小版本可以修改或移除。调用方需要锁定精确包版本，并避免把 candidate 导入转成自身稳定公共 API。生产合同若需要冻结登记与兼容性保证，继续使用包根导出。
+0.3.0 携带 Quickstart Profile v2。协议把业务中立的操作固定为 `execute-method`，Resource、Task、Result Schema 通过真实的 v2 `$id` 互相解析。Foundation 只校验 JSON-safe 交换结构；方法标识、参数 Schema 与领域结果继续归消费者所有。
+
+以上子路径公开但**不稳定**。这些 Schema 不进入 `src/registry.json`，也不扩张十八类稳定对象，后续小版本可以修改或移除。评估 v2 时应精确锁定 `0.3.0`；仍依赖 candidate v1 的接入必须继续精确锁定 `0.2.1`。
 
 ## 典型使用场景
 

package/candidate/quickstart-profile/fixtures/resource-negative-absolute-path.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "kind": "skill-family.resource",
+  "id": "acme-review-observation",
+  "location": {
+    "path": "/etc/acme-review-observation.json"
+  },
+  "role": "observation",
+  "digest": {
+    "algorithm": "sha256",
+    "value": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+  }
+}

package/candidate/quickstart-profile/fixtures/resource-negative-bad-digest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "kind": "skill-family.resource",
-  "id": "observation-main",
+  "id": "acme-review-observation",
   "location": {
-    "path": "inputs/observation.json"
+    "path": "inputs/acme-review-observation.json"
   },
   "role": "observation",
   "digest": {

package/candidate/quickstart-profile/fixtures/resource-positive-uri.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "kind": "skill-family.resource",
+  "id": "acme-review-evidence-uri",
+  "location": {
+    "uri": "urn:example:acme-review:evidence:0001"
+  },
+  "role": "evidence",
+  "digest": {
+    "algorithm": "sha256",
+    "value": "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210"
+  }
+}

package/candidate/quickstart-profile/fixtures/resource-positive.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "kind": "skill-family.resource",
-  "id": "observation-main",
+  "id": "acme-review-observation",
   "location": {
-    "path": "inputs/observation.json"
+    "path": "inputs/acme-review-observation.json"
   },
   "role": "observation",
   "digest": {

package/candidate/quickstart-profile/index.mjs

@@ -1,12 +1,31 @@
 import { readFileSync } from "node:fs";
-import { detectDialect, validateDocument } from "../../src/validator.mjs";
+import Ajv2020 from "ajv/dist/2020.js";
+import { findSchemaRegistration } from "../../src/registry.mjs";
+
+/**
+ * Candidate quickstart profile v2 (unstable).
+ *
+ * Unlike v1, the collection is registered under its real $ids in one
+ * dialect-matching Ajv instance: task and result reference the v2 Resource
+ * schema and the stable operation-request/operation-result envelopes by
+ * $ref, and no $ref is rewritten into a local $def. The candidate $ids stay
+ * absent from the stable registry on purpose.
+ */
 
 const documents = Object.freeze({
+  protocol: load("protocol.json"),
   resource: load("resource.schema.json"),
   task: load("task.schema.json"),
   result: load("result.schema.json"),
 });
 
+const VALIDATE_KINDS = Object.freeze(["resource", "task", "result"]);
+
+const STABLE_ENVELOPE_IDS = Object.freeze([
+  "https://contracts.skill-family.example/v1/operation-request.json",
+  "https://contracts.skill-family.example/v1/operation-result.json",
+]);
+
 function load(name) {
   return Object.freeze(
     JSON.parse(readFileSync(new URL(name, import.meta.url), "utf8")),
@@ -14,46 +33,226 @@ function load(name) {
 }
 
 export const QUICKSTART_PROFILE_ID = "quickstart-profile";
-export const QUICKSTART_PROFILE_VERSION = 1;
+export const QUICKSTART_PROFILE_VERSION = 2;
 export const QUICKSTART_PROTOCOL = Object.freeze({
-  name: "skill-family.quickstart-profile",
-  version: 1,
+  name: documents.protocol.name,
+  version: documents.protocol.version,
 });
+export const QUICKSTART_OPERATION = Object.freeze(
+  documents.protocol.operations.map((operation) => operation.name),
+);
+
+/** The frozen candidate protocol definition document (not a JSON Schema). */
+export function loadQuickstartProtocol() {
+  return structuredClone(documents.protocol);
+}
 
 /** Candidate-only schemas. They are deliberately absent from registry.json. */
 export function quickstartProfileSchemas() {
-  return structuredClone(documents);
+  return structuredClone({
+    resource: documents.resource,
+    task: documents.task,
+    result: documents.result,
+  });
+}
+
+/** Enumerates the collection as registry-style entries ($id + document). */
+export function listQuickstartProfileSchemas() {
+  return VALIDATE_KINDS.map((kind) => ({
+    kind,
+    $id: documents[kind].$id,
+    document: structuredClone(documents[kind]),
+  }));
+}
+
+// The stable envelopes declare a date-time format; the candidate instance
+// must define it identically so the envelopes compile under validateFormats.
+const DATE_TIME_PATTERN =
+  /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])[Tt]([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?([Zz]|[+-]([01]\d|2[0-3]):[0-5]\d)$/;
+
+function isValidDateTime(value) {
+  if (typeof value !== "string" || !DATE_TIME_PATTERN.test(value)) return false;
+  const [datePart] = value.split(/[Tt]/, 1);
+  const [year, month, day] = datePart.split("-").map(Number);
+  const roundTrip = new Date(Date.UTC(year, month - 1, day));
+  return (
+    roundTrip.getUTCFullYear() === year &&
+    roundTrip.getUTCMonth() === month - 1 &&
+    roundTrip.getUTCDate() === day
+  );
 }
 
-function linkResourceSchema(schema) {
-  const linked = structuredClone(schema);
-  const resourceId = documents.resource.$id;
-  const visit = (value) => {
-    if (Array.isArray(value)) {
-      for (const item of value) visit(item);
-      return;
+let collection = null;
+
+function getCollection() {
+  if (collection) return collection;
+  const ajv = new Ajv2020({
+    coerceTypes: false,
+    useDefaults: false,
+    allErrors: true,
+    validateFormats: true,
+    strict: true,
+  });
+  ajv.addFormat("date-time", { type: "string", validate: isValidDateTime });
+  for (const schemaId of STABLE_ENVELOPE_IDS) {
+    const registration = findSchemaRegistration(schemaId);
+    if (!registration) {
+      throw new Error(`stable envelope schema is not registered: ${schemaId}`);
     }
-    if (!value || typeof value !== "object") return;
-    if (value.$ref === resourceId) value.$ref = "#/$defs/quickstartResource";
-    for (const child of Object.values(value)) visit(child);
-  };
-  visit(linked);
-  linked.$defs = {
-    ...(linked.$defs ?? {}),
-    quickstartResource: structuredClone(documents.resource),
-  };
-  return linked;
+    ajv.addSchema(
+      JSON.parse(readFileSync(new URL(`../../${registration.file}`, import.meta.url), "utf8")),
+    );
+  }
+  for (const kind of VALIDATE_KINDS) {
+    ajv.addSchema(documents[kind]);
+  }
+  collection = Object.freeze(
+    Object.fromEntries(
+      VALIDATE_KINDS.map((kind) => [kind, ajv.getSchema(documents[kind].$id)]),
+    ),
+  );
+  return collection;
 }
 
-/** Validate one candidate profile document through the shared Ajv validator. */
+function normalizeErrors(ajvErrors) {
+  if (!ajvErrors) return [];
+  return ajvErrors.map((error) => ({
+    keyword: error.keyword,
+    instancePath: error.instancePath,
+    schemaPath: error.schemaPath,
+    message: error.message,
+    params: error.params,
+  }));
+}
+
+function escapePointerSegment(segment) {
+  return String(segment).replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+const ARRAY_INDEX_PATTERN = /^(0|[1-9]\d*)$/;
+
+// Inspects own properties through descriptors only, so accessors are refused
+// without ever being invoked. JSON would drop symbol-keyed and non-enumerable
+// properties silently and execute accessors, so all three classes fail closed.
+function probeObjectMembers(value, instancePath, ancestors) {
+  const symbolKeys = Object.getOwnPropertySymbols(value);
+  if (symbolKeys.length > 0) {
+    return {
+      instancePath: `${instancePath}/${escapePointerSegment(String(symbolKeys[0]))}`,
+      reason: "symbol-keyed property",
+    };
+  }
+  const isArray = Array.isArray(value);
+  let arrayLength = 0;
+  if (isArray) {
+    const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+    if (!lengthDescriptor || lengthDescriptor.get || lengthDescriptor.set) {
+      return { instancePath: `${instancePath}/length`, reason: "accessor property" };
+    }
+    arrayLength = lengthDescriptor.value;
+  }
+  for (const key of Object.getOwnPropertyNames(value)) {
+    if (isArray && key === "length") continue;
+    const memberPath = `${instancePath}/${escapePointerSegment(key)}`;
+    if (isArray && (!ARRAY_INDEX_PATTERN.test(key) || Number(key) >= arrayLength)) {
+      return { instancePath: memberPath, reason: "non-index array property" };
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor) continue;
+    if (descriptor.get || descriptor.set) {
+      return { instancePath: memberPath, reason: "accessor property" };
+    }
+    if (!descriptor.enumerable) {
+      return { instancePath: memberPath, reason: "non-enumerable property" };
+    }
+    const issue = probeJsonValue(descriptor.value, memberPath, ancestors);
+    if (issue) return issue;
+  }
+  return null;
+}
+
+function probeJsonValue(value, instancePath, ancestors) {
+  if (value === null) return null;
+  const type = typeof value;
+  if (type === "boolean" || type === "string") return null;
+  if (type === "number") {
+    return Number.isFinite(value) ? null : { instancePath, reason: "non-finite number" };
+  }
+  if (type === "bigint") return { instancePath, reason: "bigint" };
+  if (type === "undefined") return { instancePath, reason: "undefined" };
+  if (type === "function" || type === "symbol") return { instancePath, reason: type };
+  if (type !== "object") return { instancePath, reason: type };
+  const isArray = Array.isArray(value);
+  if (!isArray) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      return {
+        instancePath,
+        reason: `non-plain object (${Object.prototype.toString.call(value)})`,
+      };
+    }
+  }
+  if (ancestors.has(value)) return { instancePath, reason: "circular reference" };
+  ancestors.add(value);
+  const issue = probeObjectMembers(value, instancePath, ancestors);
+  ancestors.delete(value);
+  return issue;
+}
+
+/**
+ * Deep JSON-safety probe for candidate documents and caller-owned values.
+ * Pure JSON data is null, booleans, finite numbers, strings, arrays, and
+ * plain objects. Anything else (bigint, undefined, function, symbol,
+ * non-finite number, non-plain object, circular reference) is reported as
+ * { instancePath, reason } at the first offending location, instead of
+ * surviving into structuredClone, digestDocument, or JSON.stringify where it
+ * would throw or silently drift. Own properties JSON would ignore or execute
+ * are refused the same way: symbol-keyed and non-enumerable properties are
+ * dropped by serialization and accessors would be executed, so the probe
+ * rejects them through descriptors without invoking any accessor. Repeated
+ * references to the same JSON-safe object stay accepted when acyclic; only
+ * true cycles fail closed. Returns null when the value is pure JSON.
+ */
+export function findNonJsonValue(value) {
+  return probeJsonValue(value, "", new Set());
+}
+
+/**
+ * Validates one candidate profile document against the collection registered
+ * under real $ids. Returns { valid, errorCode, errors, data } with the same
+ * shape as the stable validateDocument; data is a normalized deep copy and
+ * caller input is never mutated. Documents containing non-JSON values are
+ * refused deterministically before any clone or serialization.
+ */
 export function validateQuickstartProfileDocument(kind, document) {
-  if (!Object.hasOwn(documents, kind)) {
+  if (!VALIDATE_KINDS.includes(kind)) {
     throw new TypeError(`unknown quickstart profile document kind: ${String(kind)}`);
   }
-  const schema = kind === "resource" ? documents.resource : linkResourceSchema(documents[kind]);
-  return validateDocument(document, {
-    schema,
-    dialect: detectDialect(schema),
-    policy: "strict",
-  });
+  const target = document === undefined ? null : document;
+  const jsonIssue = findNonJsonValue(target);
+  if (jsonIssue) {
+    return {
+      valid: false,
+      errorCode: "SFC1001",
+      errors: [
+        {
+          keyword: "json-value",
+          instancePath: jsonIssue.instancePath,
+          schemaPath: "#",
+          message: `value is not representable as JSON: ${jsonIssue.reason}`,
+          params: { reason: jsonIssue.reason },
+        },
+      ],
+      data: null,
+    };
+  }
+  const validate = getCollection()[kind];
+  const data = structuredClone(target);
+  const valid = validate(data) === true;
+  return {
+    valid,
+    errorCode: valid ? null : "SFC1001",
+    errors: valid ? [] : normalizeErrors(validate.errors),
+    data,
+  };
 }

package/candidate/quickstart-profile/protocol.json

@@ -0,0 +1,64 @@
+{
+  "schemaVersion": 1,
+  "kind": "skill-family.protocol-definition",
+  "name": "skill-family.quickstart-profile",
+  "version": 2,
+  "status": "candidate",
+  "description": "Candidate v2 quickstart profile protocol. One business-neutral operation (execute-method) wraps a caller-owned method around exactly one path-backed observation Resource and binds the terminal Result back to the complete canonical Task. Foundation never registers or interprets the caller method vocabulary; this definition deliberately stays outside the stable protocol registry.",
+  "terminalStates": ["succeeded", "failed", "rejected"],
+  "operations": [
+    {
+      "name": "execute-method",
+      "status": "candidate",
+      "description": "Executes one caller-owned method. params.method identifies the method and params.parameters carries caller-owned parameters; Foundation does not interpret either. params.inputs holds exactly one path-backed observation Resource; params.correlation carries run, stage, and attempt (attempt counts from 1). succeeded means the mechanism execution completed, not that a domain conclusion passed.",
+      "params": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["method", "parameters", "inputs", "correlation"],
+        "properties": {
+          "method": {
+            "type": "string",
+            "maxLength": 128,
+            "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+            "description": "Caller-owned method identifier; no Foundation method vocabulary exists."
+          },
+          "parameters": {
+            "type": "object",
+            "description": "Caller-owned parameter object; Foundation never reads its fields."
+          },
+          "inputs": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 1,
+            "description": "Exactly one path-backed observation Resource."
+          },
+          "correlation": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["run", "stage", "attempt"],
+            "properties": {
+              "run": {
+                "type": "string",
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+              },
+              "stage": {
+                "type": "string",
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+              },
+              "attempt": {
+                "type": "integer",
+                "minimum": 1
+              }
+            }
+          }
+        }
+      }
+    }
+  ],
+  "resultContract": {
+    "outputs": {
+      "execute-method": "On succeeded, outputs is mandatory and carries summary, outputs (role=output Resources), evidence (role=evidence Resources), the caller-owned domainResult, and a taskBinding that echoes operationId, the complete canonical Task digest, the observation id/digest, and the exact run/stage/attempt correlation. taskBinding.evidenceBindings carries exactly one mechanism back-reference per evidence Resource, each fixing resourceId, operationId, observationId, and the run/stage/attempt correlation; the array only proves the evidence belongs to this Task exchange and never interprets which domain conclusion the evidence supports. On failed and rejected, outputs is mandatory and null."
+    },
+    "errors": "Every error entry carries a code registered in the frozen contracts error registry; a format-conforming but unregistered code is refused. failed and rejected results carry at least one."
+  }
+}

package/candidate/quickstart-profile/resource.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://contracts.skill-family.example/candidate/quickstart-profile/v1/resource.json",
+  "$id": "https://contracts.skill-family.example/candidate/quickstart-profile/v2/resource.json",
   "title": "QuickstartResource",
-  "description": "Candidate Resource profile for one content-addressed observation, output, or evidence item.",
+  "description": "Candidate Resource profile (v2) for one content-addressed observation, output, or evidence item. location.path and location.uri are mutually exclusive; URIs are only structurally checked and never fetched.",
   "type": "object",
   "additionalProperties": false,
   "required": ["schemaVersion", "kind", "id", "location", "role", "digest"],
@@ -23,11 +23,13 @@
       "properties": {
         "path": {
           "type": "string",
-          "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$"
+          "maxLength": 1024,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(?:/[A-Za-z0-9][A-Za-z0-9._-]*)*$"
         },
         "uri": {
           "type": "string",
-          "pattern": "^[A-Za-z][A-Za-z0-9+.-]*:.+$"
+          "maxLength": 2048,
+          "pattern": "^[A-Za-z][A-Za-z0-9+.-]*:[^\\s]+$"
         }
       },
       "oneOf": [

package/candidate/quickstart-profile/result.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://contracts.skill-family.example/candidate/quickstart-profile/v1/result.json",
+  "$id": "https://contracts.skill-family.example/candidate/quickstart-profile/v2/result.json",
   "title": "QuickstartResult",
-  "description": "Candidate narrow profile over the stable terminal operation-result envelope.",
+  "description": "Candidate narrow profile (v2) over the stable terminal operation-result envelope. Every terminal state fixes outputs explicitly: succeeded requires the outputs object, failed and rejected require null outputs plus at least one error whose code is registered in the frozen contracts error registry. succeeded.outputs fixes summary, outputs, evidence, domainResult, and a taskBinding whose evidenceBindings carries exactly one mechanism back-reference per evidence Resource. domainResult is an arbitrary caller-owned JSON value that Foundation never interprets.",
   "allOf": [
     {
       "$ref": "https://contracts.skill-family.example/v1/operation-result.json"
@@ -13,12 +13,13 @@
         "protocol": {
           "const": {
             "name": "skill-family.quickstart-profile",
-            "version": 1
+            "version": 2
           }
         },
         "operation": {
-          "const": "audit"
+          "const": "execute-method"
         },
+        "completedAt": false,
         "outputs": {
           "oneOf": [
             {
@@ -28,6 +29,36 @@
               "$ref": "#/$defs/outputs"
             }
           ]
+        },
+        "errors": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "code": {
+                "enum": [
+                  "SFC1001",
+                  "SFC1002",
+                  "SFC1003",
+                  "SFC1004",
+                  "SFC1005",
+                  "SFC1006",
+                  "SFC1007",
+                  "SFC1008",
+                  "SFC1009",
+                  "SFC1010",
+                  "SFC1011",
+                  "SFC1012",
+                  "SFC2002",
+                  "SFC2003",
+                  "SFC2004",
+                  "SFC3001",
+                  "SFC3002",
+                  "SFC3003"
+                ]
+              }
+            }
+          }
         }
       },
       "allOf": [
@@ -41,7 +72,6 @@
             "required": ["state"]
           },
           "then": {
-            "type": "object",
             "required": ["outputs"],
             "properties": {
               "outputs": {
@@ -49,6 +79,24 @@
               }
             }
           }
+        },
+        {
+          "if": {
+            "properties": {
+              "state": {
+                "enum": ["failed", "rejected"]
+              }
+            },
+            "required": ["state"]
+          },
+          "then": {
+            "required": ["outputs"],
+            "properties": {
+              "outputs": {
+                "const": null
+              }
+            }
+          }
         }
       ]
     }
@@ -73,10 +121,32 @@
         }
       }
     },
+    "evidenceBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["resourceId", "operationId", "observationId", "correlation"],
+      "properties": {
+        "resourceId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+        },
+        "operationId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+        },
+        "observationId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+        },
+        "correlation": {
+          "$ref": "#/$defs/correlation"
+        }
+      }
+    },
     "taskBinding": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["operationId", "taskDigest", "observationId", "observationDigest", "correlation"],
+      "required": ["operationId", "taskDigest", "observationId", "observationDigest", "correlation", "evidenceBindings"],
       "properties": {
         "operationId": {
           "type": "string",
@@ -96,6 +166,12 @@
         },
         "correlation": {
           "$ref": "#/$defs/correlation"
+        },
+        "evidenceBindings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/evidenceBinding"
+          }
         }
       }
     },
@@ -113,7 +189,7 @@
           "items": {
             "allOf": [
               {
-                "$ref": "https://contracts.skill-family.example/candidate/quickstart-profile/v1/resource.json"
+                "$ref": "https://contracts.skill-family.example/candidate/quickstart-profile/v2/resource.json"
               },
               {
                 "type": "object",
@@ -131,7 +207,7 @@
           "items": {
             "allOf": [
               {
-                "$ref": "https://contracts.skill-family.example/candidate/quickstart-profile/v1/resource.json"
+                "$ref": "https://contracts.skill-family.example/candidate/quickstart-profile/v2/resource.json"
               },
               {
                 "type": "object",

package/candidate/quickstart-profile/task.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://contracts.skill-family.example/candidate/quickstart-profile/v1/task.json",
+  "$id": "https://contracts.skill-family.example/candidate/quickstart-profile/v2/task.json",
   "title": "QuickstartTask",
-  "description": "Candidate narrow profile over the stable operation-request envelope.",
+  "description": "Candidate narrow profile (v2) over the stable operation-request envelope. The single operation is the business-neutral execute-method; params.method and params.parameters are caller-owned and Foundation never interprets them. The Task digest binds the complete canonical Task, so the optional requestedAt timestamp is excluded from this profile.",
   "allOf": [
     {
       "$ref": "https://contracts.skill-family.example/v1/operation-request.json"
@@ -13,12 +13,13 @@
         "protocol": {
           "const": {
             "name": "skill-family.quickstart-profile",
-            "version": 1
+            "version": 2
           }
         },
         "operation": {
-          "const": "audit"
+          "const": "execute-method"
         },
+        "requestedAt": false,
         "params": {
           "type": "object",
           "additionalProperties": false,
@@ -26,6 +27,7 @@
           "properties": {
             "method": {
               "type": "string",
+              "maxLength": 128,
               "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
             },
             "parameters": {
@@ -38,7 +40,7 @@
               "items": {
                 "allOf": [
                   {
-                    "$ref": "https://contracts.skill-family.example/candidate/quickstart-profile/v1/resource.json"
+                    "$ref": "https://contracts.skill-family.example/candidate/quickstart-profile/v2/resource.json"
                   },
                   {
                     "type": "object",

package/package.json

@@ -9,7 +9,8 @@
   },
   "description": "Machine-readable contracts for Skill Family engineering.",
   "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-contracts.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 replaces the Quickstart Profile candidate with v2 while preserving the stable Contracts registry and kernel protocol.
+    changes:
+      added:
+        - Adds the v2 protocol definition with the business-neutral execute-method operation and a real $id-indexed Resource, Task, and Result schema collection.
+        - Enforces JSON-safe Task and Result boundaries, one path-backed observation, terminal output shapes, and exact evidence bindings.
+      changed:
+        - Replaces the incompatible 0.2.1 candidate surface; consumers that still require v1 must remain pinned to exactly 0.2.1.
+        - Keeps method identifiers, parameter schemas, and domain result semantics under consumer ownership.
+    upgradeNotes: Version 0.3.0 is a local, unpublished source candidate. Pin all candidate imports to an exact package version and migrate v1 integrations before selecting this version.
+  zh-CN:
+    summary: 本源码候选版以 Quickstart Profile v2 替换原 candidate，同时保持稳定 Contracts 登记表和内核协议不变。
+    changes:
+      added:
+        - 新增 v2 协议定义，以业务中立的 execute-method 作为唯一操作，并按真实 $id 登记 Resource、Task、Result Schema 集合。
+        - 收紧 Task 与 Result 的 JSON-safe 边界、单一 path-backed observation、终态输出形状及 evidence 精确回指。
+      changed:
+        - 替换与 0.2.1 不兼容的 candidate 面；仍依赖 v1 的消费者必须继续精确锁定 0.2.1。
+        - 方法标识、参数 Schema 与领域结果语义继续归消费者所有。
+    upgradeNotes: 0.3.0 当前只是本地、未发布的源码候选。candidate 导入必须精确锁定包版本，v1 接入完成迁移后才能选用本版本。