@tbox.cn/app-toolkit 0.1.0

package/tests/contracts-resolver.test.ts

@@ -0,0 +1,203 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { mkdirSync, writeFileSync, readFileSync, readlinkSync, symlinkSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveContractsForApp, invalidateContractsResolver } from '../src/core/contracts-resolver.js';
+import {
+  bumpMtime,
+  createTempApp,
+  writeFakeContractsPackage,
+  linkContracts,
+  type TempApp,
+} from './demo-app.js';
+
+/**
+ * contracts 动态解析器 fixtures 五态（F1-F5）+ symlink 换目标变体 + import 拒绝。
+ * store 假包置于 appDir 内部（非候选位——候选仅 apps 与 packages 各成员下 node_modules），
+ * dispose 随 appDir 一并清理；appDir 名经 mkdtemp 唯一，无并行碰撞。
+ */
+
+describe('contracts-resolver（D3 方案心脏）', () => {
+  let app: TempApp;
+
+  beforeEach(() => {
+    app = createTempApp('tbox-resolver-');
+    invalidateContractsResolver();
+  });
+
+  it('F1 pnpm 成员级链接：apps/server 候选命中（realpath 解 symlink + version + 双面可用）', async () => {
+    const store = join(app.appDir, 'store-f1');
+    writeFakeContractsPackage(store, { version: '0.9.0' });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    const resolved = await resolveContractsForApp(app.appDir);
+    expect(resolved.version).toBe('0.9.0');
+    expect(resolved.evaluation).toBe(true);
+    expect(resolved.strictValidation).toBe(true);
+    expect(resolved.module.resolveEffectiveService).toBeTypeOf('function');
+    expect(resolved.module.parseIntegrationsConfig).toBeTypeOf('function');
+    expect(resolved.notes).toEqual([]);
+  });
+
+  it('F2 npm 平铺：appDir 根首候选天然覆盖', async () => {
+    const store = join(app.appDir, 'store-f2');
+    writeFakeContractsPackage(store, { version: '0.9.1' });
+    linkContracts(app.appDir, store, { subdir: '' });
+    const resolved = await resolveContractsForApp(app.appDir);
+    expect(resolved.version).toBe('0.9.1');
+    expect(resolved.strictValidation).toBe(true);
+  });
+
+  it('F3 store 多版本：apps/server（0.9）优先于 apps/client（0.8）——候选序即优先级', async () => {
+    const storeV9 = join(app.appDir, 'store-f3-v9');
+    const storeV8 = join(app.appDir, 'store-f3-v8');
+    writeFakeContractsPackage(storeV9, { version: '0.9.0' });
+    writeFakeContractsPackage(storeV8, { version: '0.8.0' });
+    linkContracts(app.appDir, storeV9, { subdir: 'apps/server' });
+    linkContracts(app.appDir, storeV8, { subdir: 'apps/client' });
+    const resolved = await resolveContractsForApp(app.appDir);
+    expect(resolved.version).toBe('0.9.0');
+  });
+
+  it('F4 缺席：空目录 → 未解析产物（version null，绝不 throw）', async () => {
+    const resolved = await resolveContractsForApp(app.appDir);
+    expect(resolved.version).toBeNull();
+    expect(resolved.evaluation).toBe(false);
+    expect(resolved.strictValidation).toBe(false);
+    expect(resolved.module).toEqual({});
+    expect(resolved.notes.length).toBeGreaterThan(0);
+  });
+
+  it('F5 缺 zod 面：仅求值面在场 → evaluation true / strictValidation false（门控分支输入）', async () => {
+    const store = join(app.appDir, 'store-f5');
+    writeFakeContractsPackage(store, { version: '0.8.2', withStrict: false });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    const resolved = await resolveContractsForApp(app.appDir);
+    expect(resolved.evaluation).toBe(true);
+    expect(resolved.strictValidation).toBe(false);
+    expect(resolved.notes.some((n) => n.includes('0.8.2'))).toBe(true);
+  });
+
+  it('W4 symlink 换目标：version 轻探测读候选路径——pnpm 升级换 store 目标可觉察', async () => {
+    // 真 bug 候选防线：memoize 比对读**候选路径** version（非 realpath 缓存路径）
+    const storeV1 = join(app.appDir, 'store-w4-v1');
+    const storeV2 = join(app.appDir, 'store-w4-v2');
+    writeFakeContractsPackage(storeV1, { version: '0.8.0', withStrict: false });
+    writeFakeContractsPackage(storeV2, { version: '0.9.0', withStrict: true });
+    // storeV2 晚装语义——粗粒度 fs（CI overlayfs）同 tick 双写同 size package.json 指纹不变（边界②）
+    bumpMtime(join(storeV2, 'package.json'));
+    const linkDir = join(app.appDir, 'apps', 'server', 'node_modules', '@tbox.cn');
+    mkdirSync(linkDir, { recursive: true });
+    const link = join(linkDir, 'app-contracts');
+    symlinkSync(storeV1, link, 'dir');
+
+    const first = await resolveContractsForApp(app.appDir);
+    expect(first.version).toBe('0.8.0');
+    expect(first.strictValidation).toBe(false);
+
+    // symlink 换目标（pnpm 升级换 store 路径形态）——unlink 只摘链接本体（不动 store 内容）
+    unlinkSync(link);
+    symlinkSync(storeV2, link, 'dir');
+    expect(readlinkSync(link)).toBe(storeV2);
+
+    const second = await resolveContractsForApp(app.appDir);
+    expect(second.version).toBe('0.9.0');
+    expect(second.strictValidation).toBe(true);
+  });
+
+  it('import 拒绝：dist 存在但产物损坏 → 未解析返回（绝不 throw）——N1 构建指引分支输入', async () => {
+    const store = join(app.appDir, 'store-broken');
+    writeFakeContractsPackage(store, { version: '0.9.0', brokenDist: true });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    const resolved = await resolveContractsForApp(app.appDir);
+    expect(resolved.evaluation).toBe(false);
+    expect(resolved.strictValidation).toBe(false);
+    expect(resolved.notes.some((n) => n.includes('导入失败') || n.includes('未构建'))).toBe(true);
+  });
+
+  it('workspace 源码态：仅 src/runtime.ts（dist 缺失）→ 命中 src 态或未解析 + 构建指引（绝不 throw）', async () => {
+    const store = join(app.appDir, 'store-src-only');
+    writeFakeContractsPackage(store, { version: '0.9.0', withDist: false });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    const resolved = await resolveContractsForApp(app.appDir);
+    // vitest 管线可能转换 .ts 动态导入（TS-host 形态命中）——两种结果均合法：
+    // 命中 src 态（双面可用）或导入拒绝/产物缺失（未解析 + 构建指引）
+    if (resolved.evaluation) {
+      expect(resolved.version).toBe('0.9.0');
+    } else {
+      expect(resolved.notes.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('memoize：同 appDir 并发调用共享单次解析 promise', async () => {
+    const store = join(app.appDir, 'store-memo');
+    writeFakeContractsPackage(store, { version: '0.9.0' });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    const [a, b] = await Promise.all([
+      resolveContractsForApp(app.appDir),
+      resolveContractsForApp(app.appDir),
+    ]);
+    expect(a).toBe(b); // 同一 promise 实例——per appDir memoize
+  });
+
+  it('假包 exports 形态防线：复刻发布面双条件（types+import，无 require/default）', async () => {
+    const store = join(app.appDir, 'store-exports');
+    writeFakeContractsPackage(store, { version: '0.9.0' });
+    const pkg = JSON.parse(readFileSync(join(store, 'package.json'), 'utf8')) as {
+      exports: Record<string, Record<string, string>>;
+    };
+    expect(pkg.exports['.']).toEqual({ types: './dist/index.d.ts', import: './dist/runtime.js' });
+    expect(pkg.exports['.']?.require).toBeUndefined();
+  });
+
+  it('W4 补充：候选 package.json version 原地改写 → 轻探测察觉重解析', async () => {
+    const store = join(app.appDir, 'store-w4b');
+    writeFakeContractsPackage(store, { version: '0.9.0' });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    expect((await resolveContractsForApp(app.appDir)).version).toBe('0.9.0');
+    // 原地 bump version（pnpm update 语义形态）；mtime 前移防粗粒度 fs 同 tick 指纹不变（边界②）
+    const pkgPath = join(store, 'package.json');
+    writeFileSync(pkgPath, readFileSync(pkgPath, 'utf8').replace('0.9.0', '0.9.2'));
+    bumpMtime(pkgPath);
+    expect((await resolveContractsForApp(app.appDir)).version).toBe('0.9.2');
+  });
+
+  it('F9 dist 物化可觉察：unresolved（产物缺失，version 不变）→ 物化 dist → 下一笔 resolve 命中', async () => {
+    const store = join(app.appDir, 'store-f9-build');
+    // 源码态：仅 src/runtime.ts（vitest 下可能命中 src 态——先收敛为「双面可用或不可用」基线）
+    writeFakeContractsPackage(store, { version: '0.9.0', withDist: false });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    const before = await resolveContractsForApp(app.appDir);
+    // 物化构建产物（等同 pnpm --filter build；version 不变——旧 memoize 键（仅 version）不觉察）
+    const dist = join(store, 'dist');
+    mkdirSync(dist, { recursive: true });
+    writeFileSync(
+      join(dist, 'runtime.js'),
+      [
+        'export function resolveEffectiveService() { return { status: "service-not-configured" }; }',
+        'export function buildSupplyLookup() { return {}; }',
+        'export function moduleDomainOf(service) { return String(service).split(".")[0] ?? ""; }',
+        'export function normalizeInstances(config) { return config ?? { instances: [], defaultInstanceId: null }; }',
+        'export const RESOURCE_TYPE_IDS = ["knowledge"];',
+        'export function parseIntegrationsConfig(raw) { return raw; }',
+      ].join('\n'),
+    );
+    const after = await resolveContractsForApp(app.appDir);
+    // F9 指纹（version + 产物态）——dist 物化后恒命中双面（不再返回旧解析产物）
+    expect(after.evaluation).toBe(true);
+    expect(after.strictValidation).toBe(true);
+    expect(before).not.toBe(after); // 触发重解析（非 memo 缓存 promise）
+  });
+
+  it('F9 候选序变化可觉察：更近候选出现（首候选指纹变）→ 重扫取近者', async () => {
+    const storeFar = join(app.appDir, 'store-far');
+    writeFakeContractsPackage(storeFar, { version: '0.8.2', withStrict: false });
+    linkContracts(app.appDir, storeFar, { subdir: 'apps/server' });
+    expect((await resolveContractsForApp(app.appDir)).version).toBe('0.8.2');
+    // 更近候选（appDir 根）出现——候选序优先于 apps/server
+    const storeNear = join(app.appDir, 'store-near');
+    writeFakeContractsPackage(storeNear, { version: '0.9.0' });
+    linkContracts(app.appDir, storeNear, { subdir: '' });
+    const after = await resolveContractsForApp(app.appDir);
+    expect(after.version).toBe('0.9.0');
+    expect(after.strictValidation).toBe(true);
+  });
+});

package/tests/demo-app.ts

@@ -0,0 +1,146 @@
+import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, existsSync, rmSync, statSync, utimesSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+/**
+ * 共享 demo-app builder（F6 钉子）：W7 动线矩阵 / O 视图矩阵 / CLI golden 三族共用，
+ * 防 fixture 三份漂移。沿 cli/tests mkdtempSync 惯例（临时应用建在系统 tmp）。
+ *
+ * C2 版：app 树布局 + contracts 假包 fixture（resolver 五态）。C3/C4 随 walkManifests/views
+ * 扩展 demand/supply/schemas 产物与集成配置。
+ */
+
+export interface TempApp {
+  /** 应用根（tmp 下） */
+  appDir: string;
+  /** 清理（rm -rf tmp 根） */
+  dispose(): void;
+}
+
+/** 临时应用树：.tbox/app.json + apps/server + packages/ + config/（最小可解析布局） */
+export function createTempApp(prefix = 'tbox-toolkit-'): TempApp {
+  const appDir = mkdtempSync(join(tmpdir(), prefix));
+  mkdirSync(join(appDir, '.tbox'), { recursive: true });
+  writeFileSync(
+    join(appDir, '.tbox', 'app.json'),
+    `${JSON.stringify({ templateVersion: 'test', npmModules: [] }, null, 2)}\n`,
+  );
+  mkdirSync(join(appDir, 'apps', 'server'), { recursive: true });
+  mkdirSync(join(appDir, 'apps', 'client'), { recursive: true });
+  mkdirSync(join(appDir, 'packages'), { recursive: true });
+  mkdirSync(join(appDir, 'config'), { recursive: true });
+  return { appDir, dispose: () => rmSync(appDir, { recursive: true, force: true }) };
+}
+
+export interface FakeContractsOptions {
+  /** package.json version（默认 0.9.0） */
+  version?: string;
+  /** 是否携带严格校验面 parseIntegrationsConfig（false = F5 缺 zod 面） */
+  withStrict?: boolean;
+  /** 是否物化构建产物 dist/runtime.js（false = 仅 src/runtime.ts——workspace 源码态） */
+  withDist?: boolean;
+  /** dist/runtime.js 注入语法错误（import 拒绝 fixture） */
+  brokenDist?: boolean;
+  /** dist/runtime.js 缺求值面具名导出（形态异常 fixture） */
+  missingEvaluationExports?: boolean;
+  /** 严格校验失败 fixture（FX-1c T5）：parseIntegrationsConfig 对含该子串文档 throw */
+  rejectMarker?: string;
+  /** resolveEffectiveService 自定义函数体（FX-2c O4 fixture：默认恒 service-not-configured；
+   *  入参 (integrations, service, instanceId, supplies)，需 return EffectiveServiceResolution 形状） */
+  resolveBody?: string;
+}
+
+/** 假 contracts 包：package.json exports 形态逐字段复刻发布面（types+import 双条件、无 require/default）
+ *  ——resolver 不经 exports 解析（包根直探），该形态为 E4 类错误的机械防线。 */
+export function writeFakeContractsPackage(packageRoot: string, opts: FakeContractsOptions = {}): void {
+  const { version = '0.9.0', withStrict = true, withDist = true, brokenDist = false, missingEvaluationExports = false, rejectMarker, resolveBody } = opts;
+  const strictBody = withStrict
+    ? `export function parseIntegrationsConfig(raw) { ${
+        rejectMarker ? `if (JSON.stringify(raw).includes(${JSON.stringify(rejectMarker)})) throw new Error("fake strict reject"); ` : ''
+      }return raw; }`
+    : '';
+  const resolveLine = `export function resolveEffectiveService(integrations, service, instanceId, supplies) { ${
+    resolveBody ?? 'return { status: "service-not-configured" };'
+  } }`;
+  const exportsBody = missingEvaluationExports
+    ? `export const marker = 1;\n${strictBody}`
+    : [
+        resolveLine,
+        'export function buildSupplyLookup() { return {}; }',
+        'export function moduleDomainOf(service) { return String(service).split(".")[0] ?? ""; }',
+        'export function normalizeInstances(config) { return { instances: (config && config.instances) || [], defaultInstanceId: (config && config.defaultInstanceId) ?? null }; }',
+        'export const RESOURCE_TYPE_IDS = ["knowledge"];',
+        strictBody,
+        '',
+      ]
+        .filter(Boolean)
+        .join('\n');
+  mkdirSync(packageRoot, { recursive: true });
+  writeFileSync(
+    join(packageRoot, 'package.json'),
+    `${JSON.stringify(
+      {
+        name: '@tbox.cn/app-contracts',
+        version,
+        type: 'module',
+        exports: {
+          '.': {
+            types: './dist/index.d.ts',
+            import: './dist/runtime.js',
+          },
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  if (withDist) {
+    mkdirSync(join(packageRoot, 'dist'), { recursive: true });
+    writeFileSync(
+      join(packageRoot, 'dist', 'runtime.js'),
+      brokenDist ? 'export { syntax error here ===' : exportsBody,
+    );
+  } else {
+    mkdirSync(join(packageRoot, 'src'), { recursive: true });
+    writeFileSync(join(packageRoot, 'src', 'runtime.ts'), exportsBody);
+  }
+}
+
+export interface LinkOptions {
+  /** 候选子目录：''（appDir 根）/ 'apps/server' / 'apps/client' / 'packages/<id>' */
+  subdir: string;
+}
+
+/** 把假 contracts 包 symlink 进应用候选位（node_modules/@tbox.cn/app-contracts） */
+export function linkContracts(appDir: string, packageRoot: string, opts: LinkOptions): void {
+  const linkDir = join(appDir, opts.subdir, 'node_modules', '@tbox.cn');
+  mkdirSync(linkDir, { recursive: true });
+  symlinkSync(packageRoot, join(linkDir, 'app-contracts'), 'dir');
+}
+
+/** 应用内写文件（外部写模拟——files API / CLI / agent 动线） */
+export function writeAppFile(appDir: string, relPath: string, content: string): void {
+  const abs = join(appDir, relPath);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, content);
+}
+
+/**
+ * 外部写 mtime 前移（粗粒度文件系统确定性防御）：模拟「更晚发生的外部写」。
+ *
+ * Linux coarse-clock fs（CI 容器 overlayfs/tmpfs）时间戳粒度 = 内核 jiffy（1-10ms）——
+ * 同 tick 内同 size 重写产生相同 stat 指纹（mtimeMs+size），file-cache 依 Freshness Contract
+ * 边界②不觉察；macOS/APFS 亚毫秒粒度恒可觉察。显式前移 mtime 后 bump 值 = 写入时刻+forwardMs，
+ * 恒大于此前任何缓存指纹（时间单调性），跨文件系统确定（CI 失败复盘见 Agent Note
+ * implemented/testing/2026-09-14-file-cache-test-mtime-determinism.md）。
+ */
+export function bumpMtime(path: string, forwardMs = 60_000): void {
+  const st = statSync(path);
+  const later = new Date(st.mtimeMs + forwardMs);
+  utimesSync(path, later, later);
+}
+
+/** 应用内文件是否存在 */
+export function appFileExists(appDir: string, relPath: string): boolean {
+  return existsSync(join(appDir, relPath));
+}

package/tests/dev-manifest-catalog.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { walkManifests } from '../src/assembly/walk-manifests.js';
+import { createTempApp, type TempApp } from './demo-app.js';
+
+/**
+ * dev-manifest catalog 通道（通道 1.5）单测：聚合宽/声明窄不变量锁定。
+ * 回归背景（2026-09-15）：模板出厂 npmModules 写入 provider-custom（a41feb7c）打破
+ * 「dev 原地恒空」假设 → 旧替换式兜底永不触发 → dev 会话 catalog 为空。
+ */
+
+/** strict descriptor（形状对齐 provider-custom 出厂 manifest——parseModuleDescriptor 严格面） */
+function descriptor(name: string, provider: string, service: string): Record<string, unknown> {
+  return {
+    schemaVersion: 1,
+    name,
+    version: '1.0.0',
+    kind: 'business',
+    risk: { level: 'low', writeBoundary: 'source' },
+    distribution: { defaultMode: 'codegen' },
+    contributes: {
+      handlers: [], tools: [], cards: [], routes: [], pages: [], tabs: [],
+      providers: {
+        slots: [{ service, provider, implementation: `${provider}-impl@1`, credentialType: 'apikey' }],
+      },
+      services: [],
+    },
+    dependencies: { modules: [] },
+    env: [],
+  };
+}
+
+function writeManifest(dir: string, manifest: Record<string, unknown>): void {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'tbox.module.json'), JSON.stringify(manifest));
+}
+
+function writeDevManifest(appDir: string, redirects: Record<string, string>): void {
+  const stage = join(appDir, '.tbox-dev.local');
+  mkdirSync(stage, { recursive: true });
+  writeFileSync(join(stage, 'dev-manifest.json'), JSON.stringify({ redirects }));
+}
+
+function writeNpmModules(appDir: string, entries: unknown[]): void {
+  writeFileSync(
+    join(appDir, '.tbox', 'app.json'),
+    JSON.stringify({ templateVersion: 'test', npmModules: entries }),
+  );
+}
+
+const REG = { id: 'provider-reg', package: '@tbox.cn/app-provider-reg', version: '1.0.0' };
+
+let app: TempApp | undefined;
+afterEach(() => {
+  app?.dispose();
+  app = undefined;
+});
+
+describe('walkManifests · dev-manifest catalog 通道（聚合宽/声明窄）', () => {
+  it('D1: 登记 ∪ dev 真身并集进 catalog；双键单聚合；dev 真身不进 modules（回归锁 + 不变量锁）', () => {
+    app = createTempApp('tbox-devcat-');
+    writeNpmModules(app.appDir, [REG]);
+    writeManifest(join(app.appDir, 'packages', 'provider-reg'), descriptor('provider-reg', 'p-reg', 'reg.svc'));
+    writeManifest(join(app.appDir, 'modules', 'provider-dev'), descriptor('provider-dev', 'p-dev', 'dev.svc'));
+    writeDevManifest(app.appDir, {
+      '@tbox.cn/app-provider-dev': '../modules/provider-dev',
+      '@app/provider-dev': '../modules/provider-dev', // dev-manifest 双键同指 → 按名去重单次聚合
+    });
+
+    const walk = walkManifests(app.appDir);
+
+    expect(Object.keys(walk.catalog.providers)).toContain('p-reg');
+    expect(Object.keys(walk.catalog.providers)).toContain('p-dev');
+    expect(walk.catalog.providers['p-dev']?.['p-dev-impl@1']?.services).toEqual(['dev.svc']);
+    expect(walk.modules.map((m) => m.id)).toEqual(['provider-reg']); // 不变量：dev 真身不进声明集
+  });
+
+  it('D2: dev 真身与登记同名 → 登记真源胜（seen 短路，无二次聚合）', () => {
+    app = createTempApp('tbox-devcat-');
+    writeNpmModules(app.appDir, [REG]);
+    writeManifest(join(app.appDir, 'packages', 'provider-reg'), descriptor('provider-reg', 'p-reg', 'reg.svc'));
+    writeManifest(join(app.appDir, 'modules', 'provider-x'), descriptor('provider-reg', 'p-shadow', 'shadow.svc'));
+    writeDevManifest(app.appDir, { '@tbox.cn/app-provider-x': '../modules/provider-x' });
+
+    const walk = walkManifests(app.appDir);
+    expect(Object.keys(walk.catalog.providers)).toEqual(['p-reg']);
+    expect(walk.modules).toHaveLength(1);
+  });
+
+  it('D3: 坏 dev-manifest → 不 throw，catalog 退回纯登记（宽松哲学）', () => {
+    app = createTempApp('tbox-devcat-');
+    writeNpmModules(app.appDir, [REG]);
+    writeManifest(join(app.appDir, 'packages', 'provider-reg'), descriptor('provider-reg', 'p-reg', 'reg.svc'));
+    const stage = join(app.appDir, '.tbox-dev.local');
+    mkdirSync(stage, { recursive: true });
+    writeFileSync(join(stage, 'dev-manifest.json'), '{broken json');
+
+    const appDir = app.appDir; // 闭包内 let 控制流收窄丢失（TS18048）——闭包外捕获
+    expect(() => walkManifests(appDir)).not.toThrow();
+    expect(Object.keys(walkManifests(app.appDir).catalog.providers)).toEqual(['p-reg']);
+  });
+
+  it('D4: 空登记 + dev-manifest → catalog 含 dev 真身；modules 恒空（旧 AC-2b 语义经新通道等价）', () => {
+    app = createTempApp('tbox-devcat-');
+    writeNpmModules(app.appDir, []);
+    writeManifest(join(app.appDir, 'modules', 'provider-dev'), descriptor('provider-dev', 'p-dev', 'dev.svc'));
+    writeDevManifest(app.appDir, { '@tbox.cn/app-provider-dev': '../modules/provider-dev' });
+
+    const walk = walkManifests(app.appDir);
+    expect(Object.keys(walk.catalog.providers)).toContain('p-dev');
+    expect(walk.modules).toHaveLength(0);
+  });
+});

package/tests/error-name-safety.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import * as toolkit from '../src/index';
+
+/**
+ * error-name-safety 守卫（src 态——C4；dist 验证归 C6 minified 冒烟层②）。
+ * 沿 app-sdk 模式：barrel 枚举 Error 子类 → 断言 new X('m').name === 导出名
+ * （禁 this.name = X.name binding 形态——mangle 后静默漂移；真源 process note
+ * 2026-09-11-publish-dist-minify）。toolkit 消费面属性分发（.httpStatus/.code/.fields）
+ * 比 err.name 分发更宽裕——守卫仍钉字面量约定。
+ */
+
+const ERROR_EXPORTS = Object.entries(toolkit).filter(
+  ([, v]) => typeof v === 'function' && (v.prototype instanceof Error || v.prototype?.constructor === Error),
+);
+
+describe('error-name-safety（src 态守卫）', () => {
+  it('空集合自检阈值 ≥1（Error 子类枚举非空——barrel 变更不静默跳过）', () => {
+    expect(ERROR_EXPORTS.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it.each(ERROR_EXPORTS.map(([name]) => [name]))('%s.name === 导出名（字面量约定）', (name) => {
+    const Ctor = (toolkit as unknown as Record<string, new (msg: string) => Error>)[name];
+    const err = new Ctor('m');
+    expect(err.name).toBe(name);
+  });
+});