@loomhelm/multi-task-flow 0.2.6 → 0.2.8

package/README.md

@@ -1,8 +1,8 @@
 # `@loomhelm/multi-task-flow`
 
-独立的 Multi-task Flow Skill runtime 与本地账本 CLI，与 Go 客户端并存。包的正式入口是 `multi-task-flow`，兼容别名 `loomhelm` 仍保留；生产运行时只支持 Bun 1.4.4，包直接执行 TypeScript 源码并携带完整 Skill、合同、viewer 资源和依赖闭包。
+独立的 Multi-task Flow Skill runtime 与本地账本 CLI，与 Go 客户端并存。包的正式入口是 `multi-task-flow`，兼容别名 `loomhelm` 仍保留；生产运行时只支持 Bun 1.4.4，包直接执行 TypeScript 源码并携带完整 Skill、合同和 viewer 资源，production dependencies 由消费者安装。
 
-安装包不依赖父仓库 checkout、`~/.agents` 或全局 Skill 源包。`sharp`、`zod` 以及 viewer 运行依赖由 npm 包声明和解析；Bun 是包外部前置条件，不由包自动安装或升级。
+安装包不依赖父仓库 checkout、`~/.agents` 或全局 Skill 源包。`playwright`、`sharp`、`zod` 由 npm 根 package 声明并在消费者 `bun install` 时解析；React、ELK、vis 等只用于 workspace viewer build，Bun 是包外部前置条件，不由包自动安装或升级。
 
 ```sh
 bunx --bun --package @loomhelm/multi-task-flow@compat-v1 multi-task-flow skills list
@@ -17,16 +17,16 @@ bunx --bun --package @loomhelm/multi-task-flow@compat-v1 multi-task-flow flow vi
 可重复的生产安装必须固定 package version；`@compat-v1` 只用于接收同一兼容线内经过门禁的最新版本，`latest` 不构成身份或兼容性证明。运行前置条件是 `bun --version` 返回 `1.4.4`；Bun 由宿主提供，包不会替换或升级它。
 
 ```sh
-bunx --bun --package @loomhelm/multi-task-flow@0.2.6 multi-task-flow skills list
+bunx --bun --package @loomhelm/multi-task-flow@0.2.8 multi-task-flow skills list
 bunx --bun --package @loomhelm/multi-task-flow@compat-v1 multi-task-flow skills list
-bunx --bun --package @loomhelm/multi-task-flow@0.2.6 multi-task-flow flow view --input - < view-request.json
+bunx --bun --package @loomhelm/multi-task-flow@0.2.8 multi-task-flow flow view --input - < view-request.json
 ```
 
-当前源码投影的内部合同矩阵如下；`source_sha`、`merge_sha`、`build_id` 和 `tarball_digest` 是每个候选构建的独立身份字段，不能由这张静态表推断。
+当前源码投影的内部合同矩阵如下；`source_sha`、`merge_sha`、`build_id`、`canonicalDigestAlgorithm=path-byte-v2`、canonical digest 和 raw npm integrity 是每个候选构建的独立身份字段，不能由这张静态表推断。
 
 | 维度 | 当前值 |
 | - | - |
-| package | `@loomhelm/multi-task-flow@0.2.6` |
+| package | `@loomhelm/multi-task-flow@0.2.8` |
 | compatibility line | `compat-v1` |
 | Skill | `2.7.6` |
 | ledger contract | `3` |
@@ -39,6 +39,10 @@ bunx --bun --package @loomhelm/multi-task-flow@0.2.6 multi-task-flow flow view -
 
 npm 发布需要 npm Trusted Publisher 绑定 `IvanLi-CN/Loomhelm` 与 `skill-release-publish.yml`，以及 owner-approved release workflow；不使用长期 npm 写入 token。缺少 Trusted Publisher 或 workflow receipt 时只执行本地 build、pack 和 tarball 校验，不把本地候选称为已发布包。
 
+发布 workflow 使用同一 candidate tarball 执行 exact registry reconcile；404、processing、已知 409、timeout 和 identity mismatch 都必须记录 receipt，不能重传或重建。exact registry identity 对账成功才是 `published`，compatibility line、`latest` 和显式 `stable` 逐个 read-back 成功才是 `completed`；现有 `0.2.7` schema v2 artifact 只做 raw integrity/legacy identity 对账，禁止重传。
+
+客户端只提供 `release identity` 和 `release validate` 等本地只读检查；`release publish`、`publish:exact` 和 `publish:compat` 不提供直接 npm 写入路径，发布只能由受保护的 Skill Runtime Release workflow 完成。
+
 ```sh
 bun install --frozen-lockfile
 bun install --cwd skills/multi-task-flow --frozen-lockfile
@@ -50,7 +54,7 @@ bun --no-install run test
 bun --no-install src/cli.ts --config config.example.json status
 ```
 
-发布包构建前需要准备两个 Skill 依赖目录：`bun install --cwd skills --frozen-lockfile --ignore-scripts --backend=copy` 与 `bun install --cwd skills/multi-task-flow --frozen-lockfile`。随后在 `clients/typescript/` 执行 `bun --no-install run build`，构建会拒绝摘要不一致、缺失依赖、符号链接资源和非法 package identity。
+发布包构建前需要准备 Skill build inputs 与消费者依赖：`bun install --cwd skills --frozen-lockfile --ignore-scripts --backend=copy`、`bun install --cwd skills/multi-task-flow --frozen-lockfile` 和 `bun install --cwd clients/typescript --frozen-lockfile --ignore-scripts --backend=copy`。随后在 `clients/typescript/` 执行 `bun --no-install run build`，构建会拒绝摘要不一致、缺失 consumer dependency、符号链接资源和非法 package identity。
 
 配置路径显式传入；相对 `stateDir` 相对于配置文件所在目录解析。未传配置时使用 `~/.loomhelm`。配置拒绝未知字段、未知版本及尚未实现的 Connected mode。源码从 `client/` 移入本目录后，示例配置使用 `../../client/.loomhelm`，继续读取仓库中原来的 `client/.loomhelm/`，该目录仍被根 Git 忽略规则排除。此兼容目录只保存状态，不放置客户端源码。
 
@@ -102,7 +106,7 @@ bun --no-install src/cli.ts --config config.example.json codex retry DISPATCH_ID
 
 ## Skills 与正式任务流
 
-完整源包位于包内 `toolkit/skills/`，共享支持位于 `toolkit/skills/bin/`，预构建 viewer 资产位于对应的 Multi-task Flow dist 目录。`skills/source-manifest.json` 记录固定源提交、源摘要、安装摘要和迁移差异；`skills/catalog.json` 记录入口、脚本及依赖强度；`artifact-manifest.json` 记录包身份与逐文件摘要。资源打包将 TS 源码、完整资源、浏览器资产和生产依赖复制到 `toolkit/`，不转译、不搜索全局 dot-codex 执行代码。Skill 文档中的 `LOOMHELM_TOOLKIT_ROOT` 指向该资源根；`skills run` 原样执行 `.ts` 脚本。包的 bin、exports 和类型入口均指向 `src/`。
+完整源包位于包内 `toolkit/skills/`，共享支持位于 `toolkit/skills/bin/`，预构建 viewer 资产位于对应的 Multi-task Flow dist 目录。`skills/source-manifest.json` 记录固定源提交、源摘要、安装摘要和迁移差异；`skills/catalog.json` 记录入口、脚本及依赖强度；`artifact-manifest.json` 记录 schema v3 package identity、`path-byte-v2` canonical digest 和逐文件摘要。资源打包将 TS 源码、完整资源和浏览器资产复制到 `toolkit/`，不复制 production `node_modules`，不转译、不搜索全局 dot-codex 执行代码。Skill 文档中的 `LOOMHELM_TOOLKIT_ROOT` 指向该资源根；`skills run` 原样执行 `.ts` 脚本。包的 bin、exports 和类型入口均指向 `src/`。
 
 所有随包执行代码、合同资源和构建支持都位于 `skills/`：共享脚本在 `skills/bin/`，上游合同在 `skills/docs/vendor/dot-codex/`，维护与构建入口在 `skills/multi-task-flow/scripts/`。vendor 仅检出 `skills/` 即可保留完整源资源，不需要修改用户的 sparse checkout 或安装配置。安装目录内执行 `bun install --cwd skills --frozen-lockfile --ignore-scripts --backend=copy` 与 `bun install --cwd skills/multi-task-flow --frozen-lockfile` 准备声明的依赖，再执行 `bun --no-install run --cwd skills build` 仅构建浏览器 JS/CSS；本机 TS 无需编译。外部 Git、Codex 宿主工具及条件性 Skills 仍按既有合同检测，不复制到源包中。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomhelm/multi-task-flow",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Versioned Bun CLI and complete Multi-task Flow Skill runtime for Loomhelm",
   "type": "module",
   "engines": {
@@ -27,25 +27,15 @@
     "build": "bun ../../skills/multi-task-flow/scripts/package-client-skills.ts --require-dependencies",
     "check": "bun x --no-install tsc -p tsconfig.json --noEmit",
     "test": "bun run build && bun test test/*.test.ts",
-    "pack:check": "bun run build && bun pm pack --dry-run",
-    "publish:exact": "bun --no-install src/cli.ts release publish --dist-tag \"$npm_package_version\"",
-    "publish:compat": "bun --no-install src/cli.ts release publish --dist-tag \"${npm_config_compat_tag:?set npm_config_compat_tag=compat-vN}\""
+    "pack:check": "bun run build && bun pm pack --dry-run"
   },
   "devDependencies": {
     "typescript": "5.9.3",
     "@types/bun": "1.4.4"
   },
   "dependencies": {
-    "@xyflow/react": "12.12.1",
-    "elkjs": "0.12.1",
-    "lucide": "1.65.0",
-    "moment": "2.31.0",
     "playwright": "1.64.1",
-    "react": "19.3.1",
-    "react-dom": "19.3.1",
     "sharp": "0.35.5",
-    "vis-data": "8.0.6",
-    "vis-timeline": "8.5.6",
     "zod": "4.6.7"
   },
   "loomhelm": {

package/src/build-info.ts

@@ -18,10 +18,10 @@ function readJson(path: string): JsonObject | null {
 const packageRoot = resolve(fileURLToPath(new URL('..', import.meta.url)));
 function validatedArtifactIdentity(): PackageIdentity | null {
   const artifact = readJson(resolve(packageRoot, 'toolkit/artifact-manifest.json'));
-  if (!artifact || artifact.dependenciesBundled !== true || !Array.isArray(artifact.dependencies) || artifact.dependencies.length === 0 || artifact.dependencies.some(item => !item || typeof item !== 'object' || typeof (item as JsonObject).name !== 'string' || typeof (item as JsonObject).version !== 'string' || typeof (item as JsonObject).path !== 'string' || typeof (item as JsonObject).entry !== 'string') || !Array.isArray(artifact.files)) return null;
+  if (!artifact || artifact.schemaVersion !== 3 || artifact.dependenciesBundled !== false || artifact.canonicalDigestAlgorithm !== 'path-byte-v2' || !Array.isArray(artifact.dependencies) || artifact.dependencies.length === 0 || artifact.dependencies.some(item => !item || typeof item !== 'object' || typeof (item as JsonObject).name !== 'string' || typeof (item as JsonObject).version !== 'string' || (item as JsonObject).mode !== 'consumer-install') || !Array.isArray(artifact.files)) return null;
   try {
     const identity = validatePackageIdentity(artifact.identity);
-    if (artifact.packageName !== identity.packageName || artifact.packageVersion !== identity.packageVersion || artifact.compatibilityLine !== identity.compatibilityLine || artifact.skillVersion !== identity.skillVersion || artifact.sourceSha !== identity.sourceSha || artifact.mergeSha !== identity.mergeSha || artifact.dirty !== identity.dirty || artifact.buildId !== identity.buildId || artifact.tarballDigest !== identity.tarballDigest || artifact.gitTag !== identity.gitTag) return null;
+    if (artifact.packageName !== identity.packageName || artifact.packageVersion !== identity.packageVersion || artifact.compatibilityLine !== identity.compatibilityLine || artifact.skillVersion !== identity.skillVersion || artifact.sourceSha !== identity.sourceSha || artifact.mergeSha !== identity.mergeSha || artifact.dirty !== identity.dirty || artifact.buildId !== identity.buildId || artifact.tarballDigest !== identity.tarballDigest || artifact.gitTag !== identity.gitTag || artifact.canonicalDigestAlgorithm !== identity.canonicalDigestAlgorithm) return null;
     const { buildId, ...withoutBuildId } = identity;
     return identityDigest({ ...withoutBuildId, files: artifact.files as { path: string; sha256: string }[] }) === buildId ? identity : null;
   } catch {
@@ -47,6 +47,7 @@ export const buildInfo = Object.freeze(identity ? {
   skill_version: identity.skillVersion,
   build_id: identity.buildId,
   tarball_digest: identity.tarballDigest,
+  canonical_digest_algorithm: identity.canonicalDigestAlgorithm ?? null,
   contracts,
   policy: 'loomhelm-manual-v1',
 } : {
@@ -58,6 +59,7 @@ export const buildInfo = Object.freeze(identity ? {
   skill_version: 'unknown',
   build_id: null,
   tarball_digest: null,
+  canonical_digest_algorithm: null,
   contracts,
   policy: 'loomhelm-manual-v1',
 });

package/src/cli/release.ts

@@ -1,9 +1,8 @@
 import { execFileSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
 import { buildInfoFromArtifact, requirePublishableArtifact } from '../runtime-identity.ts';
-import { commitForGitTag, canonicalTarballDigest, gitSourceSha, gitWorkingTreeStatus, packPackageTarball, removeTarballDirectory } from '../release-tarball.ts';
+import { commitForGitTag } from '../release-tarball.ts';
 import { SkillsRuntime } from '../toolkit.ts';
 import { parseCompatibilityDistTag, validatePublication } from '../release.ts';
 
@@ -38,54 +37,19 @@ function parsePublicationArgs(args: string[]): { version?: string; distTag?: str
   };
 }
 
-async function runPublishCommand(args: string[]): Promise<void> {
-  const options = parsePublicationArgs(args);
-  const packageMetadata = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf8')) as { version?: string };
-  const version = options.version ?? packageMetadata.version;
-  if (!version) throw new Error('Missing package version');
-  const publication = validatePublication(version, options.distTag);
-  const repoRoot = repositoryRoot();
-  if (gitWorkingTreeStatus(repoRoot).trim()) throw new Error('Publication requires a clean Git checkout');
-  const sourceSha = gitSourceSha(repoRoot);
-  assertGitTagProvenance(sourceSha, version, repoRoot);
-  const gitTag = `multi-task-flow-v${version}`;
-  const buildScript = resolve(repoRoot, 'skills/multi-task-flow/scripts/package-client-skills.ts');
-  const buildEnvironment = (tarballDigest = '') => ({ ...process.env, LOOMHELM_REQUIRE_MERGE_SHA: '1', LOOMHELM_MERGE_SHA: sourceSha, LOOMHELM_GIT_TAG: gitTag, LOOMHELM_TARBALL_DIGEST: tarballDigest });
-  const build = (tarballDigest = '') => execFileSync(process.execPath, ['--no-install', buildScript, '--require-dependencies'], { cwd: packageRoot, env: buildEnvironment(tarballDigest), stdio: 'inherit' });
-  const tarballs: string[] = [];
-  try {
-    build();
-    const draft = packPackageTarball(packageRoot);
-    tarballs.push(draft);
-    const digest = canonicalTarballDigest(draft);
-    build(digest);
-    const finalTarball = packPackageTarball(packageRoot);
-    tarballs.push(finalTarball);
-    if (canonicalTarballDigest(finalTarball) !== digest) throw new Error('Tarball digest changed after embedding provenance');
-    const artifact = await new SkillsRuntime().validate();
-    const identity = requirePublishableArtifact(artifact);
-    if (identity.packageVersion !== version || identity.tarballDigest !== digest) throw new Error('Packaged provenance does not match the publication request');
-    if (options.compatibilityLine !== undefined && options.compatibilityLine !== identity.compatibilityLine) throw new Error('Declared compatibility line does not match artifact identity');
-    execFileSync(process.execPath, ['publish', '--tag', publication.distTag, finalTarball], { cwd: packageRoot, env: buildEnvironment(digest), stdio: 'inherit' });
-    console.log(JSON.stringify({ ...publication, packageName: identity.packageName, sourceSha, mergeSha: identity.mergeSha, buildId: identity.buildId, tarballDigest: digest, gitTag }));
-  } finally {
-    for (const tarball of tarballs) removeTarballDirectory(tarball);
-  }
-}
-
 export async function runReleaseCommand(args: string[]): Promise<void> {
   if (args[0] === 'help' || !args.length) {
-    console.log('release identity | validate --version VERSION [--dist-tag VERSION|compat-vN] [--compatibility-line compat-vN] [--require-provenance] | publish [--version VERSION] --dist-tag VERSION|compat-vN [--compatibility-line compat-vN]');
+    console.log('release identity | validate --version VERSION [--dist-tag VERSION|compat-vN] [--compatibility-line compat-vN] [--require-provenance]');
     return;
   }
-  if (args[0] === 'publish') { await runPublishCommand(args.slice(1)); return; }
+  if (args[0] === 'publish') throw new Error('Direct npm publication is disabled; use the protected Skill Runtime Release workflow');
   const artifact = await new SkillsRuntime().validate();
   const buildInfo = buildInfoFromArtifact(artifact);
   if (args[0] === 'identity' && args.length === 1) {
     console.log(JSON.stringify(buildInfo));
     return;
   }
-  if (args[0] !== 'validate') throw new Error('Usage: release identity | validate --version VERSION [--dist-tag VERSION|compat-vN] [--compatibility-line compat-vN] [--require-provenance] | publish [--version VERSION] --dist-tag VERSION|compat-vN [--compatibility-line compat-vN]');
+  if (args[0] !== 'validate') throw new Error('Usage: release identity | validate --version VERSION [--dist-tag VERSION|compat-vN] [--compatibility-line compat-vN] [--require-provenance]');
   const publicationArgs = parsePublicationArgs(args.slice(1).filter(option => option !== '--require-provenance'));
   let version = publicationArgs.version;
   let distTag = publicationArgs.distTag;

package/src/release-tarball.ts

@@ -24,7 +24,7 @@ export function canonicalTarballDigest(tarballPath: string): string {
     execFileSync('tar', ['-xzf', resolve(tarballPath), '-C', extractionRoot], { stdio: 'ignore' });
     const packageRoot = resolve(extractionRoot, 'package');
     if (!lstatSync(packageRoot).isDirectory()) throw new Error('Tarball does not contain a package root');
-    const files = walkFiles(packageRoot).sort((left, right) => left.localeCompare(right));
+    const files = walkFiles(packageRoot).sort((left, right) => Buffer.from(left, 'utf8').compare(Buffer.from(right, 'utf8')));
     const hash = createHash('sha256');
     for (const path of files) {
       if (path === 'toolkit/artifact-manifest.json') continue;

package/src/release.ts

@@ -2,6 +2,9 @@ import { createHash } from 'node:crypto';
 
 export const PACKAGE_NAME = '@loomhelm/multi-task-flow';
 export const COMPATIBILITY_TAG_PREFIX = 'compat-v';
+export const CANONICAL_TARBALL_DIGEST_ALGORITHM = 'path-byte-v2';
+export const LEGACY_CANONICAL_TARBALL_DIGEST_ALGORITHM = 'legacy-locale-en-us-v1';
+export type CanonicalDigestAlgorithm = typeof CANONICAL_TARBALL_DIGEST_ALGORITHM | typeof LEGACY_CANONICAL_TARBALL_DIGEST_ALGORITHM;
 const EXACT_SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
 const COMPATIBILITY_TAG = /^compat-v([1-9]\d*)$/;
 const SHA1 = /^[a-f0-9]{40}$/;
@@ -35,6 +38,7 @@ export interface PackageIdentity {
   buildId: string;
   tarballDigest: string | null;
   gitTag: string | null;
+  canonicalDigestAlgorithm?: CanonicalDigestAlgorithm;
 }
 
 export function parseExactSemVer(value: string): ExactSemVer {
@@ -124,7 +128,9 @@ export function validatePackageIdentity(value: unknown): PackageIdentity {
   if (tarballDigest !== null && !SHA256.test(tarballDigest)) throw new Error('Invalid package identity field: tarballDigest');
   const gitTag = nullableString(raw.gitTag, 'gitTag');
   if (gitTag !== null && gitTag !== `multi-task-flow-v${packageVersion}`) throw new Error('Package identity Git tag does not match package version');
-  return { packageName, packageVersion, compatibilityLine, skillVersion, sourceSha, mergeSha, dirty: raw.dirty, contracts: normalizedContracts, buildId, tarballDigest, gitTag };
+  const canonicalDigestAlgorithm = raw.canonicalDigestAlgorithm;
+  if (canonicalDigestAlgorithm !== undefined && canonicalDigestAlgorithm !== CANONICAL_TARBALL_DIGEST_ALGORITHM && canonicalDigestAlgorithm !== LEGACY_CANONICAL_TARBALL_DIGEST_ALGORITHM) throw new Error('Invalid package identity field: canonicalDigestAlgorithm');
+  return { packageName, packageVersion, compatibilityLine, skillVersion, sourceSha, mergeSha, dirty: raw.dirty, contracts: normalizedContracts, buildId, tarballDigest, gitTag, ...(canonicalDigestAlgorithm === undefined ? {} : { canonicalDigestAlgorithm }) };
 }
 
 export function identityDigest(value: Omit<PackageIdentity, 'buildId'> & { files: readonly { path: string; sha256: string }[] }): string {

package/src/runtime-identity.ts

@@ -1,4 +1,4 @@
-import { identityDigest, validatePackageIdentity, type PackageIdentity } from './release.ts';
+import { identityDigest, validatePackageIdentity, type CanonicalDigestAlgorithm, type PackageIdentity } from './release.ts';
 import type { ToolkitArtifactFile, ToolkitArtifactManifest } from './toolkit.ts';
 
 export interface RuntimeBuildInfo {
@@ -10,6 +10,7 @@ export interface RuntimeBuildInfo {
   skill_version: string;
   build_id: string;
   tarball_digest: string | null;
+  canonical_digest_algorithm: CanonicalDigestAlgorithm | null;
   contracts: {
     ledger: number;
     api: number;
@@ -22,7 +23,7 @@ export interface RuntimeBuildInfo {
 
 function validatedIdentity(artifact: ToolkitArtifactManifest): PackageIdentity {
   const identity = validatePackageIdentity(artifact.identity);
-  if (identity.packageName !== artifact.packageName || identity.packageVersion !== artifact.packageVersion || identity.compatibilityLine !== artifact.compatibilityLine || identity.skillVersion !== artifact.skillVersion || identity.sourceSha !== artifact.sourceSha || identity.mergeSha !== artifact.mergeSha || identity.dirty !== artifact.dirty || identity.buildId !== artifact.buildId || identity.tarballDigest !== artifact.tarballDigest || identity.gitTag !== artifact.gitTag) throw new Error('Toolkit artifact identity mismatch');
+  if (identity.packageName !== artifact.packageName || identity.packageVersion !== artifact.packageVersion || identity.compatibilityLine !== artifact.compatibilityLine || identity.skillVersion !== artifact.skillVersion || identity.sourceSha !== artifact.sourceSha || identity.mergeSha !== artifact.mergeSha || identity.dirty !== artifact.dirty || identity.buildId !== artifact.buildId || identity.tarballDigest !== artifact.tarballDigest || identity.gitTag !== artifact.gitTag || identity.canonicalDigestAlgorithm !== artifact.canonicalDigestAlgorithm) throw new Error('Toolkit artifact identity mismatch');
   const { buildId, ...withoutBuildId } = identity;
   const files = artifact.files as readonly ToolkitArtifactFile[];
   if (identityDigest({ ...withoutBuildId, files }) !== buildId) throw new Error('Toolkit artifact build ID mismatch');
@@ -40,6 +41,7 @@ export function buildInfoFromArtifact(artifact: ToolkitArtifactManifest): Runtim
     skill_version: identity.skillVersion,
     build_id: identity.buildId,
     tarball_digest: identity.tarballDigest,
+    canonical_digest_algorithm: identity.canonicalDigestAlgorithm ?? null,
     contracts: {
       ledger: identity.contracts.ledgerContract,
       api: identity.contracts.apiVersion,

package/src/toolkit.ts

@@ -5,16 +5,16 @@ import { delimiter, isAbsolute, relative, resolve, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { runProcess, type ProcessOptions, type ProcessResult } from './runtime/process.ts';
-import { identityDigest, validatePackageIdentity, type PackageIdentity } from './release.ts';
+import { identityDigest, validatePackageIdentity, type CanonicalDigestAlgorithm, type PackageIdentity } from './release.ts';
 
 export interface SkillCapabilityReport { name: string; ready: boolean; readinessScope: 'all-declared-scenarios'; resourcesValid: boolean; dependencies: { skill: string; kind: 'skill' | 'command' | 'host'; strength: string; condition: string; available: boolean; code: string }[]; platform: string; arch: string; nativeSupported: boolean; source: string }
 export interface ToolkitResource { path: string; source?: string; sourceSha256?: string; installedSha256?: string }
 export interface ToolkitManifest { schemaVersion: 1; commit: string; skills: string[]; files: ToolkitResource[]; additions?: ToolkitResource[] }
 export interface ToolkitOmittedResource { path: string; reason: string }
 export interface ToolkitArtifactFile { path: string; sha256: string }
-export interface ToolkitDependency { name: string; version: string; path: string; entry: string }
+export interface ToolkitDependency { name: string; version: string; mode?: 'consumer-install' | 'bundled'; path?: string; entry?: string }
 export interface ToolkitArtifactManifest {
-  schemaVersion: 2;
+  schemaVersion: 2 | 3;
   packageName: string;
   packageVersion: string;
   compatibilityLine: string;
@@ -29,6 +29,7 @@ export interface ToolkitArtifactManifest {
   buildId: string;
   tarballDigest: string | null;
   gitTag: string | null;
+  canonicalDigestAlgorithm?: CanonicalDigestAlgorithm;
   dependenciesBundled: boolean;
   dependencies: ToolkitDependency[];
   omittedResources: ToolkitOmittedResource[];
@@ -57,19 +58,25 @@ export class SkillsRuntime {
   }
   async artifact(): Promise<ToolkitArtifactManifest> {
     const value = JSON.parse(await readFile(resolve(this.root, 'artifact-manifest.json'), 'utf8')) as ToolkitArtifactManifest & { identity?: unknown };
-    if (value.schemaVersion !== 2 || value.packageName !== '@loomhelm/multi-task-flow' || value.runtime !== 'bun@1.4.4' || typeof value.sourceCommit !== 'string' || !/^[a-f0-9]{40}$/.test(value.sourceCommit) || typeof value.sourceSha !== 'string' || !/^[a-f0-9]{40}$/.test(value.sourceSha) || typeof value.candidateSha !== 'string' || !/^[a-f0-9]{40}$/.test(value.candidateSha) || value.candidateSha !== value.sourceSha || typeof value.dirty !== 'boolean' || value.dependenciesBundled !== true || !Array.isArray(value.dependencies) || value.dependencies.length === 0 || value.dependencies.some(item => !item || !isSafePackageName(item.name) || typeof item.version !== 'string' || item.version.length === 0 || !isSafeResourcePath(item.path) || !isSafeResourcePath(item.entry)) || new Set(value.dependencies.map(item => item.name)).size !== value.dependencies.length || !Array.isArray(value.omittedResources) || value.omittedResources.some(item => !item || typeof item.path !== 'string' || !isSafeResourcePath(item.path) || typeof item.reason !== 'string' || item.reason.length === 0) || new Set(value.omittedResources.map(item => item.path)).size !== value.omittedResources.length || !Array.isArray(value.files) || value.files.some(file => !file || typeof file.path !== 'string' || !isSafeResourcePath(file.path) || !/^[a-f0-9]{64}$/.test(file.sha256)) || new Set(value.files.map(file => file.path)).size !== value.files.length || !value.identity) throw new Error('Invalid toolkit artifact manifest');
+    const dependencyShapeIsValid = Array.isArray(value.dependencies) && value.dependencies.length > 0 && value.dependencies.every(dependency => {
+      if (!dependency || !isSafePackageName(dependency.name) || typeof dependency.version !== 'string' || dependency.version.length === 0) return false;
+      if (value.schemaVersion === 3) return value.dependenciesBundled === false && dependency.mode === 'consumer-install' && dependency.path === undefined && dependency.entry === undefined;
+      return value.dependenciesBundled === true && typeof dependency.path === 'string' && isSafeResourcePath(dependency.path) && typeof dependency.entry === 'string' && isSafeResourcePath(dependency.entry);
+    });
+    const commonShapeIsValid = (value.schemaVersion === 2 || value.schemaVersion === 3) && value.packageName === '@loomhelm/multi-task-flow' && value.runtime === 'bun@1.4.4' && typeof value.sourceCommit === 'string' && /^[a-f0-9]{40}$/.test(value.sourceCommit) && typeof value.sourceSha === 'string' && /^[a-f0-9]{40}$/.test(value.sourceSha) && typeof value.candidateSha === 'string' && /^[a-f0-9]{40}$/.test(value.candidateSha) && value.candidateSha === value.sourceSha && typeof value.dirty === 'boolean' && Array.isArray(value.dependencies) && new Set(value.dependencies.map(item => item.name)).size === value.dependencies.length && Array.isArray(value.omittedResources) && value.omittedResources.every(item => item && isSafeResourcePath(item.path) && typeof item.reason === 'string' && item.reason.length > 0) && new Set(value.omittedResources.map(item => item.path)).size === value.omittedResources.length && Array.isArray(value.files) && value.files.every(file => file && isSafeResourcePath(file.path) && /^[a-f0-9]{64}$/.test(file.sha256)) && new Set(value.files.map(file => file.path)).size === value.files.length && Boolean(value.identity);
+    if (!commonShapeIsValid || !dependencyShapeIsValid || (value.schemaVersion === 3 && value.canonicalDigestAlgorithm !== 'path-byte-v2') || (value.schemaVersion === 2 && value.canonicalDigestAlgorithm !== undefined && value.canonicalDigestAlgorithm !== 'legacy-locale-en-us-v1')) throw new Error('Invalid toolkit artifact manifest');
     const identity = validatePackageIdentity(value.identity);
-    if (identity.packageName !== value.packageName || identity.packageVersion !== value.packageVersion || identity.compatibilityLine !== value.compatibilityLine || identity.skillVersion !== value.skillVersion || identity.sourceSha !== value.sourceSha || identity.mergeSha !== value.mergeSha || identity.dirty !== value.dirty || identity.buildId !== value.buildId || identity.tarballDigest !== value.tarballDigest || identity.gitTag !== value.gitTag) throw new Error('Toolkit artifact identity mismatch');
+    if (identity.packageName !== value.packageName || identity.packageVersion !== value.packageVersion || identity.compatibilityLine !== value.compatibilityLine || identity.skillVersion !== value.skillVersion || identity.sourceSha !== value.sourceSha || identity.mergeSha !== value.mergeSha || identity.dirty !== value.dirty || identity.buildId !== value.buildId || identity.tarballDigest !== value.tarballDigest || identity.gitTag !== value.gitTag || identity.canonicalDigestAlgorithm !== value.canonicalDigestAlgorithm) throw new Error('Toolkit artifact identity mismatch');
     const { buildId, ...withoutBuildId } = identity;
     if (identityDigest({ ...withoutBuildId, files: value.files }) !== buildId) throw new Error('Toolkit artifact build ID mismatch');
-    for (const dependency of value.dependencies) {
+    if (value.schemaVersion === 2) for (const dependency of value.dependencies) {
       try {
-        const dependencyRoot = resolve(this.root, dependency.path);
+        const dependencyRoot = resolve(this.root, dependency.path!);
         const dependencyManifest = resolve(dependencyRoot, 'package.json');
         if (await realpath(dependencyRoot) !== dependencyRoot || !(await stat(dependencyRoot)).isDirectory() || await realpath(dependencyManifest) !== dependencyManifest || !(await stat(dependencyManifest)).isFile()) throw new Error('Unsafe toolkit dependency: ' + dependency.name);
         const metadata = JSON.parse(await readFile(dependencyManifest, 'utf8')) as { name?: string; version?: string };
         if (metadata.name !== dependency.name || metadata.version !== dependency.version) throw new Error('Toolkit dependency identity mismatch: ' + dependency.name);
-        const entry = resolve(dependencyRoot, dependency.entry);
+        const entry = resolve(dependencyRoot, dependency.entry!);
         const entryRel = relative(dependencyRoot, entry);
         if (isAbsolute(entryRel) || entryRel === '..' || entryRel.startsWith(`..${sep}`) || await realpath(entry) !== entry || !(await stat(entry)).isFile()) throw new Error('Unsafe toolkit dependency entry: ' + dependency.name);
       } catch (error) {
@@ -77,15 +84,30 @@ export class SkillsRuntime {
         throw error;
       }
     }
-    const packageManifest = resolve(this.root, '..', 'package.json');
-    try {
-      const packageMetadata = JSON.parse(await readFile(packageManifest, 'utf8')) as { dependencies?: Record<string, unknown> };
-      for (const dependency of value.dependencies) if (packageMetadata.dependencies?.[dependency.name] !== dependency.version) throw new Error('Toolkit package dependency declaration mismatch: ' + dependency.name);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
-    }
     return value;
   }
+  private async findConsumerDependencyRoot(packageRoot: string, name: string): Promise<string> {
+    // Follow only the package's normal node_modules ancestry; never consult a global or checkout fallback.
+    const marker = `${sep}node_modules${sep}`;
+    const markerIndex = packageRoot.lastIndexOf(marker);
+    const boundary = markerIndex >= 0 ? packageRoot.slice(0, markerIndex) || sep : packageRoot;
+    let current = packageRoot;
+    while (true) {
+      const dependencyRoot = resolve(current, 'node_modules', name);
+      try {
+        const metadata = await lstat(dependencyRoot);
+        if (metadata.isSymbolicLink() || !metadata.isDirectory() || await realpath(dependencyRoot) !== dependencyRoot) throw new Error('Unsafe consumer dependency: ' + name);
+        return dependencyRoot;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      }
+      if (current === boundary) break;
+      const parent = resolve(current, '..');
+      if (parent === current) break;
+      current = parent;
+    }
+    throw new Error('Missing toolkit dependency: ' + name);
+  }
   private async validateArtifact(): Promise<ToolkitArtifactManifest> {
     const rootStat = await lstat(this.root);
     if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error('Unsafe toolkit root');
@@ -115,9 +137,43 @@ export class SkillsRuntime {
       }
     };
     await walk('');
+    if (artifact.schemaVersion === 3 && [...actual].some(path => path === 'node_modules' || path.startsWith('node_modules/') || path.includes('/node_modules/'))) throw new Error('Published toolkit contains node_modules');
     for (const path of actual) if (!seen.has(path) && !omitted.has(path)) throw new Error('Unlisted toolkit resource: ' + path);
+    if (artifact.schemaVersion === 3) await this.validateConsumerDependencies(artifact);
     return artifact;
   }
+  private async validateConsumerDependencies(artifact: ToolkitArtifactManifest): Promise<void> {
+    let packageRoot = resolve(this.root, '..');
+    let packageManifest = resolve(packageRoot, 'package.json');
+    let packageMetadata: { dependencies?: Record<string, unknown> };
+    try {
+      packageMetadata = JSON.parse(await readFile(packageManifest, 'utf8')) as { dependencies?: Record<string, unknown> };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      packageRoot = this.root;
+      packageManifest = resolve(packageRoot, 'package.json');
+      try {
+        packageMetadata = JSON.parse(await readFile(packageManifest, 'utf8')) as { dependencies?: Record<string, unknown> };
+      } catch (fallbackError) {
+        if ((fallbackError as NodeJS.ErrnoException).code === 'ENOENT') throw new Error('Missing package dependency manifest');
+        throw fallbackError;
+      }
+    }
+    for (const dependency of artifact.dependencies) {
+      if (packageMetadata.dependencies?.[dependency.name] !== dependency.version) throw new Error('Toolkit package dependency declaration mismatch: ' + dependency.name);
+      const dependencyRoot = await this.findConsumerDependencyRoot(packageRoot, dependency.name);
+      try {
+        const dependencyManifest = resolve(dependencyRoot, 'package.json');
+        const manifestStat = await lstat(dependencyManifest);
+        if (manifestStat.isSymbolicLink() || !manifestStat.isFile() || await realpath(dependencyManifest) !== dependencyManifest) throw new Error('Unsafe consumer dependency: ' + dependency.name);
+        const metadata = JSON.parse(await readFile(dependencyManifest, 'utf8')) as { name?: string; version?: string };
+        if (metadata.name !== dependency.name || metadata.version !== dependency.version) throw new Error('Consumer dependency identity mismatch: ' + dependency.name);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw new Error('Missing toolkit dependency: ' + dependency.name);
+        throw error;
+      }
+    }
+  }
   async validate(): Promise<ToolkitArtifactManifest> { return this.validateArtifact(); }
   async list(): Promise<{ name: string; path: string; scripts: string[] }[]> {
     const manifest = await this.manifest();