@tbox.cn/app-toolkit 0.3.0 → 0.5.0

package/src/core/module-schema.ts

@@ -1,16 +1,30 @@
 import { z } from 'zod';
 
 /**
- * tbox.module.json schema v1（001 §3.6 字段名，003 §4.1 schema v1 定版）。
+ * tbox.module.json schema v1（001 §3.6 字段名，003 §4.1 schema v1 定版；v6 声明面翻转）。
  * app-toolkit 单一校验源（自 CLI module-schema.ts 迁入；CLI 经 re-export 消费）。
  *
  * 迁移改造（ai-build C2-5）：
  * - resourceNeedContribSchema 的 type 由 `z.enum(RESOURCE_TYPE_IDS)` 放宽为 `z.string()`——
  *   词汇校验移谓词、经 contracts 动态解析取 RESOURCE_TYPE_IDS（比静态 enum 更忠实应用版本）；
- * - demand meta additive：serviceNeedContribSchema 增 title?/description?（服务展示元数据，
+ * - demand meta additive：serviceConsumeContribSchema 增 name?/description?（服务展示元数据，
  *   manifest demand 侧 additive 扩展，catalog 聚合顺带携带——api.md ServiceDemand 对齐）；
  * - 安全钉子（H9b）：provider 名与 instance id 进凭据 stem 派生，字符集 pattern
  *   `/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/` 为第一道防线（stem 派生处另有断言防线——纵深防御）。
+ *
+ * v6 声明面翻转（integrations v6 所有权模型）：
+ * - `contributes` → `declare`（声明/行为分离——owns/consumes 语义对仗）；
+ * - `declare.services` → `declare.consumes`（无向"服务" → 消费关系，多对多）；
+ * - += `declare.owns`：薄数组（strictObject 单键——互斥事实无元数据；元数据恒在
+ *   consumes 防双数组漂移）。服务归属唯一真源；双 owner = walk OWNERSHIP_CONFLICT；
+ * - 旧键 `contributes` / `declare.services`：parseModuleDescriptor 定向检测（N1——
+ *   报错含三路径升级指引，拒 loose 静默兜底）。
+ *
+ * v7 词汇统一（标识/展示名分轴，对齐实例轴 DeploymentInstance {id, name}）：
+ * - 根键 `name` → `id`（标识键：唯一、寻址）；根键 `title` → `name`（展示名：中文、可选）；
+ * - `declare.consumes[].title` → `name`（demand meta 同步跟随）；
+ * - 旧键 parseModuleDescriptor 定向检测（legacy? 标志——walk 据此拒 loose 兜底、
+ *   CLI sync 据此拒装配改写）。
  */
 
 /** 输入字符集（安全钉子①）：provider 名 / instanceId 恒经此 pattern（进凭据 stem 派生的输入） */
@@ -39,7 +53,7 @@ export const moduleDependencySchema = z.object({
   required: z.boolean().default(true),
 });
 
-/** provider 供给槽声明（integrations v2：contributes.providers.slots 元素；
+/** provider 供给槽声明（integrations v2：declare.providers.slots 元素；
  *  provider = 厂商名（catalog 嵌套第一轴）、implementation = 'id@version'（第二轴）） */
 export const providerSlotContribSchema = z.object({
   service: z.string(),
@@ -51,8 +65,8 @@ export const providerSlotContribSchema = z.object({
   credentialSchema: z.string().optional(),
 });
 
-/** 服务需求槽声明（contributes.services 元素；业务模块声明消费——catalog 需求侧聚合源） */
-export const serviceNeedContribSchema = z.object({
+/** 服务消费槽声明（declare.consumes 元素；业务模块声明消费——catalog 需求侧聚合源） */
+export const serviceConsumeContribSchema = z.object({
   service: z.string(),
   optional: z.boolean().default(true),
   defaults: z
@@ -64,11 +78,19 @@ export const serviceNeedContribSchema = z.object({
     )
     .default([]),
   // demand meta additive（api.md ServiceDemand）：服务展示元数据，缺席 UI 回退 service id
-  title: z.string().optional(),
+  // （v7 词汇统一：title → name）
+  name: z.string().optional(),
   description: z.string().optional(),
 });
 
-/** 资源需求声明（contributes.resources 元素；type 放宽为 string——词汇校验移谓词经 resolver 取词表） */
+/** 服务归属声明（declare.owns 元素；v6 薄形状——互斥事实无元数据，strict 单键防双数组漂移） */
+export const serviceOwnContribSchema = z
+  .object({
+    service: z.string(),
+  })
+  .strict();
+
+/** 资源需求声明（declare.resources 元素；type 放宽为 string——词汇校验移谓词经 resolver 取词表） */
 export const resourceNeedContribSchema = z.object({
   id: z.string(),
   type: z.string(),
@@ -77,7 +99,11 @@ export const resourceNeedContribSchema = z.object({
 export const moduleDescriptorSchema = z
   .object({
     schemaVersion: z.number().default(1),
-    name: z.string(),
+    // v7 词汇统一（标识/展示名分轴）：id = 标识键（唯一、寻址，键 = install id 规约形态）；
+    // name = 展示名（中文、可选）——回退归视图层（name ?? id），schema 不灌值
+    id: z.string(),
+    name: z.string().optional(),
+    description: z.string().optional(),
     version: z.string().default('0.0.0'),
     kind: z.enum(['platform', 'business', 'third-party']).default('business'),
     risk: z
@@ -91,7 +117,7 @@ export const moduleDescriptorSchema = z
         defaultMode: z.enum(['hybrid', 'sdk', 'codegen', 'local']).default('codegen'),
       })
       .default({}),
-    contributes: z
+    declare: z
       .object({
         handlers: z.array(z.string()).default([]),
         tools: z.array(z.string()).default([]),
@@ -104,7 +130,8 @@ export const moduleDescriptorSchema = z
             slots: z.array(providerSlotContribSchema).default([]),
           })
           .default({}),
-        services: z.array(serviceNeedContribSchema).default([]),
+        owns: z.array(serviceOwnContribSchema).default([]),
+        consumes: z.array(serviceConsumeContribSchema).default([]),
         resources: z.array(resourceNeedContribSchema).default([]),
       })
       .default({}),
@@ -120,14 +147,63 @@ export const moduleDescriptorSchema = z
 export type ModuleDescriptor = z.infer<typeof moduleDescriptorSchema>;
 export type CardContrib = z.infer<typeof cardContribSchema>;
 export type ProviderSlotContrib = z.infer<typeof providerSlotContribSchema>;
-export type ServiceNeedContrib = z.infer<typeof serviceNeedContribSchema>;
+export type ServiceConsumeContrib = z.infer<typeof serviceConsumeContribSchema>;
+export type ServiceOwnContrib = z.infer<typeof serviceOwnContribSchema>;
 export type ResourceNeedContrib = z.infer<typeof resourceNeedContribSchema>;
 
 export type ParseModuleResult =
   | { ok: true; value: ModuleDescriptor }
-  | { ok: false; errors: string[] };
+  | { ok: false; errors: string[]; legacy?: true };
+
+/** 旧键检测（N1）：命中 → 定向错误（含三路径升级指引），不走 loose 静默兜底。
+ *  v6 分支：声明面翻转键（contributes / declare.services）；v7 分支：词汇统一翻转键
+ *  （标识 `name`→`id`、展示名 `title`→`name`）。doctor descriptor-schema 规则以错误文本
+ *  「已更名」嗅探透传 OLD_MANIFEST_KEY——新增分支消息必须保持该词。 */
+function legacyManifestKeys(raw: unknown): string[] {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return [];
+  const errors: string[] = [];
+  const obj = raw as Record<string, unknown>;
+  if ('contributes' in obj) {
+    errors.push(
+      '(root): manifest 旧键 `contributes` 已更名 `declare`（v6 声明面）——' +
+        'codegen 副本经 `module update --source` 重新生成 / sdk 模式升级模块包 / 手改两键',
+    );
+  }
+  const declare = obj.declare;
+  if (declare && typeof declare === 'object' && !Array.isArray(declare)
+    && 'services' in (declare as Record<string, unknown>)) {
+    errors.push(
+      'declare: manifest 旧键 `declare.services` 已更名 `declare.consumes`（消费关系定向化）——' +
+        '同上三路径升级',
+    );
+  }
+  // v7 词汇统一（标识/展示名分轴）：`name`→`id`（标识）、`title`→`name`（展示）。
+  // 判据以 `id` 在场性消解同名键歧义：无 id 有 name = v6 旧态；有 id 有 title = 半迁移。
+  if (!('id' in obj) && 'name' in obj) {
+    errors.push(
+      '(root): manifest 标识键 `name` 已更名 `id`（v7 词汇统一）——' +
+        'codegen 副本经 `module update --source` 重新生成 / sdk 模式升级模块包 / 手改两键',
+    );
+  }
+  const declareObj = declare && typeof declare === 'object' && !Array.isArray(declare)
+    ? (declare as Record<string, unknown>)
+    : undefined;
+  const consumeHasTitle = Array.isArray(declareObj?.consumes)
+    && (declareObj.consumes as unknown[]).some(
+      (c) => c !== null && typeof c === 'object' && 'title' in (c as Record<string, unknown>),
+    );
+  if ('title' in obj || consumeHasTitle) {
+    errors.push(
+      '(root): manifest 展示名键 `title` 已更名 `name`（v7 词汇统一；declare.consumes[].title 同步改 name）——'
+        + '同上三路径升级',
+    );
+  }
+  return errors;
+}
 
 export function parseModuleDescriptor(raw: unknown): ParseModuleResult {
+  const legacy = legacyManifestKeys(raw);
+  if (legacy.length > 0) return { ok: false, errors: legacy, legacy: true };
   const result = moduleDescriptorSchema.safeParse(raw);
   if (result.success) return { ok: true, value: result.data };
   return {

package/src/dto.ts

@@ -3,6 +3,11 @@
  * agtcodingbox / tbox-ai-coding 经 `import type` 消费（L2 DTO 单源——API 层零类型镜像）。
  * 词汇七概念：app / module / service / instance / provider / integration / resolution。
  * 弃用词汇清单见 api.md §3 尾（component/slot/scope/configMode/…——防复活）。
+ *
+ * **v7 词汇统一破例声明（一次性收敛，此后恢复 additive-only）**：标识/展示名分轴
+ * （id = 标识、name = 展示名、description = 描述——对齐实例轴 {id, name}），
+ * title 键全量退役（与 manifest name→id/title→name 同一变更）；`.title` 消费方
+ * （外部仓 import type / 运行时读）需同窗迁移。
  */
 
 // ===== 词汇基线 =====
@@ -30,17 +35,16 @@ export interface ModulesView {
 export interface ModuleDeclaration {
   /** install id（packages/ 目录名 / .tbox/app.json entry.id）——恒业务模块（provider 家族不在本清单） */
   id: string;
-  /** 包名 */
+  /** 展示名（v7 词汇统一：manifest name ?? id——恒有值） */
   name: string;
-  title: string;
   description: string;
 }
 
 /** 服务需求声明（模块 demand 单元 / 平台服务条目——v4.4 D29 双端点同型；defaults 唯一落位 ServiceDetail） */
 export interface ServiceDemand {
   service: string;
-  /** manifest demand meta；缺席 UI 回退 service id */
-  title?: string;
+  /** manifest demand meta（v7 title→name）；缺席 UI 回退 service id */
+  name?: string;
   description?: string;
   /** demand optional === false（多模块 OR 聚合见 resolution echo；平台服务条目恒 false） */
   required: boolean;
@@ -50,40 +54,44 @@ export interface ServiceDemand {
 
 /** GET /modules/:module（模块静态一站式 · PUT 读对偶） */
 export interface ModuleDetailView {
-  /** v4.4 D34：demand 服务首段去重（排序；1..N；零域 = []） */
-  domainKeys: string[];
-  /** domains[换算键] 节点原值；未配置 = null；v4.4 D34：仅单域（writable）时在场——多域/零域/共享键无单键落点 */
+  /** 模块展示名（v7 词汇统一：manifest name ?? id——恒有值） */
+  name: string;
+  /** B1 additive：模块 meta 描述（manifest description；兜底 ''） */
+  description: string;
+  /** v6 所有权模型：模块归属服务（declare.owns 展平，排序；零归属 = []）——
+   *  v5 domainKeys 退役（破坏性更名；面板 presence-detection 双读义务见 api.md §3） */
+  ownedServices: string[];
+  /** modules[install id] 集成位原值（provider/config；resources 不投影）；未配置 = null */
   integration: ModuleIntegrationNode | null;
-  /** v4.4 D34：每域一条厂商绑定解析（单域 = 单元素；零域 = []；resolveDomainBinding 单源） */
-  providerBindings: ProviderBinding[];
-  /** v4.4 D34：单域 && 域键无跨模块共享（moduleDomainWritable 单源——读标志与写守卫共用） */
+  /** v6 单数化（v5 providerBindings[] 退役）：模块级厂商绑定解析（resolveModuleBinding 单源；
+   *  单值作用于全部 ownedServices） */
+  binding: ModuleBinding | null;
+  /** v6：owns.length > 0（moduleOwnershipWritable 单源——读标志与写守卫共用） */
   configEditable: boolean;
-  /** 本模块 demand（卡片展开 + 编辑器静态上下文自足） */
+  /** 本模块 demand（declare.consumes；卡片展开 + 编辑器静态上下文自足） */
   services: ServiceDemand[];
   /** v4.4 D31：include=serviceResolutions 内嵌（demand 服务过滤 ≡ 批量 ?service= 语义；<0.9/形态异常 → null——永不 503） */
   serviceResolutions?: ServiceResolutionsView | null;
-  /** v4.4 D32：include=integrationSchemas 层级富化（多域/零域/共享键/未绑定 → null） */
+  /** v4.4 D32：include=integrationSchemas 层级富化（零归属/未绑定 → null） */
   integrationSchemas?: LayerIntegrationSchemas | null;
   /** v4.6 D36：include=integrationFieldRegistry 集成字段注册表（null 语义镜像 integrationSchemas；
    *  未知厂商/零足迹 → 非 null 空集 + unsupplied 回填——D37 轴参假想计算同此） */
   integrationFieldRegistry?: IntegrationFieldRegistryView | null;
 }
 
-/** 模块域厂商绑定解析（v4.4 D34——静态文件事实；规则 ≡ 谓词 #7 域级，resolveDomainBinding 单源） */
-export interface ProviderBinding {
-  /** 域键（= domainKeys 成员；多域模块每域一条） */
-  domain: string;
-  /** domains[domain].provider ?? root.provider（双缺 = null） */
-  effective: string | null;
+/** 模块级厂商绑定解析（v6——静态文件事实；规则 ≡ 谓词 #7 模块层，resolveModuleBinding 单源） */
+export interface ModuleBinding {
+  /** modules[install id].provider ?? root.provider（双缺 = null） */
+  provider: string | null;
   /** 生效来源层（双缺 = null） */
   layer: 'module' | 'app' | null;
 }
 
 /** 层级 config schema 计算（v4.4 D32——静态轴富化，零 contracts） */
 export interface LayerIntegrationSchemas {
-  /** 层生效厂商（resolveDomainBinding 单源） */
+  /** 层生效厂商（resolveModuleBinding 单源） */
   provider: string;
-  /** 模块级 = 本模块 demand ∩ 该厂商供给；应用级 = 供给足迹全量（configSchema = raw draft 2020-12 原文；供给在场未声明 = null） */
+  /** 模块级 = 本模块 ownedServices ∩ 该厂商供给；应用级 = 供给足迹全量（configSchema = raw draft 2020-12 原文；供给在场未声明 = null） */
   services: Record<string, { configSchema: object | null }>;
 }
 
@@ -98,13 +106,16 @@ export interface IntegrationFieldRegistryView {
   unsupplied: string[];
   /** 作用域内全部非 null schema 的 additionalProperties 均 ≠ false（聚合；空真） */
   additionalPropertiesAllowed: boolean;
-  /** 逐 key 合并产物（首声明插入序 = scope 遍历序：app 字母序 / module demand 序） */
+  /** 逐 key 合并产物（首声明插入序 = scope 遍历序：app 字母序 / module ownedServices 序） */
   fields: Array<{
     key: string;
     /** null = 类型不可调和（R3/R2 异构/R1 enum 不等——冲突折叠，客户端 RawJson 保真） */
     schema: object | null;
     /** required 聚合 = sources.some(s => s.required)；conflict 字段照常聚合 */
     sources: Array<{ service: string; required: boolean }>;
+    /** G 批：x-tbox-global 聚合旗标（sources.some——任一来源声明即 true；app/module 轴表单
+     *  仅渲染 true 字段，非全局键落 ExtraFields；service 轴全量透传） */
+    global: boolean;
   }>;
 }
 
@@ -135,12 +146,15 @@ export interface ServiceDetail extends ServiceDemand {
   /** v4.7 D38：include=integrationSchemas 生效绑定富化（三态：null 全链未绑定 /
    *  绑定无可计算 schema / 含 schema；malformed 节点 → null——不放行域级联） */
   integrationSchemas?: ServiceIntegrationSchemas | null;
+  /** G 批：include=integrationFieldRegistry 服务轴注册表（loadServiceFieldRegistry——
+   *  四分支链推导复用 D38；fields = 该 schema 全部字段带 global 旗标；null 语义镜像 D38） */
+  integrationFieldRegistry?: IntegrationFieldRegistryView | null;
 }
 
 /** 服务级生效绑定 schema（v4.7 D38 静态轴富化——零 contracts，永不 503；实例层无条件排除：
  *  node 级口径 ≠ resolution 默认实例口径，api.md §4.4 注） */
 export interface ServiceIntegrationSchemas {
-  /** 生效厂商：显式（含内联声明名）?? domains[首段].provider ?? root.provider */
+  /** 生效厂商：显式（含内联声明名）?? modules[ownerOf].provider ?? root.provider */
   provider: string;
   /** catalog 复合键（多 impl 声明序首个）> 内联 ref；miss（未知厂商/未供给/内联缺 ref）→ null（富化非门控） */
   configSchema: object | null;
@@ -207,8 +221,8 @@ export interface AppIntegrationNode {
 }
 
 /** AppIntegrationNode 键集单源（runtime const——write applyApp 全量替换白名单
- *  （缺席根键删除；services/domains/modules 域不在其中）+ views/app 投影（GET 预填 ≡ PUT body，
- *  D21/L1——文件含 services/domains 但 root 节点投影只含本键集）） */
+ *  （缺席根键删除；services/modules 域不在其中；v6 domains 键退役）+ views/app 投影
+ *  （GET 预填 ≡ PUT body，D21/L1——文件含 services/modules 但 root 节点投影只含本键集）） */
 export const APP_INTEGRATION_NODE_KEYS = [
   'provider',
   'config',
@@ -219,12 +233,17 @@ export const APP_INTEGRATION_NODE_KEYS = [
   'defaultInstanceId',
 ] as const;
 
-/** 模块域节点（恒字符串 provider——域层无凭据位，契约事实） */
+/** 模块集成位节点（v6——provider 绑定默认 + config 级联层；resources 不投影不写——
+ *  集成位编辑恒保全资源节，N2） */
 export interface ModuleIntegrationNode {
   provider?: string;
   config?: Record<string, unknown>;
 }
 
+/** ModuleIntegrationNode 可写键集单源（v6——write applyModule 全量替换白名单
+ *  （键集外 400；resources 恒随既有节点保全）+ views/modules 投影（GET ≡ PUT，三同构）） */
+export const MODULE_INTEGRATION_NODE_KEYS = ['provider', 'config'] as const;
+
 /** services[s] 整节点 */
 export interface ServiceIntegrationNode {
   /** 对象 = 自定义 API（仅槽级，P2） */
@@ -287,6 +306,9 @@ export interface ProviderEntry {
   local: boolean;
   /** 供给声明来源包名 */
   owner: string;
+  /** 厂商展示名（v7 title→name：manifest name——多包首声明；缺席 = undefined） */
+  name?: string;
+  description?: string;
 }
 
 /** GET /providers/:provider：供给足迹 */
@@ -294,12 +316,18 @@ export interface ProviderDetail {
   provider: string;
   local: boolean;
   owner: string;
+  /** 厂商展示名（同 ProviderEntry——首声明透传） */
+  name?: string;
+  description?: string;
   /** per (provider, service) 保真，同厂商异构合法；★ implementations 恒数组（H1——
    *  多元素 = 升级窗口，UI 出 impl 选择器，PUT 显式钉版） */
   services: Record<
     string,
     {
       implementations: Array<{ implementation: string; credentialType: string }>;
+      /** 服务展示名（resolveServiceDisplay——词汇 > demand > id；恒发） */
+      name?: string;
+      description?: string;
       /** v4.4 F5：include=integrationSchemas 切换态批量（纯 config——凭据结构归 /credential-types） */
       integrationSchemas?: { configSchema: object | null };
     }

package/src/factory.ts

@@ -19,9 +19,10 @@ import { loadModulesView, loadModuleDetailView } from './views/modules.js';
 import { loadAppView } from './views/app.js';
 import { loadServiceDetailView } from './views/service-detail.js';
 import { loadServiceResolutionsView, loadServiceResolutionDetail } from './views/service-resolutions.js';
-import { loadAppFormViews, loadModuleFormViews, loadServiceIntegrationSchemas } from './views/integration-schemas.js';
+import { loadAppFormViews, loadModuleFormViews, loadServiceIntegrationSchemas, loadServiceFieldRegistry } from './views/integration-schemas.js';
 import { loadCredentialsView } from './views/credentials.js';
 import { loadCredentialTypesView } from './views/credential-types.js';
+import { resolveModuleKey, resolveServiceKey } from './assembly/resolve-key.js';
 import type { WalkManifestsResult } from './assembly/walk-manifests.js';
 import type {
   AppIntegrationNode,
@@ -67,12 +68,13 @@ export interface AppToolkitOptions {
 
 /** include 协议白名单（v4.4 D30/P15——键名 = 产出字段名 1:1；per 端点；注册表 additive-only；
  *  v4.6 D36 += integrationFieldRegistry：app/module 三键，provider 轴不加——YAGNI；
- *  v4.7 D38 += service 键——服务级生效绑定 schema） */
+ *  v4.7 D38 += service 键——服务级生效绑定 schema；
+ *  G 批 += service 轴 integrationFieldRegistry——服务轴注册表（x-tbox-global 旗标全量透传）） */
 const INCLUDE_WHITELIST = {
   app: ['serviceResolutions', 'integrationSchemas', 'integrationFieldRegistry'],
   module: ['serviceResolutions', 'integrationSchemas', 'integrationFieldRegistry'],
   provider: ['integrationSchemas'],
-  service: ['integrationSchemas'],
+  service: ['integrationSchemas', 'integrationFieldRegistry'],
 } as const;
 
 /** include 校验（P15 单点在 toolkit 方法内——壳层仅解析可重复参数，零校验纪律不变）：
@@ -113,10 +115,13 @@ function assertAxisProviderUsable(
   }
 }
 
-/** ── HTTP 直通面（11 读；L1 镜像律：方法名 = load + URL 资源段；query → 选项字段 L4）── */
+/** ── HTTP 直通面（11 读；L1 镜像律：方法名 = load + URL 资源段；query → 选项字段 L4）──
+ *  **双键契约（v7 词汇统一）**：资源路径参数双键寻址（id 优先、唯一展示名兜底——resolve-key
+ *  单点；多命中 404 带候选）；query 过滤参数（loadServiceResolutions services?）恒 id-only。 */
 export interface AppToolkitRead {
   loadModules(): Promise<ModulesView>;
-  /** v4.6 D37：moduleProvider = 轴向假想绑定（缺席/空串 ≡ 按实际配置解析；需与表单 include 键同现） */
+  /** v4.6 D37：moduleProvider = 轴向假想绑定（缺席/空串 ≡ 按实际配置解析；需与表单 include 键同现）。
+   *  moduleId = 双键（id 优先、唯一展示名兜底）。 */
   loadModule(moduleId: string, o?: { include?: string[]; moduleProvider?: string }): Promise<ModuleDetailView>;
   /** v4.6 D37：appProvider = 轴向假想绑定（缺席/空串 ≡ 按实际配置解析；需与表单 include 键同现） */
   loadApp(o?: { include?: string[]; appProvider?: string }): Promise<AppView>;
@@ -132,7 +137,8 @@ export interface AppToolkitRead {
   loadCredentialTypes(provider?: string): Promise<CredentialTypesView>;
 }
 
-/** ── HTTP 直通面（4 写；body ≡ 文件节点全量替换；DELETE 无 dryRun/无 options）── */
+/** ── HTTP 直通面（4 写；body ≡ 文件节点全量替换；DELETE 无 dryRun/无 options）──
+ *  双键契约（v7）：路径键双键寻址（写侧 enqueue 闭包内解析——落盘键恒真实 id）。 */
 export interface AppToolkitWrite {
   writeAppIntegration(
     node: AppIntegrationNode,
@@ -174,11 +180,20 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
 
   const viewCtx = { appDir, cache };
 
-  /** 门控断言（policy at edge）——strictValidation false → 503（message 三分支 N1） */
+  /** 门控断言（policy at edge）——strictValidation false → 503（message 三分支 N1）；
+   *  v6 标记门（P1）：ownershipBindingV6 false → 503 第四分支（v5 contracts + v6 toolkit 偏斜
+   *  ——防静默忽略 ownerOf；门控范围 = 求值 + 写 + migrate 全体，本函数为唯一调用点）。 */
   function assertContractsUsable(contracts: ResolvedContracts): void {
     if (!contracts.strictValidation) {
       throw new AppToolkitError('CONTRACTS_NOT_RESOLVED', 503, contractsNotResolvedMessage(contracts));
     }
+    if (!contracts.ownershipBindingV6) {
+      throw new AppToolkitError(
+        'CONTRACTS_NOT_RESOLVED',
+        503,
+        `contracts ${contracts.version ?? '(版本未知)'} 不支持 v6 modules 绑定形状（OWNERSHIP_BINDING_V6 标记缺席）——升级应用 @tbox.cn/app-contracts 依赖后可用`,
+      );
+    }
   }
 
   /** 快照（同步——调用方已 await resolveContracts） */
@@ -186,6 +201,12 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
     return loadViewSnapshotSync(viewCtx, contracts);
   }
 
+  /** 服务双键解析的已配置键集（integrations services 节键——宽松形态防御式提取） */
+  function configuredServiceKeys(snap: ReturnType<typeof snapshot>): string[] {
+    const services = (snap.integrations as { services?: Record<string, unknown> } | null)?.services;
+    return services && typeof services === 'object' ? Object.keys(services) : [];
+  }
+
   /** 谓词全量 issues（求值轴/写后复查共用——contracts 注入 + buildPredicateAssembly 单源装配，FX-2b：
    *  与 CLI doctor 规则同装配面——「面板 issues ≡ doctor issues」机制保证） */
   async function predicateIssues(): Promise<IntegrationServiceIssue[]> {
@@ -196,7 +217,6 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
     const predicateContracts: PredicateContracts = {
       resolveEffectiveService: assertFn(contracts.module.resolveEffectiveService, 'resolveEffectiveService'),
       buildSupplyLookup: assertFn(contracts.module.buildSupplyLookup, 'buildSupplyLookup'),
-      moduleDomainOf: assertFn(contracts.module.moduleDomainOf, 'moduleDomainOf'),
       normalizeInstances: assertFn(contracts.module.normalizeInstances, 'normalizeInstances'),
       RESOURCE_TYPE_IDS: (contracts.module.RESOURCE_TYPE_IDS ?? []) as readonly string[],
     };
@@ -234,7 +254,9 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
       assertAxisProviderUsable('moduleProvider', o?.moduleProvider, include); // ①' D37 轴参严检（先于 404）
       const contracts = await resolveContractsForApp(appDir);
       const snap = snapshot(contracts);
-      const view = loadModuleDetailView(snap, moduleId); // ② MODULE_NOT_FOUND
+      // ② 双键寻址（v7 词汇统一）：路径参数 id 优先、唯一展示名兜底 → 真实 id（404 面）
+      const mod = resolveModuleKey(snap.walk, moduleId);
+      const view = loadModuleDetailView(snap, mod.id);
       if (include.has('serviceResolutions')) {
         view.serviceResolutions = contracts.evaluation && contracts.strictValidation
           ? await predicateIssues().then((issues) =>
@@ -243,7 +265,7 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
       }
       if (include.has('integrationSchemas') || include.has('integrationFieldRegistry')) {
         // v4.6 D37：表单层双投影同源一次计算（双取单算 + I1——假想重定向天然同步）
-        const form = loadModuleFormViews(snap, moduleId, o?.moduleProvider);
+        const form = loadModuleFormViews(snap, mod.id, o?.moduleProvider);
         if (include.has('integrationSchemas')) view.integrationSchemas = form.integrationSchemas;
         if (include.has('integrationFieldRegistry')) view.integrationFieldRegistry = form.integrationFieldRegistry;
       }
@@ -268,13 +290,19 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
       return view;
     },
     // v4.7 D38：include 镜像 loadModule 三段式——① 输入校验 400 先于 404 ② 视图 ③ 静态富化（永不 503）
+    // G 批：service 轴 += integrationFieldRegistry（loadServiceFieldRegistry——D38 四分支链复用）
     async loadService(service: string, o?: { include?: string[] }): Promise<ServiceDetail> {
       const include = validateInclude('service', o?.include);
       const contracts = await resolveContractsForApp(appDir);
       const snap = snapshot(contracts); // 单快照——detail 与 include 装配共享
-      const view = loadServiceDetailView(snap, service);
+      // 双键寻址（v7）：id 优先、唯一展示名兜底 → 真实 service id（404 面）
+      const serviceId = resolveServiceKey(snap.walk, configuredServiceKeys(snap), service);
+      const view = loadServiceDetailView(snap, serviceId);
       if (include.has('integrationSchemas')) {
-        view.integrationSchemas = loadServiceIntegrationSchemas(snap, service);
+        view.integrationSchemas = loadServiceIntegrationSchemas(snap, serviceId);
+      }
+      if (include.has('integrationFieldRegistry')) {
+        view.integrationFieldRegistry = loadServiceFieldRegistry(snap, serviceId);
       }
       return view;
     },
@@ -287,8 +315,10 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
     async loadServiceResolution(service: string) {
       const contracts = await resolveContractsForApp(appDir);
       assertContractsUsable(contracts);
+      const snap = snapshot(contracts);
+      const serviceId = resolveServiceKey(snap.walk, configuredServiceKeys(snap), service);
       const issues = await predicateIssues();
-      return loadServiceResolutionDetail(service, snapshot(contracts), issues);
+      return loadServiceResolutionDetail(serviceId, snap, issues);
     },
     async loadProviders() {
       const contracts = await resolveContractsForApp(appDir);
@@ -301,7 +331,10 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
     },
     async loadProviderService(provider: string, service: string) {
       const contracts = await resolveContractsForApp(appDir);
-      return loadProviderServiceDetailView(snapshot(contracts), provider, service);
+      const snap = snapshot(contracts);
+      // 服务轴双键寻址（provider 轴不兜底——厂商键即词汇）
+      const serviceId = resolveServiceKey(snap.walk, configuredServiceKeys(snap), service);
+      return loadProviderServiceDetailView(snap, provider, serviceId);
     },
     // v4.4 D33：凭据域双端点（应用状态轴 / 供给轴静态——零门控零求值，永不 503）
     async loadCredentials(): Promise<CredentialsView> {
@@ -330,19 +363,31 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
       await core.warmup();
       const contracts = await resolveContractsForApp(appDir);
       assertContractsUsable(contracts);
-      return enqueue(() => core.applyModule(moduleId, node as Record<string, unknown>, o));
+      // enqueue 闭包内双键解析（写时新鲜度）——落盘键恒真实 id
+      return enqueue(() => {
+        const mod = resolveModuleKey(snapshot(contracts).walk, moduleId);
+        return core.applyModule(mod.id, node as Record<string, unknown>, o);
+      });
     },
     async writeServiceIntegration(service: string, node: ServiceIntegrationNode, o?: WriteOptions) {
       await core.warmup();
       const contracts = await resolveContractsForApp(appDir);
       assertContractsUsable(contracts);
-      return enqueue(() => core.applyService(service, node as Record<string, unknown>, o));
+      return enqueue(() => {
+        const snap = snapshot(contracts);
+        const serviceId = resolveServiceKey(snap.walk, configuredServiceKeys(snap), service);
+        return core.applyService(serviceId, node as Record<string, unknown>, o);
+      });
     },
     async deleteServiceIntegration(service: string) {
       await core.warmup();
       const contracts = await resolveContractsForApp(appDir);
       assertContractsUsable(contracts);
-      return enqueue(() => core.deleteService(service));
+      return enqueue(() => {
+        const snap = snapshot(contracts);
+        const serviceId = resolveServiceKey(snap.walk, configuredServiceKeys(snap), service);
+        return core.deleteService(serviceId);
+      });
     },
   };
 
@@ -385,7 +430,6 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
       const predicateContracts: PredicateContracts = {
         resolveEffectiveService: assertFn(contracts.module.resolveEffectiveService, 'resolveEffectiveService'),
         buildSupplyLookup: assertFn(contracts.module.buildSupplyLookup, 'buildSupplyLookup'),
-        moduleDomainOf: assertFn(contracts.module.moduleDomainOf, 'moduleDomainOf'),
         normalizeInstances: assertFn(contracts.module.normalizeInstances, 'normalizeInstances'),
         RESOURCE_TYPE_IDS: (contracts.module.RESOURCE_TYPE_IDS ?? []) as readonly string[],
       };

package/src/index.ts

@@ -10,14 +10,16 @@ export {
   tabContribSchema,
   moduleDependencySchema,
   providerSlotContribSchema,
-  serviceNeedContribSchema,
+  serviceConsumeContribSchema,
+  serviceOwnContribSchema,
   resourceNeedContribSchema,
 } from './core/module-schema.js';
 export type {
   ModuleDescriptor,
   CardContrib,
   ProviderSlotContrib,
-  ServiceNeedContrib,
+  ServiceConsumeContrib,
+  ServiceOwnContrib,
   ResourceNeedContrib,
   ParseModuleResult,
 } from './core/module-schema.js';
@@ -56,16 +58,22 @@ export type {
 // ── 谓词装配单源（FX-2b/F1：CLI doctor 规则与 toolkit 工厂同装配面——双通道 walkManifests）──
 export { buildPredicateAssembly, refToEnvKey } from './integrations/predicate-io.js';
 export type { PredicateAssembly, PredicateIoInputs } from './integrations/predicate-io.js';
+// ── 应用级求值单源（cli-remove-prune-and-new：doctor integration-services 与 prune 同一求值）──
+export { evaluateAppIntegrationIssues } from './integrations/evaluate-app.js';
+export { pruneIntegrationBindings } from './integrations/prune-bindings.js';
+export type { PruneResult } from './integrations/prune-bindings.js';
 
 // ── assembly 层（目录知识——walkManifests 四产物 + catalog 双形态 + 组合单体装配）──
 export { walkManifests } from './assembly/walk-manifests.js';
-export type { WalkManifestsResult, WalkModuleInfo, WalkCatalog, WalkProviderEntry } from './assembly/walk-manifests.js';
+// 双键寻址（v7 词汇统一——factory 七方法入口单点消费的解析 helper；纯参数式零 IO）
+export { resolveModuleKey, resolveServiceKey } from './assembly/resolve-key.js';
+export type { WalkManifestsResult, WalkModuleInfo, WalkCatalog, WalkProviderEntry, DeclarationIssue, SlotMeta } from './assembly/walk-manifests.js';
 export { readAppManifest, writeAppManifest, manifestPath } from './assembly/app-manifest.js';
 export type { AppManifest, NpmModuleEntry, ModuleMode } from './assembly/app-manifest.js';
 export { loadProviderCatalog, loadProviderCatalogRaw } from './assembly/provider-catalog.js';
 export type { BridgeProviderCatalog, ProviderServiceSchemas, ProviderServiceSchemasResult } from './assembly/provider-catalog.js';
 
-// ── integrations 层（领域——读/写核心/凭据双工件/mock 绑定）──
+// ── integrations 层（领域——读/写核心/凭据双工件/mock 绑定；v6 模块绑定单源）──
 export { readIntegrationsConfig, readIntegrationsStrict } from './integrations/read.js';
 export type { ReadIntegrationsResult } from './integrations/read.js';
 export { createWriteCore, deepEqual } from './integrations/write.js';
@@ -74,6 +82,9 @@ export { ensureMockBindings } from './integrations/mock-bindings.js';
 export type { MockBindingsResult } from './integrations/mock-bindings.js';
 export { reconcileOrphanCredentials, credentialArtifactExists } from './integrations/credentials.js';
 export type { AppliedCredential, CredentialInput, OrphanIssue, PlannedCredential } from './integrations/credentials.js';
+// v6 所有权模型单源（module-binding——resolveModuleBinding/写守卫/归属表直通）
+export { buildOwnershipMap, moduleOwnershipWritable, resolveModuleBinding, providerFootprint } from './integrations/module-binding.js';
+export type { ModuleOwnershipWritability } from './integrations/module-binding.js';
 
 // ── 错误面（领域 6 码——AppToolkitError；name 字面量约定见 errors.ts）──
 export { AppToolkitError, contractsNotResolvedMessage } from './core/errors.js';
@@ -85,7 +96,7 @@ export { loadAppView } from './views/app.js';
 export { loadServiceDetailView } from './views/service-detail.js';
 export { loadProvidersView, loadProviderDetailView, loadProviderServiceDetailView } from './views/providers.js';
 export { loadServiceResolutionsView, loadServiceResolutionDetail, resolveServiceSummary } from './views/service-resolutions.js';
-export { loadAppIntegrationSchemas, loadModuleIntegrationSchemas, loadServiceIntegrationSchemas, resolveLayerIntegrationSchemas } from './views/integration-schemas.js';
+export { loadAppIntegrationSchemas, loadModuleIntegrationSchemas, loadServiceIntegrationSchemas, loadServiceFieldRegistry, resolveLayerIntegrationSchemas, formProviderOf, buildIntegrationFieldRegistry } from './views/integration-schemas.js';
 export { echoForRef, loadCredentialsView } from './views/credentials.js';
 export { loadCredentialTypesView } from './views/credential-types.js';
 export type { ViewContext, ViewSnapshot } from './views/context.js';
@@ -102,10 +113,10 @@ export type {
   ModuleDeclaration,
   ServiceDemand,
   ModuleDetailView,
+  ModuleBinding,
   AppView,
   ServiceDetail,
   ServiceIntegrationSchemas,
-  ProviderBinding,
   LayerIntegrationSchemas,
   IntegrationFieldRegistryView,
   CredentialsView,
@@ -132,7 +143,7 @@ export type {
   ContractsResolution,
   IntegrationIssue,
 } from './dto.js';
-export { APP_INTEGRATION_NODE_KEYS } from './dto.js';
+export { APP_INTEGRATION_NODE_KEYS, MODULE_INTEGRATION_NODE_KEYS } from './dto.js';
 export {
   readAppManifestFull,
   upsertNpmModule,