@tbox.cn/app-toolkit 0.3.0 → 0.5.0

package/src/assembly/walk-manifests.ts

@@ -9,15 +9,23 @@ import { readAppManifestFull, type NpmModuleEntry, type AppManifestFull } from '
  *
  * manifest 候选路径探测（packages/<id>/tbox.module.json 优先 → node_modules/<pkg>/tbox.module.json；
  * tbox-app dev 真身经 .tbox-dev.local/dev-manifest.json redirects 独立 catalog 通道直达）一次遍历同时产出：
- *   1. modules：已装模块清单（declared；demand meta title/description 透传）
+ *   1. modules：已装模块清单（declared；demand meta name/description 透传）
  *   2. catalog（富形态）：providers 嵌套（vendor→impl→entry，per-service {implementation, credentialType}
  *      保真——同厂商异构/多实现合法，D25/H1）+ 需求侧聚合
  *   3. serviceSchemas：per-service schema 复合键表——键 `${provider}\u0000${service}`（H2，同一服务
  *      多厂商供给各自 schema 零碰撞）；多 impl 同 (provider, service) 异 schema → 声明序首个
  *   4. vocabulary：所有携带 service-slots.json 的已装契约包该文件 `.slots` 键并集（fs 直读、
- *      `$comment` 忽略；探测链 = readdir(<候选>/node_modules/@tbox.cn) 过滤携带该文件的包——
- *      零缓存枚举，与 manifest 探测同机制；多行业 contracts-* 天然扩展 F8）；缺席 → []（退化 demanded ∪ configured）
- *   5. domainKeyIssues：跨模块域键冲突 issue（两模块派生同一 domains 键——P13）
+ *      `$comment` 忽略；探测三跳 = ① <候选>/node_modules/@tbox.cn/<pkg>/service-slots.json（包根）
+ *      ② 同包 src/service-slots.json（发布包 src 附带 / 模板 shim 链接）
+ *      ③ 候选自身 {service-slots.json, src/service-slots.json}（local/codegen 全量副本——
+ *      mall 生成应用主形态，不依赖 install）；零缓存枚举，与 manifest 探测同机制；
+ *      多行业 contracts-* 天然扩展 F8）；缺席 → []（退化 demanded ∪ configured）
+ *   5. slotMeta：词汇 meta 节（per-service {name,description} 展示元数据——消费端兜底链
+ *      词汇 > demand > id，views/context resolveServiceDisplay 单源）；多包发现序首声明胜出
+ *      （与 catalog addSlots 同语义）；contracts-mall 词汇锁保证 mall 域全量覆盖；缺席 → {}
+ *   6. ownership：service → moduleId 归属表（v6——declare.owns 聚合；install id 键控；
+ *      双 owner 冲突 → declarationIssues OWNERSHIP_CONFLICT + 先声明胜出）
+ *   7. declarationIssues：声明面诊断（OWNERSHIP_CONFLICT / OLD_MANIFEST_KEY——P3 通道）
  *
  * **约束（D26；FX-3/F7 边界）**：目录枚举零缓存——readdir / node_modules 候选探测 / `.tbox/app.json` 读取 /
  * dev-manifest 读取每次执行（枚举输入保持 fresh——agent 装卸模块下一笔即见）；manifest/service-slots
@@ -26,6 +34,11 @@ import { readAppManifestFull, type NpmModuleEntry, type AppManifestFull } from '
  * 宽松解析语义（坏文件静默 + 重复键首声明保留）零改动。
  */
 
+/** 声明面诊断（v6 P3 通道——OWNERSHIP_CONFLICT / OLD_MANIFEST_KEY；error 级） */
+export type DeclarationIssue =
+  | { severity: 'error'; code: 'OWNERSHIP_CONFLICT'; message: string; module?: string }
+  | { severity: 'error'; code: 'OLD_MANIFEST_KEY'; message: string; module?: string };
+
 export interface WalkManifestsResult {
   /** declared 产物（install id + descriptor；demand meta 透传） */
   modules: WalkModuleInfo[];
@@ -35,8 +48,49 @@ export interface WalkManifestsResult {
   serviceSchemas: Record<string, { configSchema?: string; credentialSchema?: string; packageDir: string }>;
   /** 服务词汇 = 所有携带 service-slots.json 的已装契约包 `.slots` 键并集（缺席 → []） */
   vocabulary: string[];
-  /** 跨模块域键冲突（P13——两模块的 service 集派生同一 domains 键） */
-  domainKeyIssues: Array<{ severity: 'warning'; code: 'DOMAIN_KEY_CONFLICT'; message: string; module?: string }>;
+  /** 词汇 meta 节：per-service {name,description} 展示元数据（多包首声明胜出；缺席 → {}） */
+  slotMeta: Record<string, SlotMeta>;
+  /** v6 服务归属表：service → moduleId（install id 键控——integrations modules 节键同轴；
+   *  双 owner 冲突 → declarationIssues + 先声明胜出；dev 通道以 manifest id 参与归属） */
+  ownership: Record<string, string>;
+  /** 声明面诊断（OWNERSHIP_CONFLICT / OLD_MANIFEST_KEY） */
+  declarationIssues: DeclarationIssue[];
+}
+
+/** 槽位展示元数据（service-slots.json meta 节元素——宽松提取，字段皆可选；v7 词汇统一 title→name） */
+export interface SlotMeta {
+  name?: string;
+  description?: string;
+}
+
+/** 词汇文件单次解析产物（slots 与 meta 同源同读——防双读漂移） */
+interface SlotsFile {
+  slots: string[];
+  meta: Record<string, SlotMeta>;
+}
+
+/** 词汇文件解析（宽松：坏文件/缺 slots 数组 → null；meta 非对象条目/无有效字段跳过） */
+function parseSlotsFile(raw: string): SlotsFile | null {
+  try {
+    const parsed = JSON.parse(raw) as { slots?: unknown; meta?: unknown };
+    if (!Array.isArray(parsed.slots)) return null;
+    const slots = parsed.slots.filter((s): s is string => typeof s === 'string');
+    const meta: Record<string, SlotMeta> = {};
+    if (parsed.meta && typeof parsed.meta === 'object' && !Array.isArray(parsed.meta)) {
+      for (const [svc, entry] of Object.entries(parsed.meta as Record<string, unknown>)) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+        const { name, description } = entry as { name?: unknown; description?: unknown };
+        const m: SlotMeta = {};
+        if (typeof name === 'string' && name.length > 0) m.name = name;
+        if (typeof description === 'string' && description.length > 0) m.description = description;
+        if (m.name !== undefined || m.description !== undefined) meta[svc] = m;
+      }
+    }
+    return { slots, meta };
+  } catch {
+    /* 宽松：坏文件跳过 */
+    return null;
+  }
 }
 
 export interface WalkModuleInfo {
@@ -49,12 +103,17 @@ export interface WalkModuleInfo {
   descriptor: ModuleDescriptor;
 }
 
-/** 富形态供给条目：per-service {implementation, credentialType} 恒数组保真（H1） */
+/** 富形态供给条目：per-service {implementation, credentialType} 恒数组保真（H1）；
+ *  name/description = 厂商展示元数据（strict manifest descriptor 透传——多包同厂商
+ *  首声明胜出，与 owner 同语义；B1 walk 层传播；v7 词汇统一 title→name） */
 export interface WalkProviderEntry {
   provider: string;
   implementation: string;
   credentialType: string;
   owner: string;
+  /** 厂商展示名（manifest name——多包首声明；缺席 = undefined） */
+  name?: string;
+  description?: string;
   local?: boolean;
   configSchema?: string;
   credentialSchema?: string;
@@ -68,8 +127,8 @@ export interface WalkCatalog {
     {
       optional: boolean;
       defaults: Array<{ provider: string; implementation: string }>;
-      /** demand meta（title/description 首声明保留——模块 manifest demand 侧 additive） */
-      title?: string;
+      /** demand meta（name/description 首声明保留——模块 manifest demand 侧 additive；v7 title→name） */
+      name?: string;
       description?: string;
       owners: string[];
     }
@@ -77,25 +136,28 @@ export interface WalkCatalog {
   credentialTypes: Record<string, { owner: string; packageDir: string; credentialSchema?: string }>;
 }
 
-/** loose 允许的 contributes 局部结构（本地声明——解跨模块类型身份耦合，TS2719 防线） */
-interface LooseContributes {
+/** loose 允许的 declare 局部结构（本地声明——解跨模块类型身份耦合，TS2719 防线） */
+interface LooseDeclare {
   providers?: { slots?: ProviderSlotContrib[] };
-  services?: Array<{
+  consumes?: Array<{
     service: string;
     optional?: boolean;
     defaults?: Array<{ provider: string; implementation: string }>;
-    title?: string;
+    name?: string;
     description?: string;
   }>;
 }
 
-/** manifest 读取结果（判别联合——strict = 完整 descriptor；loose = 部分形态宽容提取） */
+/** manifest 读取结果（判别联合——strict = 完整 descriptor；loose = 部分形态宽容提取；
+ *  legacy = 旧键（v6 声明面 / v7 词汇统一，parseModuleDescriptor legacy 标志透传）——
+ *  拒 loose 静默兜底，定向 issue）。 */
 type ReadManifestResult =
-  | { kind: 'strict'; name: string; version: string; descriptor: ModuleDescriptor; contributes: ModuleDescriptor['contributes'] }
-  | { kind: 'loose'; name?: string; contributes: LooseContributes };
+  | { kind: 'strict'; id: string; version: string; descriptor: ModuleDescriptor; declare: ModuleDescriptor['declare'] }
+  | { kind: 'loose'; id?: string; declare: LooseDeclare }
+  | { kind: 'legacy'; detail: string };
 
-/** 读单文件 manifest（坏文件 → null；宽松——strict 解析失败但有 contributes → loose 兜底，
- *  保留旧 SDK loadProviderCatalog 对部分形态 manifest 的容忍语义，C3-5 桥等价性）。
+/** 读单文件 manifest（坏文件 → null；宽松——strict 解析失败但为新形态 declare → loose 兜底；
+ *  旧键 → legacy（定向 issue，静默兜底防线——单源 = parseModuleDescriptor legacy 标志）。
  *  FX-3（F7 边界）：**文件内容**经 file-cache（stat 指纹——外部写下一笔自愈）；目录枚举仍零缓存。 */
 function readManifestFile(file: string, cache?: FileCache): ReadManifestResult | null {
   const parse = (raw: string): ReadManifestResult | null => {
@@ -103,17 +165,19 @@ function readManifestFile(file: string, cache?: FileCache): ReadManifestResult |
       const parsedRaw: unknown = JSON.parse(raw);
       const parsed = parseModuleDescriptor(parsedRaw);
       if (parsed.ok) {
-        return { kind: 'strict', name: parsed.value.name, version: parsed.value.version, descriptor: parsed.value, contributes: parsed.value.contributes };
+        return { kind: 'strict', id: parsed.value.id, version: parsed.value.version, descriptor: parsed.value, declare: parsed.value.declare };
       }
-      // loose 兜底：strict 拒（部分形态 manifest——如仅 contributes）但有 contributes → 宽松提取
-      if (parsedRaw && typeof parsedRaw === 'object' && 'contributes' in parsedRaw) {
-        const obj = parsedRaw as { name?: unknown; contributes?: ModuleDescriptor['contributes'] };
+      // 旧键（v6/v7）：parseModuleDescriptor 已定向检测（legacy 标志）——拒 loose 静默兜底
+      if (parsed.legacy) return { kind: 'legacy', detail: parsed.errors.join('; ') };
+      // loose 兜底：strict 拒（部分形态 manifest——如仅 declare）但有新形态 declare → 宽松提取
+      if (parsedRaw && typeof parsedRaw === 'object' && 'declare' in parsedRaw) {
+        const obj = parsedRaw as { id?: unknown; declare?: LooseDeclare };
         return {
           kind: 'loose',
-          ...(typeof obj.name === 'string' ? { name: obj.name } : {}),
-          contributes: {
-            providers: (obj.contributes as LooseContributes | undefined)?.providers,
-            services: (obj.contributes as LooseContributes | undefined)?.services,
+          ...(typeof obj.id === 'string' ? { id: obj.id } : {}),
+          declare: {
+            providers: obj.declare?.providers,
+            consumes: obj.declare?.consumes,
           },
         };
       }
@@ -174,10 +238,15 @@ function readDevManifestRedirects(appDir: string): DevManifestRedirect[] {
   }
 }
 
-/** 契约包发现链：readdir(node_modules/@tbox.cn) 过滤携带 service-slots.json 的包（目录枚举零缓存，F8；
- *  FX-3：slots 文件**内容**经 file-cache） */
-function discoverContractPackages(appDir: string, cache?: FileCache): Array<{ dir: string; slots: string[] }> {
-  const found: Array<{ dir: string; slots: string[] }> = [];
+/** 契约包发现链（探测三跳——词汇源真实布局全覆盖，B0）：候选集（appDir、apps/*、packages/*）×
+ *  ① node_modules/@tbox.cn/<pkg>/service-slots.json（包根——夹具/旧布局）
+ *  ② 同包 src/service-slots.json（发布包 src 随 files 附带 / 模板 shim 链接到仓库源 src/）
+ *  ③ 候选自身 {service-slots.json, src/service-slots.json}（local/codegen 全量副本——mall 生成应用
+ *     主形态，stage rewriteExportsToSrc 展开后永驻 packages/*，不依赖 install）
+ *  同包双在场（异常态）root 优先。slots 与 meta 单次解析同产（目录枚举零缓存，F8；
+ *  FX-3：文件**内容**经 file-cache）。 */
+function discoverContractPackages(appDir: string, cache?: FileCache): Array<{ dir: string; slots: string[]; meta: Record<string, SlotMeta> }> {
+  const found: Array<{ dir: string; slots: string[]; meta: Record<string, SlotMeta> }> = [];
   const candidates: Array<string> = [appDir];
   for (const sub of ['apps', 'packages']) {
     const parent = join(appDir, sub);
@@ -191,7 +260,12 @@ function discoverContractPackages(appDir: string, cache?: FileCache): Array<{ di
     }
   }
   const seenRoots = new Set<string>();
+  const addDiscovered = (dir: string, file: string): void => {
+    const parsed = cache ? cache.read(file, parseSlotsFile) : parseSlotsFile(readFileSync(file, 'utf8'));
+    if (parsed !== null && parsed !== undefined) found.push({ dir, slots: parsed.slots, meta: parsed.meta });
+  };
   for (const dir of candidates) {
+    // 跳 1/2：node_modules 位（包根 → src——显式安装真源优先）
     const scopeDir = join(dir, 'node_modules', '@tbox.cn');
     if (!existsSync(scopeDir)) continue;
     let names: string[] = [];
@@ -204,19 +278,16 @@ function discoverContractPackages(appDir: string, cache?: FileCache): Array<{ di
       const pkgDir = join(scopeDir, name);
       if (seenRoots.has(pkgDir)) continue;
       seenRoots.add(pkgDir);
-      const slotsFile = join(pkgDir, 'service-slots.json');
-      if (!existsSync(slotsFile)) continue;
-      const parseSlots = (raw: string): string[] | null => {
-        try {
-          const parsed = JSON.parse(raw) as { slots?: unknown };
-          if (Array.isArray(parsed.slots)) return parsed.slots.filter((s): s is string => typeof s === 'string');
-        } catch {
-          /* 宽松：坏文件跳过 */
-        }
-        return null;
-      };
-      const slots = cache ? cache.read(slotsFile, parseSlots) : parseSlots(readFileSync(slotsFile, 'utf8'));
-      if (slots !== null && slots !== undefined) found.push({ dir: pkgDir, slots });
+      const rootFile = join(pkgDir, 'service-slots.json');
+      const srcFile = join(pkgDir, 'src', 'service-slots.json');
+      if (existsSync(rootFile)) addDiscovered(pkgDir, rootFile);
+      else if (existsSync(srcFile)) addDiscovered(pkgDir, srcFile);
+    }
+  }
+  // 跳 3：候选自身（local/codegen 全量副本形态——后置于 nm 位：真源 > 副本，meta 首声明序随此）
+  for (const dir of candidates) {
+    for (const file of [join(dir, 'service-slots.json'), join(dir, 'src', 'service-slots.json')]) {
+      if (existsSync(file)) addDiscovered(dir, file);
     }
   }
   return found;
@@ -227,12 +298,11 @@ export function walkManifests(appDir: string, cache?: FileCache): WalkManifestsR
   const modules: WalkModuleInfo[] = [];
   const catalog: WalkCatalog = { providers: {}, services: {}, credentialTypes: {} };
   const serviceSchemas: WalkManifestsResult['serviceSchemas'] = {};
-  const domainKeyIssues: WalkManifestsResult['domainKeyIssues'] = [];
+  const declarationIssues: WalkManifestsResult['declarationIssues'] = [];
+  const ownership: Record<string, string> = {};
   const seen = new Set<string>();
-  /** 域键 → 首个声明模块（P13 冲突检测） */
-  const domainOwners = new Map<string, string>();
 
-  const addSlots = (slots: readonly ProviderSlotContrib[], owner: string, packageDir: string): void => {
+  const addSlots = (slots: readonly ProviderSlotContrib[], owner: string, packageDir: string, modMeta?: SlotMeta): void => {
     for (const slot of slots) {
       // 富形态：per-service {implementation, credentialType} 保真（同厂商多 impl 合法——声明序）
       const vendorSlots = (catalog.providers[slot.provider] ??= {});
@@ -245,6 +315,8 @@ export function walkManifests(appDir: string, cache?: FileCache): WalkManifestsR
           implementation: slot.implementation,
           credentialType: slot.credentialType,
           owner,
+          ...(modMeta?.name ? { name: modMeta.name } : {}),
+          ...(modMeta?.description ? { description: modMeta.description } : {}),
           ...(slot.local ? { local: true } : {}),
           ...(slot.configSchema ? { configSchema: slot.configSchema } : {}),
           ...(slot.credentialSchema ? { credentialSchema: slot.credentialSchema } : {}),
@@ -268,8 +340,50 @@ export function walkManifests(appDir: string, cache?: FileCache): WalkManifestsR
     }
   };
 
-  const addServiceNeed = (
-    need: { service: string; optional?: boolean; defaults?: Array<{ provider: string; implementation: string }>; title?: string; description?: string },
+  /** 厂商展示元数据（strict manifest descriptor 透传——loose 形态无 descriptor → undefined） */
+  const modMetaOf = (manifest: ReadManifestResult): SlotMeta | undefined =>
+    manifest.kind === 'strict' ? { name: manifest.descriptor.name, description: manifest.descriptor.description } : undefined;
+
+  /** v6 归属聚合：declare.owns → ownership 表（先声明胜出；冲突 → OWNERSHIP_CONFLICT）。
+   *  owner 键 = install id（integrations modules 节键同轴——npmModules 通道 = entry.id、
+   *  packages/dev 通道 = manifest id）。 */
+  const addOwns = (services: readonly string[], owner: string): void => {
+    for (const service of services) {
+      const first = ownership[service];
+      if (first === undefined) {
+        ownership[service] = owner;
+      } else if (first !== owner) {
+        declarationIssues.push({
+          severity: 'error',
+          code: 'OWNERSHIP_CONFLICT',
+          module: owner,
+          message: `服务 ${service} 归属冲突：${first} 与 ${owner} 均声明 owns（先声明 ${first} 胜出）——修正 manifest declare.owns 互斥`,
+        });
+      }
+    }
+  };
+
+  /** 旧键 legacy manifest → 定向 issue（N1：拒 loose 静默兜底）。 */
+  const pushLegacyIssue = (manifest: ReadManifestResult, module: string): void => {
+    if (manifest.kind !== 'legacy') return;
+    declarationIssues.push({
+      severity: 'error',
+      code: 'OLD_MANIFEST_KEY',
+      module,
+      message: `${module}：${manifest.detail}`,
+    });
+  };
+
+  /** declare 提取（strict/loose 双形态统一视图；legacy → null） */
+  const declareOf = (manifest: ReadManifestResult): LooseDeclare | null =>
+    manifest.kind === 'strict'
+      ? manifest.declare
+      : manifest.kind === 'loose'
+        ? manifest.declare
+        : null;
+
+  const addServiceConsume = (
+    need: { service: string; optional?: boolean; defaults?: Array<{ provider: string; implementation: string }>; name?: string; description?: string },
     owner: string,
   ): void => {
     const optional = need.optional !== false;
@@ -291,22 +405,10 @@ export function walkManifests(appDir: string, cache?: FileCache): WalkManifestsR
     catalog.services[need.service] = {
       optional,
       defaults: [...defaults],
-      ...(need.title ? { title: need.title } : {}),
+      ...(need.name ? { name: need.name } : {}),
       ...(need.description ? { description: need.description } : {}),
       owners: [owner],
     };
-    // P13 域键冲突检测（首声明占用；跨模块冲突 → issue）
-    const domain = need.service.includes('.') ? need.service.slice(0, need.service.indexOf('.')) : need.service;
-    const firstOwner = domainOwners.get(domain);
-    if (firstOwner === undefined) domainOwners.set(domain, owner);
-    else if (firstOwner !== owner) {
-      domainKeyIssues.push({
-        severity: 'warning',
-        code: 'DOMAIN_KEY_CONFLICT',
-        module: owner,
-        message: `域键 ${domain} 被多模块声明（${firstOwner} 与 ${owner}）——domains 换算歧义（P13）`,
-      });
-    }
   };
 
   // 通道 1：npmModules 登记（packages/<id> 本地优先 → node_modules/<pkg>）
@@ -315,39 +417,49 @@ export function walkManifests(appDir: string, cache?: FileCache): WalkManifestsR
     const local = join(appDir, 'packages', entry.id);
     const nm = join(appDir, 'node_modules', ...entry.package.split('/'));
     const manifest = readManifestFile(join(local, 'tbox.module.json'), cache) ?? readManifestFile(join(nm, 'tbox.module.json'), cache);
+    if (manifest?.kind === 'legacy') {
+      pushLegacyIssue(manifest, entry.id);
+      seen.add(entry.id); // 防重复报
+      continue;
+    }
     if (!manifest) continue;
     seen.add(entry.id);
     const dir = existsSync(join(local, 'tbox.module.json')) ? local : nm;
-    const contributes = manifest.contributes;
+    const declare = declareOf(manifest);
     // loose 形态（部分 manifest）不进 modules 清单（descriptor 缺名不可装配化）——仅 catalog 聚合（旧语义等价）
     if (manifest.kind === 'strict') {
       modules.push({ id: entry.id, dir, pkg: entry.mode === 'sdk' ? entry.package : `@app/${entry.id}`, descriptor: manifest.descriptor });
     }
-    const slots = contributes.providers?.slots ?? [];
-    if (slots.length) addSlots(slots, entry.package, dir);
-    const needs = contributes.services ?? [];
-    if (needs.length) {
-      for (const need of needs) {
-        addServiceNeed(need, entry.package);
-      }
-    }
+    const slots = declare?.providers?.slots ?? [];
+    if (slots.length) addSlots(slots, entry.package, dir, modMetaOf(manifest));
+    const consumes = declare?.consumes ?? [];
+    for (const need of consumes) addServiceConsume(need, entry.package);
+    // v6 归属：owner 键 = install id（integrations modules 节同轴）
+    const owns = manifest.kind === 'strict' ? manifest.descriptor.declare.owns : [];
+    if (owns.length) addOwns(owns.map((o) => o.service), entry.id);
   }
 
   // 通道 1.5：tbox-app dev manifest 真身（catalog-only——聚合宽/声明窄不变量：dev 模块
-  // 永不进 modules 清单，防 sync 污染受跟踪装配文件；登记真源优先（seen 按模块名去重））
+  // 永不进 modules 清单，防 sync 污染受跟踪装配文件；登记真源优先（seen 按模块名去重））。
+  // v6：归属以 manifest id 参与（dev 会话的 modules 集成位键同轴——N3 聚合宽/声明窄）。
   for (const { pkg, dir } of readDevManifestRedirects(appDir)) {
     const manifest = readManifestFile(join(dir, 'tbox.module.json'), cache);
-    if (!manifest?.name || seen.has(manifest.name)) continue;
-    seen.add(manifest.name);
-    const slots = manifest.contributes.providers?.slots ?? [];
-    if (slots.length) addSlots(slots, pkg, dir);
-    const needs = manifest.contributes.services ?? [];
-    if (needs.length) {
-      for (const need of needs) addServiceNeed(need, pkg);
+    if (manifest?.kind === 'legacy') {
+      pushLegacyIssue(manifest, pkg);
+      continue;
     }
+    if (!manifest?.id || seen.has(manifest.id)) continue;
+    seen.add(manifest.id);
+    const declare = declareOf(manifest);
+    const slots = declare?.providers?.slots ?? [];
+    if (slots.length) addSlots(slots, pkg, dir, modMetaOf(manifest));
+    const consumes = declare?.consumes ?? [];
+    for (const need of consumes) addServiceConsume(need, pkg);
+    const owns = manifest.kind === 'strict' ? manifest.descriptor.declare.owns : [];
+    if (owns.length) addOwns(owns.map((o) => o.service), manifest.id);
   }
 
-  // 通道 2：packages/* 约定发现（本地模块——npmModules 未登记形态，如模板天气模块）
+  // 通道 2：packages/* 约定发现（本地模块——npmModules 未登记形态，如手工放入的本地模块）
   const packagesDir = join(appDir, 'packages');
   if (existsSync(packagesDir)) {
     let entries: string[] = [];
@@ -360,32 +472,40 @@ export function walkManifests(appDir: string, cache?: FileCache): WalkManifestsR
       if (seen.has(name)) continue;
       const dir = join(packagesDir, name);
       const manifest = readManifestFile(join(dir, 'tbox.module.json'), cache);
+      if (manifest?.kind === 'legacy') {
+        pushLegacyIssue(manifest, name);
+        seen.add(name);
+        continue;
+      }
       if (!manifest) continue;
-      const modName = manifest.name ?? name;
-      if (seen.has(modName)) continue;
-      seen.add(modName);
-      const contributes = manifest.contributes;
+      const modId = manifest.id ?? name;
+      if (seen.has(modId)) continue;
+      seen.add(modId);
+      const declare = declareOf(manifest);
       if (manifest.kind === 'strict') {
-        modules.push({ id: modName, dir, pkg: `@app/${modName}`, descriptor: manifest.descriptor });
-      }
-      const slots = contributes.providers?.slots ?? [];
-      if (slots.length) addSlots(slots, `@app/${modName}`, dir);
-      const needs = contributes.services ?? [];
-      if (needs.length) {
-        for (const need of needs) {
-          addServiceNeed(need, `@app/${modName}`);
-        }
+        modules.push({ id: modId, dir, pkg: `@app/${modId}`, descriptor: manifest.descriptor });
       }
+      const slots = declare?.providers?.slots ?? [];
+      if (slots.length) addSlots(slots, `@app/${modId}`, dir, modMetaOf(manifest));
+      const consumes = declare?.consumes ?? [];
+      for (const need of consumes) addServiceConsume(need, `@app/${modId}`);
+      const owns = manifest.kind === 'strict' ? manifest.descriptor.declare.owns : [];
+      if (owns.length) addOwns(owns.map((o) => o.service), modId);
     }
   }
 
-  // 产物 4：服务词汇（契约包 service-slots.json 并集——零缓存枚举）
+  // 产物 4/5：服务词汇 + 词汇 meta（契约包 service-slots.json 并集——零缓存枚举；
+  // meta 多包发现序首声明胜出，与 catalog addSlots 同语义）
   const vocabulary = new Set<string>();
+  const slotMeta: Record<string, SlotMeta> = {};
   for (const pkg of discoverContractPackages(appDir, cache)) {
     for (const s of pkg.slots) vocabulary.add(s);
+    for (const [svc, m] of Object.entries(pkg.meta)) {
+      if (slotMeta[svc] === undefined) slotMeta[svc] = m;
+    }
   }
 
-  return { modules, catalog, serviceSchemas, vocabulary: [...vocabulary].sort(), domainKeyIssues };
+  return { modules, catalog, serviceSchemas, vocabulary: [...vocabulary].sort(), slotMeta, ownership, declarationIssues };
 }
 
 // ── CLI collectDeclared 迁入（C5——声明集合 + 双端入口探测 + declaration.moduleId 提取）──
@@ -447,7 +567,7 @@ export function collectDeclaredModules(appDir: string): DeclaredModuleInfo[] {
   for (const mod of walk.modules) {
     const mode = modeById.get(mod.id) ?? 'local';
     const hasServerEntry = probeModuleObjectExport(mod.dir, 'server', 'serverModule');
-    const c = mod.descriptor.contributes;
+    const c = mod.descriptor.declare;
     declared.push({
       id: mod.id,
       pkg: mode === 'sdk' ? mod.pkg : `@app/${mod.id}`,

package/src/core/contracts-expected.ts

@@ -13,11 +13,11 @@ import type {
  */
 
 export interface EvaluationExports {
-  /** 求值单源（TIER0；v3 显式激活 vs v4 通配语义随应用版本） */
+  /** 求值单源（TIER0；v3 显式激活 vs v4 通配语义随应用版本；v6 第五参 ownerOf） */
   resolveEffectiveService: typeof resolveEffectiveService;
   /** 供给查表派生（谓词 #12 与视图供给轴共用输入） */
   buildSupplyLookup: typeof buildSupplyLookup;
-  /** service → 首点段域前缀（谓词 #14 域键匹配） */
+  /** service → 首点段域前缀（v6 deprecated——级联键控退役，仅词汇组织消费） */
   moduleDomainOf: typeof moduleDomainOf;
   /** 部署实例注册表归一（默认实例委托——null → '*' 通配口径） */
   normalizeInstances: typeof normalizeInstances;

package/src/core/contracts-resolver.ts

@@ -38,13 +38,16 @@ export interface ResolvedContracts {
   evaluation: boolean;
   /** 严格 zod 面可用（parseIntegrationsConfig 在场——≥0.9 门控判据） */
   strictValidation: boolean;
+  /** v6 形状标记在场（OWNERSHIP_BINDING_V6——modules[owner] 绑定形状支持；标记门 P1：
+   *  v5 contracts + v6 toolkit 偏斜 → 503 第四分支，防静默忽略 ownerOf） */
+  ownershipBindingV6: boolean;
   /** 动态 import 产物（命名导出子集——Partial<EvaluationExports>） */
   module: ResolvedModule;
   /** 解析诊断（N1 构建指引 message 三分支的输入：未安装 / 版本 <0.9 / 源码态未构建） */
   notes: string[];
 }
 
-/** 求值面必需具名导出（在场 → evaluation: true） */
+/** 求值面必需具名导出（在场 → evaluation: true；moduleDomainOf v6 deprecated 但仍在发布面） */
 const EVALUATION_EXPORT_NAMES = [
   'resolveEffectiveService',
   'buildSupplyLookup',
@@ -56,10 +59,14 @@ const EVALUATION_EXPORT_NAMES = [
 /** 严格校验面具名导出（在场 → strictValidation: true；0.9+） */
 const STRICT_EXPORT_NAME = 'parseIntegrationsConfig';
 
+/** v6 形状标记导出（在场 → ownershipBindingV6: true；判据先例 = STRICT_EXPORT_NAME 出口在场性） */
+const OWNERSHIP_MARKER_NAME = 'OWNERSHIP_BINDING_V6';
+
 const UNRESOLVED: ResolvedContracts = {
   version: null,
   evaluation: false,
   strictValidation: false,
+  ownershipBindingV6: false,
   module: {},
   notes: [],
 };
@@ -203,10 +210,14 @@ async function probeCandidate(
     const mod = (await import(pathToFileURL(probeFile).href + versionQuery)) as Record<string, unknown>;
     const evaluation = EVALUATION_EXPORT_NAMES.every((name) => mod[name] !== undefined);
     const strictValidation = mod[STRICT_EXPORT_NAME] !== undefined;
+    // v6 形状标记（出口在场性——判据先例 STRICT_EXPORT_NAME）；缺席时不在此 push note
+    // （503 文案归 factory assertContractsUsable 门控单点——P1）
+    const ownershipBindingV6 = mod[OWNERSHIP_MARKER_NAME] === true;
     return {
       version,
       evaluation,
       strictValidation,
+      ownershipBindingV6,
       module: mod as ResolvedModule,
       notes: evaluation
         ? []

package/src/core/env-expansion.ts

@@ -1,21 +1,23 @@
 /**
  * 配置 JSON 环境变量占位展开（纯数据形态——自 app-sdk env-expansion.ts 迁入改造）。
  *
- * 语法（与 SDK 版语义逐字一致，共享向量 test-fixtures/env-expansion-cases.json 防漂移）：
- *   ${NAME}     占位引用；NAME 限定 [A-Z][A-Z0-9_]*（UPPER_SNAKE，最小化与正文 `${...}` 误碰）
- *   $${NAME}   转义为字面量 ${NAME}（原样保留一次 $）
+ * 语法（语义真源 = 本文件 + 共享向量 test-fixtures/env-expansion-cases.json 防漂移）：
+ *   ${NAME}        占位引用；NAME 限定 [A-Z][A-Z0-9_]*（UPPER_SNAKE，最小化与正文 `${...}` 误碰）
+ *   ${NAME:def}    POSIX 风格缺省值：NAME 未设置时用 def（字面量，不二次展开）；设置时空串也算「已设置」
+ *   $${NAME}      转义为字面量 ${NAME}（原样保留一次 $）
  *
  * 语义（评审 N1 钉死，壳层各自包装 throw/report）：
  *   - 单遍非递归：env 值内若含 `${OTHER}` 不被二次展开（注入防线）；String.replace 回调形态天然单遍。
+ *     默认值内含 `${...}` 同样不展开（POSIX 同限）；默认值含 `}` 不支持（同 POSIX 同限——正则 [^}] 截断）。
  *   - 值经 JSON 字符串转义注入；不做数值/布尔强制转换。
- *   - **本版为纯数据返回形态** `{ text?: string; missing: string[] }`——缺变量不 throw，
+ *   - **本版为纯数据返回形态** `{ text?: string; missing: string[] }`——缺变量（无缺省值时）不 throw，
  *     由壳层（CLI doctor 壳 / app-sdk 桥 throw 壳 / 沙箱宿主）决定 fail-fast 还是降级：
  *     SDK 桥壳 missing 非空即 throw（错误文案逐字等价 SDK 旧版）；CLI 壳同款。
  *   - 无 ${ 的文本快速路径：text 原文返回，零替换零开销。
  */
 
-/** 占位匹配：$ 或 $$ 后接 {[A-Z][A-Z0-9_]*}（$$ 形态同匹配，展开期判首字符去留） */
-const ENV_VAR_RE = /\$\$?\{([A-Z][A-Z0-9_]*)\}/g;
+/** 占位匹配：$ 或 $$ 后接 {NAME} 或 {NAME:default}（$$ 形态同匹配，展开期判首字符去留） */
+const ENV_VAR_RE = /\$\$?\{([A-Z][A-Z0-9_]*)(?::-([^}]*))?\}/g;
 
 /** JSON 字符串字面量转义（值 → 可直接置于 "..." 内的安全文本）——
  * 基于 JSON.stringify 切片：引号/反斜杠/控制字符（\b/\n/\r/\t/\f）转义语义与 JSON 精确一致 */
@@ -37,14 +39,14 @@ export function expandEnvVars(
 ): EnvExpansionResult {
   const missing: string[] = [];
   // 单遍替换：回调返回值不回扫（非递归语义；$${} 转义在回调内消去一个 $）
-  const out = text.replace(ENV_VAR_RE, (raw, name: string) => {
+  const out = text.replace(ENV_VAR_RE, (raw, name: string, fallback?: string) => {
     if (raw.startsWith('$$')) return raw.slice(1);
     const v = env[name];
-    if (v === undefined) {
-      missing.push(name);
-      return raw; // 占位保留（纯数据形态：missing 上报，不 throw）
-    }
-    return jsonEscape(v);
+    if (v !== undefined) return jsonEscape(v);
+    // ${NAME:def}：NAME 未设置 → 缺省值（字面量；空串默认 = 显式空值语义）
+    if (fallback !== undefined) return jsonEscape(fallback);
+    missing.push(name);
+    return raw; // 占位保留（纯数据形态：missing 上报，不 throw）
   });
   if (missing.length > 0) return { missing };
   return { text: out, missing: [] };