@tbox.cn/app-toolkit 0.4.0 → 0.6.0

package/src/views/service-resolutions.ts

@@ -11,10 +11,10 @@ import type {
   ServiceStatus,
 } from '../dto.js';
 import { AppToolkitError } from '../core/errors.js';
-import { resolveDomainBinding } from '../integrations/domain-binding.js';
+import { resolveModuleBinding } from '../integrations/module-binding.js';
 import type { ResolvedContracts } from '../core/contracts-resolver.js';
 import type { WalkCatalog } from '../assembly/walk-manifests.js';
-import { domainOfService, isSupplied, type ViewSnapshot } from './context.js';
+import { isSupplied, type ViewSnapshot } from './context.js';
 
 /**
  * 求值轴投影（views/service-resolutions；C4；FX-2c——B6 effective 填充 + F2 layer 推导；
@@ -50,22 +50,22 @@ interface InstanceEvaluation {
   effective?: EffectiveBinding;
 }
 
-/** 最特异声明层推导（F2）：inst 位 provider 在场 → 'instance'；槽级 → 'service'；域级 → 'module'；
+/** 最特异声明层推导（F2）：inst 位 provider 在场 → 'instance'；槽级 → 'service'；模块级 → 'module'；
  *  root → 'app'。实例位查找复刻 TIER0 语义（精确键优先、'*' 通配兜底——与 resolveEffectiveService
- *  的 instances 查找层同轴）。v4.4 F1：域级段消费 resolveDomainBinding 单源；返回扩 null
- *  （四层全无 provider 声明 → null——Entry.layer「未配置双缺席」口径，D31）。 */
+ *  的 instances 查找层同轴）。v6：模块级段消费 resolveModuleBinding 单源（ownerOf=walk.ownership）；
+ *  返回扩 null（四层全无 provider 声明 → null——Entry.layer「未配置双缺席」口径，D31）。 */
 function deriveBindingLayer(snapshot: ViewSnapshot, service: string, instanceId: string): BindingLayer | null {
   const integrations = snapshot.integrations as {
     provider?: unknown;
-    domains?: Record<string, { provider?: unknown }>;
     services?: Record<string, { provider?: unknown; instances?: Record<string, { provider?: unknown }> }>;
   } | null;
-  const domain = domainOfService(service);
   const slot = integrations?.services?.[service];
   const inst = slot?.instances?.[instanceId] ?? slot?.instances?.['*'];
   if (inst && inst.provider !== undefined) return 'instance';
   if (slot?.provider !== undefined) return 'service';
-  if (resolveDomainBinding(integrations, domain).layer === 'module') return 'module';
+  const owner = snapshot.walk.ownership[service];
+  if (owner !== undefined
+    && resolveModuleBinding(snapshot.integrations, owner).layer === 'module') return 'module';
   if (typeof integrations?.provider === 'string' && integrations.provider.length > 0) return 'app';
   return null;
 }
@@ -292,10 +292,8 @@ function buildInheritance(
 ): ServiceResolution['inheritance'] {
   const integrations = snapshot.integrations as {
     provider?: string;
-    domains?: Record<string, { provider?: string }>;
     services?: Record<string, { provider?: unknown; implementation?: string; instances?: Record<string, { provider?: string; implementation?: string }> }>;
   } | null;
-  const domain = domainOfService(service);
   const slot = integrations?.services?.[service];
   const cfg = snapshot.integrations as { instances?: unknown; defaultInstanceId?: unknown } | null;
   const normalized = evaluationContracts(snapshot).normalizeInstances({
@@ -304,13 +302,16 @@ function buildInheritance(
   });
   const defaultInstanceId = normalized.defaultInstanceId ?? '*';
   const defaultInstance = slot?.instances?.[defaultInstanceId] ?? slot?.instances?.['*'];
-  // module 段消费 resolveDomainBinding 单源（v4.4 F1——与 ProviderBinding / 谓词 #7 同源）
-  const domainBinding = resolveDomainBinding(integrations as Record<string, unknown> | null, domain);
+  // module 段消费 resolveModuleBinding 单源（v6——与 binding / 谓词 #7 同源；ownerOf=walk.ownership）
+  const owner = snapshot.walk.ownership[service];
+  const moduleBinding = owner !== undefined
+    ? resolveModuleBinding(integrations as Record<string, unknown> | null, owner)
+    : { provider: null as string | null, layer: null as 'module' | 'app' | null };
   return [
     { layer: 'app' as const, ...(integrations?.provider ? { provider: integrations.provider } : {}) },
     {
       layer: 'module' as const,
-      ...(domainBinding.layer === 'module' && domainBinding.provider ? { provider: domainBinding.provider } : {}),
+      ...(moduleBinding.layer === 'module' && moduleBinding.provider ? { provider: moduleBinding.provider } : {}),
     },
     {
       layer: 'service' as const,

package/tests/credentials-view.test.ts

@@ -31,10 +31,10 @@ function credHarness(): { app: TempApp; tk: AppToolkit } {
     'packages/provider-w/tbox.module.json',
     JSON.stringify({
       schemaVersion: 1,
-      name: 'provider-w',
+      id: 'provider-w',
       version: '0.1.0',
       kind: 'business',
-      contributes: {
+      declare: {
         providers: {
           slots: [
             { service: 'parking.payment', provider: 'wanda', implementation: 'wanda-parking@1', credentialType: 'wanda-c-signed-v1', credentialSchema: 'schemas/cred.json' },

package/tests/demo-app.ts

@@ -46,12 +46,15 @@ export interface FakeContractsOptions {
   /** 严格校验失败 fixture（FX-1c T5）：parseIntegrationsConfig 对含该子串文档 throw */
   rejectMarker?: string;
   /** resolveEffectiveService 自定义函数体（FX-2c O4 fixture：默认恒 service-not-configured；
-   *  入参 (integrations, service, instanceId, supplies)，需 return EffectiveServiceResolution 形状） */
+   *  入参 (integrations, service, instanceId, supplies, ownerOf)，需 return EffectiveServiceResolution 形状） */
   resolveBody?: string;
+  /** v6 形状标记（OWNERSHIP_BINDING_V6）缺席 fixture——默认在场（v6 假件签名随动 N11）；
+   *  false = v5 contracts 形态（ownershipBindingV6: false → assertContractsUsable 503 第四分支） */
+  withMarker?: boolean;
   /** service-slots.json 词汇（P9 身份判据/求值键集；缺省不物化 = 词汇空） */
   slots?: string[];
-  /** 词汇 meta 节（per-service {title,description}——B1 展示名链 fixture） */
-  meta?: Record<string, { title?: string; description?: string }>;
+  /** 词汇 meta 节（per-service {name,description}——B1 展示名链 fixture） */
+  meta?: Record<string, { name?: string; description?: string }>;
   /** service-slots.json 落位：'root' = 包根（缺省——夹具/旧布局形态）；
    *  'src' = 包内 src/（发布包 src 附带 / shim 链接形态——B0 探测跳 ②） */
   slotsLayout?: 'root' | 'src';
@@ -63,7 +66,7 @@ export interface FakeContractsOptions {
 /** 假 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, slots, meta, slotsLayout = 'root', zodRejectPaths } = opts;
+  const { version = '0.9.0', withStrict = true, withDist = true, brokenDist = false, missingEvaluationExports = false, rejectMarker, resolveBody, withMarker = true, slots, meta, slotsLayout = 'root', zodRejectPaths } = opts;
   const strictBody = withStrict
     ? `export function parseIntegrationsConfig(raw) { ${
         rejectMarker ? `if (JSON.stringify(raw).includes(${JSON.stringify(rejectMarker)})) throw new Error("fake strict reject"); ` : ''
@@ -73,9 +76,10 @@ export function writeFakeContractsPackage(packageRoot: string, opts: FakeContrac
           : ''
       }return raw; }`
     : '';
-  const resolveLine = `export function resolveEffectiveService(integrations, service, instanceId, supplies) { ${
+  const resolveLine = `export function resolveEffectiveService(integrations, service, instanceId, supplies, ownerOf) { ${
     resolveBody ?? 'return { status: "service-not-configured" };'
   } }`;
+  const markerLine = withMarker ? 'export const OWNERSHIP_BINDING_V6 = true;' : '';
   const exportsBody = missingEvaluationExports
     ? `export const marker = 1;\n${strictBody}`
     : [
@@ -84,6 +88,7 @@ export function writeFakeContractsPackage(packageRoot: string, opts: FakeContrac
         '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"];',
+        markerLine,
         strictBody,
         '',
       ]
@@ -135,7 +140,7 @@ export function writeFakeContractsPackage(packageRoot: string, opts: FakeContrac
 export function writeSelfSrcContractPackage(
   appDir: string,
   name: string,
-  content: { slots: string[]; meta?: Record<string, { title?: string; description?: string }> },
+  content: { slots: string[]; meta?: Record<string, { name?: string; description?: string }> },
 ): string {
   const dir = join(appDir, 'packages', name, 'src');
   mkdirSync(dir, { recursive: true });

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

@@ -11,20 +11,20 @@ import { createTempApp, linkContracts, writeFakeContractsPackage, writeSelfSrcCo
  */
 
 /** strict descriptor（形状对齐 provider-custom 出厂 manifest——parseModuleDescriptor 严格面） */
-function descriptor(name: string, provider: string, service: string): Record<string, unknown> {
+function descriptor(id: string, provider: string, service: string): Record<string, unknown> {
   return {
     schemaVersion: 1,
-    name,
+    id,
     version: '1.0.0',
     kind: 'business',
     risk: { level: 'low', writeBoundary: 'source' },
     distribution: { defaultMode: 'codegen' },
-    contributes: {
-      handlers: [], tools: [], cards: [], routes: [], pages: [], tabs: [],
+    declare: {
+      handlers: [], tools: [], cards: [], routes: [], pages: [], tabs: [], owns: [], consumes: [],
       providers: {
         slots: [{ service, provider, implementation: `${provider}-impl@1`, credentialType: 'apikey' }],
       },
-      services: [],
+      resources: [],
     },
     dependencies: { modules: [] },
     env: [],
@@ -125,13 +125,13 @@ describe('walkManifests · 词汇探测三跳 + slotMeta（B0）', () => {
     const store = join(app.appDir, '_store-a');
     writeFakeContractsPackage(store, {
       slots: ['auth.alipay-login', 'mall.info'],
-      meta: { 'auth.alipay-login': { title: '支付宝登录', description: '登录换码（code2Session）' } },
+      meta: { 'auth.alipay-login': { name: '支付宝登录', description: '登录换码（code2Session）' } },
     });
     linkContracts(app.appDir, store, { subdir: 'apps/server' });
 
     const walk = walkManifests(app.appDir);
     expect(walk.vocabulary).toEqual(['auth.alipay-login', 'mall.info']);
-    expect(walk.slotMeta['auth.alipay-login']).toEqual({ title: '支付宝登录', description: '登录换码（code2Session）' });
+    expect(walk.slotMeta['auth.alipay-login']).toEqual({ name: '支付宝登录', description: '登录换码（code2Session）' });
     expect(walk.slotMeta['mall.info']).toBeUndefined(); // meta 缺席槽不入表
   });
 
@@ -149,25 +149,25 @@ describe('walkManifests · 词汇探测三跳 + slotMeta（B0）', () => {
     app = createTempApp('tbox-probe-');
     writeSelfSrcContractPackage(app.appDir, 'contracts-mall', {
       slots: ['member.account', 'parking.payment'],
-      meta: { 'member.account': { title: '会员账户' } },
+      meta: { 'member.account': { name: '会员账户' } },
     });
 
     const walk = walkManifests(app.appDir);
     expect(walk.vocabulary).toEqual(['member.account', 'parking.payment']);
-    expect(walk.slotMeta['member.account']).toEqual({ title: '会员账户' });
+    expect(walk.slotMeta['member.account']).toEqual({ name: '会员账户' });
   });
 
   it('P4: 多包同槽 meta → 发现序首声明胜出（apps/* 先于 packages/* 候选序）', () => {
     app = createTempApp('tbox-probe-');
     const storeA = join(app.appDir, '_store-first');
-    writeFakeContractsPackage(storeA, { slots: ['x.y'], meta: { 'x.y': { title: '甲' } } });
+    writeFakeContractsPackage(storeA, { slots: ['x.y'], meta: { 'x.y': { name: '甲' } } });
     linkContracts(app.appDir, storeA, { subdir: 'apps/server' });
     const storeB = join(app.appDir, '_store-second');
-    writeFakeContractsPackage(storeB, { slots: ['x.y'], meta: { 'x.y': { title: '乙' } } });
+    writeFakeContractsPackage(storeB, { slots: ['x.y'], meta: { 'x.y': { name: '乙' } } });
     linkContracts(app.appDir, storeB, { subdir: 'packages/mock' });
 
     const walk = walkManifests(app.appDir);
-    expect(walk.slotMeta['x.y']).toEqual({ title: '甲' });
+    expect(walk.slotMeta['x.y']).toEqual({ name: '甲' });
   });
 
   it('P5: 坏 meta 条目（非对象/非 string/空串）→ 宽松跳过，slots 正常', () => {
@@ -176,13 +176,13 @@ describe('walkManifests · 词汇探测三跳 + slotMeta（B0）', () => {
     writeFakeContractsPackage(store, { slots: ['a.b'] });
     writeFileSync(
       join(store, 'service-slots.json'),
-      JSON.stringify({ slots: ['a.b', 'c.d', 'e.f'], meta: { 'a.b': '字符串', 'c.d': { title: 42 }, 'e.f': { title: '甲', description: '' } } }),
+      JSON.stringify({ slots: ['a.b', 'c.d', 'e.f'], meta: { 'a.b': '字符串', 'c.d': { name: 42 }, 'e.f': { name: '甲', description: '' } } }),
     );
     linkContracts(app.appDir, store, { subdir: 'apps/server' });
 
     const walk = walkManifests(app.appDir);
     expect(walk.vocabulary).toEqual(['a.b', 'c.d', 'e.f']);
-    expect(walk.slotMeta).toEqual({ 'e.f': { title: '甲' } }); // 空串 description 不入表（与 title 守卫对称）
+    expect(walk.slotMeta).toEqual({ 'e.f': { name: '甲' } }); // 空串 description 不入表（与 title 守卫对称）
   });
 
   it('P6: 无契约包（退化态）→ vocabulary 空 + slotMeta 空（P9 退化路径语义锁）', () => {

package/tests/file-cache.test.ts

@@ -132,7 +132,7 @@ describe('Freshness Contract W3/W7 — agent 动线矩阵（工厂方法级；FX
     mkdirSync(join(app.appDir, 'packages', 'module-new'), { recursive: true });
     writeFileSync(
       join(app.appDir, 'packages', 'module-new', 'tbox.module.json'),
-      JSON.stringify({ schemaVersion: 1, name: 'module-new', contributes: { services: [{ service: 'new.slot' }] } }),
+      JSON.stringify({ schemaVersion: 1, id: 'module-new', declare: { owns: [{ service: 'new.slot' }], consumes: [{ service: 'new.slot' }] } }),
     );
     const walk = walkManifests(app.appDir);
     expect(walk.modules.map((m) => m.id)).toContain('module-new');
@@ -172,10 +172,10 @@ describe('Freshness Contract W3/W7 — agent 动线矩阵（工厂方法级；FX
       join(app.appDir, 'packages', 'provider-x', 'tbox.module.json'),
       JSON.stringify({
         schemaVersion: 1,
-        name: 'provider-x',
-        contributes: {
+        id: 'provider-x',
+        declare: {
           providers: { slots: [{ service: 'parking.query', provider: 'joycity', implementation: 'joycity-parking@1', credentialType: 'joycity-c' }] },
-          services: [{ service: 'member.account' }],
+          consumes: [{ service: 'member.account' }],
         },
       }),
     );
@@ -196,7 +196,7 @@ describe('Freshness Contract W3/W7 — agent 动线矩阵（工厂方法级；FX
     mkdirSync(sdkDir, { recursive: true });
     writeFileSync(
       join(sdkDir, 'tbox.module.json'),
-      JSON.stringify({ schemaVersion: 1, name: 'module-sdk-y', contributes: { services: [{ service: 'sdk.slot-y', title: 'Sdk 槽' }] } }),
+      JSON.stringify({ schemaVersion: 1, id: 'module-sdk-y', declare: { owns: [{ service: 'sdk.slot-y' }], consumes: [{ service: 'sdk.slot-y', name: 'Sdk 槽' }] } }),
     );
     const modules2 = await tk.loadModules();
     expect(modules2.modules.map((m) => m.id)).toContain('module-sdk-y');

package/tests/module-resources.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { createAppToolkit, type AppToolkit } from '../src/factory.js';
+import { invalidateContractsResolver } from '../src/core/contracts-resolver.js';
+import { MODULE_INTEGRATION_NODE_KEYS } from '../src/dto.js';
+import type { ModuleDetailView } from '../src/dto.js';
+import { createTempApp, writeFakeContractsPackage, linkContracts, writeAppFile, type TempApp } from './demo-app.js';
+
+/**
+ * 模块资源只读投影矩阵（N2 读半边）：GET /modules/:m `resources` 四态（直填 datasetId /
+ * ref 命中台账 / ref 未命中（台账缺失·坏文件·键 miss 同归 null）/ 无 modules 节 = null）
+ * + 写侧保全不变量（MODULE_INTEGRATION_NODE_KEYS 白名单不变——resources 不进写位）。
+ * 展开语义镜像 SDK resolveKnowledge：datasetId 直填优先、ref 台账命中/miss-warn 降级。
+ */
+
+interface Harness {
+  app: TempApp;
+  tk: AppToolkit;
+}
+
+/** 自足基座：module-cs（declare.resources 声明对齐真实客服 manifest）+ integrations + 可选台账 */
+function resourcesHarness(integrations: object, knowledge: object | null): Harness {
+  const app = createTempApp('tbox-res-');
+  invalidateContractsResolver();
+  const store = join(app.appDir, 'contracts');
+  writeFakeContractsPackage(store, { version: '0.9.0' });
+  linkContracts(app.appDir, store, { subdir: 'apps/server' });
+  mkdirSync(join(app.appDir, 'packages', 'module-cs'), { recursive: true });
+  writeAppFile(
+    app.appDir,
+    'packages/module-cs/tbox.module.json',
+    JSON.stringify({
+      schemaVersion: 1,
+      id: 'module-cs',
+      version: '0.1.0',
+      kind: 'business',
+      declare: {
+        owns: [],
+        consumes: [],
+        resources: [
+          { id: 'customer-service-faq-kb', type: 'knowledge' },
+          { id: 'knowledge-assistance-kb', type: 'knowledge' },
+        ],
+      },
+      dependencies: { modules: [] },
+      env: [],
+    }),
+  );
+  writeAppFile(app.appDir, 'config/integrations.json', JSON.stringify(integrations));
+  if (knowledge !== null) {
+    writeAppFile(app.appDir, 'config/knowledge.json', JSON.stringify(knowledge));
+  }
+  const tk = createAppToolkit(app.appDir);
+  return { app, tk };
+}
+
+const FAQ_DIRECT = {
+  provider: 'mock',
+  modules: {
+    'module-cs': {
+      resources: { 'customer-service-faq-kb': { type: 'knowledge', datasetId: '20260101direct00000000000001', topK: 5, scoreThreshold: 0.5 } },
+    },
+  },
+};
+
+const FAQ_REF = {
+  provider: 'mock',
+  modules: {
+    'module-cs': {
+      resources: { 'customer-service-faq-kb': { type: 'knowledge', ref: 'customer-service-faq-generic' } },
+    },
+  },
+};
+
+const KB_REGISTRY = {
+  version: '1.0',
+  knowledge_bases: {
+    'customer-service-faq-generic': { datasetId: '20260921999def645305kQj02050918', retrieve_config: { topK: 5, scoreThreshold: 0.5 } },
+  },
+};
+
+async function detailOf(h: Harness): Promise<ModuleDetailView> {
+  return h.tk.loadModule('module-cs');
+}
+
+describe('module resources 只读投影（N2 读半边）', () => {
+  it('T1 直填 datasetId：resolvedDatasetId = 原值（无台账读取依赖）', async () => {
+    const h = resourcesHarness(FAQ_DIRECT, null); // 台账缺失——直填态不受影响
+    const v = await detailOf(h);
+    expect(v.resources).not.toBeNull();
+    expect(v.resources!['customer-service-faq-kb']).toEqual({
+      type: 'knowledge',
+      datasetId: '20260101direct00000000000001',
+      resolvedDatasetId: '20260101direct00000000000001',
+      topK: 5,
+      scoreThreshold: 0.5,
+    });
+    h.app.dispose();
+  });
+
+  it('T2 ref 命中台账：resolvedDatasetId = 台账 datasetId；文件原值 ref 保留', async () => {
+    const h = resourcesHarness(FAQ_REF, KB_REGISTRY);
+    const v = await detailOf(h);
+    expect(v.resources!['customer-service-faq-kb']).toEqual({
+      type: 'knowledge',
+      ref: 'customer-service-faq-generic',
+      resolvedDatasetId: '20260921999def645305kQj02050918',
+    });
+    h.app.dispose();
+  });
+
+  it('T3 ref 未命中键：resolvedDatasetId = null（原值 ref 保留）', async () => {
+    const h = resourcesHarness(FAQ_REF, { knowledge_bases: { 'other-kb': { datasetId: 'x' } } });
+    const v = await detailOf(h);
+    expect(v.resources!['customer-service-faq-kb']).toEqual({
+      type: 'knowledge',
+      ref: 'customer-service-faq-generic',
+      resolvedDatasetId: null,
+    });
+    h.app.dispose();
+  });
+
+  it('T3b 台账文件缺失 / 坏 JSON：同归 resolvedDatasetId = null（fail-soft 镜像 SDK）', async () => {
+    const missing = resourcesHarness(FAQ_REF, null);
+    expect((await detailOf(missing)).resources!['customer-service-faq-kb']?.resolvedDatasetId).toBeNull();
+    missing.app.dispose();
+
+    const broken = resourcesHarness(FAQ_REF, KB_REGISTRY);
+    writeAppFile(broken.app.appDir, 'config/knowledge.json', '{not-json');
+    expect((await detailOf(broken)).resources!['customer-service-faq-kb']?.resolvedDatasetId).toBeNull();
+    broken.app.dispose();
+  });
+
+  it('T4 无 modules 节 / 模块键无 resources：resources = null（null 语义：无资源 ≠ 空表）', async () => {
+    const noModules = resourcesHarness({ provider: 'mock' }, null);
+    expect((await detailOf(noModules)).resources).toBeNull();
+    noModules.app.dispose();
+
+    const noResourcesKey = resourcesHarness({ provider: 'mock', modules: { 'module-cs': { config: { k: 1 } } } }, KB_REGISTRY);
+    expect((await detailOf(noResourcesKey)).resources).toBeNull();
+    noResourcesKey.app.dispose();
+  });
+
+  it('T5 写侧保全不变量：MODULE_INTEGRATION_NODE_KEYS 白名单恒不含 resources（N2 写半边不变）', () => {
+    expect(MODULE_INTEGRATION_NODE_KEYS).toEqual(['provider', 'config']);
+  });
+});

package/tests/module-schema.test.ts

@@ -7,37 +7,67 @@ import {
 
 /**
  * module-schema（descriptor zod 单源）迁移改造验证（C2-5 + C1 P6 归位）：
- * - demand meta additive（serviceNeedContribSchema 增 title?/description?——P6）
+ * - demand meta additive（serviceConsumeContribSchema 增 name?/description?——P6）
  * - resource type 放宽（z.enum(RESOURCE_TYPE_IDS) → z.string()——词汇校验移谓词）
  * - 安全钉子 H9b（provider 字符集 pattern）
  * - 既有无 meta 素材全过（additive 等价）
+ * - v7 词汇统一（标识/展示名分轴）：id/name 翻转 + 四象限 legacy 矩阵
  */
 
 const BASE_MANIFEST = {
   schemaVersion: 1,
-  name: 'module-sample',
+  id: 'module-sample',
   version: '0.1.0',
 };
 
 describe('module-schema（descriptor zod 单源）', () => {
-  it('P6 demand meta additive：services 元素带 title/description 通过；缺席仍合法', () => {
+  it('v6 N1 旧键定向拒：顶层 contributes → ok:false + 三路径升级指引（非泛化 strict 报错）', () => {
+    const r = parseModuleDescriptor({ ...BASE_MANIFEST, contributes: { services: [] } });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.errors[0]).toContain('`contributes` 已更名 `declare`');
+    expect(r.errors[0]).toContain('module update --source');
+  });
+
+  it('v6 N1 旧键定向拒：declare.services → ok:false + consumes 指引', () => {
+    const r = parseModuleDescriptor({ ...BASE_MANIFEST, declare: { services: [{ service: 'x.y' }] } });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.errors[0]).toContain('`declare.services` 已更名 `declare.consumes`');
+  });
+
+  it('v6 owns 薄形状：strict 单键（元数据键拒——S1 防双数组漂移）；owns/consumes 双键并存合法', () => {
+    const thin = parseModuleDescriptor({ ...BASE_MANIFEST, declare: { owns: [{ service: 'a.b', optional: true } as never] } });
+    expect(thin.ok).toBe(false); // owns 元素 strict——元数据归 consumes
+    const both = parseModuleDescriptor({
+      ...BASE_MANIFEST,
+      declare: { owns: [{ service: 'a.b' }], consumes: [{ service: 'a.b', optional: false, name: 'T' }] },
+    });
+    expect(both.ok).toBe(true);
+    if (both.ok) {
+      expect(both.value.declare.owns).toEqual([{ service: 'a.b' }]);
+      expect(both.value.declare.consumes[0].name).toBe('T');
+    }
+  });
+
+  it('P6 demand meta additive：services 元素带 name/description 通过；缺席仍合法', () => {
     const withMeta = parseModuleDescriptor({
       ...BASE_MANIFEST,
-      contributes: {
-        services: [
-          { service: 'parking.query', optional: false, title: '车位查询', description: '查询车位状态' },
+      declare: {
+        consumes: [
+          { service: 'parking.query', optional: false, name: '车位查询', description: '查询车位状态' },
         ],
       },
     });
     expect(withMeta.ok).toBe(true);
     if (withMeta.ok) {
-      expect(withMeta.value.contributes.services[0].title).toBe('车位查询');
-      expect(withMeta.value.contributes.services[0].description).toBe('查询车位状态');
+      expect(withMeta.value.declare.consumes[0].name).toBe('车位查询');
+      expect(withMeta.value.declare.consumes[0].description).toBe('查询车位状态');
     }
     // 既有无 meta 素材全过（additive 等价）
     const withoutMeta = parseModuleDescriptor({
       ...BASE_MANIFEST,
-      contributes: { services: [{ service: 'parking.query' }] },
+      declare: { consumes: [{ service: 'parking.query' }] },
     });
     expect(withoutMeta.ok).toBe(true);
   });
@@ -45,7 +75,7 @@ describe('module-schema（descriptor zod 单源）', () => {
   it('resource type 放宽：任意 string 通过（词汇校验移谓词经 resolver 取词表）', () => {
     const result = parseModuleDescriptor({
       ...BASE_MANIFEST,
-      contributes: { resources: [{ id: 'kb-1', type: 'knowledge' }, { id: 'kb-2', type: 'future-type' }] },
+      declare: { resources: [{ id: 'kb-1', type: 'knowledge' }, { id: 'kb-2', type: 'future-type' }] },
     });
     expect(result.ok).toBe(true);
   });
@@ -53,14 +83,14 @@ describe('module-schema（descriptor zod 单源）', () => {
   it('H9b 安全钉子：provider 名含路径敌对字符 → 拒绝；合法字符集通过', () => {
     const evil = parseModuleDescriptor({
       ...BASE_MANIFEST,
-      contributes: {
+      declare: {
         providers: { slots: [{ service: 'a.b', provider: '../etc', implementation: 'x@1', credentialType: '-' }] },
       },
     });
     expect(evil.ok).toBe(false);
     const good = parseModuleDescriptor({
       ...BASE_MANIFEST,
-      contributes: {
+      declare: {
         providers: { slots: [{ service: 'a.b', provider: 'wanda', implementation: 'wanda-a@1', credentialType: '-' }] },
       },
     });
@@ -72,28 +102,98 @@ describe('module-schema（descriptor zod 单源）', () => {
     expect(SAFE_NAME_PATTERN.test('-lead')).toBe(false);
   });
 
-  it('零贡献合法（provider-custom 空包形态）：contributes 全 default', () => {
+  it('零贡献合法（provider-custom 空包形态）：declare 全 default', () => {
     const parsed = moduleDescriptorSchema.safeParse(BASE_MANIFEST);
     expect(parsed.success).toBe(true);
     if (parsed.success) {
-      expect(parsed.data.contributes.providers.slots).toEqual([]);
-      expect(parsed.data.contributes.services).toEqual([]);
-      expect(parsed.data.contributes.resources).toEqual([]);
+      expect(parsed.data.declare.providers.slots).toEqual([]);
+      expect(parsed.data.declare.consumes).toEqual([]);
+      expect(parsed.data.declare.resources).toEqual([]);
     }
   });
 
-  it('B1 模块 meta additive：根级 title/description 保真；缺席仍合法（回退归视图层）', () => {
-    const withMeta = parseModuleDescriptor({ ...BASE_MANIFEST, title: '停车缴费', description: '车辆查询与绑定、停车费用查询、缴费支付与开票' });
+  it('v7 B1 模块 meta：name = 展示名（id = 标识键）；缺席仍合法（回退归视图层）', () => {
+    const withMeta = parseModuleDescriptor({ ...BASE_MANIFEST, name: '停车缴费', description: '车辆查询与绑定、停车费用查询、缴费支付与开票' });
     expect(withMeta.ok).toBe(true);
     if (withMeta.ok) {
-      expect(withMeta.value.title).toBe('停车缴费');
+      expect(withMeta.value.id).toBe('module-sample');
+      expect(withMeta.value.name).toBe('停车缴费');
       expect(withMeta.value.description).toContain('停车费用查询');
     }
     const withoutMeta = moduleDescriptorSchema.safeParse(BASE_MANIFEST);
     expect(withoutMeta.success).toBe(true);
     if (withoutMeta.success) {
-      expect(withoutMeta.data.title).toBeUndefined();
+      expect(withoutMeta.data.name).toBeUndefined();
       expect(withoutMeta.data.description).toBeUndefined();
     }
   });
+
+  it('hidden 展示元数据：boolean 可选（true/false 通过、缺席合法、非 boolean 拒——清单过滤语义归视图层）', () => {
+    const hidden = parseModuleDescriptor({ ...BASE_MANIFEST, hidden: true });
+    expect(hidden.ok).toBe(true);
+    if (hidden.ok) expect(hidden.value.hidden).toBe(true);
+    const unhidden = parseModuleDescriptor({ ...BASE_MANIFEST, hidden: false });
+    expect(unhidden.ok).toBe(true);
+    if (unhidden.ok) expect(unhidden.value.hidden).toBe(false);
+    const absent = moduleDescriptorSchema.safeParse(BASE_MANIFEST);
+    expect(absent.success).toBe(true);
+    if (absent.success) expect(absent.data.hidden).toBeUndefined();
+    const bad = parseModuleDescriptor({ ...BASE_MANIFEST, hidden: 'yes' });
+    expect(bad.ok).toBe(false);
+  });
+
+  // ── v7 词汇统一：legacy 四象限矩阵（旧态/半迁移定向拒；v7 两形态放行）──
+
+  it('v7 legacy ①：v6 旧态（name 标识 + title 展示、无 id）→ 定向拒 + legacy 标志 + 双键指引', () => {
+    const r = parseModuleDescriptor({
+      schemaVersion: 1,
+      name: 'module-old',
+      title: '旧模块',
+      version: '0.1.0',
+      declare: { consumes: [{ service: 'a.b' }] },
+    });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.legacy).toBe(true);
+    const joined = r.errors.join('\n');
+    expect(joined).toContain('标识键 `name` 已更名 `id`');
+    expect(joined).toContain('展示名键 `title` 已更名 `name`');
+    expect(joined).toContain('module update --source');
+  });
+
+  it('v7 legacy ②：v6 最小旧态（仅 name 无 title）→ 定向拒 + legacy 标志', () => {
+    const r = parseModuleDescriptor({ schemaVersion: 1, name: 'module-old', version: '0.1.0' });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.legacy).toBe(true);
+    expect(r.errors[0]).toContain('标识键 `name` 已更名 `id`');
+  });
+
+  it('v7 legacy ③：半迁移（有 id 残留 title）→ 定向拒（title→name）', () => {
+    const r = parseModuleDescriptor({ ...BASE_MANIFEST, title: '残留展示名' });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.legacy).toBe(true);
+    expect(r.errors[0]).toContain('展示名键 `title` 已更名 `name`');
+  });
+
+  it('v7 legacy ④：declare.consumes[].title 残留（根级已翻转）→ 定向拒', () => {
+    const r = parseModuleDescriptor({
+      ...BASE_MANIFEST,
+      declare: { consumes: [{ service: 'a.b', title: '旧槽名' }] },
+    });
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.legacy).toBe(true);
+    expect(r.errors[0]).toContain('展示名键 `title` 已更名 `name`');
+  });
+
+  it('v7 完整形态：id + name（展示名）+ description 并存合法（同名键歧义以 id 在场性消解）', () => {
+    const r = parseModuleDescriptor({ ...BASE_MANIFEST, name: '示例模块' });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.value.id).toBe('module-sample');
+      expect(r.value.name).toBe('示例模块');
+    }
+  });
 });