skill-family-harness-node 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.16.0 locale=en baseline=sha256:27fd0f5623d5c93b3076af93231101956233f179dd0cab3d1c74dae891668ea8 -->
+## [0.16.0] - 2026-08-31
+
+Harness 0.16.0 clarifies the existing rawSink boundary and keeps output redaction outside Foundation.
+
+### Changed
+
+- Documents rawSink as a protected 0600 raw stdout/stderr sink in a fresh canonical temporary root, not a redaction API.
+- Explicitly rejects rawStreamSink, transform sinks, generic sanitizers, second runners, and new stdout callbacks for a single-consumer redaction request.
+
+### Upgrade Notes
+
+Consumers that require zero plaintext on the filesystem must own the threat model and implementation; this release adds no redaction or zero-plaintext guarantee.
+<!-- release-skill:changelog:end version=0.16.0 locale=en -->
+
+
+<!-- release-skill:changelog:start version=0.15.0 locale=en baseline=sha256:8c81395a147ed1e995e21ae0074f66d434b87070ea33350fa3e97cbcb5f2fa8e -->
+## [0.15.0] - 2026-08-29
+
+Harness 0.15.0 adds executable identity observation and a best-effort Node tree record mode.
+
+### Added
+
+- Records symlink target bytes without following links on a stable isolated tree.
+- Rechecks the original script after observing its interpreter and orders paths by Unicode code point.
+
+### Changed
+
+- Keeps omitted and reject symlink policy on the 0.14 native path.
+
+### Upgrade Notes
+
+Record mode is candidate best effort; it does not provide a transaction snapshot or hostile concurrent-writer safety.
+<!-- release-skill:changelog:end version=0.15.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.14.0 locale=en baseline=sha256:23ac2de57433409f1dafac90d7bdd130fd10bd399fd188d7d848a49320b86f30 -->
 ## [0.14.0] - 2026-08-28
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,41 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.16.0 locale=zh-CN baseline=sha256:31d28348db231171b1ea5754c514d7fe3cc336c1063026af8763d92553d225de -->
+## [0.16.0] - 2026-08-31
+
+Harness 0.16.0 澄清现有 rawSink 边界，将输出脱敏留在 Foundation 之外。
+
+### 变更
+
+- 明确 rawSink 只适用于在 fresh canonical 临时根中以 0600 保存 stdout/stderr 原始文件的场景，不是脱敏接口。
+- 明确拒绝为单一消费者脱敏需求新增 rawStreamSink、transform sink、通用 sanitizer、第二个 runner 或新的 stdout 回调。
+
+### 升级说明
+
+需要硬性保证文件系统中不出现明文的消费者，应自行定义威胁模型并实现；本版本不增加脱敏或零明文保证。
+<!-- release-skill:changelog:end version=0.16.0 locale=zh-CN -->
+
+
+<!-- release-skill:changelog:start version=0.15.0 locale=zh-CN baseline=sha256:945e9d06ed1cc8178ac13f3ec27ee753ec129d2f54ae59b59c6d8f4ec137d821 -->
+## [0.15.0] - 2026-08-29
+
+Harness 0.15.0 增加可执行文件身份观察与 Node 树 best-effort 记录模式。
+
+### 新增
+
+- 在稳定隔离树上记录 symlink 自身与原始 target bytes，不跟随链接。
+- 观察解释器后重查原脚本，并按 Unicode code point 排序路径。
+
+### 变更
+
+- 省略或 reject symlinkPolicy 时继续使用 0.14 native 路径。
+
+### 升级说明
+
+record 模式仍为 candidate best-effort，不提供事务快照或恶意并发写者安全保证。
+<!-- release-skill:changelog:end version=0.15.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.14.0 locale=zh-CN baseline=sha256:11857b4e61d5111fab3dbc5eb1afcf99fd8fd6fd41f190bad5a5e16c09633e25 -->
 ## [0.14.0] - 2026-08-28
 

package/README.md

@@ -4,28 +4,23 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.14.0 -->
+<!-- release-skill:release-version: 0.16.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.14.0** (2026-08-28)
+**0.16.0** (2026-08-31)
 
-Harness 0.14.0 adds an official atomic-write fake, a synchronized package version export, and canonical temporary workspace roots for safe raw sinks.
-
-**Added**
-
-- Adds createAtomicWriteFake({ vector }) with deterministic write, replace, and observation facts and no filesystem side effects.
-- Exposes FOUNDATION_PACKAGE_VERSION for lockstep consumers.
-- Returns canonical realpaths from TemporaryWorkspace.create() and fromBaseline(). A root returned by create() can be passed directly to superviseProcess rawSink while it remains fresh and empty. A materialized non-empty baseline root is rejected by rawSink freshness validation.
+Harness 0.16.0 clarifies the existing rawSink boundary and keeps output redaction outside Foundation.
 
 **Changed**
 
-- Documents that the fake verifies adapter wiring, not the domain guarantee or real-host qualification.
+- Documents rawSink as a protected 0600 raw stdout/stderr sink in a fresh canonical temporary root, not a redaction API.
+- Explicitly rejects rawStreamSink, transform sinks, generic sanitizers, second runners, and new stdout callbacks for a single-consumer redaction request.
 
 **Upgrade Notes**
 
-Pin Contracts, Harness, and Engineering Kit to 0.14.0 together. Use the official fake with the Contracts vectors; retain real filesystem and domain tests for production guarantees. Temporary workspace roots are canonical. A root returned by create() can be passed directly to superviseProcess rawSink while it remains fresh and empty. A materialized non-empty baseline root is rejected by rawSink freshness validation.
+Consumers that require zero plaintext on the filesystem must own the threat model and implementation; this release adds no redaction or zero-plaintext guarantee.
 <!-- release-skill:managed:end id=latest-release -->
 
 ## Problem It Solves
@@ -38,7 +33,7 @@ The Harness consumes `skill-family-contracts` (a workspace dependency), reusing
 
 ## Installation and Minimal Example
 
-Version 0.14.0 is a local candidate. Build all three tarballs into one temporary directory and install those exact files for a candidate check:
+Version 0.16.0 is a local candidate. Build all three tarballs into one temporary directory and install those exact files for a candidate check:
 
 ```sh
 pack_dir="$(mktemp -d)"
@@ -46,13 +41,13 @@ pack_dir="$(mktemp -d)"
 (cd packages/skill-family-harness-node && pnpm pack --pack-destination "$pack_dir")
 (cd packages/skill-family-engineering-kit && pnpm pack --pack-destination "$pack_dir")
 mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
-(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.14.0.tgz" "$pack_dir/skill-family-harness-node-0.14.0.tgz" "$pack_dir/skill-family-engineering-kit-0.14.0.tgz")
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.16.0.tgz" "$pack_dir/skill-family-harness-node-0.16.0.tgz" "$pack_dir/skill-family-engineering-kit-0.16.0.tgz")
 ```
 
 After publication, use the registry coordinate:
 
 ```sh
-npm install skill-family-harness-node@0.14.0
+npm install skill-family-harness-node@0.16.0
 npm info skill-family-harness-node --help
 ```
 
@@ -122,6 +117,8 @@ The capability remains **candidate**. Pin all three Foundation packages exactly
 | `TemporaryWorkspace` / `createTemporaryWorkspace` / `withTemporaryWorkspace` | Auto-cleanup temporary workspace, cleaned up even on exception paths. |
 | `digestBytes` / `computeResourceClosure` / `closureContains` | Resource closure and deterministic sha256 digest. |
 | `superviseProcess` / `validateTimeoutPolicy` | The single bounded subprocess supervisor. Its 0.11.0 `rawSink` option writes raw stdout/stderr bytes only to a fresh canonical private root, then waits for child/stream close, queued writes, fsync, and handle close. The caller must exclusively control the sink namespace for the entire call; handle protection does not prove stable pathname/root identity. |
+| `observeFilesystemTree` | Observe a complete bound tree. Default/reject preserves the existing UTF-16 member order; record uses code-point order and records symlink target bytes without following them. |
+| `observeExecutableIdentity` | Observe a caller-bound executable, its symlink chain, launch bytes, and any script interpreter chain for immediate pre-spawn re-observation. |
 | `parseRequest` / `processRequest` | Parse `operation-request`, output terminal `operation-result`. |
 | `validateReportModel` / `renderReportMarkdown` / `buildBinding` / `checkReport` | Consume a Contracts-validated report model, deterministically render neutral Markdown, and verify source/result/report binding; does not interpret business output. |
 | `normalizeAdapterSource` / `buildAdapterClosure` / `verifyAdapterBuildManifest` / `materializeAdapterBuild` | Generic text-source closure, full-manifest digest re-verification, and atomic landing of the target set; specific Profile/driver is not in the Harness. |
@@ -183,7 +180,7 @@ Mechanism failures uniformly throw `SFC2004` (EXECUTION_FAILED), with `details.k
 ### Do not use when
 
 - You need to put file-selection business rules into the Foundation (business rules are owned by the caller).
-- You need host identity policy, host drivers, remote publication, uninstall deletion, a full Qoder driver, or binary adapter source (explicitly unsupported).
+- You need host identity policy, host-specific lifecycle plans, remote publication, deleting uninstall, or binary adapter source. Host policy and lifecycle plans belong to Engineering Kit.
 - You need domain audit semantics, retry orchestration, or a compatibility-frozen Quickstart API.
 
 ### Capability selection
@@ -244,4 +241,12 @@ Mechanism failures uniformly throw `SFC2004` (EXECUTION_FAILED), with `details.k
 
 The candidate observeFilesystemTree({ root, rootBinding }) reads complete tree facts. Existing superviseProcess accepts optional per-stream raw-byte caps. Observing a payload does not accept it.
 
-Version 0.14.0 is a local source candidate and is not published. Consume the three locally verified tarballs; a version marker, unit test or successful install is not complete contract integration, migration completion, or real-host qualification.
+`observeFilesystemTree({ root, rootBinding, symlinkPolicy: { mode: "record" } })` is for a stable installation, cache, or projection tree after the host command has completed, with caller isolation and no concurrent namespace writer during the scan. It records each symlink itself as `targetBase64`, `bytes`, and `statMode`, reads only the raw target bytes, and never follows the target; regular files continue to reuse `readFileBound`. Record is a Node/JS best-effort candidate: observed drift fails closed, but the mode does not provide a transaction snapshot, same-UID malicious-concurrency, or ABA guarantee. A stable-tree result remains a normal usable result. Consumers such as release-skill own invocation timing and domain acceptance rules such as npm `.bin`.
+
+Member ordering is mode-specific for compatibility: omitted/reject mode retains the 0.14 UTF-16 relational order, while record mode uses Unicode code-point order. The selected order is also the order used to derive `membersDigest`.
+
+When the actual threat includes malicious concurrency, return a minimal upstream capability gap to Foundation for a decision. Do not copy a generic walker, native addon, Harness, schema, Registry, runner, or receipt chain into a skill family, and do not independently upgrade ordinary consumers to a four-platform native implementation.
+
+The separate candidate `observeExecutableIdentity({ boundRoots, lookup, interpreterPolicy? })` provides a read-only point-in-time observation of only the caller-explicit roots and lookup paths, for an immediate re-observation before launch. When an `/usr/bin/env` shebang resolves an interpreter through explicit `pathEntries`, the observation preserves the interpreter candidate's complete symlink chain rather than collapsing it to the final file. It is not part of `host-adapter` and does not prove wrapper control flow, ambient `PATH`, fd-exec/kernel image, signature trust, cross-call caching, host support/lifecycle, or domain acceptance; the caller owns those semantics. The candidate entry alone does not qualify a host.
+
+Version 0.16.0 is a local source candidate and is not published. Consume the three locally verified tarballs; a version marker, unit test or successful install is not complete contract integration, migration completion, or real-host qualification.

package/README.zh-CN.md

@@ -5,28 +5,23 @@
 
 # skill-family-harness-node
 
-<!-- release-skill:release-version: 0.14.0 -->
+<!-- release-skill:release-version: 0.16.0 -->
 
 Contracts 机制协议的**唯一默认 Node 实现**。这是一个薄运行时（thin runtime）：只实现机制协议，不引入业务语义，不做第二语言实现。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.14.0** (2026-08-28)
+**0.16.0** (2026-08-31)
 
-Harness 0.14.0 增加消费者契约测试用正式 atomic-write 测试替身（`fake`）、同步公开包版本导出，并让临时工作区根目录返回 canonical realpath。
-
-**新增**
-
-- 新增 `createAtomicWriteFake({ vector })`，提供确定性的写入、替换和观察事实且不触碰文件系统。
-- 公开 `FOUNDATION_PACKAGE_VERSION`，供锁步消费者使用。
-- `TemporaryWorkspace.create()` 与 `fromBaseline()` 返回 canonical realpath。`create()` 返回的根目录在保持 fresh 且为空时，可以直接传给 `superviseProcess` 的 `rawSink`。物化后的非空 baseline 根目录会被 `rawSink` 的 freshness 校验拒绝。
+Harness 0.16.0 澄清现有 rawSink 边界，将输出脱敏留在 Foundation 之外。
 
 **变更**
 
-- 明确测试替身用于验证适配器接线，不代表领域保证或真实宿主资格。
+- 明确 rawSink 只适用于在 fresh canonical 临时根中以 0600 保存 stdout/stderr 原始文件的场景，不是脱敏接口。
+- 明确拒绝为单一消费者脱敏需求新增 rawStreamSink、transform sink、通用 sanitizer、第二个 runner 或新的 stdout 回调。
 
 **升级说明**
 
-Contracts、Harness 与 Engineering Kit 须一起精确锁定到 0.14.0。用正式测试替身配合 Contracts 向量；生产保证仍须由真实文件系统和领域测试覆盖。临时工作区根目录已经 canonical。`create()` 返回的根目录在保持 fresh 且为空时，可以直接传给 `superviseProcess` 的 `rawSink`。物化后的非空 baseline 根目录会被 `rawSink` 的 freshness 校验拒绝。
+需要硬性保证文件系统中不出现明文的消费者，应自行定义威胁模型并实现；本版本不增加脱敏或零明文保证。
 <!-- release-skill:managed:end id=latest-release -->
 
 ## 解决的问题
@@ -39,7 +34,7 @@ Harness 消费 `skill-family-contracts`（工作区依赖），复用其方言
 
 ## 安装和最小示例
 
-0.14.0 是本地候选版本。候选验证先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
+0.16.0 是本地候选版本。候选验证先把三个包分别打入同一个临时目录，再安装这三个精确 tarball：
 
 ```sh
 pack_dir="$(mktemp -d)"
@@ -47,13 +42,13 @@ pack_dir="$(mktemp -d)"
 (cd packages/skill-family-harness-node && pnpm pack --pack-destination "$pack_dir")
 (cd packages/skill-family-engineering-kit && pnpm pack --pack-destination "$pack_dir")
 mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
-(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.14.0.tgz" "$pack_dir/skill-family-harness-node-0.14.0.tgz" "$pack_dir/skill-family-engineering-kit-0.14.0.tgz")
+(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-0.16.0.tgz" "$pack_dir/skill-family-harness-node-0.16.0.tgz" "$pack_dir/skill-family-engineering-kit-0.16.0.tgz")
 ```
 
 发布后再使用 registry 坐标：
 
 ```sh
-npm install skill-family-harness-node@0.14.0
+npm install skill-family-harness-node@0.16.0
 npm info skill-family-harness-node --help
 ```
 
@@ -123,6 +118,8 @@ v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字
 | `TemporaryWorkspace` / `createTemporaryWorkspace` / `withTemporaryWorkspace` | 自动清理的临时工作区，异常路径也清理。 |
 | `digestBytes` / `computeResourceClosure` / `closureContains` | 资源闭包与确定性 sha256 摘要。 |
 | `superviseProcess` / `validateTimeoutPolicy` | 唯一的受约束子进程监督器。0.11.0 的 `rawSink` 只向 fresh canonical 私有根写原始 stdout/stderr 字节，并等待子进程、流、排队写入、fsync 与句柄全部关闭。调用方必须在整个调用期间独占 sink 命名空间；句柄保护不证明 pathname 或根目录身份始终不变。 |
+| `observeFilesystemTree` | 观察完整绑定树。默认/reject 保留既有 UTF-16 成员顺序；record 使用码点顺序，记录 symlink target bytes 且不跟随目标。 |
+| `observeExecutableIdentity` | 观察调用方绑定的可执行入口、符号链接链、启动字节和脚本解释器链，供每次 spawn 前紧邻重观察。 |
 | `parseRequest` / `processRequest` | 解析 `operation-request`，输出终态 `operation-result`。 |
 | `validateReportModel` / `renderReportMarkdown` / `buildBinding` / `checkReport` | 消费经 Contracts 验证的 report model，确定性渲染中性 Markdown 并校验来源/结果/报告绑定；不解释业务输出。 |
 | `normalizeAdapterSource` / `buildAdapterClosure` / `verifyAdapterBuildManifest` / `materializeAdapterBuild` | 通用文本 source closure、manifest 全摘要复验和目标集合原子落盘；具体 Profile/driver 不在 Harness。 |
@@ -184,7 +181,7 @@ v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字
 ### Do not use when
 
 - 需要把文件选择的业务规则放入 Foundation（业务规则由调用方拥有）。
-- 需要宿主身份策略、宿主 driver、远端发布、删除式 uninstall、Qoder 完整 driver 或二进制 adapter source（明确 unsupported）。
+- 需要宿主身份策略、宿主专属生命周期计划、远端发布、删除式 uninstall 或二进制 adapter source。宿主策略与生命周期计划归 Engineering Kit。
 - 需要领域审计语义、重试编排或兼容性已冻结的 Quickstart API。
 
 ### Capability selection
@@ -244,4 +241,12 @@ v2 机制会重算每个 path-backed output 和 evidence Resource 的真实字
 
 新增候选 observeFilesystemTree({ root, rootBinding }) 读取完整树事实；既有 superviseProcess 支持可选每流原始字节上限。观察完成不等于接受载荷。
 
-0.14.0 为本地源码候选，尚未发布。消费本地已验证的三包 tarball；版本标记、单元测试或安装成功都不等于契约接入完成、迁移完成或真实宿主资格。
+`observeFilesystemTree({ root, rootBinding, symlinkPolicy: { mode: "record" } })` 适用于宿主命令完成后、调用方已隔离且扫描期间没有并发 namespace writer 的稳定安装树、缓存树或投影树。它记录 symlink 自身的 `targetBase64`、`bytes` 和 `statMode`，只读取原始 target bytes，绝不跟随 target；普通文件仍复用 `readFileBound`。record 是 Node/JS best-effort candidate：发现扫描期间的漂移会失败关闭，但不提供事务快照、同 UID 恶意并发或 ABA 保证，这不改变稳定树结果的正常使用语义。release-skill 等消费者负责调用时机，并继续负责 npm `.bin` 等领域接受规则。
+
+成员排序按模式区分，以保留兼容性：省略策略或使用 reject 时沿用 0.14 的 UTF-16 关系顺序，record 使用 Unicode 码点顺序；`membersDigest` 也按对应顺序推导。
+
+真实威胁包含恶意并发时，应形成最小上游能力缺口并交回 Foundation 裁决；不要在技能族内复制通用 walker、native addon、Harness、schema、Registry、runner 或 receipt 链，也不要自行升级为四平台原生实现。
+
+另一个独立候选 `observeExecutableIdentity({ boundRoots, lookup, interpreterPolicy? })` 只对调用方显式提供的根和查找路径做逐次只读观察，供正式启动前紧邻重观察。`/usr/bin/env` shebang 通过显式 `pathEntries` 找到解释器时，结果保留解释器候选的完整 symlink chain，不折叠成最终文件。它不属于 `host-adapter`，也不证明 wrapper 控制流、ambient `PATH`、fd-exec/内核映像、签名信任、跨调用缓存、宿主支持/生命周期或领域接受；这些语义仍由调用方负责。候选入口存在不等于宿主已获资格。
+
+0.16.0 为本地源码候选，尚未发布。消费本地已验证的三包 tarball；版本标记、单元测试或安装成功都不等于契约接入完成、迁移完成或真实宿主资格。

package/package.json

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

package/release-notes/0.15.0.yaml

@@ -0,0 +1,21 @@
+version: 0.15.0
+date: 2026-08-29
+locales:
+  en:
+    summary: Harness 0.15.0 adds executable identity observation and a best-effort Node tree record mode.
+    changes:
+      added:
+        - Records symlink target bytes without following links on a stable isolated tree.
+        - Rechecks the original script after observing its interpreter and orders paths by Unicode code point.
+      changed:
+        - Keeps omitted and reject symlink policy on the 0.14 native path.
+    upgradeNotes: Record mode is candidate best effort; it does not provide a transaction snapshot or hostile concurrent-writer safety.
+  zh-CN:
+    summary: Harness 0.15.0 增加可执行文件身份观察与 Node 树 best-effort 记录模式。
+    changes:
+      added:
+        - 在稳定隔离树上记录 symlink 自身与原始 target bytes，不跟随链接。
+        - 观察解释器后重查原脚本，并按 Unicode code point 排序路径。
+      changed:
+        - 省略或 reject symlinkPolicy 时继续使用 0.14 native 路径。
+    upgradeNotes: record 模式仍为 candidate best-effort，不提供事务快照或恶意并发写者安全保证。

package/release-notes/0.16.0.yaml

@@ -0,0 +1,17 @@
+version: 0.16.0
+date: 2026-08-31
+locales:
+  en:
+    summary: Harness 0.16.0 clarifies the existing rawSink boundary and keeps output redaction outside Foundation.
+    changes:
+      changed:
+        - Documents rawSink as a protected 0600 raw stdout/stderr sink in a fresh canonical temporary root, not a redaction API.
+        - Explicitly rejects rawStreamSink, transform sinks, generic sanitizers, second runners, and new stdout callbacks for a single-consumer redaction request.
+    upgradeNotes: Consumers that require zero plaintext on the filesystem must own the threat model and implementation; this release adds no redaction or zero-plaintext guarantee.
+  zh-CN:
+    summary: Harness 0.16.0 澄清现有 rawSink 边界，将输出脱敏留在 Foundation 之外。
+    changes:
+      changed:
+        - 明确 rawSink 只适用于在 fresh canonical 临时根中以 0600 保存 stdout/stderr 原始文件的场景，不是脱敏接口。
+        - 明确拒绝为单一消费者脱敏需求新增 rawStreamSink、transform sink、通用 sanitizer、第二个 runner 或新的 stdout 回调。
+    upgradeNotes: 需要硬性保证文件系统中不出现明文的消费者，应自行定义威胁模型并实现；本版本不增加脱敏或零明文保证。

package/src/errors.mjs

@@ -59,6 +59,8 @@ export const HARNESS_ERROR_KINDS = Object.freeze({
   HOST_BUILD_FAILED: "host-build-failed",
   HOST_PROBE_FAILED: "host-probe-failed",
   UNTRUSTED_EXECUTABLE: "untrusted-executable",
+  EXECUTABLE_NOT_FOUND: "executable-not-found",
+  UNSUPPORTED_INTERPRETER: "unsupported-interpreter",
   PORTABLE_PATH_COLLISION: "portable-path-collision",
   MANIFEST_MISMATCH: "manifest-mismatch",
   BASELINE_MISMATCH: "baseline-mismatch",

package/src/executable-identity.mjs

@@ -0,0 +1,480 @@
+import { lstat, readlink } from "node:fs/promises";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+import { digestDocument } from "skill-family-contracts";
+import { digestBytes } from "./closure.mjs";
+import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
+import { createFilesystemRootBinding, readFileBound } from "./bound-read.mjs";
+
+const POSIX = path.posix;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+const MAX_SYMLINK_DEPTH = 40;
+const MAX_SYMLINK_BYTES = 1024 * 1024;
+const ROOT_BINDING_KEYS = "basis,digest,digestAlgorithm,kind";
+const INPUT_KEYS = "boundRoots,interpreterPolicy,lookup";
+const LOOKUP_KEYS = {
+  "absolute-path": "mode,path",
+  "explicit-path-search": "command,mode,pathEntries",
+};
+const WINDOWS_DRIVE = /^[A-Za-z]:/u;
+const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+function ownKeys(value) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? Object.keys(value).sort().join(",")
+    : "";
+}
+
+function assertObject(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+}
+
+function assertCanonicalAbsolute(value, label) {
+  if (typeof value !== "string" || value.length === 0 || !POSIX.isAbsolute(value) ||
+      value.includes("\\") || value.includes("\0") || POSIX.normalize(value) !== value ||
+      (value.length > 1 && value.endsWith("/")) ||
+      value.split("/").some((segment) => segment === "." || segment === "..")) {
+    throw new TypeError(`${label} must be a normalized POSIX absolute path`);
+  }
+  return value;
+}
+
+function assertBareCommand(value, label) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 256 ||
+      value.includes("/") || value.includes("\\") || value.includes("\0") ||
+      value === "." || value === ".." || WINDOWS_DRIVE.test(value)) {
+    throw new TypeError(`${label} must be a bare command without path separators`);
+  }
+  return value;
+}
+
+function assertRootBindingShape(binding, label) {
+  assertObject(binding, label);
+  if (ownKeys(binding) !== ROOT_BINDING_KEYS || binding.kind !== "trusted-filesystem-root-binding" ||
+      binding.digestAlgorithm !== "sha256" ||
+      binding.basis !== "canonical-realpath-device-inode-type-mode-v1" ||
+      typeof binding.digest !== "string" || !SHA256_PATTERN.test(binding.digest)) {
+    throw new TypeError(`${label} is not a filesystem-root-binding value`);
+  }
+}
+
+function assertRootEntries(entries) {
+  if (!Array.isArray(entries) || entries.length === 0 || entries.length > 64) {
+    throw new TypeError("boundRoots must be a non-empty array");
+  }
+  const roots = [];
+  const seen = new Set();
+  for (const [index, entry] of entries.entries()) {
+    assertObject(entry, `boundRoots[${index}]`);
+    if (ownKeys(entry) !== "root,rootBinding") throw new TypeError("boundRoots entries are closed");
+    const root = assertCanonicalAbsolute(entry.root, `boundRoots[${index}].root`);
+    assertRootBindingShape(entry.rootBinding, `boundRoots[${index}].rootBinding`);
+    if (seen.has(root)) throw new TypeError("boundRoots must not contain duplicate roots");
+    seen.add(root);
+    roots.push({
+      root,
+      rootBinding: {
+        basis: entry.rootBinding.basis,
+        digest: entry.rootBinding.digest,
+        digestAlgorithm: entry.rootBinding.digestAlgorithm,
+        kind: entry.rootBinding.kind,
+      },
+    });
+  }
+  const ordered = [...roots].sort((left, right) => left.root.length - right.root.length || left.root.localeCompare(right.root));
+  for (let parentIndex = 0; parentIndex < ordered.length; parentIndex += 1) {
+    const parent = ordered[parentIndex].root;
+    for (let childIndex = parentIndex + 1; childIndex < ordered.length; childIndex += 1) {
+      if (pathWithinRoot(parent, ordered[childIndex].root)) {
+        throw new TypeError("boundRoots must not contain overlapping roots");
+      }
+    }
+  }
+  return roots;
+}
+
+function pathWithinRoot(root, value) {
+  return root === "/" ? value.startsWith("/") : value === root || value.startsWith(`${root}/`);
+}
+
+function assertRootReferenceArray(value, label, roots, { optional = true } = {}) {
+  if (value === undefined && optional) return undefined;
+  if (!Array.isArray(value) || value.length === 0 || value.length > 64) {
+    throw new TypeError(`${label} must be a non-empty array of bound root references`);
+  }
+  const seen = new Set();
+  return value.map((root, index) => {
+    assertCanonicalAbsolute(root, `${label}[${index}]`);
+    if (!roots.some((entry) => entry.root === root)) {
+      throw new TypeError(`${label}[${index}] must exactly reference a bound root`);
+    }
+    if (seen.has(root)) throw new TypeError(`${label} must not contain duplicate roots`);
+    seen.add(root);
+    return root;
+  });
+}
+
+function validateInput(input) {
+  assertObject(input, "observeExecutableIdentity input");
+  if (ownKeys(input) !== INPUT_KEYS && ownKeys(input) !== "boundRoots,lookup") {
+    throw new TypeError("observeExecutableIdentity input has unknown fields");
+  }
+  const roots = assertRootEntries(input.boundRoots);
+  assertObject(input.lookup, "lookup");
+  const mode = input.lookup.mode;
+  if (!Object.hasOwn(LOOKUP_KEYS, mode) || ownKeys(input.lookup) !== LOOKUP_KEYS[mode]) {
+    throw new TypeError("lookup does not match its closed mode shape");
+  }
+  const lookup = { mode };
+  if (mode === "absolute-path") {
+    lookup.path = assertCanonicalAbsolute(input.lookup.path, "lookup.path");
+  } else {
+    lookup.command = assertBareCommand(input.lookup.command, "lookup.command");
+    lookup.pathEntries = assertRootReferenceArray(input.lookup.pathEntries, "lookup.pathEntries", roots, { optional: false });
+  }
+  const requested = input.lookup.requested ?? (mode === "absolute-path" ? lookup.path : lookup.command);
+  if (typeof requested !== "string" || requested.length === 0 || requested.length > 4096 ||
+      requested.includes("\0") || requested.includes("\r") || requested.includes("\n")) {
+    throw new TypeError("lookup.requested must be a bounded string");
+  }
+  if (requested !== (mode === "absolute-path" ? lookup.path : lookup.command)) {
+    throw new TypeError("lookup.requested must equal the lookup target");
+  }
+  lookup.requested = requested;
+  let interpreterPolicy;
+  if (input.interpreterPolicy !== undefined) {
+    assertObject(input.interpreterPolicy, "interpreterPolicy");
+    const keys = ownKeys(input.interpreterPolicy);
+    if (keys !== "absoluteRoots" && keys !== "pathEntries" && keys !== "absoluteRoots,pathEntries") {
+      throw new TypeError("interpreterPolicy has unknown fields");
+    }
+    interpreterPolicy = {
+      absoluteRoots: assertRootReferenceArray(input.interpreterPolicy.absoluteRoots, "interpreterPolicy.absoluteRoots", roots),
+      pathEntries: assertRootReferenceArray(input.interpreterPolicy.pathEntries, "interpreterPolicy.pathEntries", roots),
+    };
+    if (interpreterPolicy.absoluteRoots === undefined && interpreterPolicy.pathEntries === undefined) {
+      throw new TypeError("interpreterPolicy must provide an interpreter root policy");
+    }
+  }
+  return { roots, lookup, interpreterPolicy };
+}
+
+function rootForPath(roots, value) {
+  const matches = roots.filter(({ root }) => pathWithinRoot(root, value));
+  if (matches.length !== 1) return null;
+  return matches[0];
+}
+
+function relativeToRoot(root, value) {
+  const relative = POSIX.relative(root, value);
+  if (!relative || relative.startsWith("../") || relative === ".." || POSIX.isAbsolute(relative) || relative.includes("\\")) return null;
+  return relative;
+}
+
+function statIdentity(value) {
+  return [value.dev, value.ino, value.mode, value.nlink, value.size].map(String).join(":");
+}
+
+function unsafe(message, details = {}) {
+  return mechanismError(HARNESS_ERROR_KINDS.UNSAFE_STATE_ENTRY, message, details);
+}
+
+function untrusted(message, details = {}) {
+  return mechanismError(HARNESS_ERROR_KINDS.UNTRUSTED_EXECUTABLE, message, details);
+}
+
+function notFound(message, details = {}) {
+  return mechanismError(HARNESS_ERROR_KINDS.EXECUTABLE_NOT_FOUND, message, details);
+}
+
+function unsupportedInterpreter(message, details = {}) {
+  return mechanismError(HARNESS_ERROR_KINDS.UNSUPPORTED_INTERPRETER, message, details);
+}
+
+function decodeTarget(bytes, linkPath) {
+  if (bytes.length > MAX_SYMLINK_BYTES) throw untrusted("symbolic link target is too large", { input: linkPath });
+  let target;
+  try {
+    target = decoder.decode(bytes);
+  } catch {
+    throw untrusted("symbolic link target is not valid UTF-8", { input: linkPath });
+  }
+  if (target.length === 0 || target.includes("\0") || target.includes("\\") || target.includes("\r") || target.includes("\n")) {
+    throw untrusted("symbolic link target cannot be represented as a safe path", { input: linkPath });
+  }
+  return target;
+}
+
+async function captureLink(linkPath, before, relative) {
+  let first;
+  let second;
+  let after;
+  try {
+    first = Buffer.from(await readlink(linkPath, { encoding: "buffer" }));
+    after = await lstat(linkPath, { bigint: false });
+    second = Buffer.from(await readlink(linkPath, { encoding: "buffer" }));
+  } catch (cause) {
+    throw unsafe("symbolic link changed while being observed", {
+      input: relative,
+      boundReadDisposition: "boundary-indeterminate",
+      code: cause?.code,
+    });
+  }
+  if (!sameStatIdentity(before, after) || !first.equals(second)) {
+    throw unsafe("symbolic link changed while being observed", {
+      input: relative,
+      boundReadDisposition: "boundary-indeterminate",
+    });
+  }
+  return {
+    path: linkPath,
+    targetBase64: first.toString("base64"),
+    bytes: first.length,
+    target: decodeTarget(first, linkPath),
+  };
+}
+
+function sameStatIdentity(left, right) {
+  return statIdentity(left) === statIdentity(right);
+}
+
+function safeSegment(segment) {
+  return segment.length > 0 && segment !== "." && segment !== ".." && !segment.includes("\\") &&
+    !segment.includes("\0") && !WINDOWS_DRIVE.test(segment) && !segment.includes("/");
+}
+
+/**
+ * Resolves an absolute path one component at a time.  Every component is
+ * lstat'd, and symbolic links are read as bytes without ever opening or
+ * recursing through their targets by descriptor.  The returned chain is
+ * intentionally local to this invocation; no namespace observation is cached.
+ */
+async function resolveEntry(startPath, roots, visited = new Set(), chain = [], depth = 0) {
+  if (depth > MAX_SYMLINK_DEPTH) throw unsafe("symbolic link chain exceeds the fixed depth", { input: startPath });
+  const root = rootForPath(roots, startPath);
+  if (!root) throw unsafe("executable path leaves the union of bound roots", { input: startPath });
+  const relative = relativeToRoot(root.root, startPath);
+  if (relative === null) throw mechanismError(HARNESS_ERROR_KINDS.SYMLINK_ESCAPE, "executable path is not contained by its bound root", { input: startPath });
+  const segments = relative.split("/");
+  let cursor = root.root;
+  for (let index = 0; index < segments.length; index += 1) {
+    if (!safeSegment(segments[index])) throw new TypeError("executable path contains an unsafe segment");
+    const memberPath = POSIX.join(cursor, segments[index]);
+    let before;
+    try {
+      before = await lstat(memberPath, { bigint: false });
+    } catch (cause) {
+      if (cause?.code === "ENOENT" || cause?.code === "ENOTDIR") return { missing: true, chain };
+      throw mechanismError(HARNESS_ERROR_KINDS.READ_FAILED, "executable path could not be inspected", { input: memberPath, code: cause?.code });
+    }
+    if (before.isSymbolicLink()) {
+      if (visited.has(memberPath)) throw unsafe("symbolic link chain loops", { input: memberPath });
+      const nextVisited = new Set(visited);
+      nextVisited.add(memberPath);
+      const link = await captureLink(memberPath, before, memberPath);
+      const remainder = segments.slice(index + 1);
+      const targetPath = POSIX.isAbsolute(link.target)
+        ? POSIX.resolve(link.target, ...remainder)
+        : POSIX.resolve(POSIX.dirname(memberPath), link.target, ...remainder);
+      if (!rootForPath(roots, targetPath)) {
+        throw mechanismError(HARNESS_ERROR_KINDS.SYMLINK_ESCAPE, "symbolic link target leaves the union of bound roots", { input: memberPath });
+      }
+      return resolveEntry(targetPath, roots, nextVisited, [...chain, {
+        path: link.path,
+        targetBase64: link.targetBase64,
+        bytes: link.bytes,
+      }], depth + 1);
+    }
+    if (index < segments.length - 1 && !before.isDirectory()) return { missing: true, chain };
+    if (index === segments.length - 1) return { path: memberPath, stat: before, chain };
+    cursor = memberPath;
+  }
+  return { missing: true, chain };
+}
+
+function isNativeMagic(bytes) {
+  if (bytes.length >= 4 && bytes[0] === 0x7f && bytes[1] === 0x45 && bytes[2] === 0x4c && bytes[3] === 0x46) return true;
+  if (bytes.length < 4) return false;
+  const magic = bytes.readUInt32BE(0);
+  return [0xfeedface, 0xcefaedfe, 0xfeedfacf, 0xcffaedfe, 0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic);
+}
+
+function parseShebang(bytes) {
+  if (bytes.length < 2 || bytes[0] !== 0x23 || bytes[1] !== 0x21) return null;
+  let line;
+  try {
+    line = decoder.decode(bytes.subarray(2, bytes.indexOf(0x0a, 2) === -1 ? bytes.length : bytes.indexOf(0x0a, 2))).replace(/\r$/u, "");
+  } catch {
+    throw unsupportedInterpreter("shebang is not valid UTF-8");
+  }
+  if (line.length === 0 || /["'=$]/u.test(line)) throw unsupportedInterpreter("shebang uses unsupported shell syntax");
+  const tokens = line.trim().split(/[\t ]+/u).filter(Boolean);
+  if (tokens.length === 1 && POSIX.isAbsolute(tokens[0]) && !tokens[0].includes("\\") && !tokens[0].includes("\0")) {
+    return { path: assertCanonicalAbsolute(POSIX.normalize(tokens[0]), "shebang interpreter"), request: POSIX.normalize(tokens[0]), shebangArgs: [] };
+  }
+  if (tokens.length === 2 && tokens[0] === "/usr/bin/env") {
+    return { command: assertBareCommand(tokens[1], "shebang env interpreter"), request: tokens[1], shebangArgs: [] };
+  }
+  throw unsupportedInterpreter("shebang form is outside the fixed interpreter grammar");
+}
+
+async function observeResolved(resolved, roots) {
+  if (resolved.missing) return null;
+  if (!resolved.stat.isFile() || Number(resolved.stat.nlink) !== 1 || (Number(resolved.stat.mode) & 0o111) === 0) {
+    throw untrusted("executable entry must be one executable ordinary file", { input: resolved.path });
+  }
+  const root = rootForPath(roots, resolved.path);
+  const relPath = relativeToRoot(root.root, resolved.path);
+  if (!root || relPath === null) throw mechanismError(HARNESS_ERROR_KINDS.SYMLINK_ESCAPE, "canonical executable leaves bound roots", { input: resolved.path });
+  const receipt = await readFileBound(root.root, relPath, { rootBinding: root.rootBinding });
+  if (Number(receipt.statMode) !== Number(resolved.stat.mode) || Number(receipt.bytes) !== Number(resolved.stat.size)) {
+    throw unsafe("executable changed during bound observation", { input: resolved.path, boundReadDisposition: "boundary-indeterminate" });
+  }
+  const bytes = Buffer.from(receipt.content);
+  const entryKind = isNativeMagic(bytes) ? "native-binary" : bytes[0] === 0x23 && bytes[1] === 0x21 ? "interpreter-script" : "opaque-executable";
+  return {
+    path: resolved.path,
+    symlinkChain: resolved.chain,
+    binding: root.rootBinding,
+    relPath,
+    sha256: digestBytes(bytes),
+    bytes: bytes.length,
+    statMode: Number(receipt.statMode),
+    entryKind,
+    content: bytes,
+    stat: resolved.stat,
+  };
+}
+
+async function assertStableEntry(selectedPath, selected, observed, roots) {
+  let after;
+  let final;
+  try {
+    after = await resolveEntry(selectedPath, roots);
+    if (after.missing || after.path !== selected.path || !sameStatIdentity(after.stat, selected.stat) ||
+        chainKey(after.chain) !== chainKey(selected.chain)) {
+      throw new Error("executable namespace changed during bound observation");
+    }
+    // Re-read the resolved entry through the same bound-read chokepoint.  A
+    // writer can preserve inode, mode, link count, and byte length while
+    // replacing its bytes; the digest comparison below closes that gap only
+    // for the interval between these two bound reads.
+    final = await observeResolved(after, roots);
+    if (!final || final.path !== observed.path ||
+        chainKey(final.symlinkChain) !== chainKey(observed.symlinkChain) ||
+        !sameStatIdentity(final.stat, observed.stat) ||
+        final.sha256 !== observed.sha256) {
+      throw new Error("executable content or identity changed during bound observation");
+    }
+  } catch {
+    throw unsafe("executable changed during bound observation", {
+      input: selectedPath,
+      boundReadDisposition: "boundary-indeterminate",
+    });
+  }
+}
+
+function freezeDeep(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) freezeDeep(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+function chainKey(chain) {
+  return JSON.stringify(chain);
+}
+
+async function verifyRootBindings(roots) {
+  await Promise.all(roots.map(async (entry) => {
+    const actual = await createFilesystemRootBinding(entry.root);
+    if (actual.digest !== entry.rootBinding.digest) {
+      throw unsafe("approved root binding does not match the current root", { input: entry.root, boundReadDisposition: "boundary-indeterminate" });
+    }
+  }));
+}
+
+/**
+ * Observes a deterministic explicit launch image.  PATH is entirely supplied
+ * by the caller; process.env.PATH and any ambient executable cache are never
+ * consulted.  Callers must invoke this again immediately before spawning.
+ */
+export async function observeExecutableIdentity(input = {}) {
+  const parsed = validateInput(input);
+  await verifyRootBindings(parsed.roots);
+  let selected;
+  let selectedPath;
+  if (parsed.lookup.mode === "absolute-path") {
+    selected = await resolveEntry(parsed.lookup.path, parsed.roots);
+    if (selected.missing) throw notFound("requested executable was not found", { input: parsed.lookup.path });
+    selectedPath = parsed.lookup.path;
+  } else {
+    for (const rootPath of parsed.lookup.pathEntries) {
+      const candidate = POSIX.join(rootPath, parsed.lookup.command);
+      const resolved = await resolveEntry(candidate, parsed.roots);
+      if (resolved.missing || !resolved.stat?.isFile() || Number(resolved.stat.nlink) !== 1 || (Number(resolved.stat.mode) & 0o111) === 0) continue;
+      selected = resolved;
+      selectedPath = candidate;
+      break;
+    }
+    if (!selected) throw notFound("no executable matched the explicit path search", { input: parsed.lookup.command });
+  }
+  const canonical = await observeResolved(selected, parsed.roots);
+  if (!canonical) throw notFound("requested executable was not found", { input: parsed.lookup.requested });
+  await assertStableEntry(selectedPath, selected, canonical, parsed.roots);
+  let interpreter = null;
+  let launch = { file: canonical.path, argvPrefix: [] };
+  if (canonical.entryKind === "interpreter-script") {
+    const shebang = parseShebang(canonical.content);
+    if (!shebang) throw unsupportedInterpreter("interpreter-script has no usable shebang");
+    const policy = parsed.interpreterPolicy;
+    if (!policy) throw unsupportedInterpreter("script interpretation requires an explicit interpreter policy");
+    let interpreterPath = shebang.path;
+    let interpreterResolved;
+    if (shebang.command !== undefined) {
+      if (!policy.pathEntries) throw unsupportedInterpreter("env shebang requires explicit interpreter path entries");
+      for (const rootPath of policy.pathEntries) {
+        const candidate = POSIX.join(rootPath, shebang.command);
+        const resolved = await resolveEntry(candidate, parsed.roots);
+        if (!resolved.missing && resolved.stat?.isFile() && Number(resolved.stat.nlink) === 1 && (Number(resolved.stat.mode) & 0o111) !== 0) {
+          interpreterPath = candidate;
+          interpreterResolved = resolved;
+          break;
+        }
+      }
+      if (!interpreterPath) throw unsupportedInterpreter("env shebang interpreter was not found");
+    } else if (!policy.absoluteRoots || !rootForPath(policy.absoluteRoots.map((root) => parsed.roots.find((entry) => entry.root === root)), interpreterPath)) {
+      throw unsupportedInterpreter("absolute shebang interpreter is outside its explicit policy roots", { input: interpreterPath });
+    }
+    interpreterResolved ??= await resolveEntry(interpreterPath, parsed.roots);
+    if (interpreterResolved.missing) throw unsupportedInterpreter("shebang interpreter was not found", { input: interpreterPath });
+    interpreter = await observeResolved(interpreterResolved, parsed.roots);
+    if (!interpreter || interpreter.entryKind !== "native-binary") {
+      throw untrusted("shebang interpreter must be a native binary", { input: interpreterPath });
+    }
+    await assertStableEntry(interpreterPath, interpreterResolved, interpreter, parsed.roots);
+    await assertStableEntry(selectedPath, selected, canonical, parsed.roots);
+    launch = { file: interpreter.path, argvPrefix: [canonical.path] };
+    interpreter = { request: shebang.request, canonicalEntry: { ...interpreter, content: undefined, stat: undefined }, shebangArgs: shebang.shebangArgs };
+    delete interpreter.canonicalEntry.content;
+    delete interpreter.canonicalEntry.stat;
+  }
+  await verifyRootBindings(parsed.roots);
+  const output = {
+    schemaVersion: 1,
+    kind: "skill-family.executable-identity-observation",
+    lookup: parsed.lookup.mode === "absolute-path"
+      ? { requested: parsed.lookup.requested, mode: parsed.lookup.mode, path: parsed.lookup.path, selectedPath: parsed.lookup.path }
+      : { requested: parsed.lookup.requested, mode: parsed.lookup.mode, pathEntries: parsed.lookup.pathEntries, selectedPath },
+    canonicalEntry: { ...canonical, content: undefined, stat: undefined },
+    interpreter,
+    launch,
+  };
+  delete output.canonicalEntry.content;
+  delete output.canonicalEntry.stat;
+  output.observationDigest = digestDocument(output);
+  return freezeDeep(output);
+}

package/src/filesystem-observation.mjs

@@ -1,18 +1,176 @@
 import path from "node:path";
+import { lstat, readdir, readlink } from "node:fs/promises";
 import { digestDocument } from "skill-family-contracts";
 import { digestBytes } from "./closure.mjs";
 import { HARNESS_ERROR_KINDS, mechanismError } from "./errors.mjs";
-import { assertRelativePath, createFilesystemRootBinding } from "./bound-read.mjs";
+import { assertRelativePath, createFilesystemRootBinding, readFileBound } from "./bound-read.mjs";
 import { loadNativeBoundReadAddon } from "./native/loader.mjs";
 
 const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+const SYMLINK_POLICY_KEYS = ["mode"];
+
+function compareUnicodeCodePoints(left, right) {
+  const leftPoints = Array.from(left, (character) => character.codePointAt(0));
+  const rightPoints = Array.from(right, (character) => character.codePointAt(0));
+  const length = Math.min(leftPoints.length, rightPoints.length);
+  for (let index = 0; index < length; index += 1) {
+    if (leftPoints[index] !== rightPoints[index]) return leftPoints[index] - rightPoints[index];
+  }
+  return leftPoints.length - rightPoints.length;
+}
+
+function parseSymlinkPolicy(symlinkPolicy) {
+  if (symlinkPolicy === undefined) return "reject";
+  if (symlinkPolicy === null || typeof symlinkPolicy !== "object" || Array.isArray(symlinkPolicy) ||
+      Object.keys(symlinkPolicy).sort().join(",") !== SYMLINK_POLICY_KEYS.join(",") ||
+      !["record", "reject"].includes(symlinkPolicy.mode)) {
+    throw new TypeError('observeFilesystemTree: symlinkPolicy must be { mode: "record"|"reject" }');
+  }
+  return symlinkPolicy.mode;
+}
+
+function recordBoundary(message, input, cause) {
+  throw mechanismError(HARNESS_ERROR_KINDS.UNSAFE_STATE_ENTRY, message, {
+    ...(input === undefined ? {} : { input }),
+    boundReadDisposition: "boundary-indeterminate",
+    ...(cause === undefined ? {} : { cause: cause?.message ?? String(cause) }),
+  });
+}
+
+function sameLinkStat(left, right) {
+  return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+    left.nlink === right.nlink && left.size === right.size && left.mtimeNs === right.mtimeNs &&
+    left.ctimeNs === right.ctimeNs;
+}
+
+async function readStableSymlink(relative, absolute) {
+  let before;
+  try {
+    before = await lstat(absolute, { bigint: true });
+    if (!before.isSymbolicLink()) recordBoundary("filesystem tree link changed before it could be recorded", relative);
+    const first = Buffer.from(await readlink(absolute, { encoding: "buffer" }));
+    const middle = await lstat(absolute, { bigint: true });
+    const second = Buffer.from(await readlink(absolute, { encoding: "buffer" }));
+    const after = await lstat(absolute, { bigint: true });
+    if (!sameLinkStat(before, middle) || !sameLinkStat(before, after) ||
+        !first.equals(second)) {
+      recordBoundary("filesystem tree symbolic link changed while being read", relative);
+    }
+    return {
+      path: relative,
+      type: "symlink",
+      targetBase64: first.toString("base64"),
+      bytes: first.length,
+      statMode: Number(after.mode),
+    };
+  } catch (cause) {
+    if (cause?.code === "SFC2004") throw cause;
+    recordBoundary("filesystem tree symbolic link could not be recorded", relative, cause);
+  }
+}
+
+async function collectRecordMembers(root, rootBinding, absolute, relativePrefix, members) {
+  let directoryBefore;
+  try {
+    directoryBefore = await lstat(absolute, { bigint: true });
+    if (!directoryBefore.isDirectory()) {
+      recordBoundary("filesystem tree directory changed before it could be read", relativePrefix || undefined);
+    }
+  } catch (cause) {
+    recordBoundary("filesystem tree directory could not be inspected", relativePrefix || undefined, cause);
+  }
+  let entries;
+  try {
+    entries = await readdir(absolute, { withFileTypes: true });
+  } catch (cause) {
+    recordBoundary("filesystem tree directory could not be enumerated", relativePrefix || undefined, cause);
+  }
+  for (const entry of entries) {
+    const relative = relativePrefix ? path.posix.join(relativePrefix, entry.name) : entry.name;
+    assertRelativePath(relative);
+    const child = path.join(root, ...relative.split("/"));
+    let stats;
+    try {
+      stats = await lstat(child, { bigint: true });
+    } catch (cause) {
+      recordBoundary("filesystem tree member could not be inspected", relative, cause);
+    }
+    if (stats.isSymbolicLink()) {
+      members.push(await readStableSymlink(relative, child));
+      continue;
+    }
+    if (stats.isDirectory()) {
+      members.push({ path: relative, type: "directory", statMode: Number(stats.mode) });
+      await collectRecordMembers(root, rootBinding, child, relative, members);
+      let after;
+      try {
+        after = await lstat(child, { bigint: true });
+      } catch (cause) {
+        recordBoundary("filesystem tree directory changed while being read", relative, cause);
+      }
+      if (!sameLinkStat(stats, after)) {
+        recordBoundary("filesystem tree directory changed while being read", relative);
+      }
+      continue;
+    }
+    if (stats.isFile()) {
+      if (stats.nlink !== 1n) {
+        recordBoundary("filesystem tree contains a multiply-linked regular file", relative);
+      }
+      let receipt;
+      try {
+        receipt = await readFileBound(root, relative, { rootBinding });
+      } catch (cause) {
+        throw cause;
+      }
+      const bytes = Buffer.from(receipt.content);
+      members.push({
+        path: relative,
+        type: "file",
+        sha256: digestBytes(bytes),
+        bytes: bytes.length,
+        statMode: Number(receipt.statMode),
+        contentBase64: bytes.toString("base64"),
+      });
+      continue;
+    }
+    recordBoundary("filesystem tree contains a special file", relative);
+  }
+  let directoryAfter;
+  try {
+    directoryAfter = await lstat(absolute, { bigint: true });
+  } catch (cause) {
+    recordBoundary("filesystem tree directory changed while being read", relativePrefix || undefined, cause);
+  }
+  if (!sameLinkStat(directoryBefore, directoryAfter)) {
+    recordBoundary("filesystem tree directory changed while being read", relativePrefix || undefined);
+  }
+}
+
+async function observeFilesystemTreeRecord(root, rootBinding) {
+  const members = [];
+  await collectRecordMembers(root, rootBinding, root, "", members);
+  return members;
+}
+
+function rejectCaseAliasMembers(members) {
+  const paths = new Set();
+  for (const member of members) {
+    const alias = member.path.toLowerCase();
+    if (paths.has(alias)) {
+      throw mechanismError(HARNESS_ERROR_KINDS.INVALID_PATH, "filesystem tree contains duplicate or case-alias member paths");
+    }
+    paths.add(alias);
+  }
+}
 
 /**
- * Observe every directory and regular-file member of one already bound tree.
- * Native code opens each member relative to the root and supplies its bytes
- * and descriptor facts; this layer only derives the public contract shape.
+ * Observe every member of one already bound tree. The default reject path
+ * keeps the native 0.14 contract; explicit record mode is a Node/JS
+ * best-effort observation of symlinks and reuses readFileBound for files.
  */
-export async function observeFilesystemTree({ root, rootBinding } = {}) {
+export async function observeFilesystemTree({ root, rootBinding, symlinkPolicy } = {}) {
+  const mode = parseSymlinkPolicy(symlinkPolicy);
   if (typeof root !== "string" || !path.isAbsolute(root) || path.normalize(root) !== root) {
     throw new TypeError("observeFilesystemTree: root must be a normalized absolute path");
   }
@@ -26,6 +184,24 @@ export async function observeFilesystemTree({ root, rootBinding } = {}) {
       boundReadDisposition: "boundary-indeterminate",
     });
   }
+  if (mode === "record") {
+    const members = await observeFilesystemTreeRecord(root, rootBinding);
+    rejectCaseAliasMembers(members);
+    const endBinding = await createFilesystemRootBinding(root);
+    if (endBinding.digest !== rootBinding.digest) {
+      throw mechanismError(HARNESS_ERROR_KINDS.UNSAFE_STATE_ENTRY, "root identity changed during filesystem tree observation", {
+        boundReadDisposition: "boundary-indeterminate",
+      });
+    }
+    members.sort((left, right) => compareUnicodeCodePoints(left.path, right.path));
+    return Object.freeze({
+      schemaVersion: 1,
+      kind: "skill-family.filesystem-tree-observation",
+      rootBinding,
+      members: Object.freeze(members.map((member) => Object.freeze(member))),
+      membersDigest: digestDocument(members),
+    });
+  }
   const { addon } = await loadNativeBoundReadAddon();
   if (typeof addon.observeFilesystemTreeNative !== "function") {
     throw mechanismError(HARNESS_ERROR_KINDS.UNSUPPORTED_PLATFORM, "native filesystem observation is unavailable in this prebuild");

package/src/index.mjs

@@ -30,6 +30,7 @@ export const HARNESS_CAPABILITIES = Object.freeze([
   "token-estimation",
   "upper-bound-guard",
   "supervise-process",
+  "executable-identity-observation",
   // Foundation capability completion (FG-1/FG-2): strict authority reads and
   // pre-persistence URL credential redaction.
   "strict-read",
@@ -55,6 +56,10 @@ export { classifyPathInput, resolveContained, readFileContained } from "./paths.
 // descriptor-relative traversal and same-descriptor fstat/read checks.
 export { observeFilesystemTree } from "./filesystem-observation.mjs";
 
+// Deterministic, per-call executable identity observation.  The caller owns
+// the explicit roots and PATH entries; no ambient PATH or cache is consulted.
+export { observeExecutableIdentity } from "./executable-identity.mjs";
+
 // Strict contained read (FG-1): no-follow, regular-file identity assertion,
 // and a post-read sha256 digest receipt for existing authority files.
 export { readFileStrict } from "./strict-read.mjs";

package/src/version.mjs

@@ -1,2 +1,2 @@
 /** Exact Foundation release coordinate shared by the public Harness exports. */
-export const FOUNDATION_PACKAGE_VERSION = "0.14.0";
+export const FOUNDATION_PACKAGE_VERSION = "0.16.0";