skill-family-contracts 公共 API 参考¶

本页从真实导出（src/index.mjs 与各源模块）核对，不手写无法证明新鲜度的全集。每个公共入口按 hand-off §4.3 说明：签名、输入与输出、是否纯函数、文件/进程/Git/网络副作用、稳定错误码与 details.kind、前置条件与信任锚、since 与 stability、源文件与正例/负例测试、调用方仍拥有的业务语义。

能力分组（与 docs/agents/capability-catalog.json 对应）：

对象校验 → validateDocument / compileSchema / detectDialect
来源权威收据 → validateSourceAuthorityReceipt / parseSourceAuthorityReceipt
文件系统契约 → 根绑定与固定集合 manifest/receipt Schema
登记与协议 → loadRegistry / findSchemaByObject / findProtocol / registerSchema / registerProtocol
内核协议 → loadKernelProtocol / findOperation / checkOperation
强制检查 → runChecks / collectUnresolvedRefs
fixture 校验 → listFixtures / verifyFixture / verifyAllFixtures
错误码 → ContractsError / isRegisteredErrorCode / stableError
审计表面 → canonicalJson / digestDocument / digestAuditSurface
同级适配器验证合同 → request/result Schema
真实宿主验证合同 → request/result Schema

包级常量（冻结，仅作事实投影，不另立权威）：CONTRACT_OBJECTS（42 类顶层对象，闭集）、CONTRACT_BOUNDARY、CONTRACTS_VERSION = "1.13.0"、SUPPORTED_DIALECTS、VALIDATION_POLICIES、CHECK_TYPES（9 类机械检查）、MANDATORY_RULES、RULE_BUDGET、ERROR_CODES。

对象校验 (foundation.contracts.object-validation)¶

validateDocument¶

签名：validateDocument(document, { schemaId, schema, dialect, policy = "strict" } = {})
输入：任意 JSON 文档；目标契约对象 $id 或 schema 对象；方言（draft-07 / 2020-12）；策略（strict | tolerant）。
输出：校验通过返回 {valid:true}（不含 errorCode）；失败返回 {valid:false, errorCode, errors}，不抛出（已实测：未知 $id 返回 SFC1002，文档不符返回 SFC1001）。
纯函数：是。仅读取进程内 Ajv 编译缓存，不触外部资源。
副作用：无文件/Git/网络/进程副作用；首次编译写入内存编译缓存，后续同 (schemaId,dialect,policy) 复用。
稳定错误码与 details.kind：SFC1002（未知 $id）、SFC1001（文档不符 Schema）。两者均经返回值 errorCode 表达，调用方以 valid 字段判断成败，不以 try/catch 捕获。
前置条件与信任锚：待校验文档带已登记契约对象 $id；Node >= 22.22.2；校验器固定为 Ajv 8.20.0。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-contracts/src/validator.mjs。
正例测试：packages/skill-family-contracts/test/validator.test.mjs、schemas.test.mjs、host-contracts.test.mjs、report-contracts.test.mjs。
负例测试：同上（未知 $id 与不符 Schema 均返回 valid:false）。
调用方仍拥有的业务语义：具体业务字段的语义解释、领域级校验规则。

compileSchema¶

签名：compileSchema(target, { dialect, policy = "strict" } = {})
输入：schema 对象或 $id；方言；策略。
输出：编译后的 Ajv validate 函数；或抛 ContractsError（SFC1012 SCHEMA_COMPILE_FAILED，当 schema 自身无法在声明方言下编译）。
纯函数：是。
副作用：无外部副作用，仅写入编译缓存。
稳定错误码与 details.kind：SFC1012（编译失败，抛异常——与 validateDocument 的返回式失败不同）、SFC1006（未知方言，由 detectDialect 抛）。
前置条件与信任锚：Ajv 8.20.0 固定；dialect 属冻结支持集。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-contracts/src/validator.mjs。
正例/负例测试：同 validateDocument。
调用方仍拥有的业务语义：schema 的业务含义。

detectDialect¶

签名：detectDialect(schema)
输入：带 $schema 字段的 schema 对象。
输出：方言字符串（draft-07 / 2020-12）；未知方言抛 ContractsError（SFC1006 UNSUPPORTED_DIALECT）。
纯函数：是。
副作用：无。
稳定错误码与 details.kind：SFC1006（声明方言不在冻结支持集）。
前置条件与信任锚：方言集冻结（SUPPORTED_DIALECTS）。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-contracts/src/validator.mjs。
正例/负例测试：同上。
调用方仍拥有的业务语义：方言选择策略（何时用 tolerant）。

来源权威收据 (foundation.contracts.source-authority)¶

validateSourceAuthorityReceipt / parseSourceAuthorityReceipt¶

签名：validateSourceAuthorityReceipt(receipt)；parseSourceAuthorityReceipt(receipt, actualSubjects)。
输入：闭合的外置 receipt，以及调用方实际观测的 subjects。每个 subject 只含 packageName、version、filename 与 sha256。
输出：两者均返回既有 { valid, errorCode, errors, data } 结果形态。解析成功时，data 只含 sourceRepository 与 sourceBaseCommit。
纯函数：是。输入会复制后校验，调用方对象不被修改。
副作用：无文件、进程、Git、网络或发布状态副作用。
稳定错误码：结构、排序、重复包名、实际 subjects 形状或逐字段核对失败均返回 SFC1001。
前置条件与信任锚：receipt subjects 至少一项，按 packageName 唯一、升序排列；sourceBaseCommit 是 40 位小写十六进制，SHA-256 是 64 位小写十六进制。调用方负责取得 receipt 与实际 subjects。
since / stability：0.8.4 / stable。
源文件：packages/skill-family-contracts/src/source-authority.mjs、src/schemas/source-authority-receipt.schema.json。
正例/负例测试：packages/skill-family-contracts/test/source-authority.test.mjs、source-authority-public-consumer.test.mjs。
调用方仍拥有的业务语义：receipt 的签发、存储和传输；实际包发现；校验后是否采用该来源。Contracts 不执行目标，也不解释私有发布计划。

文件系统契约 (foundation.contracts.filesystem)¶

0.9.0 新增三个稳定顶层 Schema：filesystem-root-binding、fixed-set-publication-manifest 与 fixed-set-publication-receipt。它们只描述结构与回执，不提供删除、替换或通用恢复状态机。

根绑定 Schema：https://contracts.skill-family.example/v1/filesystem-root-binding.json。值固定为 kind、digestAlgorithm、basis、digest 四个字段；绑定值可序列化且不包含公开目录句柄。
固定集合 manifest/receipt Schema：https://contracts.skill-family.example/v1/fixed-set-publication-manifest.json 与 https://contracts.skill-family.example/v1/fixed-set-publication-receipt.json。发布回执的终态只允许 succeeded、refused、failed、indeterminate。
这三个 Schema 的真实登记与 fixture 由 packages/skill-family-contracts/src/registry.json、src/schemas/ 和 test/ 共同核验；批量校验 Schema 保持 candidate，不进入稳定 Registry。

登记与协议 (foundation.contracts.registry-protocol)¶

loadRegistry / listSchemas / listProtocols / findSchemaRegistration / findSchemaByObject / findProtocol¶

签名：
loadRegistry()
listSchemas(registry = REGISTRY)
listProtocols(registry = REGISTRY)
findSchemaRegistration(schemaId, registry = REGISTRY)
findSchemaByObject(object, registry = REGISTRY)
findProtocol(name, version, registry = REGISTRY)
输入：对象名、$id、协议名/版本（其余默认读冻结 REGISTRY）。
输出：已登记 schema 元信息或协议定义；未命中返回 undefined。
纯函数：是。
副作用：无。
稳定错误码与 details.kind：登记类冲突经 registerSchema / registerProtocol 抛 SFC1003（DUPLICATE_SCHEMA_ID）/ SFC1004（DUPLICATE_PROTOCOL_NAME）。
前置条件与信任锚：registry.json 随包发布；schemaVersion=1、contractsVersion=1.4.0 为唯一权威；18 类顶层对象集合固定，新增需 ADR。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-contracts/src/registry.mjs、registry.json。
正例/负例测试：packages/skill-family-contracts/test/registry.test.mjs。
调用方仍拥有的业务语义：对象业务含义的解释。

registerSchema / registerProtocol¶

签名：
registerSchema(entry, registry = REGISTRY)
registerProtocol(entry, registry = REGISTRY)
输入：schema/protocol 登记项。
输出：写入后的 registry（默认冻结 REGISTRY 上的副作用）；重复 $id/协议名抛 ContractsError。
纯函数：否（默认向进程内冻结 registry 登记，属受控内存副作用）。
副作用：进程内 registry 变更；不落盘。
稳定错误码与 details.kind：SFC1003（重复 $id）、SFC1004（重复协议名）。
前置条件与信任锚：18 类对象集与协议名集冻结。
since / stability：0.2.0 / stable。
源文件：同上。
正例/负例测试：同上。
调用方仍拥有的业务语义：登记项的业务理由。

内核协议 (foundation.contracts.kernel-protocol)¶

loadKernelProtocol / findOperation / checkOperation¶

签名：
loadKernelProtocol()
findOperation(name, kernel = KERNEL)
checkOperation(operation, params)
输入：协议名、操作名、操作参数。
输出：协议定义或操作参数校验结果；失败时抛 ContractsError。
纯函数：是（加载为只读解析，无外部副作用）。
副作用：无。
稳定错误码与 details.kind：SFC2002（UNKNOWN_OPERATION，操作名不在冻结词汇）、SFC2003（INVALID_PARAMS，参数违反操作参数契约）。
前置条件与信任锚：kernel-protocol.json 随包发布；内核协议版本与 Contracts 版本绑定。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-contracts/src/kernel.mjs、kernel-protocol.json。
正例/负例测试：packages/skill-family-contracts/test/kernel.test.mjs。
调用方仍拥有的业务语义：操作的具体业务语义（状态机/重试/终态转 loop-agent）。

强制检查 (foundation.contracts.mandatory-checks)¶

runChecks / collectUnresolvedRefs¶

签名：
runChecks({ schemaEntries, ... } = {})
collectUnresolvedRefs(schemaEntries)
输入：待检查契约集或合成 registry/fixtures。
输出：检查结论与未解析引用清单；违反规则抛 ContractsError。
纯函数：是。
副作用：无。
稳定错误码与 details.kind：SFC1002/1003/1004/1005/1006/1008/1009/1010 对应各规则 violated；SFC1005（UNRESOLVED_REF）、SFC1008（RULE_BUDGET_EXCEEDED）、SFC1010（FIXTURE_EXPECTATION_MISMATCH）。
前置条件与信任锚：registry 与 rules 已加载；CHECK_TYPES 为 9 类闭集；RULE_BUDGET 限制 firstVersionMax 与 absoluteMax。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-contracts/src/checker.mjs、rules.json。
正例/负例测试：packages/skill-family-contracts/test/checker.test.mjs。
调用方仍拥有的业务语义：规则业务理由的解释（语义接受/拒绝属外部独立审阅）。

fixture 校验 (foundation.contracts.fixture-verification)¶

listFixtures / fixtureClasses / verifyFixture / verifyAllFixtures¶

签名：
listFixtures()
fixtureClasses()
verifyFixture(fixture)
verifyAllFixtures()
输入：fixture 类或单个 fixture 标识。
输出：逐 fixture 的校验结果（正例须通过、负例须以声明稳定码失败）。
纯函数：是（只读 fixture 目录）。
副作用：只读访问 fixture，无写。
稳定错误码与 details.kind：SFC1010（FIXTURE_EXPECTATION_MISMATCH，负例未产生预期失败）；SFC1009（UNKNOWN_ERROR_CODE，fixture 引用未登记码）。
前置条件与信任锚：fixtures 目录为公开或完全虚构数据；fixture 与审计器预期结果不共享。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-contracts/src/fixtures.mjs。
正例/负例测试：packages/skill-family-contracts/test/fixtures.test.mjs。
调用方仍拥有的业务语义：fixture 背后的业务意图（fixture 只证结构、不证语义）。

错误码 (foundation.contracts.error-codes)¶

ContractsError / errorCodeRegistry / errorCodeInfo / isRegisteredErrorCode / assertRegisteredErrorCode / stableError¶

签名：
class ContractsError extends Error（构造 (code, message, details)）
errorCodeRegistry()
errorCodeInfo(code)
isRegisteredErrorCode(code)
assertRegisteredErrorCode(code)
stableError(code, message, details)
输入：错误码字符串、错误上下文。
输出：带稳定错误码与 details 的错误对象；assertRegisteredErrorCode 对未登记码抛 TypeError。
纯函数：是（ContractsError 构造为纯对象，无外部副作用）。
副作用：无。
稳定错误码与 details.kind：错误码体系本身冻结（error-codes.json），新增码属 Contracts 变更；SFC1009 用于未登记码断言。
前置条件与信任锚：error-codes.json 随包发布；冻结对象不可变。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-contracts/src/errors.mjs、error-codes.json。
正例/负例测试：packages/skill-family-contracts/test/boundary.test.mjs、immutability.test.mjs、audit-surface.test.mjs。
调用方仍拥有的业务语义：错误码的业务归因。

Contracts 错误码一览（稳定、append-only）：

码	名称	类别
SFC1001	SCHEMA_VALIDATION_FAILED	contract
SFC1002	UNKNOWN_SCHEMA_ID	contract
SFC1003	DUPLICATE_SCHEMA_ID	contract
SFC1004	DUPLICATE_PROTOCOL_NAME	contract
SFC1005	UNRESOLVED_REF	contract
SFC1006	UNSUPPORTED_DIALECT	contract
SFC1007	UNKNOWN_CHECK_TYPE	contract
SFC1008	RULE_BUDGET_EXCEEDED	contract
SFC1009	UNKNOWN_ERROR_CODE	contract
SFC1010	FIXTURE_EXPECTATION_MISMATCH	contract
SFC1011	UNKNOWN_PROTOCOL	contract
SFC1012	SCHEMA_COMPILE_FAILED	contract
SFC2002	UNKNOWN_OPERATION	kernel
SFC2003	INVALID_PARAMS	kernel
SFC2004	EXECUTION_FAILED	kernel（机制失败统一码，承载 `details.kind`）
SFC3001	REPORT_DIGEST_MISMATCH	report
SFC3002	REPORT_ELEMENT_MISSING	report
SFC3003	REPORT_FACT_DRIFT	report

审计表面 (foundation.contracts.audit-surface)¶

canonicalJson / digestDocument / describeAuditSurface / digestAuditSurface¶

签名：
canonicalJson(value)
digestDocument(value, { algorithm = "sha256" } = {})
describeAuditSurface()
digestAuditSurface(surface = describeAuditSurface())
输入：任意 JSON 文档。
输出：canonical 字符串与 sha256 摘要；审计表面结构描述与其摘要。
纯函数：是。
副作用：无。
稳定错误码与 details.kind：非 JSON 值、未知算法（AUDIT_DIGEST_ALGORITHMS 仅 sha256）、冻结违规抛 ContractsError。
前置条件与信任锚：AUDIT_SURFACE_VERSION=1；摘要算法仅 sha256；依赖方向 Audit → Contracts，本模块不反向导入审计产物。
since / stability：0.2.0 / stable。
源文件：packages/skill-family-contracts/src/audit-surface.mjs。
正例/负例测试：packages/skill-family-contracts/test/audit-surface.test.mjs。
调用方仍拥有的业务语义：审计语义结论（接受/拒绝属外部独立审阅）。

同级适配器验证合同 (foundation.contracts.peer-adapter-verification)¶

Contracts 1.10.0 登记 adapter-peer-verification-request 与 adapter-peer-verification-result 两个稳定 Schema。request 至少包含两个显式 peer；每个 peer 携带闭集 hostId、路径类别和完整 logicalMappings。result 固定为 verified 与 peer-verification，并携带共同来源闭包、每个 peer 的标准 manifest 和 mapping。

这两个合同只描述业务中立的只读验证，不拥有 canonical source、目录写入、迁移、receipt、重试或生命周期状态。 peer 顺序不得改变共同闭包摘要或结论；未知字段、重复/缺失/悬空 mapping 和无法由真实目录证明的输入必须失败关闭。

since / stability：0.10.0 / stable。
Schema 文件：packages/skill-family-contracts/src/schemas/adapter-peer-verification-request.schema.json、adapter-peer-verification-result.schema.json。
正例/负例测试：packages/skill-family-harness-node/test/peer-adapter.test.mjs、packages/skill-family-engineering-kit/test/host.test.mjs。
调用方仍拥有的业务语义：peer 的 canonical 选择、旧 manifest 迁移解释、消费者 smoke 和发布后验证。

真实宿主验证合同 (foundation.contracts.host-verification)¶

Contracts 1.11.0 登记 host-verification-request 与 host-verification-result。两个 Schema 的 $id、 operation=host-verification 和四态结果身份从首版固定，但该能力当前是 candidate，不能据此宣称宿主、领域结果或发布已通过。

request 把共同候选绑定与每宿主 binding 分开；所有 *Sha256 与 *ClosureDigest 均为 64 位小写十六进制。调用方必须从私有 roots 严格重算这些值，不能把自报摘要当作证明。auth 固定为 existing-user-state + host-managed，只说明复用用户现有登录状态；execution.modelOverridePolicy 固定为 forbidden。
result 只允许 observed、rejected、failed、indeterminate。它不含 credential、绝对路径、环境变量、Prompt、原始 stream 或 durable receipt；observed 只表示基础设施观察完整，不表示消费者领域 PASS。requiredActions 只允许 manual-temporary-root-inspection-required。
request auth 必须精确对应已登记 Descriptor 的单值 driverId/authStrategy/credentialMutation；Descriptor 是认证组合的唯一事实源，Schema 同时机械绑定 kimi-code → kimi-code-print-v1 与 workbuddy → workbuddy-codebuddy-print-v1。 Schema 不提供通用 driver Registry 或认证 SPI。
since / stability：0.11.0 / candidate。Schema 文件： packages/skill-family-contracts/src/schemas/host-verification-request.schema.json、 packages/skill-family-contracts/src/schemas/host-verification-result.schema.json。正反例： packages/skill-family-contracts/test/schemas.test.mjs。
调用方仍拥有的业务语义：candidate 解引用、workload、领域输出、发布新鲜度、领域 PASS/FAIL 与发布决定。

能力成熟度与历史迁移政策¶

包根导出 CAPABILITY_MATURITY_LEVELS、CANDIDATE_PROMOTION_POLICY、 HISTORICAL_CANDIDATE_MIGRATION_POLICY，以及两个返回结构化副本的 describe*Policy()。它们不读取文件、不写状态，也不替消费者执行迁移。政策固定历史入口只迁移一次；新能力采用规范身份后，candidate→stable 不再改变消费者合同。消费者要取得新发布的 stable 承诺仍需更新三包精确 pin；受管投影是否重建沿用既有绑定输入合同。

since / stability：0.10.0 / stable。源文件：packages/skill-family-contracts/src/stability.mjs。正反例测试： packages/skill-family-contracts/test/candidate-promotion-compatibility.test.mjs。

Quickstart Profile v2 candidate¶

规范入口 skill-family-contracts/quickstart-profile 导出 v2 协议、按规范 $id 索引的 Resource/Task/Result Schema 集合，以及 validateQuickstartProfileDocument。历史入口 skill-family-contracts/candidate/quickstart-profile 在弃用窗口内解析到同一模块，现有消费者应迁移一次。唯一 operation 是业务中立的 execute-method；Foundation 不登记 method 词表，也不解释 parameters、evidence 或 domainResult 的领域含义。

0.10.0 把 Quickstart 六个历史 Schema 身份和 0.9.0 的两个 batch Schema 身份一次迁移到不含 /candidate/ 的规范 $id。HISTORICAL_CANDIDATE_SCHEMA_ID_MIGRATIONS 固定八项旧 ID→规范 ID；loader 只返回规范 Schema。Quickstart Bundle 让旧新 ID 指向同一编译 validator，不复制 Schema，也不登记进 stable Registry。两个 batch Schema 仍只供 validate-many-by-schema-id 使用；未知 schemaId 或任一结构畸形都使整批请求失败。

该能力从 0.2.1 起公开，稳定性仍为 candidate。0.3.0 已用 v2 替换 v1，两者不兼容：仍需 v1 的接入继续精确锁定 0.2.1；v2 新接入应使用 0.10.0 规范入口并精确锁定三包。candidate Schema 不进入稳定 src/registry.json。主动升级候选版本仍需复验；以后仅晋升 stable 时不再切入口或 Schema 身份。取得 stable 发布承诺仍需更新三包精确 pin。

与机器事实层的互链¶

能力稳定 ID 见 docs/agents/capability-catalog.json（foundation.contracts.*）。
机械校验：scripts/docs/capability-catalog-check.mjs 解析 src/index.mjs，拒绝引用不存在的入口；sourceRefs 与测试引用均指向本页所列真实文件。