@tbox.cn/app-toolkit 0.4.0 → 0.6.0

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,19 @@ 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;
+  /** 隐藏模块（additive——manifest hidden === true 时携带；默认清单已过滤，本字段仅供
+   *  ?includeHidden=true 可见时徽标呈现） */
+  hidden?: boolean;
 }
 
 /** 服务需求声明（模块 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,44 +57,50 @@ export interface ServiceDemand {
 
 /** GET /modules/:module（模块静态一站式 · PUT 读对偶） */
 export interface ModuleDetailView {
-  /** B1 additive：模块 meta 展示名（manifest title；视图层兜底 name——恒有值） */
-  title: string;
+  /** 模块展示名（v7 词汇统一：manifest name ?? id——恒有值） */
+  name: string;
   /** B1 additive：模块 meta 描述（manifest description；兜底 ''） */
   description: string;
-  /** v4.4 D34：demand 服务首段去重（排序；1..N；零域 = []） */
-  domainKeys: string[];
-  /** domains[换算键] 节点原值；未配置 = null；v4.4 D34：仅单域（writable）时在场——多域/零域/共享键无单键落点 */
+  /** 隐藏模块（additive——manifest hidden === true 时携带；详情恒 200 不受清单过滤影响，
+   *  本字段仅供面板徽标呈现） */
+  hidden?: boolean;
+  /** v6 所有权模型：模块归属服务（declare.owns 展平，排序；零归属 = []）——
+   *  v5 domainKeys 退役（破坏性更名；面板 presence-detection 双读义务见 api.md §3） */
+  ownedServices: string[];
+  /** modules[install id] 集成位原值（provider/config；resources 不投影——见 resources 字段）；未配置 = null */
   integration: ModuleIntegrationNode | null;
-  /** v4.4 D34：每域一条厂商绑定解析（单域 = 单元素；零域 = []；resolveDomainBinding 单源） */
-  providerBindings: ProviderBinding[];
-  /** v4.4 D34：单域 && 域键无跨模块共享（moduleDomainWritable 单源——读标志与写守卫共用） */
+  /** 模块资源只读镜像（N2 读半边——写侧 resources 恒保全；含 ref 台账展开态 resolvedDatasetId）；
+   *  无模块键/无资源节 = null */
+  resources?: ModuleResourcesEcho | null;
+  /** 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 }>;
 }
 
@@ -102,13 +115,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;
   }>;
 }
 
@@ -139,12 +155,18 @@ 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。
+   *  v5.1 D39：serviceProvider 轴参 = 假想重定向——仅表单投影按 X 计算，带非空轴参时
+   *  registry 恒非 null（豁免链③不镜像实际态 null）；同构 ≡ PUT 改写 provider 后实读） */
+  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；
+   *  v5.1 D39：serviceProvider 轴参在场时 = 假想短路值（非链解析产物） */
   provider: string;
   /** catalog 复合键（多 impl 声明序首个）> 内联 ref；miss（未知厂商/未供给/内联缺 ref）→ null（富化非门控） */
   configSchema: object | null;
@@ -211,8 +233,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',
@@ -223,12 +245,37 @@ 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;
+
+/** 模块资源回显（只读投影——N2 读半边：写侧仍仅 provider/config，resources 恒保全）。
+ *  原值文件镜像（L1）+ ref 台账展开态：`ref` 在场且同目录 knowledge.json 命中时
+ *  `resolvedDatasetId` = 台账 datasetId（镜像 SDK resolveKnowledge 展开语义），未命中/台账缺失 = null。
+ *  路径锚定边界：视图恒读 `<appDir>/config/`（与 toolkit readIntegrationsConfig 同源——
+ *  `TBOX_INTEGRATIONS_FILE` 为 SDK 运行时逃生舱，视图不跟随，既有分叉）。 */
+export interface ModuleResourceEcho {
+  type: 'knowledge';
+  /** 文件原值直填 datasetId（与 ref 互斥使用——并存时 SDK 侧 datasetId 优先） */
+  datasetId?: string;
+  /** 文件原值 ref（台账引用——knowledge.json knowledge_bases 键） */
+  ref?: string;
+  /** 展开态：datasetId 直填时 = 该值；ref 命中台账 = 台账 datasetId；ref 未命中/台账缺失 = null */
+  resolvedDatasetId: string | null;
+  topK?: number;
+  scoreThreshold?: number;
+}
+
+/** modules[install id].resources 只读镜像（键 = 资源 id；无模块键/无资源 = null） */
+export type ModuleResourcesEcho = Record<string, ModuleResourceEcho>;
+
 /** services[s] 整节点 */
 export interface ServiceIntegrationNode {
   /** 对象 = 自定义 API（仅槽级，P2） */
@@ -291,8 +338,8 @@ export interface ProviderEntry {
   local: boolean;
   /** 供给声明来源包名 */
   owner: string;
-  /** B1 additive：厂商展示名（manifest 模块 meta——多包首声明；缺席 = undefined） */
-  title?: string;
+  /** 厂商展示名（v7 title→name：manifest name——多包首声明；缺席 = undefined） */
+  name?: string;
   description?: string;
 }
 
@@ -301,8 +348,8 @@ export interface ProviderDetail {
   provider: string;
   local: boolean;
   owner: string;
-  /** B1 additive：厂商展示名（同 ProviderEntry——首声明透传） */
-  title?: string;
+  /** 厂商展示名（同 ProviderEntry——首声明透传） */
+  name?: string;
   description?: string;
   /** per (provider, service) 保真，同厂商异构合法；★ implementations 恒数组（H1——
    *  多元素 = 升级窗口，UI 出 impl 选择器，PUT 显式钉版） */
@@ -310,8 +357,8 @@ export interface ProviderDetail {
     string,
     {
       implementations: Array<{ implementation: string; credentialType: string }>;
-      /** B1 additive：服务展示名（resolveServiceDisplay——词汇 > demand > id；恒发） */
-      title?: 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,
@@ -44,7 +45,8 @@ import type {
  * createAppToolkit（C4 工厂；v4.4——24 方法 = 11 读（含 credentials/credential-types 双端点）
  * + 4 写 + 9 迁移面；loadApp/loadModule/loadProvider 增 include 选项；v4.6——loadApp/loadModule
  * += 轴向假想绑定选项（appProvider/moduleProvider，D37）；表单双投影经 formViews 单点装配；
- * v4.7——loadService 增 include 选项（服务级生效绑定 schema 单体））。
+ * v4.7——loadService 增 include 选项（服务级生效绑定 schema 单体）；v5.1 D39——loadService
+ * += serviceProvider 轴参（服务轴向假想绑定，三轴收口））。
  * AppToolkit = AppToolkitRead & AppToolkitWrite & AppToolkitInternals——
  * Read+Write = HTTP 直通面 additive 冻结（L1 端点↔方法 1:1，L3 命名镜像：Integration=节点级 /
  * Config=文件级）；Internals = CLI/doctor/桥消费（自由演进）。
@@ -67,12 +69,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 方法内——壳层仅解析可重复参数，零校验纪律不变）：
@@ -96,9 +99,10 @@ function validateInclude(kind: keyof typeof INCLUDE_WHITELIST, include?: string[
 const FORM_INCLUDE_KEYS = ['integrationSchemas', 'integrationFieldRegistry'] as const;
 
 /** v4.6 D37 轴参严检（400 先于 404——镜像输入校验先行）：非空轴参需与表单 include 键同现；
- *  缺席/空串 ≡ 按实际配置解析（I3——不触发严检）；错轴参数由壳层按名读取，天然静默忽略。 */
+ *  缺席/空串 ≡ 按实际配置解析（I3——不触发严检）；错轴参数由壳层按名读取，天然静默忽略。
+ *  v5.1 D39：联合类型 += serviceProvider（service 轴同律）。 */
 function assertAxisProviderUsable(
-  paramName: 'appProvider' | 'moduleProvider',
+  paramName: 'appProvider' | 'moduleProvider' | 'serviceProvider',
   value: string | undefined,
   include: ReadonlySet<string>,
 ): void {
@@ -113,14 +117,20 @@ 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 键同现） */
+  /** GET /modules：hidden 模块默认过滤（includeHidden = true 可见——对齐 ?dryRun 布尔参数先例） */
+  loadModules(o?: { includeHidden?: boolean }): Promise<ModulesView>;
+  /** 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>;
-  loadService(service: string, o?: { include?: string[] }): Promise<ServiceDetail>;
+  /** v5.1 D39：serviceProvider = 服务轴向假想绑定（缺席/空串 ≡ 按实际配置解析；需与表单 include
+   *  键同现）——假想重定向仅表单双投影，integration/suppliedBy/defaults 恒实际态（I2） */
+  loadService(service: string, o?: { include?: string[]; serviceProvider?: string }): Promise<ServiceDetail>;
   loadServiceResolutions(services?: string[]): Promise<ServiceResolutionsView>;
   loadServiceResolution(service: string): Promise<ServiceResolutionDetail>;
   loadProviders(): Promise<ProvidersView>;
@@ -132,7 +142,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 +185,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 +206,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 +222,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[],
     };
@@ -222,9 +247,9 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
   }
 
   const read = {
-    async loadModules() {
+    async loadModules(o?: { includeHidden?: boolean }) {
       const contracts = await resolveContractsForApp(appDir);
-      return loadModulesView(snapshot(contracts));
+      return loadModulesView(snapshot(contracts), o);
     },
     // v4.4 D31：门控与内嵌分离——静态方法零门控分支；include=serviceResolutions 按
     // evaluation && strictValidation 双条件装配（<0.9/形态异常 → null，永不 503——技术方案 §2.4：
@@ -234,7 +259,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 +270,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 +295,22 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
       return view;
     },
     // v4.7 D38：include 镜像 loadModule 三段式——① 输入校验 400 先于 404 ② 视图 ③ 静态富化（永不 503）
-    async loadService(service: string, o?: { include?: string[] }): Promise<ServiceDetail> {
+    // G 批：service 轴 += integrationFieldRegistry（loadServiceFieldRegistry——D38 四分支链复用）
+    // v5.1 D39：loadService += serviceProvider 轴参（三段式序对齐 loadModule——①' 严检先于 resolveContracts，
+    //   即先于 404 也先于 503；I1 双投影同源一次计算经单源链透传）
+    async loadService(service: string, o?: { include?: string[]; serviceProvider?: string }): Promise<ServiceDetail> {
       const include = validateInclude('service', o?.include);
+      assertAxisProviderUsable('serviceProvider', o?.serviceProvider, include); // ①' D39 轴参严检（先于 404）
       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, o?.serviceProvider);
+      }
+      if (include.has('integrationFieldRegistry')) {
+        view.integrationFieldRegistry = loadServiceFieldRegistry(snap, serviceId, o?.serviceProvider);
       }
       return view;
     },
@@ -287,8 +323,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 +339,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 +371,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 +438,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';
@@ -63,13 +65,15 @@ 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';
@@ -78,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';
@@ -89,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';
@@ -106,10 +113,10 @@ export type {
   ModuleDeclaration,
   ServiceDemand,
   ModuleDetailView,
+  ModuleBinding,
   AppView,
   ServiceDetail,
   ServiceIntegrationSchemas,
-  ProviderBinding,
   LayerIntegrationSchemas,
   IntegrationFieldRegistryView,
   CredentialsView,
@@ -122,6 +129,8 @@ export type {
   ServiceResolutionDetail,
   AppIntegrationNode,
   ModuleIntegrationNode,
+  ModuleResourceEcho,
+  ModuleResourcesEcho,
   ServiceIntegrationNode,
   ServiceInstanceNode,
   InlineVendorDeclaration,
@@ -136,7 +145,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,

package/src/integrations/mock-bindings.ts

@@ -29,7 +29,7 @@ export function ensureMockBindings(appDir: string): MockBindingsResult {
   }
   const slots: Array<{ service: string; provider: string; implementation: string }> = [];
   for (const mod of walkManifests(appDir).modules) {
-    for (const slot of mod.descriptor.contributes.providers?.slots ?? []) {
+    for (const slot of mod.descriptor.declare.providers?.slots ?? []) {
       if (slot.local !== true) continue;
       slots.push({ service: slot.service, provider: slot.provider, implementation: slot.implementation });
     }

package/src/integrations/module-binding.ts

@@ -0,0 +1,60 @@
+import { walkManifests, type WalkCatalog, type WalkManifestsResult, type WalkModuleInfo } from '../assembly/walk-manifests.js';
+
+/**
+ * 模块级联绑定单源（integrations v6 所有权模型——原 domain-binding.ts v4.4 F1/F3 重写）。
+ * integrations 层落位依据：谓词（同层）/ 写核（同层）/ views（下层可向上 import）三向消费
+ * 的唯一公共下层；import 前缀 guard 覆盖。
+ *
+ * 知识锚（module-tab note 单源锚表，v6 形态）：
+ *   模块级联（值 + 层） = resolveModuleBinding —— 谓词 #7（per-module 生效厂商 ≡
+ *                        `modules[m].provider ?? root.provider`）/ deriveBindingLayer 模块级段 /
+ *                        buildInheritance module 段 / binding（单数）
+ *   归属表             = walk.ownership（单源聚合产物；buildOwnershipMap 桥直通——
+ *                        registry 显式参 / 谓词 / 写守卫 / views 四消费方零第二实现）
+ *   来源层四层推导     = deriveBindingLayer（views/service-resolutions，模块级段改调本文件）
+ *   写通道可用性       = moduleOwnershipWritable —— configEditable 读标志 / applyModule 400 守卫
+ *                        共用（owns>0 唯一判据——多域归属合法化、共享键/多域判据随 D34 退役）
+ */
+
+/** 归属表构建（walk 单源直通——sdk 桥 re-export 消费；appDir 直入对齐 loadProviderCatalog
+ *  桥工效——模板装配第六行：`ownerOf: buildOwnershipMap(appDir)`）。 */
+export function buildOwnershipMap(appDir: string): Record<string, string> {
+  return walkManifests(appDir).ownership;
+}
+
+/** 模块级联绑定解析（值 + 来源层）：provider 取非空字符串（模块级优先 → root 兜底；空串 = 缺席）。
+ *  layer：modules[moduleId].provider 声明 → 'module'；root 兜底 → 'app'；双缺 → null（binding 双缺诚实态）。 */
+export function resolveModuleBinding(
+  config: Record<string, unknown> | null,
+  moduleId: string,
+): { provider: string | null; layer: 'module' | 'app' | null } {
+  const moduleProvider = (config?.modules as Record<string, { provider?: unknown }> | undefined)?.[moduleId]?.provider;
+  if (typeof moduleProvider === 'string' && moduleProvider.length > 0) {
+    return { provider: moduleProvider, layer: 'module' };
+  }
+  const rootProvider = config?.provider;
+  if (typeof rootProvider === 'string' && rootProvider.length > 0) {
+    return { provider: rootProvider, layer: 'app' };
+  }
+  return { provider: null, layer: null };
+}
+
+/** 模块集成位可写性（v6 判别联合——configEditable 读标志与 applyModule 写守卫共用单源）：
+ *  owns>0 唯一判据（D34 多域/shared-key 判据随 v6 退役——服务归属唯一真源 = declare.owns）。 */
+export type ModuleOwnershipWritability =
+  | { writable: true; ownedServices: string[] }
+  | { writable: false; reason: 'zero-ownership'; ownedServices: [] };
+
+export function moduleOwnershipWritable(
+  _walk: Pick<WalkManifestsResult, 'modules' | 'catalog' | 'ownership'>,
+  mod: WalkModuleInfo,
+): ModuleOwnershipWritability {
+  const ownedServices = (mod.descriptor.declare.owns ?? []).map((o) => o.service).sort();
+  if (ownedServices.length === 0) return { writable: false, reason: 'zero-ownership', ownedServices: [] };
+  return { writable: true, ownedServices };
+}
+
+/** 供给足迹（该厂商全部供给服务并集——应用级 integrationSchemas 作用域，D32） */
+export function providerFootprint(catalog: WalkCatalog, provider: string): string[] {
+  return [...new Set(Object.values(catalog.providers[provider] ?? {}).flatMap((e) => e.services))].sort();
+}