@tbox.cn/app-toolkit 0.5.0 → 0.6.0

package/tests/views.test.ts

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { createAppToolkit, type AppToolkit } from '../src/factory.js';
 import { invalidateContractsResolver } from '../src/core/contracts-resolver.js';
 import { walkManifests, type WalkManifestsResult } from '../src/assembly/walk-manifests.js';
-import { buildIntegrationFieldRegistry, loadModuleFormViews, loadModuleIntegrationSchemas, loadServiceFieldRegistry } from '../src/views/integration-schemas.js';
+import { buildIntegrationFieldRegistry, loadModuleFormViews, loadModuleIntegrationSchemas, loadServiceFieldRegistry, loadServiceIntegrationSchemas } from '../src/views/integration-schemas.js';
 import { resolveServiceDisplay } from '../src/views/context.js';
 import type { ViewSnapshot } from '../src/views/context.js';
 import { URL_METHOD_MAP } from './naming-alignment.test.js';
@@ -240,6 +240,96 @@ function layerHarness(): {
   return { app, tk: createAppToolkit(app.appDir), schemas, joycity };
 }
 
+/** E 系列基座（v4.7 D38 引入；v5.1 D39 提升至模块层共用——原 D38 describe 内定义）：wanda 双槽
+ *  （layerHarness 形态）+ joycity 双 impl（O6 形态）+ config/schemas/ok.json（O15 形态）+
+ *  module-parking demand。schema 内容互异防断言串扰：
+ *  wQuery={baseUrl} / wParking={mallId} / joycity@1={joycityUrl} / joycity@2={endpointV2} / ok={okEndpoint}。
+ *  每用例独立 eHarness()——fixture 全新 temp app，零 file-cache stat 指纹串扰（不取重写+bumpMtime 方案）。
+ *  供给矩阵：wanda 供给 {parking.query, parking.payment}；joycity 仅供给 {parking.query}
+ *  （provider-multi 双 impl 皆 query）——D39 用例 (厂商 × 服务) 选型须对照本矩阵。 */
+function eHarness(): {
+  app: TempApp;
+  tk: AppToolkit;
+  schemas: { wQuery: object; wParking: object; joycity1: object; joycity2: object; ok: object };
+} {
+  const app = createTempApp('tbox-d38-');
+  invalidateContractsResolver();
+  const store = join(app.appDir, 'contracts');
+  writeFakeContractsPackage(store, { version: '0.9.0' });
+  linkContracts(app.appDir, store, { subdir: 'apps/server' });
+  const schemas = {
+    wQuery: { type: 'object', properties: { baseUrl: { type: 'string', format: 'uri' } }, required: ['baseUrl'] },
+    wParking: { type: 'object', properties: { mallId: { type: 'string' } } },
+    joycity1: { type: 'object', properties: { joycityUrl: { type: 'string' } } },
+    joycity2: { type: 'object', properties: { endpointV2: { type: 'string' } } },
+    ok: { type: 'object', properties: { okEndpoint: { type: 'string' } } },
+  };
+  writeAppFile(
+    app.appDir,
+    'packages/provider-w/tbox.module.json',
+    JSON.stringify({
+      schemaVersion: 1,
+      id: 'provider-w',
+      version: '0.1.0',
+      kind: 'business',
+      declare: {
+        providers: {
+          slots: [
+            { service: 'parking.query', provider: 'wanda', implementation: 'wanda-parking@1', credentialType: 'wanda-c', configSchema: 'schemas/query.json' },
+            { service: 'parking.payment', provider: 'wanda', implementation: 'wanda-parking@1', credentialType: 'wanda-c', configSchema: 'schemas/parking.json' },
+          ],
+        },
+      },
+      dependencies: { modules: [] },
+      env: [],
+    }),
+  );
+  writeAppFile(app.appDir, 'packages/provider-w/schemas/query.json', JSON.stringify(schemas.wQuery));
+  writeAppFile(app.appDir, 'packages/provider-w/schemas/parking.json', JSON.stringify(schemas.wParking));
+  writeAppFile(
+    app.appDir,
+    'packages/provider-multi/tbox.module.json',
+    JSON.stringify({
+      schemaVersion: 1,
+      id: 'provider-multi',
+      version: '0.1.0',
+      kind: 'business',
+      declare: {
+        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' },
+          ],
+        },
+      },
+      dependencies: { modules: [] },
+      env: [],
+    }),
+  );
+  writeAppFile(app.appDir, 'packages/provider-multi/schemas/query.json', JSON.stringify(schemas.joycity1));
+  writeAppFile(app.appDir, 'packages/provider-multi/schemas/query2.json', JSON.stringify(schemas.joycity2));
+  writeAppFile(app.appDir, 'config/schemas/ok.json', JSON.stringify(schemas.ok));
+  writeAppFile(
+    app.appDir,
+    'packages/module-parking/tbox.module.json',
+    JSON.stringify({
+      schemaVersion: 1,
+      id: 'module-parking',
+      version: '0.1.0',
+      kind: 'business',
+      declare: { owns: [{ service: 'parking.query' }], consumes: [{ service: 'parking.query', optional: false }] },
+      dependencies: { modules: [] },
+      env: [],
+    }),
+  );
+  return { app, tk: createAppToolkit(app.appDir), schemas };
+}
+
+/** integrations.json 单次写入（每用例独立 harness——零缓存串扰） */
+function writeIntegrations(appDir: string, config: Record<string, unknown>): void {
+  writeAppFile(appDir, 'config/integrations.json', JSON.stringify(config));
+}
+
 describe('views/工厂（O 矩阵核心族）', () => {
   let h: Harness;
 
@@ -267,7 +357,8 @@ describe('views/工厂（O 矩阵核心族）', () => {
     const mod = await h.tk.loadModule('module-parking');
     // v4.4 D34：domainKeys/providerBindings/configEditable 显式化（include 两键可选缺席——F4）
     // v7 词汇统一：模块展示名 name 前置（恒发——兜底 id）
-    expect(Object.keys(mod)).toEqual(['name', 'description', 'ownedServices', 'integration', 'binding', 'configEditable', 'services']);
+    // resources 只读镜像（N2 读半边——基座 integrations modules 节无 resources → null 仍恒发）
+    expect(Object.keys(mod)).toEqual(['name', 'description', 'ownedServices', 'integration', 'resources', 'binding', 'configEditable', '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 反例联动）
@@ -1022,93 +1113,6 @@ describe('模块清单 provider 家族排除（2026-09-16 双缺陷批——供
 });
 
 describe('v4.7 服务级 include（D38——生效绑定单体）', () => {
-  /** E 系列基座：wanda 双槽（layerHarness 形态）+ joycity 双 impl（O6 形态）+ config/schemas/ok.json
-   *  （O15 形态）+ module-parking demand。schema 内容互异防断言串扰：
-   *  wQuery={baseUrl} / wParking={mallId} / joycity@1={joycityUrl} / joycity@2={endpointV2} / ok={okEndpoint}。
-   *  每用例独立 eHarness()——fixture 全新 temp app，零 file-cache stat 指纹串扰（不取重写+bumpMtime 方案）。 */
-  function eHarness(): {
-    app: TempApp;
-    tk: AppToolkit;
-    schemas: { wQuery: object; wParking: object; joycity1: object; joycity2: object; ok: object };
-  } {
-    const app = createTempApp('tbox-d38-');
-    invalidateContractsResolver();
-    const store = join(app.appDir, 'contracts');
-    writeFakeContractsPackage(store, { version: '0.9.0' });
-    linkContracts(app.appDir, store, { subdir: 'apps/server' });
-    const schemas = {
-      wQuery: { type: 'object', properties: { baseUrl: { type: 'string', format: 'uri' } }, required: ['baseUrl'] },
-      wParking: { type: 'object', properties: { mallId: { type: 'string' } } },
-      joycity1: { type: 'object', properties: { joycityUrl: { type: 'string' } } },
-      joycity2: { type: 'object', properties: { endpointV2: { type: 'string' } } },
-      ok: { type: 'object', properties: { okEndpoint: { type: 'string' } } },
-    };
-    writeAppFile(
-      app.appDir,
-      'packages/provider-w/tbox.module.json',
-      JSON.stringify({
-        schemaVersion: 1,
-        id: 'provider-w',
-        version: '0.1.0',
-        kind: 'business',
-        declare: {
-          providers: {
-            slots: [
-              { service: 'parking.query', provider: 'wanda', implementation: 'wanda-parking@1', credentialType: 'wanda-c', configSchema: 'schemas/query.json' },
-              { service: 'parking.payment', provider: 'wanda', implementation: 'wanda-parking@1', credentialType: 'wanda-c', configSchema: 'schemas/parking.json' },
-            ],
-          },
-        },
-        dependencies: { modules: [] },
-        env: [],
-      }),
-    );
-    writeAppFile(app.appDir, 'packages/provider-w/schemas/query.json', JSON.stringify(schemas.wQuery));
-    writeAppFile(app.appDir, 'packages/provider-w/schemas/parking.json', JSON.stringify(schemas.wParking));
-    writeAppFile(
-      app.appDir,
-      'packages/provider-multi/tbox.module.json',
-      JSON.stringify({
-        schemaVersion: 1,
-        id: 'provider-multi',
-        version: '0.1.0',
-        kind: 'business',
-        declare: {
-          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' },
-            ],
-          },
-        },
-        dependencies: { modules: [] },
-        env: [],
-      }),
-    );
-    writeAppFile(app.appDir, 'packages/provider-multi/schemas/query.json', JSON.stringify(schemas.joycity1));
-    writeAppFile(app.appDir, 'packages/provider-multi/schemas/query2.json', JSON.stringify(schemas.joycity2));
-    writeAppFile(app.appDir, 'config/schemas/ok.json', JSON.stringify(schemas.ok));
-    writeAppFile(
-      app.appDir,
-      'packages/module-parking/tbox.module.json',
-      JSON.stringify({
-        schemaVersion: 1,
-        id: 'module-parking',
-        version: '0.1.0',
-        kind: 'business',
-        declare: { owns: [{ service: 'parking.query' }], consumes: [{ service: 'parking.query', optional: false }] },
-        dependencies: { modules: [] },
-        env: [],
-      }),
-    );
-    return { app, tk: createAppToolkit(app.appDir), schemas };
-  }
-
-  /** integrations.json 单次写入（每用例独立 harness——零缓存串扰） */
-  function writeIntegrations(appDir: string, config: Record<string, unknown>): void {
-    writeAppFile(appDir, 'config/integrations.json', JSON.stringify(config));
-  }
-
   it('E1 显式 string + catalog schema（分支②）', async () => {
     const h = eHarness();
     writeIntegrations(h.app.appDir, { services: { 'parking.query': { provider: 'wanda' } } });
@@ -1287,6 +1291,170 @@ describe('v4.7 服务级 include（D38——生效绑定单体）', () => {
   });
 });
 
+/**
+ * v5.1 D39 测试族（服务轴向假想绑定——?serviceProvider= 表单双投影重定向）。
+ * 供给矩阵（eHarness）：wanda 供给 {parking.query, parking.payment}；joycity 仅供给
+ * {parking.query}（provider-multi 双 impl 皆 query）——用例 (厂商 × 服务) 选型须对照本矩阵：
+ * catalog-miss 形态（D39-7）与豁免链正例（D39-6）不得混淆供给边界。每用例独立 eHarness
+ * （零 file-cache stat 指纹串扰）；D39-8/D39-9 用 layerHarness（x-tbox-global 标记 fixture）。
+ */
+describe('v5.1 D39（服务轴向假想绑定 serviceProvider）', () => {
+  it('D39-1 假想 happy + I1：双投影切 joycity 且 provider 一致 + 单键边界正例', async () => {
+    const h = eHarness();
+    writeIntegrations(h.app.appDir, { services: { 'parking.query': { provider: 'wanda' } } });
+    const both = ['integrationSchemas', 'integrationFieldRegistry'];
+    const v = await h.tk.loadService('parking.query', { include: both, serviceProvider: 'joycity' });
+    // I1：双投影同源同口径（fields = joycity schema 字段——catalog 复合键声明序首个 = @1 的 joycityUrl）
+    expect(v.integrationSchemas).toEqual({ provider: 'joycity', configSchema: h.schemas.joycity1 });
+    expect(v.integrationFieldRegistry?.provider).toBe('joycity');
+    expect(v.integrationFieldRegistry!.fields.map((f) => f.key)).toEqual(['joycityUrl']);
+    // 单键边界正例：仅 integrationSchemas + 轴参 → 200 假想计算；registry 未请求 = 缺席（S7-1 尾部先例）
+    const only = await h.tk.loadService('parking.query', { include: ['integrationSchemas'], serviceProvider: 'joycity' });
+    expect(only.integrationSchemas).toEqual({ provider: 'joycity', configSchema: h.schemas.joycity1 });
+    expect('integrationFieldRegistry' in only).toBe(false);
+    h.app.dispose();
+  });
+
+  it('D39-2 I2 锁：integration/suppliedBy/defaults 恒实际态', async () => {
+    const h = eHarness();
+    writeIntegrations(h.app.appDir, { services: { 'parking.query': { provider: 'wanda', config: { baseUrl: 'https://w.example' } } } });
+    const base = await h.tk.loadService('parking.query');
+    const v = await h.tk.loadService('parking.query', { include: ['integrationSchemas', 'integrationFieldRegistry'], serviceProvider: 'joycity' });
+    expect(v.integration).toEqual(base.integration); // 文件逐字原值不被重定向（预览不产生「已保存」误导）
+    expect(v.suppliedBy).toEqual(base.suppliedBy); // catalog 静态切片恒实际
+    expect(v.defaults).toEqual(base.defaults); // manifest 预填恒实际
+    expect(v.integrationSchemas?.provider).toBe('joycity'); // 对照：表单层已重定向
+    h.app.dispose();
+  });
+
+  it('D39-3 I3 锁 + 错轴静默忽略：空串 ≡ 缺席 ≡ 实际；appProvider/moduleProvider 被无视', async () => {
+    const h = eHarness();
+    writeIntegrations(h.app.appDir, { services: { 'parking.query': { provider: 'wanda' } } });
+    const empty = await h.tk.loadService('parking.query', { include: ['integrationFieldRegistry'], serviceProvider: '' });
+    const absent = await h.tk.loadService('parking.query', { include: ['integrationFieldRegistry'] });
+    expect(empty.integrationFieldRegistry).toEqual(absent.integrationFieldRegistry);
+    // 错轴参数（变量绕过多余属性检查——运行时按名读取，appProvider/moduleProvider 被无视；S7-4 先例镜像）
+    const opts = { include: ['integrationFieldRegistry'], serviceProvider: '', appProvider: 'joycity', moduleProvider: 'joycity' };
+    const wrongAxis = await h.tk.loadService('parking.query', opts);
+    expect(wrongAxis.integrationFieldRegistry).toEqual(absent.integrationFieldRegistry);
+    h.app.dispose();
+  });
+
+  it('D39-4 轴参严检矩阵：400 先于 404（镜像 S7-1 形态）', async () => {
+    const h = eHarness();
+    await expect(h.tk.loadService('parking.query', { serviceProvider: 'x' })).rejects.toMatchObject({
+      code: 'VALIDATION_FAILED', httpStatus: 400, fields: ['serviceProvider'],
+    });
+    await expect(h.tk.loadService('parking.query', { include: [], serviceProvider: 'x' })).rejects.toMatchObject({
+      code: 'VALIDATION_FAILED', httpStatus: 400, fields: ['serviceProvider'],
+    });
+    // 先于 404：ghost 服务 + 无表单键轴参 → 400（非 SERVICE_NOT_FOUND）；表单键在场 → 放行至 404
+    await expect(h.tk.loadService('ghost', { serviceProvider: 'x' })).rejects.toMatchObject({
+      code: 'VALIDATION_FAILED', httpStatus: 400, fields: ['serviceProvider'],
+    });
+    await expect(h.tk.loadService('ghost', { include: ['integrationSchemas'], serviceProvider: 'x' })).rejects.toMatchObject({
+      code: 'SERVICE_NOT_FOUND', httpStatus: 404,
+    });
+    h.app.dispose();
+  });
+
+  it('D39-5 同构承诺锁：假想 ≡ PUT 改写 provider 后实读（双投影；S6 写通道先例）', async () => {
+    const h = eHarness();
+    const both = ['integrationSchemas', 'integrationFieldRegistry'];
+    writeIntegrations(h.app.appDir, { services: { 'parking.query': { provider: 'wanda' } } });
+    const hyp = await h.tk.loadService('parking.query', { include: both, serviceProvider: 'joycity' });
+    // 状态演进全经 toolkit 写通道——写后本实例缓存即刻失效，免外部写缓存关注
+    const cur = await h.tk.loadService('parking.query');
+    const w = await h.tk.writeServiceIntegration('parking.query', { ...cur.integration!, provider: 'joycity' });
+    expect(w.written).toBe(true);
+    const act = await h.tk.loadService('parking.query', { include: both });
+    expect(act.integrationSchemas).toEqual(hyp.integrationSchemas);
+    expect(act.integrationFieldRegistry).toEqual(hyp.integrationFieldRegistry);
+    h.app.dispose();
+  });
+
+  it('D39-6 假想豁免链三分支：malformed 不污染 / 内联不读取无 H9 / 未绑定仍非 null', async () => {
+    // ① malformed 节点（E14 形态）+ 假想 → 非 null（短路在节点读取之前——坏形态只影响实际态投影）
+    const h = eHarness();
+    writeIntegrations(h.app.appDir, {
+      modules: { 'module-parking': { provider: 'wanda' } },
+      services: { 'parking.query': { provider: { provider: 'my-api' } } },
+    });
+    const bad = await h.tk.loadService('parking.query', { include: ['integrationFieldRegistry'], serviceProvider: 'joycity' });
+    expect(bad.integrationFieldRegistry).not.toBeNull();
+    expect(bad.integrationFieldRegistry!.provider).toBe('joycity');
+    // 实际态对照：同坏节点无轴参 → 整字段 null（E14 双态互证——预览与坏文件解耦）
+    const badActual = await h.tk.loadService('parking.query', { include: ['integrationSchemas'] });
+    expect(badActual.integrationSchemas).toBeNull();
+    h.app.dispose();
+    // ② 内联 ref 逃逸节点（E4 形态）+ 假想 → 无 H9 400（短路不读节点内联 ref——换厂商即离开内联）
+    const h2 = eHarness();
+    writeIntegrations(h2.app.appDir, {
+      services: { 'parking.query': { provider: { provider: 'my-api', credentialType: '-', configSchema: 'config/schemas-evil/x.json' } } },
+    });
+    const inline = await h2.tk.loadService('parking.query', { include: ['integrationSchemas'], serviceProvider: 'joycity' });
+    expect(inline.integrationSchemas).toEqual({ provider: 'joycity', configSchema: h2.schemas.joycity1 });
+    h2.app.dispose();
+    // ③ 全链未绑定（E8 形态）+ 假想 → 仍非 null（服务轴恒可写——无 module 轴零归属豁免形态）；
+    //    wanda 供给 payment（供给矩阵）→ mallId 字段在场
+    const h3 = eHarness();
+    writeIntegrations(h3.app.appDir, { services: { 'parking.payment': {} } });
+    const unbound = await h3.tk.loadService('parking.payment', { include: ['integrationFieldRegistry'], serviceProvider: 'wanda' });
+    // fields[].schema = 字段子 schema（非整文件 schema——G 批锁 :1777 同型）
+    expect(unbound.integrationFieldRegistry).toEqual({
+      provider: 'wanda', schemaless: [], unsupplied: [], additionalPropertiesAllowed: true,
+      fields: [{ key: 'mallId', schema: { type: 'string' }, sources: [{ service: 'parking.payment', required: false }], global: false }],
+    });
+    h3.app.dispose();
+  });
+
+  it('D39-7 catalog miss：假想未知厂商 → 非 null 空集（schemaless=[service]）', async () => {
+    const h = eHarness();
+    writeIntegrations(h.app.appDir, { services: { 'parking.query': { provider: 'wanda' } } });
+    const v = await h.tk.loadService('parking.query', { include: ['integrationSchemas', 'integrationFieldRegistry'], serviceProvider: 'ghost-vendor' });
+    expect(v.integrationSchemas).toEqual({ provider: 'ghost-vendor', configSchema: null });
+    expect(v.integrationFieldRegistry).toEqual({
+      provider: 'ghost-vendor', schemaless: ['parking.query'], unsupplied: [], additionalPropertiesAllowed: true, fields: [],
+    });
+    h.app.dispose();
+  });
+
+  it('D39-8 global 旗标假想透传：标记位如实（layerHarness——true 正例 + 未标记 false 不过滤）', async () => {
+    const h = layerHarness();
+    // joycity 供给 parking.query → 假想后 fields = joycity query schema 字段（fixture 全标记 → global:true）
+    const joy = await h.tk.loadService('parking.query', { include: ['integrationFieldRegistry'], serviceProvider: 'joycity' });
+    expect(joy.integrationFieldRegistry!.provider).toBe('joycity');
+    expect(joy.integrationFieldRegistry!.fields.length).toBeGreaterThan(0);
+    expect(joy.integrationFieldRegistry!.fields.every((f) => f.global)).toBe(true);
+    // wanda 供给 parking.payment → mallId global:true / parkLotId global:false 在场（服务轴不过滤——G 批语义假想不变）；
+    // payment 先配置入词汇（P9：契约包 ∪ 已配置——layerHarness 初始 integrations.json 未配置 payment；
+    // 覆盖写后 payment 节点 {} 实际态级联双缺 → null，假想 wanda 短路仍非 null——豁免链③同型，S7-7 外部写先例）
+    writeAppFile(h.app.appDir, 'config/integrations.json', JSON.stringify({ services: { 'parking.payment': {} } }));
+    const wan = await h.tk.loadService('parking.payment', { include: ['integrationFieldRegistry'], serviceProvider: 'wanda' });
+    expect(wan.integrationFieldRegistry!.fields.map((f) => f.key).sort()).toEqual(['mallId', 'parkLotId']);
+    expect(wan.integrationFieldRegistry!.fields.find((f) => f.key === 'mallId')!.global).toBe(true);
+    expect(wan.integrationFieldRegistry!.fields.find((f) => f.key === 'parkLotId')!.global).toBe(false);
+    h.app.dispose();
+  });
+
+  it('D39-9 单源锁：loadServiceFieldRegistry(snap,s,X) ≡ buildIntegrationFieldRegistry over 链函数', async () => {
+    const h = layerHarness();
+    const { loadViewSnapshotSync } = await import('../src/views/context.js');
+    const snap = loadViewSnapshotSync({ appDir: h.app.appDir }, await h.tk.resolveContracts());
+    const X = 'joycity';
+    const reg = loadServiceFieldRegistry(snap, 'parking.query', X);
+    const schemas = loadServiceIntegrationSchemas(snap, 'parking.query', X);
+    expect(schemas).not.toBeNull();
+    // 结构性断言（依赖契约锁——registry 旁路重取 schema 破 I1 即刻红；S8 同族意图）
+    const manual = buildIntegrationFieldRegistry({
+      provider: schemas!.provider,
+      services: { 'parking.query': { configSchema: schemas!.configSchema } },
+    });
+    expect(reg).toEqual(manual);
+    h.app.dispose();
+  });
+});
+
 /**
  * v4.6 D36/D37 测试族（S5 接续 S1-S4）：S5a 纯代数（直调合成 layer 字面量，零 fs）/
  * S5b 接线序 + 等价锁 / S6 同构（假想 ≡ 写后实读）/ S7 边界（400·null 两态·I2·空集）/
@@ -1891,6 +2059,46 @@ describe('B1 展示名链', () => {
     h2.app.dispose();
   });
 
+  it('T2b loadModulesView：hidden 模块默认过滤；includeHidden 可见 + 徽标；detail 恒 200 不滤', async () => {
+    const app = createTempApp('tbox-hidden-');
+    invalidateContractsResolver();
+    const store = joinStore(app.appDir, 'contracts');
+    writeFakeContractsPackage(store, { version: '0.9.0' });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    const manifest = (id: string, name: string, extra: Record<string, unknown> = {}): string =>
+      JSON.stringify({
+        schemaVersion: 1,
+        id,
+        version: '0.1.0',
+        kind: 'business',
+        name,
+        declare: { owns: [], consumes: [] },
+        dependencies: { modules: [] },
+        env: [],
+        ...extra,
+      });
+    mkdirSync(join(app.appDir, 'packages', 'module-visible'), { recursive: true });
+    writeAppFile(app.appDir, 'packages/module-visible/tbox.module.json', manifest('module-visible', '可见模块'));
+    mkdirSync(join(app.appDir, 'packages', 'module-secret'), { recursive: true });
+    writeAppFile(app.appDir, 'packages/module-secret/tbox.module.json', manifest('module-secret', '隐藏模块', { hidden: true }));
+
+    const tk = createAppToolkit(app.appDir);
+    // 默认：hidden 模块不进清单（可见模块无 hidden 键——additive 纪律）
+    const def = await tk.loadModules();
+    expect(def.modules.map((m) => m.id)).toEqual(['module-visible']);
+    expect(def.modules[0]).not.toHaveProperty('hidden');
+    // includeHidden = true：可见并携带 hidden: true 徽标
+    const inc = await tk.loadModules({ includeHidden: true });
+    expect(inc.modules.map((m) => m.id).sort()).toEqual(['module-secret', 'module-visible']);
+    expect(inc.modules.find((m) => m.id === 'module-secret')?.hidden).toBe(true);
+    expect(inc.modules.find((m) => m.id === 'module-visible')).not.toHaveProperty('hidden');
+    // detail 端点恒 200 不滤——视图携带 hidden 徽标
+    const detail = await tk.loadModule('module-secret');
+    expect(detail.name).toBe('隐藏模块');
+    expect(detail.hidden).toBe(true);
+    app.dispose();
+  });
+
   it('T3 loadModuleDetailView：meta 恒发；services[] 词汇优先（demand 车位查询被词汇停车查询压过——防漂移锁）', async () => {
     const h2 = displayHarness();
     const v = await h2.tk.loadModule('module-parking');

package/tests/write-core.test.ts

@@ -368,3 +368,37 @@ describe('写核心管线（FX-1c）', () => {
     expect(err.fields).toEqual(['a.b']);
   });
 });
+
+describe('孤儿凭据写后对账（PUT 路径追平——finalize 单点）', () => {
+  let h: Harness;
+  beforeEach(() => {
+    h = harness();
+  });
+  afterEach(() => {
+    h.app.dispose();
+  });
+
+  it('P1 PUT 替换弃 credentialRef → ORPHANED_CREDENTIAL warning（message 含被弃 stem）', async () => {
+    writeAppFile(h.app.appDir, 'config/credentials/wd-parking.json', JSON.stringify({ type: 'wanda-c', k: 'v' }));
+    await h.tk.writeServiceIntegration('parking.query', {
+      provider: 'wanda', implementation: 'w@1', credentialRef: 'secret://wd-parking',
+    } as never);
+    const r = await h.tk.writeServiceIntegration('parking.query', {} as never);
+    expect(r.written).toBe(true);
+    const orphan = r.issues.find((i) => i.code === 'ORPHANED_CREDENTIAL');
+    expect(orphan).toBeTruthy();
+    expect(orphan?.message).toContain('wd-parking');
+  });
+
+  it('P2 真写报全量孤儿 / dryRun 不报 / no-diff 不报', async () => {
+    writeAppFile(h.app.appDir, 'config/credentials/stray.json', JSON.stringify({ type: 'x', k: 'v' }));
+    const node = { provider: 'wanda', implementation: 'w@1' } as never;
+    const dry = await h.tk.writeServiceIntegration('parking.query', node, { dryRun: true });
+    expect(dry.issues.some((i) => i.code === 'ORPHANED_CREDENTIAL')).toBe(false);
+    const real = await h.tk.writeServiceIntegration('parking.query', node);
+    expect(real.issues.some((i) => i.code === 'ORPHANED_CREDENTIAL' && i.message.includes('stray'))).toBe(true);
+    const nodiff = await h.tk.writeServiceIntegration('parking.query', node);
+    expect(nodiff.written).toBe(false);
+    expect(nodiff.issues.some((i) => i.code === 'ORPHANED_CREDENTIAL')).toBe(false);
+  });
+});