release-skill 0.4.1 → 0.5.0

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/platforms/codebuddy.mjs

@@ -88,15 +88,55 @@ export const CODEBUDDY_REQUIREMENT_FILE = 'release-skill-codebuddy-manual-instal
 export const CODEBUDDY_ATTESTATION_FILE = 'release-skill-codebuddy-attestation.json';
 
 /**
- * Unified marketplace the WorkBuddy desktop app and the codebuddy CLI install
- * release-skill from (verified fact). The attestation `marketplace` field must
- * equal this value; the install path is validated against this marketplace
- * segment in both channels.
+ * Default unified marketplace the WorkBuddy desktop app and the codebuddy CLI
+ * install from (verified fact). A distribution may override this by declaring
+ * `marketplace` (see resolveCodeBuddyMarketplace); the install path is
+ * validated against the resolved marketplace segment in both channels, and a
+ * declared attestation `marketplace` field must equal the resolved name.
  */
 export const CODEBUDDY_MARKETPLACE_NAME = 'artifact-skill-set';
-/** Marketplace source URL used by the isolated-CLI install path. */
+/** Default marketplace source URL (used only when no marketplace override is declared). */
 export const CODEBUDDY_MARKETPLACE_SOURCE = 'https://github.com/ifoohoo/artifact-skill-set';
 
+/**
+ * Resolve the unified marketplace name for a codebuddy action.
+ *
+ * Falls back to CODEBUDDY_MARKETPLACE_NAME when the action carries no
+ * `marketplace` (legacy frozen plans, byte-identical behavior). A declared
+ * marketplace must be a non-empty string; anything else fails closed.
+ *
+ * @param {object} [action] - expanded codebuddy action (may be undefined).
+ * @returns {string} the resolved marketplace name.
+ * @throws {Error} when a declared marketplace is not a non-empty string.
+ */
+export function resolveCodeBuddyMarketplace(action) {
+  const marketplace = action?.marketplace ?? CODEBUDDY_MARKETPLACE_NAME;
+  if (typeof marketplace !== 'string' || marketplace.length === 0) {
+    throw new Error(`codebuddy marketplace must be a non-empty string when declared, got ${JSON.stringify(action?.marketplace)}`);
+  }
+  return marketplace;
+}
+
+/**
+ * Resolve the marketplace source URL for a codebuddy action, when knowable.
+ *
+ * The default marketplace has a verified source constant; a configured
+ * marketplace only has a source when the distribution declared
+ * `marketplaceSource`. When neither applies, null is returned and callers
+ * must NOT fabricate a URL.
+ *
+ * @param {object} [action] - expanded codebuddy action (may be undefined).
+ * @returns {string|null} the source URL, or null when unknown.
+ */
+export function resolveCodeBuddyMarketplaceSource(action) {
+  if (action?.marketplace === undefined || action?.marketplace === null) {
+    return CODEBUDDY_MARKETPLACE_SOURCE;
+  }
+  return typeof action.marketplaceSource === 'string' && action.marketplaceSource.length > 0
+    ? action.marketplaceSource
+    : null;
+}
+
 /** Authoritative codebuddy plugin manifest (single candidate, no precedence). */
 export const CODEBUDDY_PLUGIN_MANIFEST_RELATIVE = join('.codebuddy-plugin', 'plugin.json');
 
@@ -185,7 +225,7 @@ export function codebuddyAuthorityDir(context, planDigest, plugin) {
 /**
  * 统一人工安装说明：面向 CodeBuddy / WorkBuddy 的人工结果流程。
  *
- * @param {{plugin:string, version:string, ref:string, attestationDir:string, requiresInstalledClosure:boolean}} p
+ * @param {{plugin:string, version:string, ref:string, attestationDir:string, requiresInstalledClosure:boolean, marketplace:string, marketplaceSource:string|null}} p
  * @returns {string[]}
  */
 function buildCodeBuddyManualInstructions({
@@ -194,11 +234,13 @@ function buildCodeBuddyManualInstructions({
   ref,
   attestationDir,
   requiresInstalledClosure,
+  marketplace,
+  marketplaceSource,
 }) {
   return [
     `CodeBuddy/WorkBuddy 插件安装无法锁定冻结 ref（codebuddy CLI marketplace add/install 没有 ref 选项，跟踪默认分支），因此安装是需要人工结果证明的手动步骤。`,
     `1) publish 完成所有远端写入后进入 PUBLISHED 状态（自动化 Git 分支/标签、npm 和 GitHub Release 写入已完成）。此 codebuddy 检查点标记为需要人工安装。`,
-    `2) 从统一市场 "${CODEBUDDY_MARKETPLACE_NAME}" (${CODEBUDDY_MARKETPLACE_SOURCE}) 安装 release-skill。确认安装的插件版本等于冻结版本 ${version}。`,
+    `2) 从统一市场 "${marketplace}"${marketplaceSource ? ` (${marketplaceSource})` : ''} 安装 ${plugin}。确认安装的插件版本等于冻结版本 ${version}。`,
     `3) 将人工结果 JSON 写入: ${attestationDir}/${CODEBUDDY_ATTESTATION_FILE}`,
     `   必填字段: platform="codebuddy", version, planDigest（冻结计划摘要）, result("passed" 或 "failed"), actor（确认人）, confirmedAt（ISO 8601 时间戳）${requiresInstalledClosure ? '，installChannel("desktop" 或 "cli")，installPath（实际安装后的插件目录）' : ''}`,
     `   可选字段: note（备注）`,
@@ -312,15 +354,35 @@ export function validateCodeBuddyAttestation(attestation, action, isoNow, boundP
     if (normalized.installPath.includes('..')) {
       return { valid: false, error: 'codebuddy attestation installPath must not contain path traversal ("..")', normalized: null };
     }
-    // CLI 通道：installPath 必须以预期后缀结尾
+    // CLI 通道：installPath 必须以预期后缀结尾（市场名解析自冻结动作，
+    // 未声明时回落到默认统一市场常量）
     if (normalized.installChannel === 'cli') {
-      const expectedSuffix = `.workbuddy/plugins/marketplaces/${CODEBUDDY_MARKETPLACE_NAME}/plugins/${action.plugin}`;
+      let resolvedMarketplace;
+      try {
+        resolvedMarketplace = resolveCodeBuddyMarketplace(action);
+      } catch (resolveErr) {
+        return { valid: false, error: resolveErr.message, normalized: null };
+      }
+      const expectedSuffix = `.workbuddy/plugins/marketplaces/${resolvedMarketplace}/plugins/${action.plugin}`;
       if (!normalized.installPath.endsWith(expectedSuffix)) {
         return { valid: false, error: `codebuddy CLI attestation installPath must end with "${expectedSuffix}", got "${normalized.installPath}"`, normalized: null };
       }
     }
   }
 
+  // 可选 marketplace 字段：一旦声明必须等于冻结动作解析出的市场名
+  if (normalized.marketplace !== undefined) {
+    let resolvedMarketplace;
+    try {
+      resolvedMarketplace = resolveCodeBuddyMarketplace(action);
+    } catch (resolveErr) {
+      return { valid: false, error: resolveErr.message, normalized: null };
+    }
+    if (normalized.marketplace !== resolvedMarketplace) {
+      return { valid: false, error: `codebuddy attestation marketplace "${normalized.marketplace}" does not match the resolved marketplace "${resolvedMarketplace}"`, normalized: null };
+    }
+  }
+
   // result 只接受 passed 或 failed
   if (normalized.result !== 'passed' && normalized.result !== 'failed') {
     return { valid: false, error: `codebuddy attestation result "${normalized.result}" must be "passed" or "failed"`, normalized: null };
@@ -454,6 +516,22 @@ export async function executeCodeBuddyManualRequirement(action, context) {
 
   const ref = action.ref ?? `v${action.version}`;
 
+  // Unified marketplace identity: resolved from the frozen action (declared
+  // `marketplace`/`marketplaceSource`), falling back to the default constants
+  // for legacy plans. A fabricated source URL is never emitted for a
+  // configured marketplace without a declared marketplaceSource.
+  let marketplace;
+  try {
+    marketplace = resolveCodeBuddyMarketplace(action);
+  } catch (marketplaceErr) {
+    return createResult({
+      actionType,
+      status: ActionStatus.EXECUTE_FAILED,
+      error: marketplaceErr.message,
+    });
+  }
+  const marketplaceSource = resolveCodeBuddyMarketplaceSource(action);
+
   // (B) Stable plugin-level authority dir, shared across
   // publish/reconcile/verify run dirs.
   let attestationDir;
@@ -473,6 +551,8 @@ export async function executeCodeBuddyManualRequirement(action, context) {
     ref,
     attestationDir,
     requiresInstalledClosure: Boolean(context.plan?.skillResourceClosure),
+    marketplace,
+    marketplaceSource,
   });
 
   // 统一 requirement 结构：不再包含隔离目录信息
@@ -484,6 +564,8 @@ export async function executeCodeBuddyManualRequirement(action, context) {
     repo: action.repo,
     ref,
     entrySkill: action.entrySkill,
+    marketplace,
+    ...(marketplaceSource ? { marketplaceSource } : {}),
     planDigest,
     attestationDir,
     attestationFile: CODEBUDDY_ATTESTATION_FILE,
@@ -497,7 +579,7 @@ export async function executeCodeBuddyManualRequirement(action, context) {
       ...(context.plan?.skillResourceClosure
         ? {
             installChannel: '<"desktop" or "cli">',
-            installPath: `<actual .workbuddy/plugins/marketplaces/${CODEBUDDY_MARKETPLACE_NAME}/plugins/${action.plugin} directory>`,
+            installPath: `<actual .workbuddy/plugins/marketplaces/${marketplace}/plugins/${action.plugin} directory>`,
           }
         : {}),
       note: '<optional note>',

package/src/platforms/registry.mjs

@@ -359,9 +359,10 @@ const CODEBUDDY = Object.freeze({
     marketplace: '.claude-plugin/marketplace.json',
   }),
   marketplaceSourceForm: null,
-  // codebuddy installs from a unified marketplace but carries no marketplace
-  // identity in the action (the marketplace is a fixed constant in
-  // ./codebuddy.mjs); the entry-version binding does not apply (null = N/A).
+  // codebuddy installs from a unified marketplace whose identity is optional
+  // on the action: a distribution may declare `marketplace` to override the
+  // default constant in ./codebuddy.mjs (resolveCodeBuddyMarketplace); the
+  // entry-version binding does not apply either way (null = N/A).
   marketplaceEntryCarriesVersion: null,
   // codebuddy has no marketplace add that can pin a frozen ref (attestation
   // loop instead), so the marketplace ref form does not apply (null = N/A).

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;
 }
 
 /**