skill-family-engineering-kit 0.2.1 → 0.4.0

package/docs/reference/api/harness/index.html

@@ -972,6 +972,157 @@
       </ul>
     </nav>
 
+</li>
+
+        <li class="md-nav__item">
+  <a href="#基线物化-foundationharnessbaseline-materialization" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        基线物化 (foundation.harness.baseline-materialization)
+
+    </span>
+  </a>
+
+    <nav class="md-nav" aria-label="基线物化 (foundation.harness.baseline-materialization)">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#computeDirectoryDigest--materializeBaseline" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        computeDirectoryDigest / materializeBaseline
+
+    </span>
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
+</li>
+
+        <li class="md-nav__item">
+  <a href="#只读-chokepoint-foundationharnessread-chokepoint" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        只读 chokepoint (foundation.harness.read-chokepoint)
+
+    </span>
+  </a>
+
+    <nav class="md-nav" aria-label="只读 chokepoint (foundation.harness.read-chokepoint)">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#createReadChokepoint" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        createReadChokepoint
+
+    </span>
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
+</li>
+
+        <li class="md-nav__item">
+  <a href="#策略化表面扫描-foundationharnesssurface-scan" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        策略化表面扫描 (foundation.harness.surface-scan)
+
+    </span>
+  </a>
+
+    <nav class="md-nav" aria-label="策略化表面扫描 (foundation.harness.surface-scan)">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#scanSurface" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        scanSurface
+
+    </span>
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
+</li>
+
+        <li class="md-nav__item">
+  <a href="#token-上界估算-foundationharnesstoken-estimation" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        token 上界估算 (foundation.harness.token-estimation)
+
+    </span>
+  </a>
+
+    <nav class="md-nav" aria-label="token 上界估算 (foundation.harness.token-estimation)">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#estimateTokenUpperBound" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        estimateTokenUpperBound
+
+    </span>
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
+</li>
+
+        <li class="md-nav__item">
+  <a href="#通用上限守卫-foundationharnessupper-bound-guard" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        通用上限守卫 (foundation.harness.upper-bound-guard)
+
+    </span>
+  </a>
+
+    <nav class="md-nav" aria-label="通用上限守卫 (foundation.harness.upper-bound-guard)">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#openUsageGuard--appendUsageEvent--readUsage--closeUsageGuard" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        openUsageGuard / appendUsageEvent / readUsage / closeUsageGuard
+
+    </span>
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
+</li>
+
+        <li class="md-nav__item">
+  <a href="#Quickstart-Profile-v2-candidate" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        Quickstart Profile v2 candidate
+
+    </span>
+  </a>
+
 </li>
 
         <li class="md-nav__item">
@@ -2242,6 +2393,157 @@
       </ul>
     </nav>
 
+</li>
+
+        <li class="md-nav__item">
+  <a href="#基线物化-foundationharnessbaseline-materialization" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        基线物化 (foundation.harness.baseline-materialization)
+
+    </span>
+  </a>
+
+    <nav class="md-nav" aria-label="基线物化 (foundation.harness.baseline-materialization)">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#computeDirectoryDigest--materializeBaseline" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        computeDirectoryDigest / materializeBaseline
+
+    </span>
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
+</li>
+
+        <li class="md-nav__item">
+  <a href="#只读-chokepoint-foundationharnessread-chokepoint" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        只读 chokepoint (foundation.harness.read-chokepoint)
+
+    </span>
+  </a>
+
+    <nav class="md-nav" aria-label="只读 chokepoint (foundation.harness.read-chokepoint)">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#createReadChokepoint" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        createReadChokepoint
+
+    </span>
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
+</li>
+
+        <li class="md-nav__item">
+  <a href="#策略化表面扫描-foundationharnesssurface-scan" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        策略化表面扫描 (foundation.harness.surface-scan)
+
+    </span>
+  </a>
+
+    <nav class="md-nav" aria-label="策略化表面扫描 (foundation.harness.surface-scan)">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#scanSurface" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        scanSurface
+
+    </span>
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
+</li>
+
+        <li class="md-nav__item">
+  <a href="#token-上界估算-foundationharnesstoken-estimation" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        token 上界估算 (foundation.harness.token-estimation)
+
+    </span>
+  </a>
+
+    <nav class="md-nav" aria-label="token 上界估算 (foundation.harness.token-estimation)">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#estimateTokenUpperBound" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        estimateTokenUpperBound
+
+    </span>
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
+</li>
+
+        <li class="md-nav__item">
+  <a href="#通用上限守卫-foundationharnessupper-bound-guard" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        通用上限守卫 (foundation.harness.upper-bound-guard)
+
+    </span>
+  </a>
+
+    <nav class="md-nav" aria-label="通用上限守卫 (foundation.harness.upper-bound-guard)">
+      <ul class="md-nav__list">
+
+          <li class="md-nav__item">
+  <a href="#openUsageGuard--appendUsageEvent--readUsage--closeUsageGuard" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        openUsageGuard / appendUsageEvent / readUsage / closeUsageGuard
+
+    </span>
+  </a>
+
+</li>
+
+      </ul>
+    </nav>
+
+</li>
+
+        <li class="md-nav__item">
+  <a href="#Quickstart-Profile-v2-candidate" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        Quickstart Profile v2 candidate
+
+    </span>
+  </a>
+
 </li>
 
         <li class="md-nav__item">
@@ -2274,7 +2576,7 @@
 
 <h1 id="skill-family-harness-node-公共-API-参考">skill-family-harness-node 公共 API 参考<a class="headerlink" href="#skill-family-harness-node-公共-API-参考" title="Permanent link">&para;</a></h1>
 <p>本页从真实导出（<code>src/index.mjs</code> 与各源模块）核对，不手写无法证明新鲜度的全集。每个公共入口按 hand-off §4.3 说明：签名、输入与输出、是否纯函数、文件/进程/Git/网络副作用、稳定错误码与 <code>details.kind</code>、前置条件与信任锚、<code>since</code> 与 <code>stability</code>、源文件与正例/负例测试、调用方仍拥有的业务语义。</p>
-<p>Harness 是薄运行时：消费 Contracts，只实现业务中立机制；不拥有业务语义、编排、Git、网络与第二语言。包级常量：<code>HARNESS_CAPABILITIES</code>（9 项能力，闭集）、<code>HARNESS_EXCLUSIONS</code>（明确排除 <code>business-semantics</code> / <code>workflow-orchestration</code> / <code>git-writes</code> / <code>model-calls</code> / <code>release-state</code> / <code>remote-network-access</code>）。</p>
+<p>Harness 是薄运行时：消费 Contracts，只实现业务中立机制；不拥有业务语义、编排、Git、网络与第二语言。包级常量：<code>HARNESS_CAPABILITIES</code>（16 项能力，闭集）、<code>HARNESS_EXCLUSIONS</code>（明确排除 <code>business-semantics</code> / <code>workflow-orchestration</code> / <code>git-writes</code> / <code>model-calls</code> / <code>release-state</code> / <code>remote-network-access</code>）。</p>
 <p>能力分组（与 <code>docs/agents/capability-catalog.json</code> 对应）：</p>
 <ul>
 <li><a href="#契约校验-foundationharnesscontract-validation">契约校验</a> → <code>validateContractDocument</code> / <code>getValidator</code></li>
@@ -2286,6 +2588,11 @@
 <li><a href="#报告-foundationharnessreport">报告</a> → <code>validateReportModel</code> / <code>renderReportMarkdown</code> / <code>buildBinding</code> / <code>verifyBinding</code> / <code>checkReport</code></li>
 <li><a href="#宿主适配机制-foundationharnesshost-adapter">宿主适配机制</a> → <code>normalizeAdapterSource</code> / <code>buildAdapterClosure</code> / <code>materializeAdapterBuild</code> / <code>probeVersionVector</code></li>
 <li><a href="#持久状态底座-foundationharnessstate-store">持久状态底座</a> → <code>openStateStore</code> / <code>appendEvent</code> / <code>readSnapshot</code> / <code>verifyStateStore</code> …</li>
+<li><a href="#基线物化-foundationharnessbaseline-materialization">基线物化</a> → <code>computeDirectoryDigest</code> / <code>materializeBaseline</code>（FND-ADR-009）</li>
+<li><a href="#只读-chokepoint-foundationharnessread-chokepoint">只读 chokepoint</a> → <code>createReadChokepoint</code>（FND-ADR-009）</li>
+<li><a href="#策略化表面扫描-foundationharnesssurface-scan">策略化表面扫描</a> → <code>scanSurface</code>（FND-ADR-009）</li>
+<li><a href="#token-上界估算-foundationharnesstoken-estimation">token 上界估算</a> → <code>estimateTokenUpperBound</code>（FND-ADR-009）</li>
+<li><a href="#通用上限守卫-foundationharnessupper-bound-guard">通用上限守卫</a> → <code>openUsageGuard</code> / <code>appendUsageEvent</code> / <code>readUsage</code> / <code>closeUsageGuard</code>（FND-ADR-009）</li>
 <li><a href="#机制错误-foundationharnesserrors">机制错误</a> → <code>HarnessError</code> / <code>mechanismError</code> / <code>HARNESS_ERROR_KINDS</code></li>
 </ul>
 <hr />
@@ -2416,7 +2723,7 @@
 <li>纯函数：是（无时钟、无环境、无网络、无模型调用）。</li>
 <li>副作用：无文件/Git/网络。</li>
 <li>稳定错误码与 <code>details.kind</code>：<code>SFC3001</code>（<code>REPORT_DIGEST_MISMATCH</code>，绑定摘要不符或报告非模型规范渲染）、<code>SFC3002</code>（<code>REPORT_ELEMENT_MISSING</code>，强制元素缺失）、<code>SFC3003</code>（<code>REPORT_FACT_DRIFT</code>，报告改写绑定结果事实或字节与确定性再渲染不一致）。风格告警由 <code>collectStyleWarnings</code> 产出，仅建议、不编码、不阻断。</li>
-<li>前置条件与信任锚：<code>REPORT_RENDERER_NAME</code> / <code>VERSION</code> 取自各自 package（当前 <code>0.2.1</code>）；双输出成组写入并拒绝路径别名与输入覆盖。</li>
+<li>前置条件与信任锚：<code>REPORT_RENDERER_NAME</code> / <code>VERSION</code> 取自各自 package（当前 <code>0.3.0</code>）；双输出成组写入并拒绝路径别名与输入覆盖。</li>
 <li><code>since</code> / <code>stability</code>：<code>0.2.0</code> / <code>stable</code>。</li>
 <li>源文件：<code>packages/skill-family-harness-node/src/report.mjs</code>。</li>
 <li>正例/负例测试：<code>packages/skill-family-harness-node/test/report.test.mjs</code>。</li>
@@ -2541,9 +2848,123 @@
 <td><code>host-contract-invalid</code> / <code>host-build-failed</code> / <code>host-probe-failed</code> / <code>untrusted-executable</code> / <code>portable-path-collision</code> / <code>manifest-mismatch</code></td>
 <td>宿主适配异常</td>
 </tr>
+<tr>
+<td><code>baseline-mismatch</code> / <code>content-guard-rejected</code></td>
+<td>基线物化失败关闭</td>
+</tr>
+<tr>
+<td><code>read-chokepoint-rejected</code></td>
+<td>只读准入拒绝</td>
+</tr>
+<tr>
+<td><code>surface-scan-violation</code> / <code>scan-policy-invalid</code></td>
+<td>表面扫描失败关闭</td>
+</tr>
+<tr>
+<td><code>upper-bound-exceeded</code></td>
+<td>上限守卫越限</td>
+</tr>
 </tbody>
 </table>
 <hr />
+<h2 id="基线物化-foundationharnessbaseline-materialization">基线物化 (foundation.harness.baseline-materialization)<a class="headerlink" href="#基线物化-foundationharnessbaseline-materialization" title="Permanent link">&para;</a></h2>
+<p>FND-ADR-009。把冻结基线物化为字节保真的临时副本：物化前校验源摘要、物化后同时校验副本摘要与源摘要（捕获物化中途的任一侧变化）；副本内符号链接一律拒绝。</p>
+<h3 id="computeDirectoryDigest--materializeBaseline">computeDirectoryDigest / materializeBaseline<a class="headerlink" href="#computeDirectoryDigest--materializeBaseline" title="Permanent link">&para;</a></h3>
+<ul>
+<li>签名：</li>
+<li><code>computeDirectoryDigest(rootDir)</code>（async，返回 64 位小写 sha256 十六进制摘要）</li>
+<li><code>materializeBaseline({ baselineDir, baselineDigest, prefix = "sf-baseline-" } = {})</code>（async，返回物化根路径）</li>
+<li>输入：基线目录与冻结摘要。</li>
+<li>输出：确定性目录摘要；物化后的临时目录根路径。</li>
+<li>纯函数：否（读源树、在系统临时目录创建副本）。</li>
+<li>副作用：只读源基线；写系统临时目录并在失败时清理。</li>
+<li>稳定错误码与 <code>details.kind</code>：摘要不符（物化前或物化后）抛 <code>SFC2004</code> + <code>baseline-mismatch</code>（details 含 <code>phase</code>：<code>pre-materialization</code> / <code>post-materialization</code>）；目录不可用抛 <code>invalid-root</code>；建目录失败抛 <code>workspace-create-failed</code>。</li>
+<li>前置条件与信任锚：调用方持有冻结摘要；同一权限级进程可在物化窗口内改动源，机制以双端摘要捕获并失败关闭，不承诺抵御同权限恶意进程。</li>
+<li><code>since</code> / <code>stability</code>：<code>0.3.0</code> / <code>stable</code>。</li>
+<li>源文件：<code>packages/skill-family-harness-node/src/baseline.mjs</code>。</li>
+<li>正例/负例测试：<code>packages/skill-family-harness-node/test/baseline.test.mjs</code>。</li>
+<li>调用方仍拥有的业务语义：残留内容判定（<code>contentGuard</code> 谓词）与副本最终去处。</li>
+</ul>
+<p><code>TemporaryWorkspace.fromBaseline({ baselineDir, baselineDigest, prefix, contentGuard })</code> 与 <code>createTemporaryWorkspace({ baseline: { ... } })</code> 把物化接入工作区生命周期：<code>contentGuard</code> 缺省为允许（字节保真是机制契约，残留判定归消费者）；守卫抛错包装为 <code>content-guard-rejected</code> 并 dispose 副本。</p>
+<hr />
+<h2 id="只读-chokepoint-foundationharnessread-chokepoint">只读 chokepoint (foundation.harness.read-chokepoint)<a class="headerlink" href="#只读-chokepoint-foundationharnessread-chokepoint" title="Permanent link">&para;</a></h2>
+<p>FND-ADR-009。把受保护区域的读取集中到一个准入入口：允许根集合 + 可选身份谓词；越界、链接逃逸与非授权身份一律 <code>read-chokepoint-rejected</code>。</p>
+<h3 id="createReadChokepoint">createReadChokepoint<a class="headerlink" href="#createReadChokepoint" title="Permanent link">&para;</a></h3>
+<ul>
+<li>签名：<code>createReadChokepoint({ allowRoots, allowIdentity } = {})</code> → <code>{ assertReadAllowed, read }</code></li>
+<li>输入：非空允许根集合；可选身份谓词 <code>(identity) =&gt; boolean</code>。</li>
+<li>输出：准入后的 <code>{ root, relPath, absolute }</code> 或受收容读取结果。</li>
+<li>纯函数：否（<code>async</code>，含只读文件系统访问）。</li>
+<li>副作用：只读 realpath / 收容读取；不写。</li>
+<li>稳定错误码与 <code>details.kind</code>：越界/逃逸/非授权抛 <code>SFC2004</code> + <code>read-chokepoint-rejected</code>；资源缺失抛 <code>missing-resource</code>；参数非法抛 <code>TypeError</code>。</li>
+<li>前置条件与信任锚：调用方声明允许根集合与身份规则；机制不解释任何私有身份或路径语义。</li>
+<li><code>since</code> / <code>stability</code>：<code>0.3.0</code> / <code>stable</code>。</li>
+<li>源文件：<code>packages/skill-family-harness-node/src/chokepoint.mjs</code>。</li>
+<li>正例/负例测试：<code>packages/skill-family-harness-node/test/chokepoint.test.mjs</code>。</li>
+<li>调用方仍拥有的业务语义：允许根集合、身份谓词、准入后读取语义。</li>
+</ul>
+<p>字符串输入与 <code>{ root, relPath }</code> 输入走同一 <code>resolveContained</code> 收容分类（含 macOS <code>/var → /private/var</code> 等符号链接前缀根的统一规范化）。</p>
+<hr />
+<h2 id="策略化表面扫描-foundationharnesssurface-scan">策略化表面扫描 (foundation.harness.surface-scan)<a class="headerlink" href="#策略化表面扫描-foundationharnesssurface-scan" title="Permanent link">&para;</a></h2>
+<p>FND-ADR-009。按 <code>surface-scan-policy</code> 契约文档对声明表面做路径与内容模式扫描：首个命中即失败关闭；策略非法或模式不可编译同样失败关闭；缺失扫描文件不静默跳过。</p>
+<h3 id="scanSurface">scanSurface<a class="headerlink" href="#scanSurface" title="Permanent link">&para;</a></h3>
+<ul>
+<li>签名：<code>scanSurface({ root, relPaths, policy, encoding = "utf8" } = {})</code>（async）</li>
+<li>输入：扫描根、相对路径清单、策略契约文档。</li>
+<li>输出：<code>{ scanned, bytes, policy }</code>（冻结对象）。</li>
+<li>纯函数：否（只读文件系统访问；进程内正则编译，无持久状态）。</li>
+<li>副作用：只读；不写。</li>
+<li>稳定错误码与 <code>details.kind</code>：命中抛 <code>SFC2004</code> + <code>surface-scan-violation</code>（details 含 <code>kindOfHit</code>：<code>path</code> / <code>content</code>）；策略非法或模式不可编译抛 <code>scan-policy-invalid</code>；缺失文件抛 <code>missing-resource</code>；参数非法抛 <code>TypeError</code>。</li>
+<li>前置条件与信任锚：策略文档通过契约校验；<code>allowedUses</code> 只携带不解释，命中不被豁免（豁免由消费者层实现）。</li>
+<li><code>since</code> / <code>stability</code>：<code>0.3.0</code> / <code>stable</code>。</li>
+<li>源文件：<code>packages/skill-family-harness-node/src/surface-scan.mjs</code>。</li>
+<li>正例/负例测试：<code>packages/skill-family-harness-node/test/surface-scan.test.mjs</code>。</li>
+<li>调用方仍拥有的业务语义：策略内容、允许用途语义与命中后的处置。</li>
+</ul>
+<p>注入式自测约定：扫描器无状态——注入模式并扫描后移除注入，再次扫描结果字节一致（自测见测试文件，不冒充独立复核）。</p>
+<hr />
+<h2 id="token-上界估算-foundationharnesstoken-estimation">token 上界估算 (foundation.harness.token-estimation)<a class="headerlink" href="#token-上界估算-foundationharnesstoken-estimation" title="Permanent link">&para;</a></h2>
+<p>FND-ADR-009。确定性领域估算原语：UTF-8 字节数纯函数，无模型、无网络、无 tokenizer 依赖、无持久状态导入；结果符合 <code>token-estimate-result</code> 契约（无时间戳，<code>guarantees</code> 为封闭枚举）。</p>
+<h3 id="estimateTokenUpperBound">estimateTokenUpperBound<a class="headerlink" href="#estimateTokenUpperBound" title="Permanent link">&para;</a></h3>
+<ul>
+<li>签名：<code>estimateTokenUpperBound(text)</code>（纯函数）</li>
+<li>输入：文本字符串。</li>
+<li>输出：<code>token-estimate-result</code> 对象（<code>upperBound === inputBytes</code>）。</li>
+<li>纯函数：是；零依赖。</li>
+<li>副作用：无。</li>
+<li>稳定错误码与 <code>details.kind</code>：非字符串输入抛 <code>TypeError</code>（无 SFC 码）。</li>
+<li>前置条件与信任锚：输入为 JavaScript 字符串；估算只承诺上界（字节数即上界），不承诺真实 token 计数。</li>
+<li><code>since</code> / <code>stability</code>：<code>0.3.0</code> / <code>stable</code>。</li>
+<li>源文件：<code>packages/skill-family-harness-node/src/token-estimate.mjs</code>。</li>
+<li>正例/负例测试：<code>packages/skill-family-harness-node/test/token-estimate.test.mjs</code>。</li>
+<li>调用方仍拥有的业务语义：估算结果的解释与消费侧换算（模型调用与真实 token 计数不在 Foundation）。</li>
+</ul>
+<hr />
+<h2 id="通用上限守卫-foundationharnessupper-bound-guard">通用上限守卫 (foundation.harness.upper-bound-guard)<a class="headerlink" href="#通用上限守卫-foundationharnessupper-bound-guard" title="Permanent link">&para;</a></h2>
+<p>FND-ADR-009。复用 state-store 事件账与 token-lock 显式占用实现通用上限守卫：越限事件失败关闭且不写入；上限值、单位类别与超限策略全部由消费者配置，模块不携带任何固定数额或定价词汇。</p>
+<h3 id="openUsageGuard--appendUsageEvent--readUsage--closeUsageGuard">openUsageGuard / appendUsageEvent / readUsage / closeUsageGuard<a class="headerlink" href="#openUsageGuard--appendUsageEvent--readUsage--closeUsageGuard" title="Permanent link">&para;</a></h3>
+<ul>
+<li>签名：</li>
+<li><code>openUsageGuard({ stateRoot, owner, payloadSchemas, reducer, initial = 0, upperBound, lockRoot, lockPath, clock } = {})</code>（async）</li>
+<li><code>appendUsageEvent(guard, event, { beforeCommit } = {})</code>（async）</li>
+<li><code>readUsage(guard)</code>（async）</li>
+<li><code>closeUsageGuard(guard)</code>（async）</li>
+<li>输入：事件负载、纯归约函数、非负上限、状态根与锁根/锁路径。</li>
+<li>输出：追加结果、当前用量读数、守卫句柄。</li>
+<li>纯函数：否（写事件账与锁文件）。</li>
+<li>副作用：在受收容路径写事件账与锁文件；打开时显式占用锁、关闭时释放。</li>
+<li>稳定错误码与 <code>details.kind</code>：越限抛 <code>SFC2004</code> + <code>upper-bound-exceeded</code>（details 含 <code>upperBound</code> / <code>projected</code>，事件不写入）；锁被占用抛 <code>store-locked</code>；事件账断链抛 <code>chain-broken</code>；事件 schema 违规抛 <code>event-schema-invalid</code>。</li>
+<li>前置条件与信任锚：<code>lockRoot</code>/<code>lockPath</code> 由消费者指定在 state store 根之外；事件账是唯一权威；fencing 不承诺抵御同权限恶意进程。</li>
+<li><code>since</code> / <code>stability</code>：<code>0.3.0</code> / <code>stable</code>。</li>
+<li>源文件：<code>packages/skill-family-harness-node/src/budget-guard.mjs</code>。</li>
+<li>正例/负例测试：<code>packages/skill-family-harness-node/test/budget-guard.test.mjs</code>。</li>
+<li>调用方仍拥有的业务语义：事件含义、归约函数、上限数值与超限后的业务处置（定价与计费语义留在消费者）。</li>
+</ul>
+<hr />
+<h2 id="Quickstart-Profile-v2-candidate">Quickstart Profile v2 candidate<a class="headerlink" href="#Quickstart-Profile-v2-candidate" title="Permanent link">&para;</a></h2>
+<p><code>skill-family-harness-node/candidate/quickstart-profile</code> 负责创建 observation Resource、Task 与终态 Result，并复验真实文件字节、Resource id 全局唯一性、Task digest、operation 身份、逐字段 <code>run/stage/attempt</code> 以及 evidence 精确回指。<code>verifyQuickstartExchange</code> 把机制拒绝转换成结构化结果，抛出式入口继续使用已登记的 <code>SFC2004</code> 与稳定 <code>details.kind</code>。</p>
+<p>该入口不选择 method，不解释 domainResult，也不拥有重试、调度或生命周期。0.3.0 的 v2 与 0.2.1 的 v1 不兼容；接入必须精确锁定所选版本。</p>
+<hr />
 <h2 id="与机器事实层的互链">与机器事实层的互链<a class="headerlink" href="#与机器事实层的互链" title="Permanent link">&para;</a></h2>
 <ul>
 <li>能力稳定 ID 见 <code>docs/agents/capability-catalog.json</code>（<code>foundation.harness.*</code>）。</li>

package/docs/reference/api/index.html

@@ -671,6 +671,17 @@
     </span>
   </a>
 
+</li>
+
+        <li class="md-nav__item">
+  <a href="#Quickstart-Profile-v2-candidate" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        Quickstart Profile v2 candidate
+
+    </span>
+  </a>
+
 </li>
 
     </ul>
@@ -1737,6 +1748,17 @@
     </span>
   </a>
 
+</li>
+
+        <li class="md-nav__item">
+  <a href="#Quickstart-Profile-v2-candidate" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        Quickstart Profile v2 candidate
+
+    </span>
+  </a>
+
 </li>
 
     </ul>
@@ -1796,8 +1818,10 @@
 <ul>
 <li>机制失败统一 <code>SFC2004</code>（<code>EXECUTION_FAILED</code>），由 <code>details.kind</code> 区分（<code>HARNESS_ERROR_KINDS</code> 冻结枚举）；Contracts 校验失败（<code>SFC1001</code> / <code>SFC1002</code>）经 <code>validateDocument</code> 返回值表达、不抛异常。</li>
 <li>Kit 顶层命令集合固定为 4 个（<code>scaffold</code> / <code>adopt-plan</code> / <code>projection</code> / <code>check</code>），不扩张；<code>host apply</code> / <code>install</code> / <code>update</code> / <code>uninstall</code>、Qoder 完整 driver、二进制 adapter source、远端发布、业务状态机、模型编排、领域审计语义均明确 unsupported。</li>
-<li>所有版本字段从 <code>package.json</code> 与 Contracts 真源生成或由 fact-check 校验；<code>CONTRACTS_VERSION=1.4.0</code> 与 npm 包版本 <code>0.2.1</code> 并行。</li>
+<li>所有版本字段从 <code>package.json</code> 与 Contracts 真源生成或由 fact-check 校验；<code>CONTRACTS_VERSION=1.4.0</code> 与 npm 包版本 <code>0.3.0</code> 并行。</li>
 </ul>
+<h2 id="Quickstart-Profile-v2-candidate">Quickstart Profile v2 candidate<a class="headerlink" href="#Quickstart-Profile-v2-candidate" title="Permanent link">&para;</a></h2>
+<p>三个包都通过既有 candidate 子路径公开 Quickstart Profile v2。Contracts 定义 <code>execute-method</code> 交换结构，Harness 复验字节和绑定，Kit 从显式消费者 Schema 生成离线 Bundle。该能力仍标记为 <code>candidate</code>，0.3.0 的 v2 与 0.2.1 的 v1 不兼容；消费者必须精确锁定所选包版本。</p>
 
 
 

package/docs/reference/compatibility/index.html

@@ -595,6 +595,17 @@
     </span>
   </a>
 
+</li>
+
+        <li class="md-nav__item">
+  <a href="#Quickstart-Profile-candidate-兼容性" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        Quickstart Profile candidate 兼容性
+
+    </span>
+  </a>
+
 </li>
 
         <li class="md-nav__item">
@@ -1748,6 +1759,17 @@
     </span>
   </a>
 
+</li>
+
+        <li class="md-nav__item">
+  <a href="#Quickstart-Profile-candidate-兼容性" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        Quickstart Profile candidate 兼容性
+
+    </span>
+  </a>
+
 </li>
 
         <li class="md-nav__item">
@@ -1840,33 +1862,56 @@
 <tbody>
 <tr>
 <td><code>skill-family-contracts</code></td>
-<td>0.2.1</td>
+<td>0.3.0</td>
 <td>Contracts 1.4.0 机器契约</td>
 <td>公开发布目标（private: false）</td>
 </tr>
 <tr>
 <td><code>skill-family-harness-node</code></td>
-<td>0.2.1</td>
+<td>0.3.0</td>
 <td>Contracts 的 Node 薄机制运行时</td>
 <td>公开发布目标</td>
 </tr>
 <tr>
 <td><code>skill-family-engineering-kit</code></td>
-<td>0.2.1</td>
+<td>0.3.0</td>
 <td>四个工程命令（CLI <code>skill-family-kit</code>）</td>
 <td>公开发布目标</td>
 </tr>
 <tr>
 <td>工作区仓</td>
-<td>0.2.1</td>
+<td>0.3.0</td>
 <td>私有父工作区（private: true）</td>
 <td>仅开发真源</td>
 </tr>
 </tbody>
 </table>
 <blockquote>
-<p>契约权威版本（<code>CONTRACTS_VERSION</code>）为 <code>1.4.0</code>，npm 包版本为 <code>0.2.1</code>，两套版本并行，不混用。</p>
+<p>契约权威版本（<code>CONTRACTS_VERSION</code>）为 <code>1.4.0</code>，npm 包版本为 <code>0.3.0</code>，两套版本并行，不混用。</p>
 </blockquote>
+<h2 id="Quickstart-Profile-candidate-兼容性">Quickstart Profile candidate 兼容性<a class="headerlink" href="#Quickstart-Profile-candidate-兼容性" title="Permanent link">&para;</a></h2>
+<table>
+<thead>
+<tr>
+<th>包版本</th>
+<th>candidate profile</th>
+<th>兼容规则</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>0.2.1</td>
+<td>v1</td>
+<td>已有接入可继续精确锁定 0.2.1</td>
+</tr>
+<tr>
+<td>0.3.0</td>
+<td>v2</td>
+<td>使用 <code>execute-method</code>、真实 <code>$id</code> Schema 集合与离线 Bundle；必须精确锁定 0.3.0</td>
+</tr>
+</tbody>
+</table>
+<p>v2 替换 v1，不提供双轨兼容层。稳定 Contracts 1.4.0、18 类对象、内核协议与错误码登记不随 candidate 切换而变化。</p>
 <h2 id="Node-支持矩阵">Node 支持矩阵<a class="headerlink" href="#Node-支持矩阵" title="Permanent link">&para;</a></h2>
 <ul>
 <li>引擎要求：<code>&gt;=22.22.2 &lt;23</code>（锁定 major 22）。</li>
@@ -1922,6 +1967,7 @@
 <li><strong>Kit 命令</strong>：顶层命令固定 4 个（scaffold/adopt-plan/projection/check），不扩张；<code>REFUSED_MUTATION_FLAGS</code> 在 CLI 入口即拒。</li>
 <li><strong>Node/pnpm/projen</strong>：跟随 <code>.foundation/version-lock.json</code> 与 <code>package.json</code> 的精确锁定，升级须经 <code>pnpm synth</code> 重新生成受管投影。</li>
 <li><strong>宿主</strong>：新增受支持宿主须登记 descriptor 并绑定受信 driver；unsupported 宿主（如 qoder）只参考结构，不声称已在其上运行。</li>
+<li><strong>Candidate</strong>：candidate 子路径允许在后续 minor 版本修改或移除；0.2.1 v1 与 0.3.0 v2 不混装，消费者按所需 profile 精确锁定三个包版本。</li>
 </ul>
 <h2 id="反兼容边界明确不支持">反兼容边界（明确不支持）<a class="headerlink" href="#反兼容边界明确不支持" title="Permanent link">&para;</a></h2>
 <ul>