skill-family-engineering-kit 0.3.0 → 0.4.0

package/docs/architecture/index.html

@@ -1972,7 +1972,7 @@ Contracts（结构、协议、错误码、协议名登记）
 <tbody>
 <tr>
 <td>Contracts</td>
-<td>结构、协议、错误码、协议名登记；18 类顶层对象；9 条 mandatory rule</td>
+<td>结构、协议、错误码、协议名登记；20 类顶层对象；9 条 mandatory rule</td>
 <td>业务字段语义、领域审计、远端写入、模型生成</td>
 </tr>
 <tr>
@@ -2024,7 +2024,7 @@ Contracts（结构、协议、错误码、协议名登记）
 <li>涉及制品关系/版本锁 → artifact-graph。</li>
 <li>只有一个消费者或尚未证明跨两个真实消费者重复 → 留在消费者，不扩张 Foundation。</li>
 </ol>
-<p>第 8 步是扩张闸门：新增组件必须说明删除它会让两个以上真实消费者重复实现，并经独立 fixture 验证。机器可读版见 <code>docs/agents/architecture-routing.md</code>。</p>
+<p>第 8 步是扩张闸门：新增组件必须说明删除它会让两个以上真实消费者重复实现，并经独立 fixture 验证；进入门 1 另要求至少一个现有真实消费者加一个结构同型的可预见消费者（第二消费者不要求已上线，但需求必须能用同一结构表达，调整记录见 FND-ADR-009）。第 9 步是有限封闭语义闸门（对应 FND-ADR-001 门 8）：能力若携带少量领域语义，必须满足语义能被少数稳定封闭枚举覆盖，或为确定性估算原语——算法、适用范围与偏差方向已在契约中声明；本闸门不取消门 2「语义无关」一票否决。机器可读版见 <code>docs/agents/architecture-routing.md</code>。</p>
 <h2 id="信任与副作用边界">信任与副作用边界<a class="headerlink" href="#信任与副作用边界" title="Permanent link">&para;</a></h2>
 <p>Foundation 的信任前提与副作用约定按层固化，调用方据此判断风险：</p>
 <ul>
@@ -2050,6 +2050,12 @@ Contracts（结构、协议、错误码、协议名登记）
 涉及制品关系/版本锁? ──是──▶ artifact-graph
         │否
 只有一个消费者/未证明跨两个真实消费者? ──是──▶ 留在消费者，不扩张
+        │否
+携带少量领域语义? ──是──▶ 有限封闭语义：稳定闭枚举可覆盖，或为确定性
+         │               估算原语（算法/适用范围/偏差方向已契约声明）→ 可纳入；
+         │               否则留在消费者（FND-ADR-001 门 8，不取消门 2 一票否决）
+         │否
+        ──▶ 可纳入
 </code></pre>
 <h2 id="与外部项目的路由关系">与外部项目的路由关系<a class="headerlink" href="#与外部项目的路由关系" title="Permanent link">&para;</a></h2>
 <p>Foundation 不是全能底座。下列职责明确在 Foundation 之外：</p>
@@ -2066,11 +2072,12 @@ Contracts（结构、协议、错误码、协议名登记）
 <li><strong>宿主接入线</strong>（FND-FR-001/FND-FR-002，FND-ADR-003）：Contracts 登记 descriptor/source/manifest/probe/plan/receipt；Harness 实现通用 source closure、原子 build/materialize 和 probe 分类；Kit 注入具体 Profile 与受信 driver。当前只支持 describe/build/probe/plan，<code>apply</code> 稳定拒绝，安装/卸载/更新均未实现。</li>
 <li><strong>持久状态底座线</strong>（FND-FR-003，FND-ADR-004）：append-only 事件、hash chain、快照与校验恢复；只提供状态底座，状态机、任务节点、重试、终态、记忆等业务语义不纳入 Foundation。</li>
 <li><strong>人类报告线</strong>（FND-FR-004，FND-ADR-005）：双层合同——机器结果是唯一真源，人类报告由机器结果确定性渲染（Markdown + digest 绑定 + 分级检查），不自由撰写。</li>
+<li><strong>有限封闭语义工具线</strong>（FND-ADR-009）：基线物化 + contentGuard（摘要不符、物化中途变化、守卫检出均失败关闭）、通用只读 chokepoint（允许根集合 + 可选身份谓词）、策略化表面扫描（策略契约 + 注入式自测）、token 上界估算（确定性领域估算原语，无模型/网络/tokenizer 依赖）、通用上限守卫（复用 state-store 事件账与 token-lock，上限与超限策略由消费者配置）。</li>
 </ul>
 <p>三包结构保持、不拆第四包（FND-ADR-007）；制品治理采用 artifact-graph CLI 与版本锁（FND-ADR-006）。</p>
 <h2 id="首版预算">首版预算<a class="headerlink" href="#首版预算" title="Permanent link">&para;</a></h2>
 <ul>
-<li>顶层 Contracts 对象：18 类（完整清单以 <code>packages/skill-family-contracts/src/registry.json</code> 为唯一真源）：project-manifest、profile-descriptor、managed-file-lock、operation-request、operation-result、migration-manifest、adapter-source、report-model、report-binding、host-descriptor、host-registry、host-capability-fact、host-probe-result、adapter-build-manifest、host-operation-plan、host-operation-receipt、state-event-envelope、state-snapshot-metadata；</li>
+<li>顶层 Contracts 对象：20 类（完整清单以 <code>packages/skill-family-contracts/src/registry.json</code> 为唯一真源）：project-manifest、profile-descriptor、managed-file-lock、operation-request、operation-result、migration-manifest、adapter-source、report-model、report-binding、host-descriptor、host-registry、host-capability-fact、host-probe-result、adapter-build-manifest、host-operation-plan、host-operation-receipt、state-event-envelope、state-snapshot-metadata、token-estimate-result、surface-scan-policy；</li>
 <li>Kit 顶层命令：4 个（scaffold、adopt-plan、projection、check）；</li>
 <li>强制机械规则：当前 9 条，预算不超过 20 条，绝对上限 30 条；CR-001 对登记表内全部 Schema 做统一编译；</li>
 <li>叶子包：3 个（skill-family-contracts、skill-family-harness-node、skill-family-engineering-kit）；</li>

package/docs/en/architecture/index.html

@@ -1972,7 +1972,7 @@ Horizontal (attachment surfaces, no new vertical layers):
 <tbody>
 <tr>
 <td>Contracts</td>
-<td>Structure, protocols, error codes, protocol-name registry; 18 top-level object kinds; 9 mandatory rules</td>
+<td>Structure, protocols, error codes, protocol-name registry; 20 top-level object kinds; 9 mandatory rules</td>
 <td>Business-field semantics, domain auditing, remote writes, model generation</td>
 </tr>
 <tr>
@@ -2024,7 +2024,7 @@ Horizontal (attachment surfaces, no new vertical layers):
 <li>Involves artifact relationships / version-lock → artifact-graph.</li>
 <li>Has only one consumer, or has not been proven to repeat across two real consumers → keep it with the consumer; do not expand Foundation.</li>
 </ol>
-<p>Step 8 is the expansion gate: a new component must justify that deleting it would force two or more real consumers to re-implement it, and this must be verified by an independent fixture. The machine-readable version is in <code>docs/agents/architecture-routing.md</code>.</p>
+<p>Step 8 is the expansion gate: a new component must justify that deleting it would force two or more real consumers to re-implement it, and this must be verified by an independent fixture; admission gate 1 additionally requires at least one existing real consumer plus one structurally isomorphic foreseeable consumer (the second consumer need not be live, but its need must be expressible with the same structure; adjustment record in FND-ADR-009). Step 9 is the finite-closed-semantics gate (FND-ADR-001 gate 8): a capability carrying limited domain semantics must satisfy either — its semantics are covered by a small stable closed enumeration, or it is a deterministic estimation primitive whose algorithm, scope, and bias direction are declared in the contract; this gate does not cancel gate 2's "semantics-free" veto. The machine-readable version is in <code>docs/agents/architecture-routing.md</code>.</p>
 <h2 id="Trust-and-Side-Effect-Boundaries">Trust and Side-Effect Boundaries<a class="headerlink" href="#Trust-and-Side-Effect-Boundaries" title="Permanent link">&para;</a></h2>
 <p>Foundation's trust assumptions and side-effect conventions are solidified per layer; callers judge risk accordingly:</p>
 <ul>
@@ -2050,6 +2050,14 @@ Involves tasks/retries/rework/acceptance? ──yes──▶ loop-agent
 Involves artifact relationships/version-lock? ──yes──▶ artifact-graph
         │no
 Only one consumer / not proven across two real consumers? ──yes──▶ keep with consumer, do not expand
+        │no
+Carries limited domain semantics? ──yes──▶ finite closed semantics: covered by a
+         │                stable closed enumeration, or a deterministic estimation
+         │                primitive (algorithm/scope/bias declared in the contract)
+         │                → admissible; otherwise keep with consumer
+         │                (FND-ADR-001 gate 8; does not cancel gate 2's veto)
+         │no
+        ──▶ admissible
 </code></pre>
 <h2 id="Routing-Relationships-with-External-Projects">Routing Relationships with External Projects<a class="headerlink" href="#Routing-Relationships-with-External-Projects" title="Permanent link">&para;</a></h2>
 <p>Foundation is not an all-powerful base. The following responsibilities are explicitly outside Foundation:</p>
@@ -2066,11 +2074,12 @@ Only one consumer / not proven across two real consumers? ──yes──▶ kee
 <li><strong>Host-access line</strong> (FND-FR-001/FND-FR-002, FND-ADR-003): Contracts registers descriptor/source/manifest/probe/plan/receipt; Harness implements generic source closure, atomic build/materialize, and probe classification; Kit injects the concrete Profile and trusted driver. Currently only describe/build/probe/plan are supported; <code>apply</code> is stably refused; install/uninstall/update are unimplemented.</li>
 <li><strong>Durable state-substrate line</strong> (FND-FR-003, FND-ADR-004): append-only events, hash chain, snapshots, and verification recovery; provides only the state substrate, not business semantics such as state machines, task nodes, retries, terminal states, or memory.</li>
 <li><strong>Human-report line</strong> (FND-FR-004, FND-ADR-005): a two-layer contract — machine results are the sole source of truth, and the human report is deterministically rendered from machine results (Markdown + digest binding + graded checks), not freely authored.</li>
+<li><strong>Finite-closed-semantics tools line</strong> (FND-ADR-009): baseline materialization + contentGuard (digest mismatch, mid-materialization change, and guard rejection all fail closed), generic read chokepoint (allowed-root set + optional identity predicate), strategy-driven surface scan (policy contract + injection self-test), token upper-bound estimation (deterministic estimation primitive with no model/network/tokenizer dependency), and a generic upper-bound guard (reusing the state-store event ledger and token-lock; the bound and over-limit policy are consumer-configured).</li>
 </ul>
 <p>The three-package structure is preserved and a fourth package is not split out (FND-ADR-007); artifact governance uses the artifact-graph CLI and version-lock (FND-ADR-006).</p>
 <h2 id="First-Version-Budget">First-Version Budget<a class="headerlink" href="#First-Version-Budget" title="Permanent link">&para;</a></h2>
 <ul>
-<li>Top-level Contracts objects: 18 kinds (the complete list uses <code>packages/skill-family-contracts/src/registry.json</code> as the sole source of truth): project-manifest, profile-descriptor, managed-file-lock, operation-request, operation-result, migration-manifest, adapter-source, report-model, report-binding, host-descriptor, host-registry, host-capability-fact, host-probe-result, adapter-build-manifest, host-operation-plan, host-operation-receipt, state-event-envelope, state-snapshot-metadata;</li>
+<li>Top-level Contracts objects: 20 kinds (the complete list uses <code>packages/skill-family-contracts/src/registry.json</code> as the sole source of truth): project-manifest, profile-descriptor, managed-file-lock, operation-request, operation-result, migration-manifest, adapter-source, report-model, report-binding, host-descriptor, host-registry, host-capability-fact, host-probe-result, adapter-build-manifest, host-operation-plan, host-operation-receipt, state-event-envelope, state-snapshot-metadata, token-estimate-result, surface-scan-policy;</li>
 <li>Kit top-level commands: 4 (scaffold, adopt-plan, projection, check);</li>
 <li>Mandatory mechanical rules: currently 9, budget not exceeding 20, absolute ceiling 30; CR-001 uniformly compiles all Schemas within the registry;</li>
 <li>Leaf packages: 3 (skill-family-contracts, skill-family-harness-node, skill-family-engineering-kit);</li>

package/docs/public/status/index.html

@@ -1792,17 +1792,17 @@
 <tbody>
 <tr>
 <td><code>skill-family-contracts</code></td>
-<td>0.3.0</td>
+<td>0.4.0</td>
 <td><a href="https://github.com/ifoohoo/skill-family-contracts">ifoohoo/skill-family-contracts</a></td>
 </tr>
 <tr>
 <td><code>skill-family-harness-node</code></td>
-<td>0.3.0</td>
+<td>0.4.0</td>
 <td><a href="https://github.com/ifoohoo/skill-family-harness-node">ifoohoo/skill-family-harness-node</a></td>
 </tr>
 <tr>
 <td><code>skill-family-engineering-kit</code></td>
-<td>0.3.0</td>
+<td>0.4.0</td>
 <td><a href="https://github.com/ifoohoo/skill-family-engineering-kit">ifoohoo/skill-family-engineering-kit</a></td>
 </tr>
 </tbody>

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

@@ -972,6 +972,146 @@
       </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">
@@ -2253,6 +2393,146 @@
       </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">
@@ -2296,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>
@@ -2308,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 />
@@ -2563,9 +2848,119 @@
 <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>