skill-family-harness-node 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.5.0 locale=en baseline=sha256:03eca87a8c9bea814e741518168696f17c869bdb71baf2046cef4c3596d9ebf3 -->
+## [0.5.0] - 2026-08-16
+
+This release adds the declared read surface assertion (FND-ADR-010) and the structured surface scanner (FND-ADR-011) to the stable Harness surface, growing HARNESS_CAPABILITIES from 16 to 18 entries, and adds three dependency-reviewed runtime libraries.
+
+### Added
+
+- Adds assertDeclaredReadSurface (FND-ADR-010): a no-execution, syntax-surface-only assertion that every node:fs named import inside a declared module set stays inside the consumer-declared read surface, with a closed violation vocabulary and a frozen declared-read-surface-result envelope.
+- Adds scanSurfaceStructured (FND-ADR-011): the structured sibling of scanSurface. IP-shaped candidates enter a single standard parse entry (ipaddr.js) with consumer-declared CIDR approval and fail closed when unparseable; scoped and unscoped coordinates, registries and hosts need consumer-declared approval; format adapters (pnpm-lockfile via @pnpm/lockfile.fs with yaml AST comment regions, and tree-json) parse structurally with no position-level exemptions; binary and symlink policies fail closed. The closed nine-rule vocabulary travels in details.rule of the structured-scan-violation mechanism error.
+- Adds three dependency-reviewed runtime libraries for the structured scanner, reviewed per FND-ADR-006 section-4 analogy (dependency-closure pre-review, executor self-review pending independent review): ipaddr.js 2.5.0 (MIT, zero dependencies), yaml 2.9.0 (ISC), and @pnpm/lockfile.fs 1001.1.35 (MIT, 18 transitive dependencies all inside the approved public coordinates).
+- Grows HARNESS_CAPABILITIES from 16 to 18 entries for the two new mechanisms.
+
+### Changed
+
+- Documents the relationship of the two policy documents to workspace-private leak policies: a workspace-private leak-policy.json instance document is not a subset, not isomorphic and not a migration target of the surface-scan-policy or structured-scan-policy schemas — the documents share rule vocabulary and fail-closed semantics by design, but their byte-level shapes are independent and must not be compared for compatibility. scanSurface is the execution-core generalization projection: the public, consumer-parameterized form of the same mechanism family, without any private identity, path, or approval-list interpretation of its own.
+- Records the cost of the dependency-review decision honestly: the harness tarball grows with the @pnpm/lockfile.fs closure, the thin-runtime property changes from zero third-party runtime dependencies to three reviewed ones, and the pnpm-lockfile adapter writes one temporary lockfile copy under the OS temp directory (removed afterwards). The engineering-kit offline-consumer verification gates now derive the complete third-party production closure of the three Foundation packages mechanically (identity-deduplicated, npm: alias-aware, range-scoped override selectors) instead of a single-package closure, so the review decision is continuously verified against the real installed bytes.
+- Keeps mechanism purity: no execution of scanned files, no model calls, no network; symlinked entries are never followed.
+
+### Upgrade Notes
+
+Version 0.5.0 is the FND-ADR-010/011 harness line. Mechanism imports use the stable capability names published in HARNESS_CAPABILITIES; structured-scan policies must pass the structured-scan-policy contract validation of contract-spec 1.5.0.
+<!-- release-skill:changelog:end version=0.5.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.4.0 locale=en baseline=sha256:72d3fe048ced8eb44a84fabe6f1fdd2eb0c938b4f6bb98740474f72aec04d873 -->
 ## [0.4.0] - 2026-08-16
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,29 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.5.0 locale=zh-CN baseline=sha256:003472359596147fe26ad2ba53a82303a217c28cb89a6afacdaa955793001f71 -->
+## [0.5.0] - 2026-08-16
+
+本版在稳定 Harness 面上新增声明读取表面断言（FND-ADR-010）与结构化表面扫描器（FND-ADR-011），HARNESS_CAPABILITIES 从 16 项增至 18 项，并引入三个经依赖评审的运行时库。
+
+### 新增
+
+- 新增 assertDeclaredReadSurface（FND-ADR-010）：不执行、仅语法面的断言，声明模块集内的每个 node:fs 具名导入必须落在消费者声明的读取表面内，违规词汇表为闭集，返回冻结的 declared-read-surface-result 信封。
+- 新增 scanSurfaceStructured（FND-ADR-011）：scanSurface 的结构化兄弟。IP 形候选统一进入单一标准解析入口（ipaddr.js），按消费者声明的 CIDR 批准，不可解析即失败关闭；坐标（scoped 与非 scoped）、注册表与主机均需消费者声明批准；格式适配器（pnpm-lockfile 经 @pnpm/lockfile.fs + yaml AST 注释区域，tree-json 经 JSON.parse）结构化解析且无位置级豁免；二进制与符号链接策略失败关闭。闭集九规则词汇表经 structured-scan-violation 机制错误的 details.rule 承载。
+- 为结构化扫描器引入三个经依赖评审的运行时库，评审按 FND-ADR-006 第 4 节类比执行（依赖闭包预审，执行者自审，独立复核另行安排）：ipaddr.js 2.5.0（MIT，零依赖）、yaml 2.9.0（ISC）、@pnpm/lockfile.fs 1001.1.35（MIT，18 个传递依赖全部在批准公共坐标内）。
+- HARNESS_CAPABILITIES 从 16 项增至 18 项，覆盖两个新机制。
+
+### 变更
+
+- 显式说明两个策略文档与工作区私有 leak 策略的关系：工作区私有的 leak-policy.json 实例文档既不是 surface-scan-policy 或 structured-scan-policy schema 的子集、也不同构、更不是迁移目标——两类文档按设计共享规则词汇与失败关闭语义，但字节级形状相互独立，不得比较兼容性。scanSurface 是执行内核通用化投影：同一机制族的公开、消费者参数化形态，自身不解释任何私有身份、路径或批准清单。
+- 如实记录依赖评审决策的成本：harness tarball 随 @pnpm/lockfile.fs 闭包扩大；薄运行时属性从零第三方运行时依赖变为三个经评审依赖；pnpm-lockfile 适配器会在 OS 临时目录写一份临时锁文件副本（用后即删）。engineering-kit 的离线消费者验证门随之把第三方闭包推导从单包闭包机械扩展为三个 Foundation 包的完整生产闭包（真实身份去重、npm: 别名感知、range-scoped override selector），使评审决策持续对着真实安装字节被验证。
+- 保持机制纯度：不执行被扫描文件、无模型调用、无网络；永不跟随符号链接。
+
+### 升级说明
+
+0.5.0 是 FND-ADR-010/011 harness 线。机制导入使用 HARNESS_CAPABILITIES 公布的稳定能力名；structured-scan 策略必须通过契约规格 1.5.0 的 structured-scan-policy 契约校验。
+<!-- release-skill:changelog:end version=0.5.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.4.0 locale=zh-CN baseline=sha256:dafaa1100bf6163a28d53fc982a30e8325d8bd3cab43bbb6daf2e6002befa2c1 -->
 ## [0.4.0] - 2026-08-16
 

package/README.md

@@ -4,30 +4,31 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.4.0 -->
+<!-- release-skill:release-version: 0.5.0 -->
 
 The **single default Node implementation** of the Contracts mechanism protocol. This is a thin runtime: it only implements the mechanism protocol, introduces no business semantics, and does not provide a second-language implementation.
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.4.0** (2026-08-16)
+**0.5.0** (2026-08-16)
 
-This release adds five finite-closed-semantics mechanisms and a token-lock primitive to the stable Harness surface (FND-ADR-009), grows HARNESS_CAPABILITIES from 9 to 16 entries, and ships the rename-directory-no-replace native-prebuild candidate.
+This release adds the declared read surface assertion (FND-ADR-010) and the structured surface scanner (FND-ADR-011) to the stable Harness surface, growing HARNESS_CAPABILITIES from 16 to 18 entries, and adds three dependency-reviewed runtime libraries.
 
 **Added**
 
-- Adds five finite-closed-semantics mechanisms (FND-ADR-009), namely frozen-baseline materialization with contentGuard, the generic read chokepoint, strategy-driven surface scanning, deterministic token upper-bound estimation, and the generic upper-bound guard.
-- Adds the token-lock primitive for exclusive token-file publication and digest verification.
-- Grows HARNESS_CAPABILITIES from 9 to 16 entries for the new mechanisms.
-- Adds the rename-directory-no-replace candidate, a native-prebuild addon proving no-replace directory renames on darwin-arm64, darwin-x64, linux-arm64-gnu, and linux-x64-gnu, with a release receipt and SBOM.
+- Adds assertDeclaredReadSurface (FND-ADR-010): a no-execution, syntax-surface-only assertion that every node:fs named import inside a declared module set stays inside the consumer-declared read surface, with a closed violation vocabulary and a frozen declared-read-surface-result envelope.
+- Adds scanSurfaceStructured (FND-ADR-011): the structured sibling of scanSurface. IP-shaped candidates enter a single standard parse entry (ipaddr.js) with consumer-declared CIDR approval and fail closed when unparseable; scoped and unscoped coordinates, registries and hosts need consumer-declared approval; format adapters (pnpm-lockfile via @pnpm/lockfile.fs with yaml AST comment regions, and tree-json) parse structurally with no position-level exemptions; binary and symlink policies fail closed. The closed nine-rule vocabulary travels in details.rule of the structured-scan-violation mechanism error.
+- Adds three dependency-reviewed runtime libraries for the structured scanner, reviewed per FND-ADR-006 section-4 analogy (dependency-closure pre-review, executor self-review pending independent review): ipaddr.js 2.5.0 (MIT, zero dependencies), yaml 2.9.0 (ISC), and @pnpm/lockfile.fs 1001.1.35 (MIT, 18 transitive dependencies all inside the approved public coordinates).
+- Grows HARNESS_CAPABILITIES from 16 to 18 entries for the two new mechanisms.
 
 **Changed**
 
-- Keeps the Quickstart Profile v2 Task/Result exchange verification delivered in 0.3.0, including real-byte recomputation for path-backed outputs and evidence, duplicate Resource id rejection, and exact evidence binding verification.
-- Leaves method selection, retry policy, and domain result interpretation to the consumer.
+- Documents the relationship of the two policy documents to workspace-private leak policies: a workspace-private leak-policy.json instance document is not a subset, not isomorphic and not a migration target of the surface-scan-policy or structured-scan-policy schemas — the documents share rule vocabulary and fail-closed semantics by design, but their byte-level shapes are independent and must not be compared for compatibility. scanSurface is the execution-core generalization projection: the public, consumer-parameterized form of the same mechanism family, without any private identity, path, or approval-list interpretation of its own.
+- Records the cost of the dependency-review decision honestly: the harness tarball grows with the @pnpm/lockfile.fs closure, the thin-runtime property changes from zero third-party runtime dependencies to three reviewed ones, and the pnpm-lockfile adapter writes one temporary lockfile copy under the OS temp directory (removed afterwards). The engineering-kit offline-consumer verification gates now derive the complete third-party production closure of the three Foundation packages mechanically (identity-deduplicated, npm: alias-aware, range-scoped override selectors) instead of a single-package closure, so the review decision is continuously verified against the real installed bytes.
+- Keeps mechanism purity: no execution of scanned files, no model calls, no network; symlinked entries are never followed.
 
 **Upgrade Notes**
 
-Version 0.4.0 is released on npm and the public mirror. Pin the candidate subpath to exactly 0.4.0; mechanism imports use the stable capability names published in HARNESS_CAPABILITIES.
+Version 0.5.0 is the FND-ADR-010/011 harness line. Mechanism imports use the stable capability names published in HARNESS_CAPABILITIES; structured-scan policies must pass the structured-scan-policy contract validation of contract-spec 1.5.0.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -41,14 +42,14 @@ The Harness consumes `skill-family-contracts` (a workspace dependency), reusing
 ## Installation and Minimal Example
 
 ```sh
-npm install skill-family-harness-node@0.4.0
+npm install skill-family-harness-node@0.5.0
 npm info skill-family-harness-node --help
 ```
 
 The minimal example shows validating a contract document inside Node:
 
 ```js
-// Run from an empty directory: npm install skill-family-harness-node@0.4.0
+// Run from an empty directory: npm install skill-family-harness-node@0.5.0
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {

package/README.zh-CN.md

@@ -5,30 +5,31 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.4.0 -->
+<!-- release-skill:release-version: 0.5.0 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.4.0** (2026-08-16)
+**0.5.0** (2026-08-16)
 
-本版在稳定 Harness 面上新增五项有限封闭语义机制与 token-lock 原语（FND-ADR-009），HARNESS_CAPABILITIES 从 9 项增至 16 项，并随附 rename-directory-no-replace 原生预编译候选。
+本版在稳定 Harness 面上新增声明读取表面断言（FND-ADR-010）与结构化表面扫描器（FND-ADR-011），HARNESS_CAPABILITIES 从 16 项增至 18 项，并引入三个经依赖评审的运行时库。
 
 **新增**
 
-- 新增五项有限封闭语义机制（FND-ADR-009）：冻结基线物化 + contentGuard、通用只读 chokepoint、策略化表面扫描、确定性 token 上界估算与通用上限守卫。
-- 新增 token-lock 原语：独占 token 文件发布与摘要复验。
-- HARNESS_CAPABILITIES 从 9 项增至 16 项，覆盖上述新机制。
-- 新增 rename-directory-no-replace 候选：覆盖 darwin-arm64、darwin-x64、linux-arm64-gnu、linux-x64-gnu 的原生预编译 no-replace 目录改名 addon，附带发布 receipt 与 SBOM。
+- 新增 assertDeclaredReadSurface（FND-ADR-010）：不执行、仅语法面的断言，声明模块集内的每个 node:fs 具名导入必须落在消费者声明的读取表面内，违规词汇表为闭集，返回冻结的 declared-read-surface-result 信封。
+- 新增 scanSurfaceStructured（FND-ADR-011）：scanSurface 的结构化兄弟。IP 形候选统一进入单一标准解析入口（ipaddr.js），按消费者声明的 CIDR 批准，不可解析即失败关闭；坐标（scoped 与非 scoped）、注册表与主机均需消费者声明批准；格式适配器（pnpm-lockfile 经 @pnpm/lockfile.fs + yaml AST 注释区域，tree-json 经 JSON.parse）结构化解析且无位置级豁免；二进制与符号链接策略失败关闭。闭集九规则词汇表经 structured-scan-violation 机制错误的 details.rule 承载。
+- 为结构化扫描器引入三个经依赖评审的运行时库，评审按 FND-ADR-006 第 4 节类比执行（依赖闭包预审，执行者自审，独立复核另行安排）：ipaddr.js 2.5.0（MIT，零依赖）、yaml 2.9.0（ISC）、@pnpm/lockfile.fs 1001.1.35（MIT，18 个传递依赖全部在批准公共坐标内）。
+- HARNESS_CAPABILITIES 从 16 项增至 18 项，覆盖两个新机制。
 
 **变更**
 
-- 保持 0.3.0 交付的 Quickstart Profile v2 Task/Result 交换校验：path-backed output 与 evidence 重算真实字节、拒绝重复 Resource id、evidence 精确绑定逐项复验。
-- 方法选择、重试策略与领域结果解释继续归消费者所有。
+- 显式说明两个策略文档与工作区私有 leak 策略的关系：工作区私有的 leak-policy.json 实例文档既不是 surface-scan-policy 或 structured-scan-policy schema 的子集、也不同构、更不是迁移目标——两类文档按设计共享规则词汇与失败关闭语义，但字节级形状相互独立，不得比较兼容性。scanSurface 是执行内核通用化投影：同一机制族的公开、消费者参数化形态，自身不解释任何私有身份、路径或批准清单。
+- 如实记录依赖评审决策的成本：harness tarball 随 @pnpm/lockfile.fs 闭包扩大；薄运行时属性从零第三方运行时依赖变为三个经评审依赖；pnpm-lockfile 适配器会在 OS 临时目录写一份临时锁文件副本（用后即删）。engineering-kit 的离线消费者验证门随之把第三方闭包推导从单包闭包机械扩展为三个 Foundation 包的完整生产闭包（真实身份去重、npm: 别名感知、range-scoped override selector），使评审决策持续对着真实安装字节被验证。
+- 保持机制纯度：不执行被扫描文件、无模型调用、无网络；永不跟随符号链接。
 
 **升级说明**
 
-0.4.0 已发布到 npm 与 public 镜像仓。candidate 子路径必须精确锁定 0.4.0；机制导入使用 HARNESS_CAPABILITIES 公布的稳定能力名。
+0.5.0 是 FND-ADR-010/011 harness 线。机制导入使用 HARNESS_CAPABILITIES 公布的稳定能力名；structured-scan 策略必须通过契约规格 1.5.0 的 structured-scan-policy 契约校验。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -42,14 +43,14 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 ## 安装和最小示例
 
 ```sh
-npm install skill-family-harness-node@0.4.0
+npm install skill-family-harness-node@0.5.0
 npm info skill-family-harness-node --help
 ```
 
 最小示例演示在 Node 内校验一份契约文档：
 
 ```js
-// 从空目录运行：npm install skill-family-harness-node@0.4.0
+// 从空目录运行：npm install skill-family-harness-node@0.5.0
 import { validateContractDocument } from "skill-family-harness-node";
 
 const document = {

package/package.json

@@ -5,7 +5,10 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node/issues"
   },
   "dependencies": {
-    "skill-family-contracts": "0.4.0"
+    "@pnpm/lockfile.fs": "1001.1.35",
+    "ipaddr.js": "2.5.0",
+    "skill-family-contracts": "0.5.0",
+    "yaml": "2.9.0"
   },
   "description": "Thin Node.js mechanism runtime for Skill Family engineering contracts.",
   "engines": {
@@ -39,7 +42,7 @@
     "url": "https://github.com/ifoohoo/skill-family-harness-node.git"
   },
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "scripts": {
     "check": "node --test",
     "test": "node --test"

package/release-notes/0.5.0.yaml

@@ -0,0 +1,29 @@
+version: 0.5.0
+date: 2026-08-16
+locales:
+  en:
+    summary: This release adds the declared read surface assertion (FND-ADR-010) and the structured surface scanner (FND-ADR-011) to the stable Harness surface, growing HARNESS_CAPABILITIES from 16 to 18 entries, and adds three dependency-reviewed runtime libraries.
+    changes:
+      added:
+        - "Adds assertDeclaredReadSurface (FND-ADR-010): a no-execution, syntax-surface-only assertion that every node:fs named import inside a declared module set stays inside the consumer-declared read surface, with a closed violation vocabulary and a frozen declared-read-surface-result envelope."
+        - "Adds scanSurfaceStructured (FND-ADR-011): the structured sibling of scanSurface. IP-shaped candidates enter a single standard parse entry (ipaddr.js) with consumer-declared CIDR approval and fail closed when unparseable; scoped and unscoped coordinates, registries and hosts need consumer-declared approval; format adapters (pnpm-lockfile via @pnpm/lockfile.fs with yaml AST comment regions, and tree-json) parse structurally with no position-level exemptions; binary and symlink policies fail closed. The closed nine-rule vocabulary travels in details.rule of the structured-scan-violation mechanism error."
+        - "Adds three dependency-reviewed runtime libraries for the structured scanner, reviewed per FND-ADR-006 section-4 analogy (dependency-closure pre-review, executor self-review pending independent review): ipaddr.js 2.5.0 (MIT, zero dependencies), yaml 2.9.0 (ISC), and @pnpm/lockfile.fs 1001.1.35 (MIT, 18 transitive dependencies all inside the approved public coordinates)."
+        - Grows HARNESS_CAPABILITIES from 16 to 18 entries for the two new mechanisms.
+      changed:
+        - "Documents the relationship of the two policy documents to workspace-private leak policies: a workspace-private leak-policy.json instance document is not a subset, not isomorphic and not a migration target of the surface-scan-policy or structured-scan-policy schemas — the documents share rule vocabulary and fail-closed semantics by design, but their byte-level shapes are independent and must not be compared for compatibility. scanSurface is the execution-core generalization projection: the public, consumer-parameterized form of the same mechanism family, without any private identity, path, or approval-list interpretation of its own."
+        - "Records the cost of the dependency-review decision honestly: the harness tarball grows with the @pnpm/lockfile.fs closure, the thin-runtime property changes from zero third-party runtime dependencies to three reviewed ones, and the pnpm-lockfile adapter writes one temporary lockfile copy under the OS temp directory (removed afterwards). The engineering-kit offline-consumer verification gates now derive the complete third-party production closure of the three Foundation packages mechanically (identity-deduplicated, npm: alias-aware, range-scoped override selectors) instead of a single-package closure, so the review decision is continuously verified against the real installed bytes."
+        - "Keeps mechanism purity: no execution of scanned files, no model calls, no network; symlinked entries are never followed."
+    upgradeNotes: Version 0.5.0 is the FND-ADR-010/011 harness line. Mechanism imports use the stable capability names published in HARNESS_CAPABILITIES; structured-scan policies must pass the structured-scan-policy contract validation of contract-spec 1.5.0.
+  zh-CN:
+    summary: 本版在稳定 Harness 面上新增声明读取表面断言（FND-ADR-010）与结构化表面扫描器（FND-ADR-011），HARNESS_CAPABILITIES 从 16 项增至 18 项，并引入三个经依赖评审的运行时库。
+    changes:
+      added:
+        - 新增 assertDeclaredReadSurface（FND-ADR-010）：不执行、仅语法面的断言，声明模块集内的每个 node:fs 具名导入必须落在消费者声明的读取表面内，违规词汇表为闭集，返回冻结的 declared-read-surface-result 信封。
+        - 新增 scanSurfaceStructured（FND-ADR-011）：scanSurface 的结构化兄弟。IP 形候选统一进入单一标准解析入口（ipaddr.js），按消费者声明的 CIDR 批准，不可解析即失败关闭；坐标（scoped 与非 scoped）、注册表与主机均需消费者声明批准；格式适配器（pnpm-lockfile 经 @pnpm/lockfile.fs + yaml AST 注释区域，tree-json 经 JSON.parse）结构化解析且无位置级豁免；二进制与符号链接策略失败关闭。闭集九规则词汇表经 structured-scan-violation 机制错误的 details.rule 承载。
+        - 为结构化扫描器引入三个经依赖评审的运行时库，评审按 FND-ADR-006 第 4 节类比执行（依赖闭包预审，执行者自审，独立复核另行安排）：ipaddr.js 2.5.0（MIT，零依赖）、yaml 2.9.0（ISC）、@pnpm/lockfile.fs 1001.1.35（MIT，18 个传递依赖全部在批准公共坐标内）。
+        - HARNESS_CAPABILITIES 从 16 项增至 18 项，覆盖两个新机制。
+      changed:
+        - 显式说明两个策略文档与工作区私有 leak 策略的关系：工作区私有的 leak-policy.json 实例文档既不是 surface-scan-policy 或 structured-scan-policy schema 的子集、也不同构、更不是迁移目标——两类文档按设计共享规则词汇与失败关闭语义，但字节级形状相互独立，不得比较兼容性。scanSurface 是执行内核通用化投影：同一机制族的公开、消费者参数化形态，自身不解释任何私有身份、路径或批准清单。
+        - "如实记录依赖评审决策的成本：harness tarball 随 @pnpm/lockfile.fs 闭包扩大；薄运行时属性从零第三方运行时依赖变为三个经评审依赖；pnpm-lockfile 适配器会在 OS 临时目录写一份临时锁文件副本（用后即删）。engineering-kit 的离线消费者验证门随之把第三方闭包推导从单包闭包机械扩展为三个 Foundation 包的完整生产闭包（真实身份去重、npm: 别名感知、range-scoped override selector），使评审决策持续对着真实安装字节被验证。"
+        - 保持机制纯度：不执行被扫描文件、无模型调用、无网络；永不跟随符号链接。
+    upgradeNotes: 0.5.0 是 FND-ADR-010/011 harness 线。机制导入使用 HARNESS_CAPABILITIES 公布的稳定能力名；structured-scan 策略必须通过契约规格 1.5.0 的 structured-scan-policy 契约校验。

package/src/declared-read-surface.mjs

@@ -0,0 +1,198 @@
+import path from "node:path";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
+
+/**
+ * Static declared read surface verification (FND-ADR-010).
+ *
+ * assertDeclaredReadSurface({ root, declaredReaders }) checks, by static
+ * source analysis, that every `.mjs`/`.js` module under `root` only reads
+ * node:fs through the consumer-declared reader set:
+ *
+ *   - a module that imports named APIs from "node:fs" without being declared
+ *     violates rule `undeclared-module-imports-fs`;
+ *   - a declared module importing an API outside its declared set violates
+ *     rule `fs-api-outside-declared-set`;
+ *   - any write-family fs API name appearing anywhere in the tree (whole
+ *     source substring detection, including comments and string literals)
+ *     violates rule `write-family-fs-api` (conservative approximation: static
+ *     syntax-level violations are never under-reported).
+ *
+ * The verdict semantics mirror the audit tree's P3 check one-to-one; the
+ * result is shaped as the contracts `declared-read-surface-result` envelope
+ * whose scope, rule enumeration and guarantees are the machine contract.
+ * Input is fully parameterized: root and declaredReaders are consumer data,
+ * the mechanism knows no audit paths, no workspace layout, and no business
+ * meaning of any module.
+ *
+ * Violations are collected as an evidence list (deterministic order:
+ * sorted module list, then rule order per module) rather than stopping at
+ * the first hit; `ok` is false exactly when the list is non-empty.
+ *
+ * Mechanism purity: read-only (never writes, never executes the scanned
+ * modules, no model call, no network); symlinked entries under the root are
+ * never followed and never scanned (conservative: a symlink may not smuggle
+ * a module out of the declared surface).
+ */
+
+const MODULE_EXTENSIONS = [".mjs", ".js"];
+const FS_NAMED_IMPORT_PATTERN = /import\s*\{([^}]*)\}\s*from\s*"node:fs"/g;
+
+// Write-family API names are built by composition so this module's own
+// source never contains the full forbidden names as literals (self-hit
+// hygiene, inherited from the audit tree's P3 check). Detection of scanned
+// modules is unaffected: they would spell the full names.
+const WRITE_FS_VERBS = ["writeFile", "appendFile", "mkdir", "rm", "unlink", "rename", "copyFile"];
+const WRITE_FS_APIS = WRITE_FS_VERBS.map((verb) => `${verb}Sync`).concat([
+  `${"createWrite"}Stream`,
+]);
+
+export const DECLARED_READ_SURFACE_RULES = Object.freeze({
+  UNDECLARED_MODULE_IMPORTS_FS: "undeclared-module-imports-fs",
+  FS_API_OUTSIDE_DECLARED_SET: "fs-api-outside-declared-set",
+  WRITE_FAMILY_FS_API: "write-family-fs-api",
+});
+
+const RESULT_GUARANTEES = Object.freeze([
+  "syntax-surface-only",
+  "conservative-approximation",
+  "no-execution",
+  "no-model-calls",
+  "no-network-access",
+]);
+
+function invalidInput(reason, extra) {
+  return mechanismError(
+    HARNESS_ERROR_KINDS.DECLARED_READ_SURFACE_INVALID,
+    `assertDeclaredReadSurface: ${reason}`,
+    extra,
+  );
+}
+
+function assertPlainObject(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw invalidInput(`${label} must be a plain object`);
+  }
+}
+
+function isValidDeclaredModulePath(modulePath) {
+  if (typeof modulePath !== "string" || modulePath.length === 0) return false;
+  if (modulePath.includes("\0")) return false;
+  if (modulePath.includes("\\")) return false;
+  if (path.posix.isAbsolute(modulePath)) return false;
+  if (/^[A-Za-z]:/.test(modulePath)) return false;
+  const normalized = path.posix.normalize(modulePath);
+  if (normalized === "." || normalized === "..") return false;
+  if (normalized.split("/").some((segment) => segment === "..")) return false;
+  return normalized === modulePath;
+}
+
+function collectModules(root) {
+  const modules = [];
+  const walk = (directory) => {
+    const entries = readdirSync(directory, { withFileTypes: true }).sort((a, b) =>
+      a.name.localeCompare(b.name),
+    );
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue; // never followed, never scanned
+      const fullPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile() && MODULE_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) {
+        modules.push(fullPath);
+      }
+    }
+  };
+  walk(root);
+  return modules;
+}
+
+function namedFsImports(source) {
+  return [...source.matchAll(FS_NAMED_IMPORT_PATTERN)].flatMap((match) =>
+    match[1].split(",").map((api) => api.trim()).filter(Boolean),
+  );
+}
+
+/**
+ * Static declared read surface verification. Returns the contracts
+ * declared-read-surface-result envelope (frozen). Invalid inputs (non-empty
+ * root that is not a directory, empty declaredReaders, illegal module path
+ * shapes, malformed declared sets) throw SFC2004 with details.kind
+ * declared-read-surface-invalid; a detected violation is reported in the
+ * result's violations list (ok: false), never as an exception.
+ */
+export function assertDeclaredReadSurface({ root, declaredReaders } = {}) {
+  if (typeof root !== "string" || root.length === 0) {
+    throw invalidInput("root must be a non-empty path");
+  }
+  assertPlainObject(declaredReaders, "declaredReaders");
+  const readerKeys = Object.keys(declaredReaders);
+  if (readerKeys.length === 0) {
+    throw invalidInput("declaredReaders must declare at least one reader module");
+  }
+  const declared = new Map();
+  for (const key of readerKeys) {
+    if (!isValidDeclaredModulePath(key)) {
+      throw invalidInput(`declared reader module path has an illegal shape: ${JSON.stringify(key)}`);
+    }
+    const apis = declaredReaders[key];
+    if (!Array.isArray(apis)) {
+      throw invalidInput(`declared set for ${key} must be an array of fs API names`);
+    }
+    for (const api of apis) {
+      if (typeof api !== "string" || api.length === 0) {
+        throw invalidInput(`declared set for ${key} contains a malformed fs API name`);
+      }
+    }
+    declared.set(key, apis);
+  }
+
+  const rootResolved = path.resolve(root);
+  let rootStat;
+  try {
+    rootStat = statSync(rootResolved);
+  } catch {
+    throw invalidInput("root does not exist or cannot be inspected", { root: "<opaque>" });
+  }
+  if (!rootStat.isDirectory()) {
+    throw invalidInput("root is not a directory", { root: "<opaque>" });
+  }
+
+  const modules = collectModules(rootResolved);
+  const violations = [];
+  const pushViolation = (entry) => violations.push(entry);
+
+  for (const module of modules) {
+    const relative = path.relative(rootResolved, module).split(path.sep).join("/");
+    const source = readFileSync(module, "utf8");
+    const fsImports = namedFsImports(source);
+    const allowed = declared.get(relative);
+    if (fsImports.length > 0 && allowed === undefined) {
+      pushViolation({ module: relative, rule: DECLARED_READ_SURFACE_RULES.UNDECLARED_MODULE_IMPORTS_FS });
+    }
+    if (allowed !== undefined) {
+      for (const api of fsImports) {
+        if (!allowed.includes(api)) {
+          pushViolation({ module: relative, api, rule: DECLARED_READ_SURFACE_RULES.FS_API_OUTSIDE_DECLARED_SET });
+        }
+      }
+    }
+    for (const api of WRITE_FS_APIS) {
+      if (source.includes(api)) {
+        pushViolation({ module: relative, api, rule: DECLARED_READ_SURFACE_RULES.WRITE_FAMILY_FS_API });
+      }
+    }
+  }
+
+  return Object.freeze({
+    schemaVersion: 1,
+    kind: "skill-family.declared-read-surface-result",
+    ok: violations.length === 0,
+    violations,
+    scannedModules: modules.map((module) =>
+      path.relative(rootResolved, module).split(path.sep).join("/"),
+    ),
+    scope: "esm-named-imports-only",
+    guarantees: [...RESULT_GUARANTEES],
+  });
+}

package/src/errors.mjs

@@ -65,6 +65,10 @@ export const HARNESS_ERROR_KINDS = Object.freeze({
   READ_CHOKEPOINT_REJECTED: "read-chokepoint-rejected",
   SURFACE_SCAN_VIOLATION: "surface-scan-violation",
   SCAN_POLICY_INVALID: "scan-policy-invalid",
+  DECLARED_READ_SURFACE_VIOLATION: "declared-read-surface-violation",
+  DECLARED_READ_SURFACE_INVALID: "declared-read-surface-invalid",
+  STRUCTURED_SCAN_VIOLATION: "structured-scan-violation",
+  STRUCTURED_SCAN_INVALID: "structured-scan-invalid",
   UPPER_BOUND_EXCEEDED: "upper-bound-exceeded",
 });
 

package/src/index.mjs

@@ -25,6 +25,8 @@ export const HARNESS_CAPABILITIES = Object.freeze([
   "baseline-materialization",
   "read-chokepoint",
   "surface-scan",
+  "declared-read-surface",
+  "structured-scan",
   "token-estimation",
   "upper-bound-guard",
 ]);
@@ -66,6 +68,10 @@ export { createReadChokepoint } from "./chokepoint.mjs";
 
 export { scanSurface } from "./surface-scan.mjs";
 
+export { assertDeclaredReadSurface } from "./declared-read-surface.mjs";
+
+export { scanSurfaceStructured, STRUCTURED_SCAN_RULES, isIpv6ShapedRun, extractIpCandidates, normalizeIpToken, classifyIpToken, collectLockfileCommentRegions } from "./structured-scan.mjs";
+
 export { estimateTokenUpperBound } from "./token-estimate.mjs";
 
 export {

package/src/structured-scan.mjs

@@ -0,0 +1,652 @@
+import { findSchemaByObject } from "skill-family-contracts";
+import { mkdtempSync, rmSync, writeFileSync, lstatSync, readlinkSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import ipaddr from "ipaddr.js";
+import { readWantedLockfile } from "@pnpm/lockfile.fs";
+import { parseDocument, visit } from "yaml";
+import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
+import { classifyPathInput, readFileContained, resolveContained } from "./paths.mjs";
+import { validateContractDocument } from "./validation.mjs";
+
+const POLICY_SCHEMA_ID = findSchemaByObject("structured-scan-policy").$id;
+
+/**
+ * Structured surface scanner (FND-ADR-011).
+ *
+ * scanSurfaceStructured({ root, relPaths, policy }) is the public,
+ * consumer-parameterized form of the same mechanism family as scanSurface:
+ * it scans consumer-declared files under a consumer-declared root against a
+ * consumer-declared structured-scan-policy contract document, and fails
+ * closed on the first hit (structured-scan-violation with details.rule from
+ * the closed vocabulary). The mechanism owns no private identity, no
+ * workspace layout, no approval list: every network, registry, coordinate,
+ * adapter, host-key pattern and binary approval is consumer data.
+ *
+ * Closed rule vocabulary (details.rule):
+ *   non-public-address                  CIDR-outside or unparseable IP-shaped token
+ *   private-npm-scope                   scoped coordinate outside approvedCoordinates
+ *   unapproved-dependency-coordinate    unscoped coordinate outside approvedCoordinates
+ *   non-approved-registry               URL reference outside approvedRegistries
+ *   non-reserved-hostname               host that is not localhost, not an approved
+ *                                       registry host, and not hostKeyPattern-shaped
+ *   format-adapter-parse-failed         a registered adapter could not parse the file
+ *   format-adapter-unknown              a registered adapter name is not implemented
+ *   binary-unclassified                 non-text file outside binaryPolicy.approvedPaths
+ *   symlink-forbidden                   symlinked entry (readlink records the target
+ *                                       text; the target is never followed)
+ *
+ * Address semantics: lexical candidate boundaries (rules (A)-(E) for
+ * IPv6-shaped runs plus dotted-decimal IPv4 shape) feed a single standard
+ * parse entry (ipaddr.js); an unparseable candidate fails closed
+ * (non-public-address) — no undocumented syntax exemption exists. IPv4-mapped
+ * and compatible embedded addresses delegate to the embedded IPv4's CIDR
+ * classification. Bias direction is declared in the policy contract:
+ * conservative, never silently skipped.
+ *
+ * Format adapters: files whose relative path matches a registered
+ * formatAdapters[].pathPattern are parsed structurally; a parse failure is
+ * format-adapter-parse-failed (fail-closed) and an unregistered adapter name
+ * is format-adapter-unknown (fail-closed). There is no position-level whole
+ * key or whole file exemption: every key and every string leaf value of a
+ * parsed document still runs the full structure rules. Built-in adapters:
+ * "pnpm-lockfile" (@pnpm/lockfile.fs semantic object plus yaml AST comment
+ * regions) and "tree-json" (JSON.parse).
+ *
+ * Mechanism purity: never executes scanned files, no model call, no network;
+ * the only write is a temporary lockfile copy under the OS temp directory
+ * (cleaned up) for the pnpm-lockfile adapter. Symlinked entries are never
+ * followed.
+ */
+
+export const STRUCTURED_SCAN_RULES = Object.freeze({
+  NON_PUBLIC_ADDRESS: "non-public-address",
+  PRIVATE_NPM_SCOPE: "private-npm-scope",
+  UNAPPROVED_DEPENDENCY_COORDINATE: "unapproved-dependency-coordinate",
+  NON_APPROVED_REGISTRY: "non-approved-registry",
+  NON_RESERVED_HOSTNAME: "non-reserved-hostname",
+  FORMAT_ADAPTER_PARSE_FAILED: "format-adapter-parse-failed",
+  FORMAT_ADAPTER_UNKNOWN: "format-adapter-unknown",
+  BINARY_UNCLASSIFIED: "binary-unclassified",
+  SYMLINK_FORBIDDEN: "symlink-forbidden",
+});
+
+// ---------------------------------------------------------------- patterns
+
+const URL_PATTERN = /[A-Za-z][A-Za-z0-9+.-]*:\/\/(\[[^\]/\s]+\]|[A-Za-z0-9][A-Za-z0-9-]*(?:\.[A-Za-z0-9-]+)+[^/\s"'<>\\:]*)/g;
+const EMAIL_PATTERN = /[A-Za-z0-9._%+-]+@([A-Za-z0-9][A-Za-z0-9.-]*\.[A-Za-z]{2,})/g;
+const HOST_KEY_STRING_PATTERN = /"(?:host|hostname|server|endpoint)"\s*:\s*"([^"]+)"/g;
+const HOST_KEY_ARRAY_PATTERN = /"hosts"\s*:\s*\[([^\]]*)\]/g;
+const QUOTED_TOKEN_PATTERN = /"([^"]+)"/g;
+const NPM_SCOPE_PATTERN = /(?<![A-Za-z0-9._%+-])@([a-z0-9][a-z0-9._-]*)\/([a-z0-9][a-z0-9._-]*)/g;
+const IP_RUN_PATTERN = /[0-9A-Za-z:.]+(?:%[0-9A-Za-z._~-]+)?/g;
+const IPV4_SHAPED_PATTERN = /\d{1,3}(?:\.\d{1,3}){3}/g;
+const HEX_GROUP_SEGMENT_PATTERN = /^[0-9A-Fa-f]{1,4}$/;
+const ALPHA_SHORT_SEGMENT_PATTERN = /^[A-Za-z]{1,4}$/;
+const HEX_LETTER_PATTERN = /[A-Fa-f]/;
+const DECIMAL_DIGIT_PATTERN = /[0-9]/;
+const LOCKFILE_URL_REFERENCE_PATTERN = /^(https?|git|git\+https|git\+ssh|ssh):/;
+const LOCAL_LOCKFILE_REF_PREFIXES = ["link:", "file:", "path:", "workspace:"];
+
+/**
+ * Lexical boundary judgement: is a colon-containing run IP-shaped?
+ * Rules (A)-(E) are the public lexical boundary: (A) contains "::"; (B) at
+ * least four non-empty colon segments; (C) at least three segments and all
+ * non-empty segments are 1-4 hex digits with a hex letter present; (D) an
+ * empty segment exists, all non-empty segments are hex groups, at least two
+ * non-empty segments, with a hex letter present; (E) at least one non-empty
+ * segment is a 1-4 letter alpha run while a decimal digit exists elsewhere.
+ * Documented non-address classes (pure-decimal colon runs, pure-alpha colon
+ * runs, digest-prefix runs, single-group colon labels, semver/plain text)
+ * are kept clean by independent positive fixtures; everything that cannot be
+ * classified as non-address enters the single parse entry and fails closed
+ * when unparseable.
+ */
+export function isIpv6ShapedRun(run) {
+  if (!run.includes(":")) return false;
+  if (run.includes("::")) return true; // (A)
+  const segments = run.split(":");
+  const nonEmptySegments = segments.filter((segment) => segment.length > 0);
+  const hasEmptySegment = nonEmptySegments.length !== segments.length;
+  if (nonEmptySegments.length >= 4) return true; // (B)
+  const allHexGroups =
+    nonEmptySegments.length > 0 && nonEmptySegments.every((segment) => HEX_GROUP_SEGMENT_PATTERN.test(segment));
+  if (allHexGroups && nonEmptySegments.length >= 3 && HEX_LETTER_PATTERN.test(run)) return true; // (C)
+  if (hasEmptySegment && allHexGroups && nonEmptySegments.length >= 2 && HEX_LETTER_PATTERN.test(run)) return true; // (D)
+  if (nonEmptySegments.some((segment) => ALPHA_SHORT_SEGMENT_PATTERN.test(segment)) && DECIMAL_DIGIT_PATTERN.test(run)) return true; // (E)
+  return false;
+}
+
+/** IP-shaped candidate extraction. Sentence punctuation is stripped before
+ * the rules; IPv4 candidates not covered by a colon candidate are added. */
+export function extractIpCandidates(text) {
+  const candidates = [];
+  for (const match of text.matchAll(IP_RUN_PATTERN)) {
+    let run = match[0];
+    let index = match.index;
+    const leadingDots = run.match(/^\.+/);
+    if (leadingDots) {
+      index += leadingDots[0].length;
+      run = run.slice(leadingDots[0].length);
+    }
+    const trailingDots = run.match(/\.+$/);
+    if (trailingDots) run = run.slice(0, run.length - trailingDots[0].length);
+    if (isIpv6ShapedRun(run)) {
+      candidates.push({ token: run, index, shape: "ipv6" });
+    }
+  }
+  for (const match of text.matchAll(IPV4_SHAPED_PATTERN)) {
+    const coveredByColonCandidate = candidates.some(
+      (entry) => match.index >= entry.index && match.index + match[0].length <= entry.index + entry.token.length,
+    );
+    if (!coveredByColonCandidate) {
+      candidates.push({ token: match[0], index: match.index, shape: "ipv4" });
+    }
+  }
+  candidates.sort((a, b) => a.index - b.index);
+  return candidates;
+}
+
+/** Normalizes a candidate for the parse entry: URL brackets and %zone-id. */
+export function normalizeIpToken(token) {
+  let core = String(token);
+  if (core.startsWith("[")) {
+    const close = core.indexOf("]");
+    core = close === -1 ? core.slice(1) : core.slice(1, close);
+  }
+  const zone = core.indexOf("%");
+  if (zone !== -1) core = core.slice(0, zone);
+  return core;
+}
+
+function withinApprovedNetworks(cidrs, addr) {
+  for (const [cidrAddress, cidrRange] of cidrs) {
+    if (cidrAddress.kind() !== addr.kind()) continue; // ipaddr.match throws across kinds; classify by family
+    if (addr.match(cidrAddress, cidrRange)) return { allowed: true, reason: "approved-network" };
+  }
+  return { allowed: false, reason: "outside-approved-networks" };
+}
+
+function classifyIpv4Octets(cidrs, octets) {
+  return withinApprovedNetworks(cidrs, new ipaddr.IPv4(octets));
+}
+
+/**
+ * Single address classification entry: brackets/zone id/case/IPv4/IPv6 all
+ * pass through here. ipaddr.parse failure is fail-closed
+ * (unparseable-ip-shaped-token); IPv4-mapped/compatible embeddings delegate
+ * to the embedded IPv4's CIDR classification.
+ */
+export function classifyIpToken(cidrs, token) {
+  const core = normalizeIpToken(token);
+  let addr;
+  try {
+    addr = ipaddr.parse(core);
+  } catch {
+    return { allowed: false, reason: "unparseable-ip-shaped-token" };
+  }
+  if (addr.kind() === "ipv6") {
+    const bytes = addr.toByteArray();
+    const embedded =
+      bytes.slice(0, 10).every((byte) => byte === 0) &&
+      ((bytes[10] === 0xff && bytes[11] === 0xff) || (bytes[10] === 0 && bytes[11] === 0));
+    if (embedded) {
+      const verdict = classifyIpv4Octets(cidrs, bytes.slice(12));
+      return { allowed: verdict.allowed, reason: `embedded-ipv4:${verdict.reason}` };
+    }
+  }
+  return withinApprovedNetworks(cidrs, addr);
+}
+
+function lineOf(bytes, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < bytes.length; i += 1) {
+    if (bytes[i] === 0x0a) line += 1;
+  }
+  return line;
+}
+
+function isIpShapedToken(bare) {
+  if (isIpv6ShapedRun(bare)) return true;
+  return IPV4_SHAPED_PATTERN.test(bare);
+}
+
+function registryHosts(approvedRegistries) {
+  const hosts = new Set();
+  for (const registry of approvedRegistries) {
+    const match = registry.match(/^[a-z][a-z0-9+.-]*:\/\/([^/]+)/i);
+    if (match) {
+      const bare = match[1].toLowerCase().replace(/\.$/, "");
+      const portIndex = bare.indexOf(":");
+      hosts.add(portIndex === -1 ? bare : bare.slice(0, portIndex));
+    }
+  }
+  return hosts;
+}
+
+// ----------------------------------------------------------- policy loading
+
+function loadPolicy(policy) {
+  const checked = validateContractDocument(policy, { schemaId: POLICY_SCHEMA_ID });
+  if (!checked.valid) {
+    throw mechanismError(HARNESS_ERROR_KINDS.STRUCTURED_SCAN_INVALID, "structured-scan policy document is invalid", {
+      errors: checked.errors,
+    });
+  }
+
+  const cidrs = [];
+  for (const cidr of policy.allowedNetworks) {
+    let parsed;
+    try {
+      parsed = ipaddr.parseCIDR(cidr);
+    } catch (cause) {
+      throw mechanismError(
+        HARNESS_ERROR_KINDS.STRUCTURED_SCAN_INVALID,
+        `structured-scan policy contains an invalid CIDR: ${cidr}`,
+        { cidr, cause: cause && cause.message ? cause.message : String(cause) },
+      );
+    }
+    cidrs.push(parsed);
+  }
+
+  let hostKeyPattern = null;
+  if (typeof policy.hostKeyPattern === "string") {
+    try {
+      hostKeyPattern = new RegExp(policy.hostKeyPattern);
+    } catch (cause) {
+      throw mechanismError(
+        HARNESS_ERROR_KINDS.STRUCTURED_SCAN_INVALID,
+        "structured-scan policy hostKeyPattern does not compile",
+        { cause: cause && cause.message ? cause.message : String(cause) },
+      );
+    }
+  }
+
+  const adapters = [];
+  for (const adapter of policy.formatAdapters) {
+    let pattern;
+    try {
+      pattern = new RegExp(adapter.pathPattern);
+    } catch (cause) {
+      throw mechanismError(
+        HARNESS_ERROR_KINDS.STRUCTURED_SCAN_INVALID,
+        `structured-scan policy adapter ${adapter.name} pathPattern does not compile`,
+        { adapter: adapter.name, cause: cause && cause.message ? cause.message : String(cause) },
+      );
+    }
+    adapters.push({ name: adapter.name, pattern });
+  }
+
+  return {
+    schemaVersion: policy.schemaVersion,
+    kind: policy.kind,
+    allowedNetworks: cidrs,
+    approvedRegistries: [...policy.approvedRegistries],
+    approvedCoordinates: new Set(policy.approvedCoordinates),
+    formatAdapters: adapters,
+    symlinkPolicy: policy.symlinkPolicy.mode,
+    binaryPolicy: { mode: policy.binaryPolicy.mode, approvedPaths: new Set(policy.binaryPolicy.approvedPaths) },
+    hostKeyPattern,
+    approvedRegistryHosts: registryHosts(policy.approvedRegistries),
+  };
+}
+
+// ---------------------------------------------------------------- scanning
+
+function scanViolation(relPath, rule, evidence) {
+  return mechanismError(HARNESS_ERROR_KINDS.STRUCTURED_SCAN_VIOLATION, "structured scan matched a violation", {
+    path: relPath,
+    rule,
+    evidence,
+  });
+}
+
+function checkHost(ctx, relPath, host, context, text, index) {
+  if (typeof host !== "string" || host.length === 0) return;
+  let bare = host;
+  const atIndex = bare.lastIndexOf("@");
+  if (atIndex !== -1) bare = bare.slice(atIndex + 1);
+  if (bare.startsWith("[")) {
+    const verdict = classifyIpToken(ctx.allowedNetworks, bare);
+    if (!verdict.allowed) {
+      throw scanViolation(relPath, STRUCTURED_SCAN_RULES.NON_PUBLIC_ADDRESS, `${host}（${verdict.reason}）`);
+    }
+    return;
+  }
+  const portIndex = bare.indexOf(":");
+  if (portIndex !== -1) bare = bare.slice(0, portIndex);
+  bare = bare.toLowerCase().replace(/\.$/, "");
+  if (bare.length === 0) return;
+  if (isIpShapedToken(bare)) {
+    const verdict = classifyIpToken(ctx.allowedNetworks, bare);
+    if (!verdict.allowed) {
+      throw scanViolation(relPath, STRUCTURED_SCAN_RULES.NON_PUBLIC_ADDRESS, `${host}（${verdict.reason}）`);
+    }
+    return;
+  }
+  if (!bare.includes(".")) {
+    if (bare === "localhost") return;
+    if (context === "host-key" && ctx.hostKeyPattern?.test(bare)) return;
+    throw scanViolation(relPath, STRUCTURED_SCAN_RULES.NON_RESERVED_HOSTNAME, host);
+  }
+  if (ctx.approvedRegistryHosts.has(bare)) return;
+  throw scanViolation(relPath, STRUCTURED_SCAN_RULES.NON_RESERVED_HOSTNAME, host);
+}
+
+/** Full structure rules over one text buffer. Throws on first hit. */
+function scanStructure(ctx, relPath, bytes) {
+  const text = bytes.toString("utf8");
+
+  for (const match of text.matchAll(URL_PATTERN)) checkHost(ctx, relPath, match[1], "url", text, match.index);
+  for (const match of text.matchAll(EMAIL_PATTERN)) checkHost(ctx, relPath, match[1], "email", text, match.index);
+  for (const match of text.matchAll(HOST_KEY_STRING_PATTERN)) checkHost(ctx, relPath, match[1], "host-key", text, match.index);
+  for (const arrayMatch of text.matchAll(HOST_KEY_ARRAY_PATTERN)) {
+    for (const tokenMatch of arrayMatch[1].matchAll(QUOTED_TOKEN_PATTERN)) {
+      checkHost(ctx, relPath, tokenMatch[1], "host-key", text, arrayMatch.index);
+    }
+  }
+
+  for (const match of text.matchAll(NPM_SCOPE_PATTERN)) {
+    const coordinate = `@${match[1]}/${match[2]}`;
+    if (!ctx.approvedCoordinates.has(coordinate)) {
+      throw scanViolation(relPath, STRUCTURED_SCAN_RULES.PRIVATE_NPM_SCOPE, match[0]);
+    }
+  }
+
+  for (const { token, index } of extractIpCandidates(text)) {
+    const verdict = classifyIpToken(ctx.allowedNetworks, token);
+    if (!verdict.allowed) {
+      throw scanViolation(relPath, STRUCTURED_SCAN_RULES.NON_PUBLIC_ADDRESS, `${token}（${verdict.reason}）`);
+    }
+  }
+}
+
+/** Binary judgement (fail-closed): non-text control bytes in the first 8KB. */
+function looksBinary(bytes) {
+  const limit = Math.min(bytes.length, 8192);
+  for (let i = 0; i < limit; i += 1) {
+    const b = bytes[i];
+    if (b === 9 || b === 10 || b === 11 || b === 12 || b === 13) continue;
+    if (b < 32 || b === 127) return true;
+  }
+  return false;
+}
+
+// ----------------------------------------------------------- format adapters
+
+/** yaml AST comment regions; an unparseable document yields none (the
+ * semantic parse path reports format-adapter-parse-failed). */
+export function collectLockfileCommentRegions(bytes) {
+  const text = Buffer.isBuffer(bytes) ? bytes.toString("utf8") : String(bytes);
+  let doc;
+  try {
+    doc = parseDocument(text);
+  } catch {
+    return [];
+  }
+  const regions = [];
+  if (doc.commentBefore) regions.push(doc.commentBefore);
+  if (doc.comment) regions.push(doc.comment);
+  visit(doc, {
+    Node(_key, node) {
+      if (node.commentBefore) regions.push(node.commentBefore);
+      if (node.comment) regions.push(node.comment);
+    },
+  });
+  return regions;
+}
+
+function lockfileDependencyName(depPath) {
+  let dep = String(depPath);
+  if (dep.startsWith("/")) dep = dep.slice(1);
+  if (dep.startsWith("@")) {
+    const secondAt = dep.indexOf("@", 1);
+    return secondAt === -1 ? dep : dep.slice(0, secondAt);
+  }
+  const firstAt = dep.indexOf("@");
+  return firstAt === -1 ? dep : dep.slice(0, firstAt);
+}
+
+function isLocalLockfileRef(depPathOrVersion) {
+  return (
+    typeof depPathOrVersion === "string" &&
+    LOCAL_LOCKFILE_REF_PREFIXES.some((prefix) => depPathOrVersion.startsWith(prefix))
+  );
+}
+
+/**
+ * "pnpm-lockfile" adapter: comment regions are scanned first (independent of
+ * the semantic parse), then @pnpm/lockfile.fs parses the document (parse
+ * failure fails closed); every non-local importer dependency and every
+ * packages/snapshots coordinate must be in approvedCoordinates (scoped =
+ * private-npm-scope, unscoped = unapproved-dependency-coordinate; orphan
+ * entries are judged too); URL references must start with an approved
+ * registry; keys and string leaf values continue through the full structure
+ * rules. The adapter writes one temporary copy under the OS temp directory
+ * for the parser and removes it afterwards.
+ */
+async function scanLockfileContent(ctx, relPath, bytes) {
+  const commentRegions = collectLockfileCommentRegions(bytes);
+  commentRegions.forEach((region, index) => {
+    scanStructure(ctx, `${relPath}#yaml-comment-${index + 1}`, Buffer.from(region, "utf8"));
+  });
+
+  let lockfile = null;
+  let parseError = null;
+  const tmpDir = mkdtempSync(path.join(os.tmpdir(), "sf-structured-lockfile-"));
+  try {
+    writeFileSync(path.join(tmpDir, "pnpm-lock.yaml"), bytes);
+    lockfile = await readWantedLockfile(tmpDir, { ignoreIncompatible: false });
+  } catch (cause) {
+    parseError = cause;
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+  // The semantic parse must yield a lockfile document (a versioned map); a
+  // scalar or otherwise non-semantic parse result is a parse failure.
+  if (
+    parseError ||
+    lockfile === null ||
+    typeof lockfile !== "object" ||
+    typeof lockfile.lockfileVersion !== "string"
+  ) {
+    throw scanViolation(
+      relPath,
+      STRUCTURED_SCAN_RULES.FORMAT_ADAPTER_PARSE_FAILED,
+      `pnpm-lock.yaml could not be parsed by @pnpm/lockfile.fs, fail-closed（${String(parseError?.message ?? "no semantic lockfile document").slice(0, 200)}）`,
+    );
+  }
+
+  for (const [importerId, importer] of Object.entries(lockfile.importers ?? {})) {
+    for (const section of ["dependencies", "devDependencies", "optionalDependencies"]) {
+      for (const [name, entry] of Object.entries(importer?.[section] ?? {})) {
+        if (isLocalLockfileRef(entry?.version)) continue;
+        if (!ctx.approvedCoordinates.has(name)) {
+          throw scanViolation(
+            relPath,
+            name.startsWith("@") ? STRUCTURED_SCAN_RULES.PRIVATE_NPM_SCOPE : STRUCTURED_SCAN_RULES.UNAPPROVED_DEPENDENCY_COORDINATE,
+            `importer ${importerId} dependency ${name}（version ${entry?.version ?? "?"}）not in approvedCoordinates`,
+          );
+        }
+      }
+    }
+  }
+
+  for (const [mapName, map] of [["packages", lockfile.packages ?? {}], ["snapshots", lockfile.snapshots ?? {}]]) {
+    for (const [depPath, entry] of Object.entries(map)) {
+      const baseDepPath = depPath.split("(")[0];
+      if (isLocalLockfileRef(baseDepPath)) continue;
+      const name = lockfileDependencyName(baseDepPath);
+      if (!ctx.approvedCoordinates.has(name)) {
+        throw scanViolation(
+          relPath,
+          name.startsWith("@") ? STRUCTURED_SCAN_RULES.PRIVATE_NPM_SCOPE : STRUCTURED_SCAN_RULES.UNAPPROVED_DEPENDENCY_COORDINATE,
+          `${mapName} coordinate ${depPath} not in approvedCoordinates（orphan entries are not exempt）`,
+        );
+      }
+    }
+  }
+
+  const walk = (node, segments) => {
+    if (Array.isArray(node)) {
+      node.forEach((item, index) => walk(item, [...segments, String(index)]));
+      return;
+    }
+    if (node && typeof node === "object") {
+      for (const [key, value] of Object.entries(node)) {
+        if (typeof key === "string" && key.length > 0) {
+          scanStructure(ctx, `${relPath}#/${[...segments, key].join("/")}（key）`, Buffer.from(key, "utf8"));
+        }
+        walk(value, [...segments, key]);
+      }
+      return;
+    }
+    if (typeof node === "string") {
+      if (LOCKFILE_URL_REFERENCE_PATTERN.test(node) && !ctx.approvedRegistries.some((registry) => node.startsWith(registry))) {
+        throw scanViolation(relPath, STRUCTURED_SCAN_RULES.NON_APPROVED_REGISTRY, `${segments.join("/") || "<root>"} references an unapproved registry: ${node.slice(0, 120)}`);
+      }
+      scanStructure(ctx, `${relPath}#/${segments.join("/")}`, Buffer.from(node, "utf8"));
+    } else if (node !== null && node !== undefined) {
+      scanStructure(ctx, `${relPath}#/${segments.join("/")}`, Buffer.from(String(node), "utf8"));
+    }
+  };
+  walk(lockfile, []);
+}
+
+/**
+ * "tree-json" adapter: JSON.parse; a parse failure is
+ * format-adapter-parse-failed (fail-closed). There is no position-level
+ * whole-key exemption: every key and every value runs the full structure
+ * rules first.
+ */
+function scanTreeJsonContent(ctx, relPath, bytes) {
+  let parsed;
+  try {
+    parsed = JSON.parse(bytes.toString("utf8"));
+  } catch (cause) {
+    throw scanViolation(
+      relPath,
+      STRUCTURED_SCAN_RULES.FORMAT_ADAPTER_PARSE_FAILED,
+      `tree.json could not be JSON.parse'd, fail-closed（${String(cause?.message ?? cause).slice(0, 200)}）`,
+    );
+  }
+
+  const walk = (node, segments) => {
+    if (Array.isArray(node)) {
+      node.forEach((item, index) => walk(item, [...segments, String(index)]));
+      return;
+    }
+    if (node && typeof node === "object") {
+      for (const [key, value] of Object.entries(node)) {
+        if (typeof key === "string" && key.length > 0) {
+          scanStructure(ctx, `${relPath}#/${[...segments, key].join("/")}（key）`, Buffer.from(key, "utf8"));
+        }
+        walk(value, [...segments, key]);
+      }
+      return;
+    }
+    if (node !== null && node !== undefined) {
+      scanStructure(ctx, `${relPath}#/${segments.join("/")}`, Buffer.from(String(node), "utf8"));
+    }
+  };
+  walk(parsed, []);
+}
+
+function findAdapter(ctx, relPath) {
+  const normalized = relPath.split(path.sep).join("/");
+  for (const adapter of ctx.formatAdapters) {
+    if (adapter.pattern.test(normalized)) return adapter;
+  }
+  return null;
+}
+
+const BUILTIN_ADAPTERS = Object.freeze({
+  "pnpm-lockfile": scanLockfileContent,
+  "tree-json": scanTreeJsonContent,
+});
+
+// ------------------------------------------------------------------- entry
+
+/**
+ * Structured surface scan. Returns a frozen { scanned, bytes, policy } result
+ * mirroring scanSurface; a violation throws SFC2004 with details.kind
+ * structured-scan-violation and details.rule from the closed vocabulary, and
+ * an invalid policy throws structured-scan-invalid.
+ */
+export async function scanSurfaceStructured({ root, relPaths, policy, encoding = "utf8" } = {}) {
+  if (typeof root !== "string" || root.length === 0) {
+    throw new TypeError("scanSurfaceStructured: root must be a non-empty path");
+  }
+  if (!Array.isArray(relPaths)) {
+    throw new TypeError("scanSurfaceStructured: relPaths must be an array of root-relative path strings");
+  }
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+    throw new TypeError("scanSurfaceStructured: policy must be a structured-scan-policy contract document");
+  }
+  const ctx = loadPolicy(policy);
+
+  const scanned = [];
+  let bytes = 0;
+  for (const relPath of relPaths) {
+    if (typeof relPath !== "string" || relPath.length === 0) {
+      throw new TypeError("scanSurfaceStructured: every relPath entry must be a non-empty string");
+    }
+    const normalized = relPath.split(path.sep).join("/");
+    const classification = classifyPathInput(relPath);
+    if (!classification.ok) {
+      throw mechanismError(
+        classification.kind,
+        `path rejected before resolution (kind: ${classification.kind})`,
+        { input: relPath },
+      );
+    }
+    // Symlink entries are judged before any resolution: readlink-no-follow
+    // records the target text and the target is never read. This applies to
+    // in-tree links and links that would escape alike.
+    const fullPath = path.resolve(root, relPath);
+    let stat;
+    try {
+      stat = lstatSync(fullPath);
+    } catch (cause) {
+      throw mechanismError(
+        HARNESS_ERROR_KINDS.STRUCTURED_SCAN_INVALID,
+        "scanSurfaceStructured: declared resource cannot be inspected",
+        { path: normalized, cause: cause && cause.message ? cause.message : String(cause) },
+      );
+    }
+    if (stat.isSymbolicLink()) {
+      let target = "<unreadable>";
+      try {
+        target = readlinkSync(fullPath);
+      } catch {
+        // readlink failure is itself evidence: never follow, only record.
+      }
+      throw scanViolation(normalized, STRUCTURED_SCAN_RULES.SYMLINK_FORBIDDEN, `target: ${target}`);
+    }
+    await resolveContained(root, relPath);
+    const readResult = await readFileContained(root, relPath);
+    const raw = Buffer.isBuffer(readResult) ? readResult : Buffer.from(readResult);
+    bytes += raw.length;
+    scanned.push(normalized);
+
+    if (looksBinary(raw)) {
+      if (!ctx.binaryPolicy.approvedPaths.has(normalized)) {
+        throw scanViolation(normalized, STRUCTURED_SCAN_RULES.BINARY_UNCLASSIFIED, "<non-text control byte; fail-closed>");
+      }
+      continue;
+    }
+
+    const adapter = findAdapter(ctx, normalized);
+    if (adapter !== null) {
+      const implementation = BUILTIN_ADAPTERS[adapter.name];
+      if (!implementation) {
+        throw scanViolation(normalized, STRUCTURED_SCAN_RULES.FORMAT_ADAPTER_UNKNOWN, `unimplemented adapter ${adapter.name}, fail-closed`);
+      }
+      await implementation(ctx, normalized, raw);
+      continue;
+    }
+    scanStructure(ctx, normalized, raw);
+  }
+
+  return Object.freeze({ scanned, bytes, policy: structuredClone(policy) });
+}