@tbox.cn/app-toolkit 0.1.0

package/tests/views.test.ts

@@ -0,0 +1,427 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { join } from 'node:path';
+import { mkdirSync, readFileSync, symlinkSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createAppToolkit, type AppToolkit } from '../src/factory.js';
+import { invalidateContractsResolver } from '../src/core/contracts-resolver.js';
+import { URL_METHOD_MAP } from './naming-alignment.test.js';
+import { createTempApp, writeFakeContractsPackage, linkContracts, writeAppFile, type TempApp } from './demo-app.js';
+
+/**
+ * views/工厂测试矩阵（C4——O1-O16 核心族；O 矩阵挂载点 = 本文件 + file-cache.test.ts W3/W7）。
+ * 覆盖：O1 integration 逐字等价 / O2 静态零求值键 / O3 resolutions 键集 + required OR /
+ * O8 P14 三处等价 / O9 issues 过滤 / O13 门控正反例 + 默认实例委托 / 门控 503 三分支 /
+ * N1 映射表激活（13 行 × 工厂方法 typeof）/ 静态端点写位读对偶。
+ */
+
+interface Harness {
+  app: TempApp;
+  tk: AppToolkit;
+}
+
+function harnessWithContracts(opts: { version?: string; withStrict?: boolean } = {}): Harness {
+  const app = createTempApp('tbox-views-');
+  invalidateContractsResolver();
+  const store = joinStore(app.appDir, 'contracts');
+  writeFakeContractsPackage(store, { version: opts.version ?? '0.9.0', withStrict: opts.withStrict ?? true });
+  linkContracts(app.appDir, store, { subdir: 'apps/server' });
+  // 应用结构：parking 模块（packages/ 约定发现）+ 注册表两实例 + integrations.json
+  mkdirDeep(join(app.appDir, 'packages', 'module-parking'));
+  writeAppFile(
+    app.appDir,
+    'packages/module-parking/tbox.module.json',
+    JSON.stringify({
+      schemaVersion: 1,
+      name: 'module-parking',
+      version: '0.1.0',
+      kind: 'business',
+      contributes: {
+        services: [{ service: 'parking.query', optional: false, title: '车位查询' }],
+      },
+      dependencies: { modules: [] },
+      env: [],
+    }),
+  );
+  writeAppFile(
+    app.appDir,
+    'config/integrations.json',
+    JSON.stringify({
+      provider: 'mock',
+      instances: [
+        { id: 'mall-bj-01', name: '北京店' },
+        { id: 'mall-sh-01', name: '上海店' },
+      ],
+      defaultInstanceId: 'mall-bj-01',
+      domains: { parking: { provider: 'wanda' } },
+      services: {
+        'parking.query': { provider: { provider: 'my-custom-api', credentialType: '-' }, implementation: 'my-custom-parking@1' },
+        'auth.alipay-login': {},
+      },
+    }),
+  );
+  const tk = createAppToolkit(app.appDir);
+  return { app, tk };
+}
+
+function joinStore(appDir: string, name: string): string {
+  return join(appDir, name);
+}
+function mkdirDeep(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+}
+
+describe('views/工厂（O 矩阵核心族）', () => {
+  let h: Harness;
+
+  beforeEach(() => {
+    h = harnessWithContracts();
+  });
+
+  it('O1 integration 字段逐字等价（文件节点原值——预填真值不变式 D21）', async () => {
+    const detail = await h.tk.loadService('parking.query');
+    const fileConfig = ((await h.tk.readIntegrationsConfig()) ?? { services: {} }) as {
+      services: Record<string, unknown>;
+    };
+    expect(detail.integration).toEqual(fileConfig.services['parking.query']);
+    // root 节点原值（/app 读对偶）
+    const appView = await h.tk.loadApp();
+    expect(appView.integration?.provider).toBe('mock');
+    // 模块域节点原值
+    const mod = await h.tk.loadModule('module-parking');
+    expect(mod.integration).toEqual({ provider: 'wanda' });
+  });
+
+  it('O2 静态投影零求值键：/app、/modules/:m、/services/:s 结构性无 resolution/issues/contracts', async () => {
+    const appView = await h.tk.loadApp();
+    expect(Object.keys(appView)).toEqual(['services', 'integration']);
+    const mod = await h.tk.loadModule('module-parking');
+    expect(Object.keys(mod)).toEqual(['integration', 'services']);
+    const svc = await h.tk.loadService('parking.query');
+    expect(Object.keys(svc).some((k) => ['resolution', 'issues', 'contracts'].includes(k))).toBe(false);
+    // 静态端点在 <0.9 下照常（永不 503——O13 反例联动）
+  });
+
+  it('O8 P14 三处等价：map 值 ≡ 单体 resolution 摘要基（单源函数结构保证）', async () => {
+    const batch = await h.tk.loadServiceResolutions();
+    const single = await h.tk.loadServiceResolution('parking.query');
+    const entry = batch.resolutions['parking.query'];
+    // extends 结构：单体 = 摘要基 + instances/inheritance
+    expect(single.resolution.status).toBe(entry.status);
+    expect(single.resolution.provider).toBe(entry.provider);
+    expect(single.resolution.supplied).toBe(entry.supplied);
+    expect(single.resolution.module).toBe(entry.module);
+    expect(single.resolution.required).toBe(entry.required);
+    expect(single.resolution.instances).toBeInstanceOf(Array);
+    expect(single.resolution.inheritance).toHaveLength(4);
+  });
+
+  it('O3 键集 = 服务词汇 ∪ 已配置；required echo（OR 聚合 + 平台 false）', async () => {
+    // vocabulary 空（无契约包 fixture）→ 键集 = 已配置（parking.query + auth.alipay-login）
+    const batch = await h.tk.loadServiceResolutions();
+    expect(Object.keys(batch.resolutions).sort()).toEqual(['auth.alipay-login', 'parking.query']);
+    // parking.query 由 module-parking demand required:0 → required true
+    expect(batch.resolutions['parking.query'].required).toBe(true);
+  });
+
+  it('O9 issues 过滤：单体 = service 过滤子集；集合恒全量', async () => {
+    const batch = await h.tk.loadServiceResolutions();
+    const single = await h.tk.loadServiceResolution('auth.alipay-login');
+    expect(single.issues.every((i) => i.service === 'auth.alipay-login')).toBe(true);
+    expect(batch.issues.length).toBeGreaterThanOrEqual(single.issues.length);
+  });
+
+  it('O13 门控正反例：<0.9 求值 503 三分支 + 静态 200；多实例无显式默认 → 通配口径', async () => {
+    // 正例：≥0.9 求值可用（harness 默认）
+    const batch = await h.tk.loadServiceResolutions();
+    expect(batch.contracts.strictValidation).toBe(true);
+    h.app.dispose();
+
+    // 反例：缺 zod 面（0.8.2）→ 求值 throw 503 + message 升级指引；静态照常
+    const low = harnessWithContracts({ version: '0.8.2', withStrict: false });
+    await expect(low.tk.loadServiceResolutions()).rejects.toMatchObject({
+      code: 'CONTRACTS_NOT_RESOLVED',
+      httpStatus: 503,
+    });
+    await expect(low.tk.loadServiceResolutions()).rejects.toThrow(/升级应用 @tbox.cn\/app-contracts/);
+    // 静态永不 503
+    const appView = await low.tk.loadApp();
+    expect(appView.services).toBeInstanceOf(Array);
+    // 写端点同样门控
+    await expect(
+      low.tk.writeServiceIntegration('parking.query', { provider: 'mock' }),
+    ).rejects.toMatchObject({ code: 'CONTRACTS_NOT_RESOLVED', httpStatus: 503 });
+    low.app.dispose();
+
+    // 默认实例委托：无 defaultInstanceId（多实例）→ '*' 通配口径（normalizeInstances null → '*'）
+    const wild = harnessWithContracts();
+    writeAppFile(
+      wild.app.appDir,
+      'config/integrations.json',
+      JSON.stringify({
+        provider: 'mock',
+        instances: [
+          { id: 'mall-bj-01', name: '北京店' },
+          { id: 'mall-sh-01', name: '上海店' },
+        ],
+        services: { 'auth.alipay-login': {} },
+      }),
+    );
+    const single = await wild.tk.loadServiceResolution('auth.alipay-login');
+    // 通配实例枚举条目在场（无注册表无节点 → instances []；显式空槽 = 通配激活）
+    expect(single.resolution.status).toBe('service-not-configured');
+    wild.app.dispose();
+  });
+
+  it('N1 命名对齐：13 行映射表 × 工厂方法 typeof（L1 改名漂移即红）', async () => {
+    for (const row of URL_METHOD_MAP) {
+      const fn = (h.tk as unknown as Record<string, unknown>)[row.method];
+      expect(typeof fn, row.method).toBe('function');
+    }
+  });
+
+  it('写核心 PUT 全量替换：GET 预填原始节点 → PUT 回整节点（instances map 随节点）+ restartScheduled', async () => {
+    let appliedCalls = 0;
+    const tk2 = createAppToolkit(h.app.appDir, { onApplied: () => (appliedCalls += 1) });
+    const svc = await tk2.loadService('parking.query');
+    const node = { ...(svc.integration ?? {}), credentialRef: 'secret://wanda-mall-bj-01-parking' };
+    const result = await tk2.writeServiceIntegration('parking.query', node);
+    expect(result.written).toBe(true);
+    expect(result.restartScheduled).toBe(true);
+    expect(appliedCalls).toBe(1);
+    // 回读逐字等价（GET = PUT = 落盘物三位一体）
+    const reread = await tk2.loadService('parking.query');
+    expect(reread.integration).toEqual(node);
+  });
+
+  it('no-diff 深度等价 → written:false + restartScheduled:false；dryRun files 恒 []', async () => {
+    const svc = await h.tk.loadService('parking.query');
+    const result = await h.tk.writeServiceIntegration('parking.query', svc.integration ?? {});
+    expect(result.written).toBe(false);
+    expect(result.restartScheduled).toBe(false);
+    // dryRun：复读管线不落盘
+    const dry = await h.tk.writeServiceIntegration('parking.query', { provider: 'mock' }, { dryRun: true });
+    expect(dry.written).toBe(false);
+    expect(dry.files).toEqual([]);
+  });
+
+  it('写时自动初始化（R13 语义翻转提示）+ N1 清域（模块 {} 删 domains 键）', async () => {
+    h.app.dispose();
+    const fresh = createTempApp('tbox-views-fresh-');
+    invalidateContractsResolver();
+    const store = joinStore(fresh.appDir, 'contracts');
+    writeFakeContractsPackage(store, { version: '0.9.0' });
+    linkContracts(fresh.appDir, store, { subdir: 'apps/server' });
+    const tk = createAppToolkit(fresh.appDir);
+    // 缺席文件首写 → 骨架物化 + R13 warning
+    const r = await tk.writeServiceIntegration('auth.alipay-login', {});
+    expect(r.written).toBe(true);
+    expect(r.issues.some((i) => i.code === 'SKELETON_MATERIALIZED')).toBe(true);
+    fresh.dispose();
+  });
+
+  it('O15 安全钉子：configSchema 逃逸三用例 400 + 合法相对路径 200（H9/FX-2a）', async () => {
+    const writeConfigWithSchema = (ref: string): void => {
+      writeAppFile(
+        h.app.appDir,
+        'config/integrations.json',
+        JSON.stringify({
+          provider: 'mock',
+          instances: [{ id: 'mall-bj-01', name: '北京店' }],
+          defaultInstanceId: 'mall-bj-01',
+          services: {
+            'parking.query': {
+              provider: { provider: 'my-custom-api', credentialType: '-', configSchema: ref },
+              implementation: 'my-custom-parking@1',
+            },
+          },
+        }),
+      );
+    };
+    // ① 同前缀兄弟目录（原 startsWith 无分隔符边界绕过点——schemas-evil）
+    writeConfigWithSchema('config/schemas-evil/x.json');
+    await expect(h.tk.loadProviderService('my-custom-api', 'parking.query')).rejects.toMatchObject({
+      code: 'VALIDATION_FAILED',
+      httpStatus: 400,
+    });
+    // ② 绝对路径
+    writeConfigWithSchema('/etc/passwd');
+    await expect(h.tk.loadProviderService('my-custom-api', 'parking.query')).rejects.toMatchObject({
+      code: 'VALIDATION_FAILED',
+      httpStatus: 400,
+    });
+    // ③ symlink 逃逸（realpath 复核——凭据 JSON 当 schema 回显防线）
+    writeAppFile(h.app.appDir, 'config/credentials/secret.json', JSON.stringify({ type: 'api-key', apiKey: 'REAL-SECRET' }));
+    mkdirSync(join(h.app.appDir, 'config', 'schemas'), { recursive: true });
+    symlinkSync(join(h.app.appDir, 'config', 'credentials', 'secret.json'), join(h.app.appDir, 'config', 'schemas', 'link.json'));
+    writeConfigWithSchema('config/schemas/link.json');
+    await expect(h.tk.loadProviderService('my-custom-api', 'parking.query')).rejects.toMatchObject({
+      code: 'VALIDATION_FAILED',
+      httpStatus: 400,
+    });
+    // ④ 合法相对路径 → 正常返回 schema；缺席文件 → null（非法不误伤）
+    writeAppFile(h.app.appDir, 'config/schemas/ok.json', JSON.stringify({ type: 'object', properties: { baseUrl: { type: 'string' } } }));
+    writeConfigWithSchema('config/schemas/ok.json');
+    const detail = await h.tk.loadProviderService('my-custom-api', 'parking.query');
+    expect(detail.integrationSchemas.configSchema).toEqual({ type: 'object', properties: { baseUrl: { type: 'string' } } });
+    writeConfigWithSchema('config/schemas/absent.json');
+    const absent = await h.tk.loadProviderService('my-custom-api', 'parking.query');
+    expect(absent.integrationSchemas.configSchema).toBeNull();
+  });
+
+  it('O4 effective/credential 填充 + 掩码零真值（FX-2c）：effective 投影 + layer + CredentialEcho + inheritance 默认实例', async () => {
+    const app = createTempApp('tbox-o4-');
+    invalidateContractsResolver();
+    const store = joinStore(app.appDir, 'contracts');
+    writeFakeContractsPackage(store, {
+      version: '0.9.0',
+      resolveBody: [
+        'const slot = integrations && integrations.services && integrations.services[service];',
+        'if (!slot) return { status: "service-not-configured" };',
+        'const prov = typeof slot.provider === "string" ? slot.provider : slot.provider && slot.provider.provider;',
+        'if (!prov) return { status: "service-not-configured" };',
+        'return { status: "ok", effective: { provider: prov, implementation: slot.implementation || "impl@1", config: slot.config || {}, ...(slot.credentialRef ? { credentialRef: slot.credentialRef } : {}) } };',
+      ].join(' '),
+    });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    writeAppFile(
+      app.appDir,
+      'config/integrations.json',
+      JSON.stringify({
+        instances: [{ id: 'mall-1', name: '一店' }],
+        defaultInstanceId: 'mall-1',
+        services: {
+          'parking.query': {
+            provider: 'wanda',
+            implementation: 'wanda-parking@1',
+            credentialRef: 'secret://wanda-parking.query',
+            config: { baseUrl: 'https://api.example' },
+          },
+        },
+      }),
+    );
+    writeAppFile(
+      app.appDir,
+      'config/credentials/wanda-parking.query.json',
+      JSON.stringify({ type: 'wanda-c-signed-v1', appKey: 'SECRET-APP-KEY', appSecret: 'SECRET-APP-SECRET' }),
+    );
+    const tk = createAppToolkit(app.appDir);
+    const detail = await tk.loadServiceResolution('parking.query');
+    const inst = detail.resolution.instances.find((i) => i.instanceId === 'mall-1');
+    expect(inst?.status).toBe('ok');
+    expect(inst?.effective).toEqual({
+      provider: 'wanda',
+      implementation: 'wanda-parking@1',
+      config: { baseUrl: 'https://api.example' },
+      credentialRef: 'secret://wanda-parking.query',
+      layer: 'service',
+    });
+    expect(inst?.credential).toEqual({
+      type: 'wanda-c-signed-v1',
+      ref: 'secret://wanda-parking.query',
+      file: 'config/credentials/wanda-parking.query.json',
+      masked: { appKey: 'SE****', appSecret: 'SE****' },
+    });
+    // O4 零真值：序列化后 grep 断言
+    const serialized = JSON.stringify(detail);
+    expect(serialized).not.toContain('SECRET-APP-KEY');
+    expect(serialized).not.toContain('SECRET-APP-SECRET');
+    // inheritance 实例层 = 默认实例口径（FX-2c）：无实例级声明 → 继承位（provider 缺席）
+    expect(detail.resolution.inheritance.find((l) => l.layer === 'instance')).toEqual({ layer: 'instance' });
+    app.dispose();
+  });
+});
+
+describe('O6/O7/O10/O14（FX-3 补全）', () => {
+  it('O6 供给 implementations 数组保真（同厂商多 impl 声明序——H1 尊重 TIER0 数组真相）', async () => {
+    const app = createTempApp('tbox-o6-');
+    invalidateContractsResolver();
+    const store = joinStore(app.appDir, 'contracts');
+    writeFakeContractsPackage(store, { version: '0.9.0' });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    writeAppFile(app.appDir, 'packages/provider-multi/package.json', JSON.stringify({ name: '@app/provider-multi', version: '0.1.0' }));
+    writeAppFile(
+      app.appDir,
+      'packages/provider-multi/tbox.module.json',
+      JSON.stringify({
+        schemaVersion: 1,
+        name: 'provider-multi',
+        contributes: {
+          providers: {
+            slots: [
+              { service: 'parking.query', provider: 'joycity', implementation: 'joycity-parking@1', credentialType: 'joycity-c', configSchema: 'schemas/query.json' },
+              { service: 'parking.query', provider: 'joycity', implementation: 'joycity-parking@2', credentialType: 'joycity-c', configSchema: 'schemas/query2.json' },
+            ],
+          },
+        },
+      }),
+    );
+    writeAppFile(app.appDir, 'packages/provider-multi/schemas/query.json', JSON.stringify({ type: 'object', properties: { baseUrl: { type: 'string' } } }));
+    writeAppFile(app.appDir, 'packages/provider-multi/schemas/query2.json', JSON.stringify({ type: 'object', properties: { endpoint: { type: 'string' } } }));
+    const tk = createAppToolkit(app.appDir);
+    const detail = await tk.loadProvider('joycity');
+    expect(detail.services['parking.query']?.implementations).toEqual([
+      { implementation: 'joycity-parking@1', credentialType: 'joycity-c' },
+      { implementation: 'joycity-parking@2', credentialType: 'joycity-c' },
+    ]);
+    // O7 组合单体：多 impl → implementations.length > 1 + schema 取默认 impl（声明序首个）
+    const combo = await tk.loadProviderService('joycity', 'parking.query');
+    expect(combo.implementations).toHaveLength(2);
+    expect(combo.integrationSchemas.configSchema).toEqual({ type: 'object', properties: { baseUrl: { type: 'string' } } });
+    expect(combo.integrationSchemas.credentialSchema).toBeNull(); // 供给在场未声明 credentialSchema → null（非 404）
+    app.dispose();
+  });
+
+  it('O10 statusMessage 逐实例直投（binding-unresolved 不吞不并）', async () => {
+    const app = createTempApp('tbox-o10-');
+    invalidateContractsResolver();
+    const store = joinStore(app.appDir, 'contracts');
+    writeFakeContractsPackage(store, {
+      version: '0.9.0',
+      resolveBody: [
+        'const slot = integrations && integrations.services && integrations.services[service];',
+        'if (!slot) return { status: "service-not-configured" };',
+        'if (instanceId === "mall-b") return { status: "binding-unresolved", message: service + "@" + instanceId + "：多 impl 需显式钉版（无派生）" };',
+        'const prov = typeof slot.provider === "string" ? slot.provider : slot.provider && slot.provider.provider;',
+        'if (!prov) return { status: "service-not-configured" };',
+        'return { status: "ok", effective: { provider: prov, implementation: "impl@1", config: {} } };',
+      ].join(' '),
+    });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    writeAppFile(
+      app.appDir,
+      'config/integrations.json',
+      JSON.stringify({
+        instances: [{ id: 'mall-a' }, { id: 'mall-b' }],
+        defaultInstanceId: 'mall-a',
+        services: { 'parking.query': { provider: 'mock' } },
+      }),
+    );
+    const tk = createAppToolkit(app.appDir);
+    const detail = await tk.loadServiceResolution('parking.query');
+    const byId = Object.fromEntries(detail.resolution.instances.map((i) => [i.instanceId, i]));
+    expect(byId['mall-a']?.status).toBe('ok');
+    expect(byId['mall-b']?.status).toBe('binding-unresolved');
+    expect(byId['mall-b']?.statusMessage).toContain('多 impl 需显式钉版');
+    expect(detail.resolution.status).toBe('ok'); // 摘要 = 默认实例（mall-a）口径
+    app.dispose();
+  });
+
+  it('O14 谓词 code 枚举 ⊆ api.md §5 清单（additive-only 纪律——文档单源对账）', () => {
+    const source = readFileSync(fileURLToPath(new URL('../src/integrations/predicate.ts', import.meta.url)), 'utf8');
+    const codes = new Set([...source.matchAll(/code: '([A-Z_]+)'/g)].map((m) => m[1]));
+    expect(codes.size).toBeGreaterThan(10); // 自检阈值（扫描面非空）
+    // api.md §5 表（谓词 code 枚举单源）+ predicate 头映射表 additive 族
+    const ENUM = new Set([
+      // api.md §5 表
+      'CREDENTIAL_FILE_MISSING', 'CREDENTIAL_TYPE_MISMATCH', 'IMPL_WITHOUT_PROVIDER', 'INSTANCE_SUPPLY_UNMATCHED',
+      'SCHEMA_FILE_MISSING', 'DOMAIN_CONFIG_UNUSED', 'DOMAIN_CONFIG_INVALID', 'INSTANCE_KEY_NOT_REGISTERED',
+      'REALM_SWITCH_HINT', 'WILDCARD_ALIGNMENT', 'VENDOR_NOT_INSTALLED', 'BINDING_UNRESOLVED', 'DOMAIN_KEY_UNMATCHED',
+      'RESOURCE_TYPE_UNKNOWN', 'RESOURCE_NOT_DECLARED',
+      // 谓词头映射表 additive（检查族编号映射：#3/#4/#5 内联/#13/v4）
+      'SLOT_NOT_DECLARED', 'SLOT_NOT_CONFIGURED', 'INLINE_PROVIDER_INVALID', 'MULTI_INSTANCE_NO_DEFAULT', 'INSTANCE_DISABLED',
+    ]);
+    for (const c of codes) {
+      expect(ENUM.has(c), `谓词 code ${c} ∉ api.md §5 清单（additive-only——新增须先登记 api.md §5）`).toBe(true);
+    }
+  });
+});

package/tests/write-core.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createAppToolkit, type AppToolkit } from '../src/factory.js';
+import { AppToolkitError } from '../src/core/errors.js';
+import { createTempApp, writeFakeContractsPackage, linkContracts, writeAppFile, type TempApp } from './demo-app.js';
+
+/**
+ * 写核心管线矩阵（FX-1c——B1/B2/B3 钉死 + F3 九步定序 + F4 输入扩位）。
+ * 评审复现三场景全量入库：T1 writeAppIntegration 节点忽略（B1）、
+ * T2 同 node 新凭据丢弃（B2）、T3 dryRun 落凭据文件（B3）。
+ * 覆盖：dryRun × no-diff × 凭据 三态组合 / 严格校验失败次序（T5）/
+ * 恶意 map 键 400（T6）/ 幂等 overwrote（T7）/ ByInstance ref 回填实际值（T8）。
+ */
+
+const INTEGRATIONS_FILE = 'config/integrations.json';
+
+interface Harness {
+  app: TempApp;
+  tk: AppToolkit;
+  readConfig(): Record<string, unknown>;
+  credFile(stem: string): string;
+}
+
+function harness(opts: { rejectMarker?: string } = {}): Harness {
+  const app = createTempApp('tbox-write-core-');
+  const store = join(app.appDir, 'contracts-store');
+  writeFakeContractsPackage(store, { version: '0.9.0', withStrict: true, rejectMarker: opts.rejectMarker });
+  linkContracts(app.appDir, store, { subdir: 'apps/server' });
+  writeAppFile(app.appDir, INTEGRATIONS_FILE, JSON.stringify({ services: {} }, null, 2));
+  const tk = createAppToolkit(app.appDir);
+  return {
+    app,
+    tk,
+    readConfig: () => JSON.parse(readFileSync(join(app.appDir, INTEGRATIONS_FILE), 'utf8')) as Record<string, unknown>,
+    credFile: (stem) => join(app.appDir, 'config', 'credentials', `${stem}.json`),
+  };
+}
+
+describe('写核心管线（FX-1c）', () => {
+  let h: Harness;
+
+  beforeEach(() => {
+    h = harness();
+  });
+  afterEach(() => {
+    h.app.dispose();
+  });
+
+  it('T1 writeAppIntegration 节点合并（B1 钉死）：node 生效 + dryRun 无 dryRun 键注入 + 回读等价', async () => {
+    const node = {
+      provider: 'mock-x',
+      config: { baseUrl: 'https://x.example' },
+      instances: [{ id: 'mall-1', name: '一号店' }],
+      defaultInstanceId: 'mall-1',
+    };
+    const r = await h.tk.writeAppIntegration(node as never);
+    expect(r.written).toBe(true);
+    expect(r.files).toEqual([INTEGRATIONS_FILE]);
+    const cfg = h.readConfig();
+    expect(cfg.provider).toBe('mock-x');
+    expect(cfg.config).toEqual({ baseUrl: 'https://x.example' });
+    expect(cfg.instances).toEqual([{ id: 'mall-1', name: '一号店' }]);
+    expect(cfg.defaultInstanceId).toBe('mall-1');
+    // B1 伴随缺陷钉死：dryRun 键永不进文档
+    expect('dryRun' in cfg).toBe(false);
+    // 回读逐字等价（GET = PUT = 落盘物）
+    const app = await h.tk.loadApp();
+    expect(app.integration).toEqual(node);
+    // dryRun + 不同节点 → 不落盘
+    const r2 = await h.tk.writeAppIntegration({ provider: 'changed' } as never, { dryRun: true });
+    expect(r2.written).toBe(false);
+    expect(r2.files).toEqual([]);
+    expect(h.readConfig().provider).toBe('mock-x');
+  });
+
+  it('T2 同 node 新凭据（B2 钉死）：凭据落盘 + written:true + files 仅凭据路径 + integrations 不重写', async () => {
+    const node = { provider: 'joycity' };
+    const r1 = await h.tk.writeServiceIntegration('parking.query', node, {
+      credentials: { type: 'api-key', values: { apiKey: 'FIRST' } },
+    });
+    expect(r1.written).toBe(true);
+    expect(r1.files).toEqual([INTEGRATIONS_FILE, 'config/credentials/joycity-parking.query.json']);
+    expect(r1.credentials).toEqual([{ stem: 'joycity-parking.query', ref: 'secret://joycity-parking.query', overwrote: false }]);
+    const before = readFileSync(join(h.app.appDir, INTEGRATIONS_FILE), 'utf8');
+    // 密钥轮换：同 node + 新凭据值
+    const r2 = await h.tk.writeServiceIntegration('parking.query', node, {
+      credentials: { type: 'api-key', values: { apiKey: 'ROTATED-SECOND' } },
+    });
+    expect(r2.written).toBe(true);
+    expect(r2.files).toEqual(['config/credentials/joycity-parking.query.json']);
+    expect(r2.restartScheduled).toBe(false); // 工厂未注入 onApplied
+    expect(r2.credentials[0].overwrote).toBe(true);
+    // integrations.json 未被重写（内容逐字不变）；凭据文件为新值
+    expect(readFileSync(join(h.app.appDir, INTEGRATIONS_FILE), 'utf8')).toBe(before);
+    expect(readFileSync(h.credFile('joycity-parking.query'), 'utf8')).toContain('ROTATED-SECOND');
+  });
+
+  it('T3 dryRun + credentials（B3 钉死）：零落盘 + credentials[] 预览 + files 恒 []', async () => {
+    const r = await h.tk.writeServiceIntegration('parking.query', { provider: 'joycity' }, {
+      dryRun: true,
+      credentials: { type: 'api-key', values: { apiKey: 'SECRET-DRYRUN' } },
+    });
+    expect(r.written).toBe(false);
+    expect(r.files).toEqual([]);
+    expect(r.credentials).toEqual([{ stem: 'joycity-parking.query', ref: 'secret://joycity-parking.query', overwrote: false }]);
+    // 凭据目录与 integrations.json 均零变更
+    expect(existsSync(h.credFile('joycity-parking.query'))).toBe(false);
+    expect((h.readConfig().services as Record<string, unknown>)['parking.query']).toBeUndefined();
+  });
+
+  it('T4 dryRun 于已写 stem：overwrote:true 预览且磁盘态零变更（不重写）', async () => {
+    await h.tk.writeServiceIntegration('parking.query', { provider: 'joycity' }, {
+      credentials: { type: 'api-key', values: { apiKey: 'FIRST' } },
+    });
+    const before = readFileSync(h.credFile('joycity-parking.query'), 'utf8');
+    const r = await h.tk.writeServiceIntegration('parking.query', { provider: 'joycity' }, {
+      dryRun: true,
+      credentials: { type: 'api-key', values: { apiKey: 'SHOULD-NOT-WRITE' } },
+    });
+    expect(r.credentials[0].overwrote).toBe(true);
+    expect(readFileSync(h.credFile('joycity-parking.query'), 'utf8')).toBe(before);
+  });
+
+  it('T5 严格校验失败次序：凭据零落盘 + integrations 零变更（落盘后置于校验通过）', async () => {
+    h.app.dispose();
+    h = harness({ rejectMarker: '__reject__' });
+    await expect(
+      h.tk.writeServiceIntegration('parking.query', { provider: 'joycity', __reject__: true } as never, {
+        credentials: { type: 'api-key', values: { apiKey: 'X' } },
+      }),
+    ).rejects.toThrow();
+    expect(existsSync(h.credFile('joycity-parking.query'))).toBe(false);
+    expect((h.readConfig().services as Record<string, unknown>)['parking.query']).toBeUndefined();
+  });
+
+  it('T6 恶意 map 键 400（F4）：instances id / slot instances 键 / credentialsByInstance 键 / ByInstance 键', async () => {
+    // root.instances[].id
+    await expect(
+      h.tk.writeAppIntegration({ instances: [{ id: '../evil', name: 'x' }] } as never),
+    ).rejects.toMatchObject({ code: 'VALIDATION_FAILED', httpStatus: 400 });
+    // slot.instances map 键
+    await expect(
+      h.tk.writeServiceIntegration('parking.query', { provider: 'mock', instances: { '../evil': {} } } as never),
+    ).rejects.toMatchObject({ code: 'VALIDATION_FAILED', httpStatus: 400 });
+    // credentialsByInstance 选项键
+    await expect(
+      h.tk.writeServiceIntegration('parking.query', { provider: 'mock' }, {
+        credentialsByInstance: { 'a/b': { type: 'api-key', values: { k: 'v' } } },
+      }),
+    ).rejects.toMatchObject({ code: 'VALIDATION_FAILED', httpStatus: 400 });
+    // ByInstance 层无通配语义：'*' 亦拒
+    await expect(
+      h.tk.writeAppIntegration({ credentialRefByInstance: { '*': 'secret://x' } } as never),
+    ).rejects.toMatchObject({ code: 'VALIDATION_FAILED', httpStatus: 400 });
+    // 正例：slot instances 通配键豁免（TIER0 合法态）
+    const ok = await h.tk.writeServiceIntegration('parking.query', { provider: 'mock', instances: { '*': {} } });
+    expect(ok.written).toBe(true);
+  });
+
+  it('T7 重复同凭据写：overwrote:true 透出幂等（D-B2——written 仍 true）', async () => {
+    const cred = { type: 'api-key', values: { apiKey: 'SAME' } };
+    const r1 = await h.tk.writeServiceIntegration('parking.query', { provider: 'joycity' }, { credentials: cred });
+    expect(r1.credentials[0].overwrote).toBe(false);
+    const r2 = await h.tk.writeServiceIntegration('parking.query', { provider: 'joycity' }, { credentials: cred });
+    expect(r2.written).toBe(true);
+    expect(r2.credentials[0].overwrote).toBe(true);
+  });
+
+  it('T8 applyApp credentialsByInstance ref 回填 = plan 实际 ref（非硬编码格式拼接）', async () => {
+    const r = await h.tk.writeAppIntegration({ provider: 'p-x' } as never, {
+      credentialsByInstance: { 'mall-1': { type: 'api-key', values: { apiKey: 'V' } } },
+    });
+    expect(r.written).toBe(true);
+    const cfg = h.readConfig();
+    expect((cfg.credentialRefByInstance as Record<string, string>)['mall-1']).toBe('secret://p-x-mall-1-global');
+    expect(r.credentials).toEqual([{ stem: 'p-x-mall-1-global', ref: 'secret://p-x-mall-1-global', overwrote: false }]);
+    expect(existsSync(h.credFile('p-x-mall-1-global'))).toBe(true);
+  });
+
+  it('AppToolkitError 面：code/httpStatus/fields 结构化（消费面属性分发）', () => {
+    const err = new AppToolkitError('VALIDATION_FAILED', 400, 'm', ['a.b']);
+    expect(err.name).toBe('AppToolkitError');
+    expect(err.code).toBe('VALIDATION_FAILED');
+    expect(err.httpStatus).toBe(400);
+    expect(err.fields).toEqual(['a.b']);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@tbox.cn/app-contracts": ["../contracts/src/index.ts"],
+      "@tbox.cn/app-contracts/*": ["../contracts/src/*"]
+    }
+  },
+  "include": ["src", "tests"]
+}

package/tsup.config.ts

@@ -0,0 +1,29 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+  },
+  format: ['esm'],
+  target: 'node20',
+  platform: 'node',
+  outDir: 'dist',
+  clean: true,
+  sourcemap: false,
+  // dts worker 以命令行式传参会撞 TS5074(incremental 需单文件 emit 或 tsBuildInfoFile);
+  // 声明产物一次性构建无需增量——仅 dts 关闭,typecheck 的增量缓存不受影响。
+  dts: { compilerOptions: { incremental: false } },
+  // 运行时依赖面 external（contracts 恒 devDep 且限 import type——零 external 条目）
+  external: ['zod', 'ajv'],
+  // 发布 JS 产物 minify（2026-09-11 沿 app-sdk/cli 先例，commit 72383576）：ESM 导出名恒保留
+  // （export{mangled as 原名}）、d.ts 独立管线原样；标识符 mangle 安全前提与守卫真源见
+  // .agents/notes/implemented/process/2026-09-11-publish-dist-minify.md
+  // 打包纪律三件套（README 同文）：禁 createRequire(import.meta.url)；动态 import 路径禁字面量
+  // 包名折叠（resolver 运行时计算——agtcodingbox esbuild packages:"external" 已核不进 bundle）；
+  // 导出 Error 类构造器 this.name 字符串字面量约定（src 态守卫 tests/error-name-safety.test.ts，C4 建立时随 views 落）。
+  minify: true,
+  esbuildOptions(options) {
+    // charset utf8：谓词 message 等中文字面保留（esbuild 缺省 ASCII 转义 \uXXXX——膨胀且不可 grep）
+    options.charset = 'utf8';
+  },
+});