release-skill 0.4.2 → 0.5.1

package/src/core/plan.mjs

@@ -15,10 +15,13 @@
  * @module core/plan
  */
 
-import { readFile, writeFile, rename, mkdir, open, link, unlink, lstat } from 'node:fs/promises';
+import { readFile, mkdir, lstat } from 'node:fs/promises';
 import { basename, dirname, join, resolve, parse, sep } from 'node:path';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
+import { digestDocument } from 'skill-family-contracts';
+import { writeFileAtomic } from 'skill-family-harness-node';
+import { publishFileExclusive, HARNESS_ERROR_KINDS as INFLIGHT_KINDS } from './foundation-inflight.mjs';
 import { canonicalJson, sha256Hex } from './digest.mjs';
 import { ReleaseError, GATE_FAILED } from './errors.mjs';
 import { readTrustedPackageResource } from './trusted-resource.mjs';
@@ -248,6 +251,11 @@ function stripRecordLayerV2(plan) {
  * @returns {string} Lowercase 64-char hex SHA-256 digest.
  */
 export function computePlanDigest(plan) {
+  // 输入域适配：计划绑定层可能含条件置 undefined 的字段（如 codebuddy 的
+  // marketplace），本地语义为省略该字段。因此不直接用严格 digestDocument，
+  // 而是经 digest.mjs 的宽松输入域包装（contracts 权威序列化 + 本地归一化）
+  // 后由 Foundation digestBytes 摘要 —— 对纯 JSON 计划与 digestDocument 字节
+  // 完全一致，对含 undefined 的计划保持迁移前字节语义。
   if (plan.planVersion === 2) {
     return sha256Hex(canonicalJson(stripRecordLayerV2(plan)));
   }
@@ -286,15 +294,11 @@ export async function writePlanAtomic(planPath, plan) {
   // 4. Serialise
   const json = JSON.stringify(augmented, null, 2);
 
-  // 5. Write to temp file in the same directory
+  // 5. Write atomically via Foundation (contained, exclusive temp, fsync, rename)
   const dir = dirname(planPath);
   await prepareAuthorityDirectory(dir);
   await assertAuthorityFileTarget(planPath);
-  const tmpPath = `${dir}/.release-plan-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`;
-  await writeFile(tmpPath, json, 'utf8');
-
-  // 6. Atomic rename
-  await rename(tmpPath, planPath);
+  await writeFileAtomic(dir, basename(planPath), json);
 
   return { planPath, planDigest };
 }
@@ -303,9 +307,11 @@ export async function writePlanAtomic(planPath, plan) {
  * Create a digest-addressed plan authority exactly once.
  *
  * The target must be named by the computed digest. An existing byte-identical
- * authority is reused; an existing divergent file fails closed. A temporary
- * file is fsynced and atomically linked into place so concurrent prepares can
- * never replace an authority that another process already created.
+ * authority is reused; an existing divergent file fails closed. The write
+ * delegates to Foundation `publishFileExclusive` (temp + fsync + exclusive
+ * link + byte/mode/identity verification + directory fsync); this wrapper
+ * supplies the idempotent-same-bytes branch that the in-flight Foundation
+ * version does not have (G4 conflict-surface.md 第一节).
  */
 export async function writePlanImmutable(planPath, plan) {
   const planDigest = computePlanDigest(plan);
@@ -324,21 +330,15 @@ export async function writePlanImmutable(planPath, plan) {
   const dir = dirname(planPath);
   await prepareAuthorityDirectory(dir);
   await assertAuthorityFileTarget(planPath);
-  const tmpPath = join(dir, `.release-plan-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`);
-  const handle = await open(tmpPath, 'wx', 0o600);
-  try {
-    await handle.writeFile(json, 'utf8');
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
 
   try {
-    await link(tmpPath, planPath);
-  } catch (error) {
-    if (error.code !== 'EEXIST') throw error;
-    const existing = await readFile(planPath, 'utf8');
-    if (existing !== json) {
+    await publishFileExclusive(dir, basename(planPath), json, { mode: 0o600 });
+  } catch (cause) {
+    if (cause?.details?.kind === INFLIGHT_KINDS.EXCLUSIVE_PUBLISH_CONFLICT) {
+      // 同字节幂等：目标已存在且字节相同 → 幂等成功（Foundation 在途版
+      // EEXIST 直接抛冲突，无幂等分支；wrapper 补齐，fail-closed 无双路径）。
+      const existing = await readFile(planPath, 'utf8').catch(() => null);
+      if (existing === json) return { planPath, planDigest };
       // planVersion 2 (design: t1-2-digest-decoupling.md §4.1): record-layer
       // fields (status/createdAt/baseline) are excluded from the digest, so
       // re-preparing over identical binding content yields the SAME digest
@@ -346,7 +346,7 @@ export async function writePlanImmutable(planPath, plan) {
       // it is genuinely self-consistent (its embedded digest and recomputed
       // digest both equal this digest) -- the authority is never replaced.
       // Any other divergence (tampering, malformed file) still fails closed.
-      if (plan.planVersion === 2) {
+      if (plan.planVersion === 2 && existing !== null) {
         let existingPlan = null;
         try {
           existingPlan = JSON.parse(existing);
@@ -367,8 +367,11 @@ export async function writePlanImmutable(planPath, plan) {
         { planPath, planDigest },
       );
     }
-  } finally {
-    await unlink(tmpPath).catch(() => {});
+    throw new ReleaseError(
+      GATE_FAILED,
+      `immutable plan authority write failed: ${cause?.message ?? String(cause)}`,
+      { planPath, planDigest },
+    );
   }
 
   return { planPath, planDigest };
@@ -531,8 +534,18 @@ export function validatePlanActionCompleteness(plan, options = {}) {
         if (!frozen.parentCommit || frozen.parentCommit !== unit.previousPublicBaseline?.commit) {
           failures.push(`unit "${unitId}" frozenSnapshot.parentCommit does not match previous public baseline commit`);
         }
-      } else if (frozen.parentCommit) {
-        failures.push(`unit "${unitId}" create-release-branch must not freeze a parentCommit`);
+      } else if (branchStrategy === 'create-release-branch') {
+        // Chain-integrity gate (0.5.1): create-release-branch creates an
+        // orphan root commit (no parent). It is only legitimate for the
+        // FIRST release of a repository (previousPublicBaseline.mode=none).
+        // A later release using it would start a fresh lineage disconnected
+        // from the published history — the historical orphan-root channel.
+        if (unit.previousPublicBaseline?.mode === 'bound') {
+          failures.push(`unit "${unitId}" create-release-branch is only valid for first releases (previousPublicBaseline.mode=none), but a bound previous public baseline exists`);
+        }
+        if (frozen.parentCommit) {
+          failures.push(`unit "${unitId}" create-release-branch must not freeze a parentCommit`);
+        }
       }
       if (
         branchStrategy === 'advance-existing-branch' &&
@@ -1149,7 +1162,7 @@ export function validatePlanActionCompleteness(plan, options = {}) {
         // 不能只比较两个可一起篡改的字符串；必须重新由 distribution 的 installationContract 计算并验证
         if (hasFieldGroup && dist.installationContract) {
           // 从 distribution 的 installationContract 重新计算摘要
-          const recomputedDigest = sha256Hex(canonicalJson(dist.installationContract));
+          const recomputedDigest = digestDocument(dist.installationContract);
           const actionDigest = action.parameters?.installationContractDigest;
           const distDigest = dist.installationContractDigest;
 

package/src/core/run.mjs

@@ -12,7 +12,7 @@
  * @module core/run
  */
 
-import { link, lstat, mkdir, open, readFile, unlink } from 'node:fs/promises';
+import { lstat, mkdir, readFile } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import { dirname, join, resolve, basename, relative, isAbsolute } from 'node:path';
 import Ajv from 'ajv';
@@ -22,6 +22,7 @@ import { assertImmutablePlanAuthority, computePlanDigest } from './plan.mjs';
 import { sha256Hex } from './digest.mjs';
 import { ReleaseError, GATE_FAILED } from './errors.mjs';
 import { readTrustedPackageResource } from './trusted-resource.mjs';
+import { publishFileExclusive, HARNESS_ERROR_KINDS as INFLIGHT_KINDS } from './foundation-inflight.mjs';
 
 const RELEASE_RUN_SCHEMA = JSON.parse((await readTrustedPackageResource(
   'schemas/release-run.schema.json',
@@ -578,25 +579,18 @@ function sealRun(run) {
   return sealed;
 }
 
-async function syncDirectory(dir) {
-  const handle = await open(dir, 'r');
-  try {
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
-}
-
 /**
  * Write a run file atomically to disk.
  *
  * Validates the run against the schema before writing.
- * Uses temp-file + rename for atomicity.
+ * Delegates to Foundation `publishFileExclusive` (temp + fsync + exclusive
+ * link + byte/mode/identity verification + directory fsync).
  *
  * **Exclusive-create semantics**: if a file already exists at `runPath`
  * with different bytes, the write fails.  This prevents a stale run from
  * silently overwriting a newer run record.  Writes are idempotent when
- * the content is byte-identical.
+ * the content is byte-identical (wrapper-supplied branch; the in-flight
+ * Foundation version has no same-bytes idempotency — G4 conflict-surface.md).
  *
  * @param {string} runPath - Absolute path to write the run to.
  * @param {Object} run - The run object to write.
@@ -608,34 +602,26 @@ export async function writeRunAtomic(runPath, run) {
   const sealed = sealRun(run);
   const json = JSON.stringify(sealed, null, 2);
   const dir = dirname(runPath);
-  const tmpPath = `${dir}/.release-run-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`;
   await mkdir(dir, { recursive: true });
 
-  const handle = await open(tmpPath, 'wx', 0o600);
   try {
-    await handle.writeFile(json, 'utf8');
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
-
-  try {
-    try {
-      await link(tmpPath, runPath);
-      await syncDirectory(dir);
-    } catch (error) {
-      if (error.code !== 'EEXIST') throw error;
-      const existing = await readFile(runPath, 'utf8');
-      if (existing !== json) {
-        throw new ReleaseError(
-          GATE_FAILED,
-          'run file already exists with different bytes; exclusive-create rejected overwrite',
-          { runPath },
-        );
-      }
+    await publishFileExclusive(dir, basename(runPath), json, { mode: 0o600 });
+  } catch (cause) {
+    if (cause?.details?.kind === INFLIGHT_KINDS.EXCLUSIVE_PUBLISH_CONFLICT) {
+      // 同字节幂等：目标已存在且字节相同 → 幂等成功（fail-closed 无双路径）。
+      const existing = await readFile(runPath, 'utf8').catch(() => null);
+      if (existing === json) return Object.freeze(sealed);
+      throw new ReleaseError(
+        GATE_FAILED,
+        'run file already exists with different bytes; exclusive-create rejected overwrite',
+        { runPath },
+      );
     }
-  } finally {
-    await unlink(tmpPath).catch(() => {});
+    throw new ReleaseError(
+      GATE_FAILED,
+      `run file write failed: ${cause?.message ?? String(cause)}`,
+      { runPath },
+    );
   }
 
   return Object.freeze(sealed);

package/src/core/skill-resource-closure.mjs

@@ -10,7 +10,7 @@
 import { lstat, readFile, readdir } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 
-import { canonicalJson, sha256Hex } from './digest.mjs';
+import { canonicalJson, digestDocument } from 'skill-family-contracts';
 import { GATE_FAILED, ReleaseError } from './errors.mjs';
 import { computeFrozenSnapshot } from '../snapshot/frozen.mjs';
 
@@ -258,6 +258,8 @@ export function createSkillResourceClosureReceipt(result, identity = {}) {
 }
 
 export function assertSkillResourceClosureReceipt(expected, observed, label = 'release unit') {
+  // 收据对象均为纯 JSON（JSON.parse 派生或固定字段投影），直接委托 Foundation
+  // contracts 严格 canonicalJson 比较（非 JSON 输入 fail-closed，抛 TypeError）。
   if (canonicalJson(expected) !== canonicalJson(observed)) {
     throw new ReleaseError(
       GATE_FAILED,
@@ -319,9 +321,9 @@ export async function checkSkillResourceClosure({
     })).digest;
   } catch (error) {
     snapshotError = error;
-    inputDigest = sha256Hex(canonicalJson({
+    inputDigest = digestDocument({
       invalidTree: error.message,
-    }));
+    });
   }
   const skillPaths = await discoverSkills(scanRoot);
   const findings = [];
@@ -426,6 +428,6 @@ export async function checkSkillResourceClosure({
     sourceOnlyCount,
     findings,
   };
-  result.receiptDigest = sha256Hex(canonicalJson(receiptProjection(result)));
+  result.receiptDigest = digestDocument(receiptProjection(result));
   return result;
 }

package/src/core/trusted-resource.mjs

@@ -1,12 +1,23 @@
 /**
  * Read package-owned runtime resources without following untrusted links.
  * Installed adapters use this for schemas and native manifests.
+ *
+ * 机制已委托 Foundation（skill-family-foundation-adoption-20260815 节点 1.6）：
+ * - 异步变体 `readTrustedPackageResource`：路径包含三层校验（词法/符号链接/
+ *   realpath 逃逸）委托 `resolveContained`，读取委托 `readFileContained`；
+ *   本地保留域策略前置校验 `assertStat`（拒绝任何符号链接、非常规文件与
+ *   硬链接），失败原因映射保持原语义。
+ * - 同步变体 `readTrustedPackageResourceSync`：Foundation 无同步路径 API，
+ *   词法分类委托同步纯函数 `classifyPathInput`，其余本地同步实现保留
+ *   （残留，见 1.6 run-report 剩余风险）。
  */
 
 import { lstatSync, readFileSync, realpathSync } from 'node:fs';
-import { lstat, readFile, realpath } from 'node:fs/promises';
+import { lstat } from 'node:fs/promises';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 
+import { classifyPathInput, readFileContained, resolveContained } from 'skill-family-harness-node';
+
 import { CONFIG_INVALID, ReleaseError } from './errors.mjs';
 import { PKG_ROOT } from './pkg-root.mjs';
 
@@ -18,6 +29,8 @@ function fail(code, resource, reason) {
   );
 }
 
+// ---- 同步变体保留的本地实现（Foundation 无同步路径 API，文档化残留） ----
+
 function lexicalPath(resource, code) {
   if (typeof resource !== 'string' || resource.length === 0 || isAbsolute(resource)) {
     fail(code, String(resource), 'INVALID_RESOURCE_PATH');
@@ -43,7 +56,44 @@ function assertPhysicalContainment(physicalRoot, physicalPath, resource, code) {
   }
 }
 
+// ---- Foundation 机制错误 → 本地失败语义映射 ----
+
+/** 把 Foundation HarnessError（SFC2004 + details.kind）映射为本地失败原因。 */
+function harnessKindToReason(kind) {
+  switch (kind) {
+    case 'path-traversal':
+      return 'RESOURCE_PATH_ESCAPE';
+    case 'symlink-escape':
+      // 本地语义：lstat 前置校验对任何符号链接一律报 SYMLINK（不区分指向）。
+      // Foundation 对指向包外的符号链接先抛 symlink-escape，映射回 SYMLINK
+      // 保持原失败原因；包内符号链接由本地 assertStat 以 SYMLINK 拦截。
+      return 'SYMLINK';
+    case 'realpath-escape':
+      return 'PHYSICAL_PATH_ESCAPE';
+    case 'missing-resource':
+      return 'MISSING';
+    case 'read-failed':
+      return 'READ_FAILED';
+    default:
+      // invalid-path / absolute-path / windows-drive-path / unc-path /
+      // windows-path / invalid-root 等统一归入无效资源路径。
+      return 'INVALID_RESOURCE_PATH';
+  }
+}
+
+function mapHarnessError(cause, resource, code) {
+  if (cause && cause.code === 'SFC2004' && cause.details && typeof cause.details.kind === 'string') {
+    fail(code, resource, harnessKindToReason(cause.details.kind));
+  }
+  throw cause;
+}
+
 export function readTrustedPackageResourceSync(resource, { code = CONFIG_INVALID } = {}) {
+  // 词法分类委托 Foundation classifyPathInput（同步纯函数；比本地词法检查
+  // 更严格地拒绝反斜杠/NUL/UNC/盘符相对等跨平台歧义输入，fail-closed）。
+  const classification = classifyPathInput(resource, process.platform);
+  if (!classification.ok) fail(code, String(resource), 'INVALID_RESOURCE_PATH');
+
   const path = lexicalPath(resource, code);
   let stat;
   try {
@@ -70,27 +120,26 @@ export function readTrustedPackageResourceSync(resource, { code = CONFIG_INVALID
 }
 
 export async function readTrustedPackageResource(resource, { code = CONFIG_INVALID } = {}) {
-  const path = lexicalPath(resource, code);
+  // 机制委托：resolveContained（词法/符号链接/realpath 三层包含校验）。
+  let target;
+  try {
+    target = await resolveContained(PKG_ROOT, resource);
+  } catch (cause) {
+    mapHarnessError(cause, resource, code);
+  }
+
+  // 本地域策略前置：拒绝任何符号链接（含指向包内目标的）、非常规文件与硬链接。
   let stat;
   try {
-    stat = await lstat(path);
+    stat = await lstat(target);
   } catch {
     fail(code, resource, 'MISSING');
   }
   assertStat(stat, resource, code);
 
-  let physicalRoot;
-  let physicalPath;
   try {
-    physicalRoot = await realpath(PKG_ROOT);
-    physicalPath = await realpath(path);
-  } catch {
-    fail(code, resource, 'REALPATH_FAILED');
-  }
-  assertPhysicalContainment(physicalRoot, physicalPath, resource, code);
-  try {
-    return await readFile(physicalPath);
-  } catch {
-    fail(code, resource, 'READ_FAILED');
+    return await readFileContained(PKG_ROOT, resource);
+  } catch (cause) {
+    mapHarnessError(cause, resource, code);
   }
 }

package/src/producers/build-adapters.mjs

@@ -21,9 +21,10 @@
 import { readdir, mkdir, lstat, realpath, open, rm } from 'node:fs/promises';
 import { constants as fsConstants } from 'node:fs';
 import { join, dirname, relative, isAbsolute, sep, resolve, posix as pathPosix } from 'node:path';
-import { createHash } from 'node:crypto';
 
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
+import { digestDocument } from 'skill-family-contracts';
+import { digestBytes } from 'skill-family-harness-node';
 import { PLATFORMS as PLATFORM_REGISTRY } from '../platforms/registry.mjs';
 
 /**
@@ -186,11 +187,14 @@ async function ensureTrustedOutputDirectory(rootPath, rootIdentity, relativeDir,
  * @returns {string}
  */
 export function computeBuildAdaptersDigest(sourceBytes) {
-  const h = createHash('sha256');
-  for (const buf of sourceBytes) h.update(buf);
-  h.update(`node:${process.version}`);
-  h.update('locale:en-US timezone:UTC');
-  return `sha256:${h.digest('hex')}`;
+  // 多段哈希（源字节 + node 版本 + 固定 locale/timezone）等价于对拼接字节
+  // 的 sha256，委托 Foundation digestBytes 实现，字节逐位一致。
+  const bytes = Buffer.concat([
+    ...sourceBytes,
+    Buffer.from(`node:${process.version}`),
+    Buffer.from('locale:en-US timezone:UTC'),
+  ]);
+  return `sha256:${digestBytes(bytes)}`;
 }
 
 // Platform definitions, derived from the platform registry (the single source
@@ -488,8 +492,21 @@ async function generateAdapterFiles(platform, skills, templateJson, root, market
     });
   }
 
-  // Copy bin/ entry point and bundle (text files)
-  const binFiles = ['release-skill.mjs', 'release-skill.bundle.mjs'];
+  // Copy bin/ entry point and bundle (text files). The self-contained
+  // bundle ships runtime sidecars next to it (JSON resources read via
+  // new URL(<rel>, import.meta.url) by inlined Foundation modules, e.g.
+  // error-codes.json); enumerate the directory so every sidecar is
+  // replicated deterministically. The source CLI (release-skill-cli.mjs)
+  // is never shipped into adapters. The wrapper and the bundle are
+  // required entries: a missing one fails closed before any write.
+  const binFiles = (await readdir(join(root, 'bin')))
+    .filter((name) => name !== 'release-skill-cli.mjs')
+    .sort();
+  for (const required of ['release-skill.mjs', 'release-skill.bundle.mjs']) {
+    if (!binFiles.includes(required)) {
+      throw new Error(`SECURITY: required bundle entry is missing: bin/${required}`);
+    }
+  }
   for (const name of binFiles) {
     const srcPath = join(root, 'bin', name);
     const content = await readTrustedFile(srcPath, root, `bin/${name}`);
@@ -752,8 +769,9 @@ export async function produceBuildAdapters({ inputs, output, outputRoots, platfo
  * @returns {string}
  */
 export function digestEntryOutputs(entries) {
+  // 纯 JSON 投影（platform 条件展开 + 定字段），直接委托 Foundation digestDocument。
   const canonical = entries.map(({ platform, path, type, mode, sha256, size }) => ({
     ...(platform ? { platform } : {}), path, type, mode, size, sha256,
   }));
-  return `sha256:${sha256Hex(canonicalJson(canonical))}`;
+  return `sha256:${digestDocument(canonical)}`;
 }

package/src/producers/render-public-assets.mjs

@@ -13,9 +13,10 @@
 
 import { readFile, writeFile, readdir, stat, mkdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';
-import { createHash } from 'node:crypto';
 
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
+import { digestDocument } from 'skill-family-contracts';
+import { digestBytes } from 'skill-family-harness-node';
 
 /**
  * Compute an implementation digest from the source bytes of this module.
@@ -24,11 +25,14 @@ import { canonicalJson, sha256Hex } from '../core/digest.mjs';
  * @returns {string}
  */
 export function computeRenderDigest(sourceBytes) {
-  const h = createHash('sha256');
-  for (const buf of sourceBytes) h.update(buf);
-  h.update(`node:${process.version}`);
-  h.update('locale:en-US timezone:UTC');
-  return `sha256:${h.digest('hex')}`;
+  // 多段哈希（源字节 + node 版本 + 固定 locale/timezone）等价于对拼接字节
+  // 的 sha256，委托 Foundation digestBytes 实现，字节逐位一致。
+  const bytes = Buffer.concat([
+    ...sourceBytes,
+    Buffer.from(`node:${process.version}`),
+    Buffer.from('locale:en-US timezone:UTC'),
+  ]);
+  return `sha256:${digestBytes(bytes)}`;
 }
 
 /**
@@ -145,8 +149,9 @@ export async function produceRenderPublicAssets({ inputs, output } = {}) {
  * @returns {string}
  */
 export function digestEntryOutputs(entries) {
+  // 纯 JSON 投影（定字段），直接委托 Foundation digestDocument。
   const canonical = entries.map(({ path, type, mode, sha256, size }) => ({
     path, type, mode, size, sha256,
   }));
-  return `sha256:${sha256Hex(canonicalJson(canonical))}`;
+  return `sha256:${digestDocument(canonical)}`;
 }

package/src/producers/sync-skills.mjs

@@ -11,9 +11,10 @@
 
 import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { createHash } from 'node:crypto';
 
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
+import { digestDocument } from 'skill-family-contracts';
+import { digestBytes } from 'skill-family-harness-node';
 
 /**
  * Compute an implementation digest from the source bytes of this module.
@@ -22,11 +23,14 @@ import { canonicalJson, sha256Hex } from '../core/digest.mjs';
  * @returns {string}
  */
 export function computeSyncSkillsDigest(sourceBytes) {
-  const h = createHash('sha256');
-  for (const buf of sourceBytes) h.update(buf);
-  h.update(`node:${process.version}`);
-  h.update('locale:en-US timezone:UTC');
-  return `sha256:${h.digest('hex')}`;
+  // 多段哈希（源字节 + node 版本 + 固定 locale/timezone）等价于对拼接字节
+  // 的 sha256，委托 Foundation digestBytes 实现，字节逐位一致。
+  const bytes = Buffer.concat([
+    ...sourceBytes,
+    Buffer.from(`node:${process.version}`),
+    Buffer.from('locale:en-US timezone:UTC'),
+  ]);
+  return `sha256:${digestBytes(bytes)}`;
 }
 
 /**
@@ -89,8 +93,9 @@ export async function produceSyncSkills({ inputs, output } = {}) {
  * @returns {string}
  */
 export function digestEntryOutputs(entries) {
+  // 纯 JSON 投影（定字段），直接委托 Foundation digestDocument。
   const canonical = entries.map(({ path, type, mode, sha256, size }) => ({
     path, type, mode, size, sha256,
   }));
-  return `sha256:${sha256Hex(canonicalJson(canonical))}`;
+  return `sha256:${digestDocument(canonical)}`;
 }

package/src/snapshot/public-map.mjs

@@ -24,9 +24,10 @@
 import { lstat, readFile, mkdir, readdir, realpath, chmod as fsChmod } from 'node:fs/promises';
 import { open as fsOpen } from 'node:fs/promises';
 import { relative, resolve, dirname, sep as pathSep, isAbsolute } from 'node:path';
-import { posix } from 'node:path';
+import { posix, win32 } from 'node:path';
 import { constants as fsConstants } from 'node:fs';
 import { createHash } from 'node:crypto';
+import { classifyPathInput } from 'skill-family-harness-node';
 import {
   ReleaseError,
   PUBLIC_FILE_MISSING,
@@ -81,7 +82,14 @@ const MAX_PATH_LENGTH = 4096;
  */
 export function _isContainedWith(relativeFn, isAbsoluteFn, root, candidate, relPathSep = pathSep) {
   const rel = relativeFn(root, candidate);
-  return rel !== '' && rel !== '..' && !rel.startsWith(`..${relPathSep}`) && !isAbsoluteFn(rel);
+  if (rel === '' || rel === '..' || rel.startsWith(`..${relPathSep}`) || isAbsoluteFn(rel)) {
+    return false;
+  }
+  // 词法分类委托 Foundation classifyPathInput（同步纯函数）：对相对路径做
+  // 跨平台歧义输入 fail-closed（反斜杠分隔符/NUL/UNC/盘符相对/绝对路径）。
+  // 平台从注入的 relativeFn 推导，保持纯同步、无文件系统访问的既有契约。
+  const platform = relativeFn === win32.relative ? 'win32' : 'posix';
+  return classifyPathInput(rel, platform).ok === true;
 }
 
 /**