@tbox.cn/app-toolkit 0.7.5 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -224,6 +224,9 @@ declare const moduleDescriptorSchema: z.ZodObject<{
224
224
  order?: number | undefined;
225
225
  }>, "many">>;
226
226
  providers: z.ZodDefault<z.ZodObject<{
227
+ /** 供给商标识自声明(v8——零槽厂商入 catalog:「custom 即 provider 模块」。
228
+ * charset 同 provider 槽(名字进凭据 stem 派生——输入约束①安全面)。 */
229
+ id: z.ZodOptional<z.ZodString>;
227
230
  slots: z.ZodDefault<z.ZodArray<z.ZodObject<{
228
231
  service: z.ZodString;
229
232
  provider: z.ZodString;
@@ -259,7 +262,9 @@ declare const moduleDescriptorSchema: z.ZodObject<{
259
262
  configSchema?: string | undefined;
260
263
  credentialSchema?: string | undefined;
261
264
  }[];
265
+ id?: string | undefined;
262
266
  }, {
267
+ id?: string | undefined;
263
268
  slots?: {
264
269
  service: string;
265
270
  provider: string;
@@ -349,6 +354,7 @@ declare const moduleDescriptorSchema: z.ZodObject<{
349
354
  configSchema?: string | undefined;
350
355
  credentialSchema?: string | undefined;
351
356
  }[];
357
+ id?: string | undefined;
352
358
  };
353
359
  owns: {
354
360
  service: string;
@@ -386,6 +392,7 @@ declare const moduleDescriptorSchema: z.ZodObject<{
386
392
  order?: number | undefined;
387
393
  }[] | undefined;
388
394
  providers?: {
395
+ id?: string | undefined;
389
396
  slots?: {
390
397
  service: string;
391
398
  provider: string;
@@ -482,6 +489,7 @@ declare const moduleDescriptorSchema: z.ZodObject<{
482
489
  configSchema?: string | undefined;
483
490
  credentialSchema?: string | undefined;
484
491
  }[];
492
+ id?: string | undefined;
485
493
  };
486
494
  owns: {
487
495
  service: string;
@@ -546,6 +554,7 @@ declare const moduleDescriptorSchema: z.ZodObject<{
546
554
  order?: number | undefined;
547
555
  }[] | undefined;
548
556
  providers?: {
557
+ id?: string | undefined;
549
558
  slots?: {
550
559
  service: string;
551
560
  provider: string;
@@ -994,1185 +1003,1227 @@ declare function resolveContractsForApp(appDir: string): Promise<ResolvedContrac
994
1003
  declare function invalidateContractsResolver(appDir?: string): void;
995
1004
 
996
1005
  /**
997
- * integration-services 谓词单源(integrations v4;自 CLI doctor/integration-services.ts 迁入——
998
- * doctor 第 19 条与 toolkit 工厂 evaluateIntegrationServices 共用此函数,单源不变)。
999
- * 纯函数、零副作用、零 I/O——contracts 经 input.contracts 注入(resolver 装配,版本解耦)。
1000
- *
1001
- * 结构化输出(H7 v4.3):IntegrationIssue { severity, code, message, service?, module?, instance? }——
1002
- * 检查逻辑零改动(~24 处 push 机械加 code/定位字段;level→severity 字段同名随 班车,
1003
- * severity 取值恒等旧 level——doctor 门控行为等价)。
1004
- * **code 枚举单源 = 本文件头映射表(additive-only;api.md §5 表与本表同步)**:
1005
- * CREDENTIAL_FILE_MISSING #1 error effective credentialRef 引用凭据文件不在场
1006
- * CREDENTIAL_TYPE_MISMATCH #2 error 凭据文件 .type 与绑定 credentialType 不一致
1007
- * SLOT_NOT_DECLARED #3 warning 服务槽无消费方声明(拼写/需求方未安装/旧槽位词汇;
1008
- * v6.1 归属豁免——owned 服务不报)
1009
- * SLOT_NOT_CONFIGURED #4 warning 需求方缺口(服务槽未配置)
1010
- * INSTANCE_SUPPLY_UNMATCHED #5 error 绑定未命中已装供给(槽级/实例级覆盖)
1011
- * IMPL_WITHOUT_PROVIDER #5/#13 error impl-only(implementation 缺 provider 绑定组头)
1012
- * INLINE_PROVIDER_INVALID #5 error 内联厂商声明超受控形状(槽级/实例级)
1013
- * SCHEMA_FILE_MISSING #6 error credentialType schema 引用不存在
1014
- * DOMAIN_CONFIG_INVALID #7 error root/modules 死配置(键 ∉ 引用厂商 schema properties;
1015
- * api.md DOMAIN_CONFIG_UNUSED 行预留 warning 级,
1016
- * 现行为 error 恒等旧谓词——doctor 门控等价)
1017
- * INSTANCE_KEY_NOT_REGISTERED #8 error ByInstance 键/实例键 ∉ 注册表白名单
1018
- * REALM_SWITCH_HINT #9 warning 实现覆盖跨厂商(凭据域切换确认)
1019
- * WILDCARD_ALIGNMENT #10 warning 通配形态齐步提示
1020
- * MULTI_INSTANCE_NO_DEFAULT v4 warning 多实例无 defaultInstanceId(无 scope 访问落全局会话)
1021
- * VENDOR_NOT_INSTALLED #11 error root/modules 厂商未命中已装供给
1022
- * BINDING_UNRESOLVED #12 error 绑定不可解析(resolveEffectiveService 求值失败)
1023
- * IMPL_WITHOUT_PROVIDER #5/#13 error impl-only(implementation 缺 provider 绑定组头)
1024
- * RESOURCE_TYPE_UNKNOWN #15 error modules 资源节 type ∉ 词汇表
1025
- * RESOURCE_NOT_DECLARED #16 warning 资源键/资源 id ∉ 模块声明集
1026
- * MODULE_CONFIG_DEAD v6 error modules[m](未安装 ∨ owns=0)携带 provider/config
1027
- * (统一吸收原「#16 升级」特例—— 一码一义)
1028
- * GLOBAL_FIELD_UNDECLARED #17 warning 全局层键过 #7 但 ∉ 引用厂商 x-tbox-global 并集(G 批;
1029
- * 零声明厂商整体跳过——#7 同遍历双判定)
1030
- * ORPHANED_CREDENTIAL 写后对账 warning 凭据文件不再被引用(toolkit 写路径产出,非本谓词)
1031
- * (v6 退役:DOMAIN_KEY_UNMATCHED #14——domains 键随归属模型退场)
1032
- *
1033
- * 输入形状(调用方负责装载):
1034
- * - integrations:config/integrations.json 解析产物(宽松 Record 透传——严格 zod 校验归模板 loader)
1035
- * - suppliedProviders:已声明供给(`${vendor}\u0000${implementation}` 拼接键 → 槽集合;同源聚合)
1036
- * - demandedServices:已声明需求(service → { optional, owners })
1037
- * - supplies:派生查表(contracts buildSupplyLookup 产物;缺席 → #12 跳过,M3 降级兼容)
1038
- * - malls:可选实例 id 白名单(v4 源 = root instances 注册表 ids;缺席 → ByInstance 键检查跳过)
1039
- * - credentialSchemas:可选(credentialType → schema 文件引用路径;manifest 声明聚合)
1040
- * - configSchemas:可选(service/slot → schema 文件引用路径)
1006
+ * DTO 全量(api.md §3 字段级单源落源——39 类型(v8:+ResolvedProvider/ProviderBinding/
1007
+ * ProviderSupplyScope/ProviderSupplyView,−ProviderDetail/dto 侧 SaveResult 死定义;
1008
+ * 11 项弃用标记按两迭代协议 0.9.0 删);演进 additive-only,铁律 #8——v8 弃用窗口例外
1009
+ * 声明见各 @deprecated)。
1010
+ * agtcodingbox / tbox-ai-coding 经 `import type` 消费(L2 DTO 单源——API 层零类型镜像)。
1011
+ * 词汇七概念:app / module / service / instance / provider / integration / resolution。
1012
+ * 弃用词汇清单见 api.md §3 尾(component/slot/scope/configMode/…——防复活)。
1041
1013
  *
1042
- * 检查族(v3):
1043
- * #1 effective credentialRef → 档内凭据文件在场
1044
- * #2 凭据文件 .type 与绑定 credentialType 对齐(错配 = transport 期「未知认证类型」前置暴露;
1045
- * 继承绑定(槽级 provider 缺席)经 effective 求值取厂商——supplies 在场时)
1046
- * #5 实例 impl-only 禁止 + 覆盖命中供给(含槽级内联形状;provider-only = 派生位,合法)
1047
- * #6 manifest configSchema/credentialSchema 引用文件存在性(内联与 manifest 绑定同查)
1048
- * #7 root/modules 死配置:root.config/configByInstance/modules[m].config 键 ⊆ 引用厂商(并集)
1049
- * 各槽 schema properties——引用面 = root.provider ∪ modules.*.provider ∪ 槽级(terse 化防退化);
1050
- * modules 层 per-module 生效厂商 = resolveModuleBinding 单源(≡ modules[m].provider ?? root.provider)
1051
- * #8 ByInstance/实例键 ∈ malls 白名单(v4:源 = root instances 注册表 ids——参考表在场时
1052
- * 激活;'**' 通配键豁免;注册表缺席 → 跳过;modules 键 = install id 非 instanceId,不适用)
1053
- * #9 实现覆盖跨厂商提示(realm switch——凭据域切换确认)
1054
- * #11 root/modules 厂商未命中已装供给(vendor 集合 = suppliedProviders 键前缀展开)
1055
- * #12 绑定可解析性:逐 (service, instanceId) 经 contracts resolveEffectiveService 求值
1056
- * (级联单源复用,谓词零级联实现;v6 ownerOf=ownership 显式参透传),binding-unresolved → error
1057
- * #13 槽级/实例级 impl-only(implementation 需伴随 provider——provider 是绑定组头;
1058
- * zod 之外的第二道防线——doctor 读裸 JSON)
1059
- * MODULE_CONFIG_DEAD:modules[m] 携带 provider/config 且(m ∉ installedModuleIds ∨ ownership
1060
- * 无任何 service 归属 m)→ error(键级 #16 warning 与本检查可同节点共发——键级 vs 值级不同断言面)
1061
- * #17(G 批):与 #7 同遍历双判定——键 ∈ schema properties 但 ∉ x-tbox-global 并集 →
1062
- * warning;引用厂商零全局声明(集空/缺席)→ 该厂商键整体跳过;检查序在 MODULE_CONFIG_DEAD 后
1063
- * #15-#16 modules 资源节对账(v5 延续):type ∉ RESOURCE_TYPE_IDS → error;键 ∉ 已装模块 id 集 /
1064
- * 资源 id ∉ 模块 manifest declare.resources 声明集 → warning
1014
+ * **v7 词汇统一破例声明(一次性收敛,此后恢复 additive-only)**:标识/展示名分轴
1015
+ * (id = 标识、name = 展示名、description = 描述——对齐实例轴 {id, name}),
1016
+ * title 键全量退役(与 manifest name→id/title→name 同一变更);`.title` 消费方
1017
+ * (外部仓 import type / 运行时读)需同窗迁移。
1065
1018
  */
1066
-
1067
- /** contracts 注入面(resolver 装配产物运行时视图 = EvaluationExports 求值子集) */
1068
- type PredicateContracts = Pick<EvaluationExports, 'resolveEffectiveService' | 'buildSupplyLookup' | 'normalizeInstances' | 'RESOURCE_TYPE_IDS'>;
1069
- /** 派生查表形状(contracts buildSupplyLookup 产物;结构等价 TIER0 SupplyLookup——谓词零 contracts 静态依赖) */
1070
- type SupplyLookup = Record<string, readonly string[]>;
1071
- interface IntegrationServicePredicateInput {
1072
- integrations: {
1073
- provider?: string;
1074
- config?: Record<string, unknown>;
1075
- configByInstance?: Record<string, Record<string, unknown>>;
1076
- credentialRef?: string;
1077
- credentialRefByInstance?: Record<string, string>;
1078
- services: Record<string, {
1079
- provider?: string | Record<string, unknown>;
1080
- implementation?: string;
1081
- config?: Record<string, unknown>;
1082
- credentialRef?: string;
1083
- instances?: Record<string, {
1084
- enabled?: boolean;
1085
- provider?: unknown;
1086
- implementation?: unknown;
1087
- credentialRef?: string;
1088
- }>;
1089
- }>;
1090
- /** v4 部署实例注册表(参考表——#8 白名单源 + 多实例无默认 warning) */
1091
- instances?: Array<{
1092
- id: string;
1093
- name?: string;
1094
- attributes?: Record<string, unknown>;
1095
- }>;
1096
- /** v4 默认实例(normalizeInstances 解析语义:显式 ?? 单候选唯一解) */
1097
- defaultInstanceId?: string | null;
1098
- /** v6 模块集成位(modules 节三键——宽松透传;严格 zod 归模板 loader) */
1099
- modules?: Record<string, {
1100
- provider?: string;
1101
- config?: Record<string, unknown>;
1102
- resources?: Record<string, {
1103
- type?: unknown;
1104
- }>;
1019
+ /** contracts 求值五态原样(EffectiveServiceResolution.status)+ 视图轴降级态
1020
+ * (evaluation-unavailable——toolkit 视图独有,非 contracts 求值产物:contracts 不可用
1021
+ * (未安装/无严格面/v6 标记缺席)时读求值轴不再 503,改投静态骨架 + 本态标记;
1022
+ * 消费方按非 ok 态渲染,statusMessage 携带 N1 分支指引) */
1023
+ type ServiceStatus = 'ok' | 'service-not-configured' | 'instance-not-found' | 'instance-disabled' | 'binding-unresolved' | 'evaluation-unavailable';
1024
+ /** 四配置层(instance 为 map 字段层) */
1025
+ type BindingLayer = 'app' | 'module' | 'service' | 'instance';
1026
+ /** provider + 来源层对(成对出现防漂移——「生效绑定」原子形状) */
1027
+ interface ResolvedProvider {
1028
+ provider: string | null;
1029
+ layer: BindingLayer | null;
1030
+ }
1031
+ /** 三轴同构 provider 绑定解析(v8——app/module/service 静态视图缺省携带;静态零 contracts,
1032
+ * 「数据来源」状态服务端单源——派生知识不泄漏客户端)。
1033
+ * 口径钉子:静态三视图 = node 级口径(effective.layer 恒 ≠ 'instance',实例层无条件排除);
1034
+ * 求值轴 Entry.binding = 默认实例口径(layer 可为 'instance')。两口径文档化分立。 */
1035
+ interface ProviderBinding {
1036
+ /** 本节点显式配置(文件 provider 归一:缺席/空串/malformed = null;弃用内联对象 = 其名) */
1037
+ configured: string | null;
1038
+ /** 实际生效(configured 非空 = 本层;否则 = 继承上级;全链未配置 = {null, null}) */
1039
+ effective: ResolvedProvider;
1040
+ /** 清除本级配置后的继承回落(「跟随上级」选项回显);app 轴恒 {null, null}(无上级) */
1041
+ inherited: ResolvedProvider;
1042
+ /** @deprecated 0.8.0 = effective.provider——仅 ModuleDetailView.binding 双写(App/Service 新
1043
+ * 字段不发射);0.9.0 删 */
1044
+ provider?: string | null;
1045
+ /** @deprecated 0.8.0 = effective.layer——同上;0.9.0 删 */
1046
+ layer?: BindingLayer | null;
1047
+ }
1048
+ /** 纯模块清单(无 services——卡片展开走 /modules/:m);provider 家族包不在清单
1049
+ * (供给/实施载体非可配置业务模块——供给轴归 /providers;判定 = install id / 包名
1050
+ * basename 去 scope 后 `provider-` 前缀;已装 provider 详情 GET /modules/:m 仍 200) */
1051
+ interface ModulesView {
1052
+ modules: ModuleDeclaration[];
1053
+ }
1054
+ interface ModuleDeclaration {
1055
+ /** install id(packages/ 目录名 / .tbox/app.json entry.id)——恒业务模块(provider 家族不在本清单) */
1056
+ id: string;
1057
+ /** 展示名(v7 词汇统一:manifest name ?? id——恒有值) */
1058
+ name: string;
1059
+ description: string;
1060
+ /** 隐藏模块(additive——manifest hidden === true 时携带;默认清单已过滤,本字段仅供
1061
+ * ?includeHidden=true 可见时徽标呈现) */
1062
+ hidden?: boolean;
1063
+ }
1064
+ /** 服务需求声明(模块 demand 单元 / 平台服务条目 / owned-not-consumed 投影条目——
1065
+ * v4.4 双端点同型;defaults 唯一落位 ServiceDetail) */
1066
+ interface ServiceDemand {
1067
+ service: string;
1068
+ /** manifest demand meta(v7 title→name);缺席 UI 回退 service id */
1069
+ name?: string;
1070
+ description?: string;
1071
+ /** demand optional === false(多模块 OR 聚合见 resolution echo;平台服务条目与 owned
1072
+ * 投影条目恒 false——无 demand 源) */
1073
+ required: boolean;
1074
+ }
1075
+ /** GET /modules/:module(模块静态一站式 · PUT 读对偶) */
1076
+ interface ModuleDetailView {
1077
+ /** 模块展示名(v7 词汇统一:manifest name ?? id——恒有值) */
1078
+ name: string;
1079
+ /** B1 additive:模块 meta 描述(manifest description;兜底 '') */
1080
+ description: string;
1081
+ /** 隐藏模块(additive——manifest hidden === true 时携带;详情恒 200 不受清单过滤影响,
1082
+ * 本字段仅供面板徽标呈现) */
1083
+ hidden?: boolean;
1084
+ /** v6 所有权模型:模块归属服务(declare.owns 展平,排序;零归属 = [])——
1085
+ * v5 domainKeys 退役(破坏性更名;面板 presence-detection 双读义务见 api.md §3) */
1086
+ ownedServices: string[];
1087
+ /** modules[install id] 集成位原值(provider/config;resources 不投影——见 resources 字段);未配置 = null */
1088
+ integration: ModuleIntegrationNode | null;
1089
+ /** 模块资源只读镜像(N2 读半边——写侧 resources 恒保全;含 ref 台账展开态 resolvedDatasetId);
1090
+ * 无模块键/无资源节 = null */
1091
+ resources?: ModuleResourcesEcho | null;
1092
+ /** v8 三轴同构升级(ModuleBinding 升形):模块级绑定解析(moduleProviderBinding 单源——
1093
+ * configured/effective/inherited;legacy provider/layer 双写仅本视图发射,0.9.0 删) */
1094
+ binding: ProviderBinding;
1095
+ /** v6:owns.length > 0(moduleOwnershipWritable 单源——读标志与写守卫共用) */
1096
+ configEditable: boolean;
1097
+ /** 本模块服务面 = demand ∪ owned 去重投影(2026-09-21 服务面投影批——通用合并无 consumes
1098
+ * 空判特例:consume 条目胜出[声明序原样、required = optional === false];owned-not-consumed
1099
+ * 追加[ownedServices 排序序、Set 去重,required 恒 false]。卡片展开 + 编辑器静态上下文自足) */
1100
+ services: ServiceDemand[];
1101
+ /** v4.4 include=serviceResolutions 内嵌(v6.1 键集 = owned ∪ demand 服务过滤 ≡ 批量 ?service= 语义;<0.9/形态异常 → null——永不 503) */
1102
+ serviceResolutions?: ServiceResolutionsView | null;
1103
+ /** v4.4 include=integrationSchemas 层级富化(零归属/未绑定 → null) */
1104
+ integrationSchemas?: LayerIntegrationSchemas | null;
1105
+ /** v4.6 include=integrationFieldRegistry 集成字段注册表(null 语义镜像 integrationSchemas;
1106
+ * 未知厂商/零足迹 → 非 null 空集 + unsupplied 回填—— 轴参假想计算同此) */
1107
+ integrationFieldRegistry?: IntegrationFieldRegistryView | null;
1108
+ }
1109
+ /** 模块级厂商绑定解析(v6——静态文件事实;规则 ≡ 谓词 #7 模块层,resolveModuleBinding 单源)。
1110
+ * @deprecated 0.8.0——三轴同构 ProviderBinding 取代(ModuleDetailView.binding 升形,
1111
+ * 旧 {provider, layer} = 新 effective 子集且由 legacy 字段双写承载);0.9.0 删除类型。 */
1112
+ interface ModuleBinding {
1113
+ /** modules[install id].provider ?? root.provider(双缺 = null) */
1114
+ provider: string | null;
1115
+ /** 生效来源层(双缺 = null) */
1116
+ layer: 'module' | 'app' | null;
1117
+ }
1118
+ /** 层级 config schema 计算(v4.4——静态轴富化,零 contracts)。
1119
+ * @deprecated 0.8.0——表单统一走 integrationFieldRegistry(消费投影);原始投影降为
1120
+ * registry 构造内部输入(wire include 键 integrationSchemas 标记弃用,0.9.0 删)。 */
1121
+ interface LayerIntegrationSchemas {
1122
+ /** 层生效厂商(resolveModuleBinding 单源) */
1123
+ provider: string;
1124
+ /** 模块级 = 本模块 ownedServices ∩ 该厂商供给;应用级 = 供给足迹全量(configSchema = raw draft 2020-12 原文;供给在场未声明 = null) */
1125
+ services: Record<string, {
1126
+ configSchema: object | null;
1127
+ }>;
1128
+ }
1129
+ /** v4.6 集成字段注册表(层级表单服务端预计算——合并代数// 服务端单源;
1130
+ * 消费 resolveLayerIntegrationSchemas 产物构造,禁旁路直取 serviceSchemas) */
1131
+ interface IntegrationFieldRegistryView {
1132
+ /** echo:本注册表计算口径(假想时 = 轴参值——) */
1133
+ provider: string;
1134
+ /** 作用域内 configSchema === null 的服务(UI「未提供参数模板」提示行) */
1135
+ schemaless: string[];
1136
+ /** 作用域内全部非 null schema 的 additionalProperties 均 ≠ false(聚合;空真) */
1137
+ additionalPropertiesAllowed: boolean;
1138
+ /** 逐 key 合并产物(首声明插入序 = scope 遍历序:app 字母序 / module ownedServices 序) */
1139
+ fields: Array<{
1140
+ key: string;
1141
+ /** null = 类型不可调和(/ 异构/ enum 不等——冲突折叠,客户端 RawJson 保真) */
1142
+ schema: object | null;
1143
+ /** required 聚合 = sources.some(s => s.required);conflict 字段照常聚合 */
1144
+ sources: Array<{
1145
+ service: string;
1146
+ required: boolean;
1105
1147
  }>;
1106
- };
1107
- /** 已声明供给(`${vendor}\u0000${implementation}` → 槽集合;credentialType 供 #2/#6 绑定侧对齐) */
1108
- suppliedProviders: Record<string, {
1109
- services: string[];
1110
- owner: string;
1111
- credentialType?: string;
1148
+ /** G 批:x-tbox-global 聚合旗标(sources.some——任一来源声明即 true;app/module 轴表单
1149
+ * 仅渲染 true 字段,非全局键落 ExtraFields;service 轴全量透传) */
1150
+ global: boolean;
1151
+ }>;
1152
+ }
1153
+ /** GET /app(应用静态视图:平台服务 + root 原值) */
1154
+ interface AppView {
1155
+ /** 平台服务(v4.4 服务词汇 − 模块占用——与模块 demand 同型 ServiceDemand[];
1156
+ * title/description 缺席 = UI 回退 service id;required 恒 false——平台服务无 demand 源) */
1157
+ services: ServiceDemand[];
1158
+ /** root 节点原值;文件缺席 = null */
1159
+ integration: AppIntegrationNode | null;
1160
+ /** v8:app 轴绑定解析(appProviderBinding——configured ≡ effective(无上级);
1161
+ * inherited 恒 {null, null};「数据来源」状态单源) */
1162
+ binding: ProviderBinding;
1163
+ /** v4.4 include=serviceResolutions 内嵌(全量键集 ≡ 批量无参;<0.9/形态异常 → null——永不 503) */
1164
+ serviceResolutions?: ServiceResolutionsView | null;
1165
+ /** v4.4 include=integrationSchemas 层级富化(root.provider 缺席 → null) */
1166
+ integrationSchemas?: LayerIntegrationSchemas | null;
1167
+ /** v4.6 include=integrationFieldRegistry 集成字段注册表(root.provider 缺席且无轴参 → null;
1168
+ * 未知厂商/零足迹 → 非 null 空集—— 轴参假想计算同此) */
1169
+ integrationFieldRegistry?: IntegrationFieldRegistryView | null;
1170
+ }
1171
+ /** GET /services/:service(服务静态单体) */
1172
+ interface ServiceDetail extends ServiceDemand {
1173
+ /** 文件 services[s] 逐字原值(编辑预填源);无声明 = null */
1174
+ integration: ServiceIntegrationNode | null;
1175
+ /** v8:service 轴绑定解析(serviceProviderBinding 单源——node 级口径,实例层排除;
1176
+ * inherited = 上级绑定 owner 模块 ?? root——「跟随上级」选项回显) */
1177
+ binding: ProviderBinding;
1178
+ /** v4.7 include=integrationSchemas 生效绑定富化(三态:null 全链未绑定 /
1179
+ * 绑定无可计算 schema / 含 schema;malformed 节点 → null——不放行域级联)
1180
+ * @deprecated 0.8.0——表单统一走 integrationFieldRegistry;生效厂商归 binding.effective。0.9.0 删 */
1181
+ integrationSchemas?: ServiceIntegrationSchemas | null;
1182
+ /** G 批:include=integrationFieldRegistry 服务轴注册表(loadServiceFieldRegistry——
1183
+ * 四分支链推导复用 fields = 该 schema 全部字段带 global 旗标;null 语义镜像 。
1184
+ * v5.1 serviceProvider 轴参 = 假想重定向——仅表单投影按 X 计算,带非空轴参时
1185
+ * registry 恒非 null(豁免链③不镜像实际态 null);同构 ≡ PUT 改写 provider 后实读) */
1186
+ integrationFieldRegistry?: IntegrationFieldRegistryView | null;
1187
+ }
1188
+ /** 服务级生效绑定 schema(v4.7 静态轴富化——零 contracts,永不 503;实例层无条件排除:
1189
+ * node 级口径 ≠ resolution 默认实例口径,api.md §4.4 注)。
1190
+ * @deprecated 0.8.0——表单统一走 integrationFieldRegistry;生效厂商归 binding.effective。0.9.0 删 */
1191
+ interface ServiceIntegrationSchemas {
1192
+ /** 生效厂商:显式(含内联声明名)?? modules[ownerOf].provider ?? root.provider */
1193
+ provider: string;
1194
+ /** catalog 复合键(多 impl 声明序首个)> 内联 ref;miss(未知厂商/未供给/内联缺 ref)→ null(富化非门控) */
1195
+ configSchema: object | null;
1196
+ }
1197
+ /** GET /service-resolutions(批量求值 · 唯一求值集合面) */
1198
+ interface ServiceResolutionsView {
1199
+ /** contracts echo(仅求值轴两端点携带) */
1200
+ contracts: ContractsResolution;
1201
+ /** 键集 = 服务词汇 ∪ 已配置 ∪ 归属(v6.1 += 归属——owned 服务恒可求值;模块/平台/孤儿全量) */
1202
+ resolutions: Record<string, ServiceResolutionEntry>;
1203
+ /** 谓词全量(doctor 同源;恒全量——subset 消费方客户端过滤) */
1204
+ issues: IntegrationIssue[];
1205
+ }
1206
+ /** 求值摘要单元(行内嵌; 单一形状) */
1207
+ interface ServiceResolutionEntry {
1208
+ /** 默认实例口径(normalizeInstances 委托) */
1209
+ status: ServiceStatus;
1210
+ statusMessage?: string;
1211
+ /** 生效绑定对(provider 在场时恒在场;默认实例口径——layer 可为 'instance';
1212
+ * 与静态三视图 binding.effective 同概念同形状——「binding 一词到底」) */
1213
+ binding?: ResolvedProvider;
1214
+ /** @deprecated 0.8.0 → binding.provider(双写一个窗口);0.9.0 删 */
1215
+ provider?: string;
1216
+ /** @deprecated 0.8.0 → binding.layer(同上);0.9.0 删 */
1217
+ layer?: BindingLayer;
1218
+ /** provider 在场时在场:(provider, service) ∈ 供给关系 */
1219
+ supplied?: boolean;
1220
+ /** owner 模块 install id(v6.1 = walk.ownership 归属单源——install id 轴,与模块清单 id 恒可 join;
1221
+ * 旧实现 demand owners[0] 为包名/@app 轴且漏 owned-not-consumed,已退役);平台服务/孤儿缺席 */
1222
+ module?: string;
1223
+ /** demand echo(OR 聚合);平台/孤儿恒 false;集成就绪判定单源(§7) */
1224
+ required?: boolean;
1225
+ }
1226
+ /** 求值完整结构(extends = 列表项 ⊂ 单体的编译期保证——) */
1227
+ interface ServiceResolution extends ServiceResolutionEntry {
1228
+ /** 枚举规则(全实例逐一;默认实例求值 = 摘要基,不重复头部) */
1229
+ instances: ResolvedInstance[];
1230
+ inheritance: Array<{
1231
+ layer: BindingLayer;
1232
+ provider?: string;
1233
+ implementation?: string;
1112
1234
  }>;
1113
- /** 已声明需求(service → { optional, owners }) */
1114
- demandedServices: Record<string, {
1115
- optional: boolean;
1116
- owners: string[];
1235
+ }
1236
+ /** GET /service-resolutions/:service(求值单体) */
1237
+ interface ServiceResolutionDetail {
1238
+ contracts: ContractsResolution;
1239
+ resolution: ServiceResolution;
1240
+ /** service === :service 过滤子集 */
1241
+ issues: IntegrationIssue[];
1242
+ }
1243
+ /** root 节点 */
1244
+ interface AppIntegrationNode {
1245
+ /** 恒字符串(app/module 级无内联形态) */
1246
+ provider?: string;
1247
+ config?: Record<string, unknown>;
1248
+ configByInstance?: Record<string, Record<string, unknown>>;
1249
+ credentialRef?: string;
1250
+ credentialRefByInstance?: Record<string, string>;
1251
+ /** 整组替换(id 字符集受输入约束①) */
1252
+ instances?: Array<{
1253
+ id: string;
1254
+ name: string;
1255
+ attributes?: Record<string, unknown>;
1117
1256
  }>;
1118
- /** 派生查表(buildSupplyLookup 产物;缺席 → #12 跳过 + #2 继承绑定不查 credentialType) */
1119
- supplies?: SupplyLookup;
1120
- /** v6 服务归属表(walk.ownership——#12 ownerOf 透传 + MODULE_CONFIG_DEAD owns=0 判据;
1121
- * 缺席 = 归属面不可判 → MODULE_CONFIG_DEAD 退化为仅「未安装」分支) */
1122
- ownership?: Record<string, string>;
1123
- /** v6 已装模块 id 集(.tbox/app.json entry.id ∪ packages/ 目录名;缺席 → 「未安装」分支跳过) */
1124
- installedModuleIds?: ReadonlySet<string>;
1125
- /** malls 白名单(deployments 控制面 extract;缺席 → ByInstance 键检查跳过) */
1126
- malls?: string[];
1127
- /** credentialType → schema 文件引用缺失(manifest 声明指向缺失文件;#6) */
1128
- credentialSchemaMissing?: Record<string, boolean>;
1129
- /** 厂商 → 槽 schema properties 键集(#7 用;调用方从 manifest configSchema 引用解析) */
1130
- vendorConfigKeys?: Record<string, Set<string>>;
1131
- /** G 批:厂商 → x-tbox-global 标记键集(#17 用;#7 同循环收集——零新增 IO);
1132
- * 缺席/空集 = 该厂商零声明 → #17 对其键整体跳过 */
1133
- vendorGlobalConfigKeys?: Record<string, Set<string>>;
1134
- /** 厂商 → configSchema 引用文件缺失(#7 跳过该厂商——无 schema 不能判死配置) */
1135
- vendorConfigSchemaMissing?: Record<string, boolean>;
1136
- /** 凭据文件缺失(#1:credentialRef stem → 档内 credentials/<stem>.json 在场;域中立注入) */
1137
- credentialFileMissing?: Record<string, boolean>;
1138
- /** 凭据文件 .type(stem → type;#2 对齐判定——文件无 type 则缺键,跳过) */
1139
- credentialFileType?: Record<string, string | undefined>;
1140
- /** #9:实现覆盖跨厂商提示位(CLI 侧组装) */
1141
- realmSwitchHints?: string[];
1142
- /** v5:已装模块 id → manifest declare.resources 声明 id 集(值空集 = 无声明,资源级跳过;
1143
- * 缺席 = 无需求面信息——键未知/资源未声明检查跳过,type 检查恒跑) */
1144
- moduleResourceNeeds?: Record<string, ReadonlySet<string>>;
1257
+ defaultInstanceId?: string | null;
1145
1258
  }
1146
- /** 结构化 issue(H7 v4.3):code 枚举单源 = 本文件头映射表(additive-only) */
1147
- interface IntegrationServiceIssue {
1148
- severity: 'error' | 'warning';
1149
- code: string;
1150
- message: string;
1151
- service?: string;
1152
- module?: string;
1153
- instance?: string;
1259
+ /** AppIntegrationNode 键集单源(runtime const——write applyApp 全量替换白名单
1260
+ * (缺席根键删除;services/modules 域不在其中;v6 domains 键退役)+ views/app 投影
1261
+ * (GET 预填 ≡ PUT body,/L1——文件含 services/modules 但 root 节点投影只含本键集)) */
1262
+ declare const APP_INTEGRATION_NODE_KEYS: readonly ["provider", "config", "configByInstance", "credentialRef", "credentialRefByInstance", "instances", "defaultInstanceId"];
1263
+ /** 模块集成位节点(v6——provider 绑定默认 + config 级联层;resources 不投影不写——
1264
+ * 集成位编辑恒保全资源节,N2) */
1265
+ interface ModuleIntegrationNode {
1266
+ provider?: string;
1267
+ config?: Record<string, unknown>;
1154
1268
  }
1155
- /** 内联厂商声明受控形状(v2:provider/credentialType/configSchema) */
1156
- declare function isControlledInlineProvider(raw: unknown): boolean;
1157
- /** #8 检查族导出(FX-2b 单源):toolkit 写路径轻量复查(registryCheck)消费——
1158
- * 覆盖 configByInstance / credentialRefByInstance / services[s].instances 三键位;
1159
- * malls = root instances 注册表 ids(参考表缺席 → 消费方跳过,勿传空集)。 */
1160
- declare function checkInstanceKeys(integrations: {
1161
- configByInstance?: Record<string, unknown>;
1162
- credentialRefByInstance?: Record<string, unknown>;
1163
- services?: Record<string, {
1164
- instances?: Record<string, unknown>;
1269
+ /** ModuleIntegrationNode 可写键集单源(v6——write applyModule 全量替换白名单
1270
+ * (键集外 400;resources 恒随既有节点保全)+ views/modules 投影(GET ≡ PUT,三同构)) */
1271
+ declare const MODULE_INTEGRATION_NODE_KEYS: readonly ["provider", "config"];
1272
+ /** 模块资源回显(只读投影——N2 读半边:写侧仍仅 provider/config,resources 恒保全)。
1273
+ * 原值文件镜像(L1)+ ref 台账展开态:`ref` 在场且同目录 knowledge.json 命中时
1274
+ * `resolvedDatasetId` = 台账 datasetId(镜像 SDK resolveKnowledge 展开语义),未命中/台账缺失 = null。
1275
+ * 路径锚定边界:视图恒读 `<appDir>/config/`(与 toolkit readIntegrationsConfig 同源——
1276
+ * `TBOX_INTEGRATIONS_FILE` 为 SDK 运行时逃生舱,视图不跟随,既有分叉)。 */
1277
+ interface ModuleResourceEcho {
1278
+ type: 'knowledge';
1279
+ /** 文件原值直填 datasetId(与 ref 互斥使用——并存时 SDK 侧 datasetId 优先) */
1280
+ datasetId?: string;
1281
+ /** 文件原值 ref(台账引用——knowledge.json knowledge_bases 键) */
1282
+ ref?: string;
1283
+ /** 展开态:datasetId 直填时 = 该值;ref 命中台账 = 台账 datasetId;ref 未命中/台账缺失 = null */
1284
+ resolvedDatasetId: string | null;
1285
+ topK?: number;
1286
+ scoreThreshold?: number;
1287
+ }
1288
+ /** modules[install id].resources 只读镜像(键 = 资源 id;无模块键/无资源 = null) */
1289
+ type ModuleResourcesEcho = Record<string, ModuleResourceEcho>;
1290
+ /** services[s] 整节点 */
1291
+ interface ServiceIntegrationNode {
1292
+ /** 对象 = 自定义 API(仅槽级) */
1293
+ provider?: string | InlineVendorDeclaration;
1294
+ /** 内联 provider 时必填 */
1295
+ implementation?: string;
1296
+ config?: Record<string, unknown>;
1297
+ credentialRef?: string;
1298
+ /** 键 = instanceId / '*'(随节点全量替换) */
1299
+ instances?: Record<string, ServiceInstanceNode>;
1300
+ }
1301
+ /** services[s].instances[k] 节点 */
1302
+ interface ServiceInstanceNode {
1303
+ /** provider 恒字符串(内联仅槽级合法) */
1304
+ provider?: string;
1305
+ implementation?: string;
1306
+ config?: Record<string, unknown>;
1307
+ credentialRef?: string;
1308
+ /** 缺省 true;false → instance-disabled */
1309
+ enabled?: boolean;
1310
+ }
1311
+ interface InlineVendorDeclaration {
1312
+ /** @deprecated 0.8.0——内联声明形态弃用:自定义 API 统一为 provider-custom 包自声明
1313
+ * (provider 即模块——AI 实施即补槽声明;provider 恒字符串三层同构)。类型随节点
1314
+ * wire 形状保留至 0.9.0(TIER0 zod 兼容读同窗);存量节点编辑器打开即自愈迁移。 */
1315
+ provider: string;
1316
+ credentialType: string;
1317
+ configSchema?: string;
1318
+ }
1319
+ interface CredentialValues {
1320
+ type: string;
1321
+ values: Record<string, string>;
1322
+ }
1323
+ interface ResolvedInstance {
1324
+ /** 注册表 id;'*' = 通配 */
1325
+ instanceId: string;
1326
+ status: ServiceStatus;
1327
+ /** 逐实例诊断(binding-unresolved 等直投) */
1328
+ statusMessage?: string;
1329
+ /** 该实例合并结果 */
1330
+ effective?: EffectiveBinding;
1331
+ }
1332
+ /** GET /providers:厂商基本信息 */
1333
+ interface ProvidersView {
1334
+ providers: ProviderEntry[];
1335
+ }
1336
+ interface ProviderEntry {
1337
+ provider: string;
1338
+ /** Mock 旗标(provider 级聚合) */
1339
+ local: boolean;
1340
+ /** 厂商展示名(v7 title→name:manifest name——多包首声明;缺席 = undefined) */
1341
+ name?: string;
1342
+ }
1343
+ /** GET /providers/:p/services/:s:表单 schema 唯一暴露面 */
1344
+ interface ProviderServiceDetail {
1345
+ provider: string;
1346
+ service: string;
1347
+ /** ★ 恒数组(通常 1);credentialType 保留(/credential-types 寻址键) */
1348
+ implementations: Array<{
1349
+ implementation: string;
1350
+ credentialType: string;
1165
1351
  }>;
1166
- }, malls: readonly string[]): IntegrationServiceIssue[];
1167
- /** 谓词主体:integrations 配置 × catalog 声明 交叉校验(error/warning 分级;contracts 注入) */
1168
- declare function evaluateIntegrationServices(input: IntegrationServicePredicateInput & {
1169
- contracts: PredicateContracts;
1170
- }): IntegrationServiceIssue[];
1171
-
1172
- /**
1173
- * walkManifests(appDir)——单次遍历四产物(/;ai-build)。
1174
- *
1175
- * manifest 候选路径探测(packages/<id>/tbox.module.json 优先 → node_modules/<pkg>/tbox.module.json;
1176
- * tbox-app dev 真身经 .tbox-dev.local/dev-manifest.json redirects 独立 catalog 通道直达)一次遍历同时产出:
1177
- * 1. modules:已装模块清单(declared;demand meta name/description 透传)
1178
- * 2. catalog(富形态):providers 嵌套(vendor→impl→entry,per-service {implementation, credentialType}
1179
- * 保真——同厂商异构/多实现合法,/H1)+ 需求侧聚合
1180
- * 3. serviceSchemas:per-service schema 复合键表——键 `${provider}\u0000${service}`(H2,同一服务
1181
- * 多厂商供给各自 schema 零碰撞);多 impl 同 (provider, service) 异 schema → 声明序首个
1182
- * 4. vocabulary:所有携带 service-slots.json 的已装契约包该文件 `.slots` 键并集(fs 直读、
1183
- * `$comment` 忽略;探测三跳 = ① <候选>/node_modules/@tbox.cn/<pkg>/service-slots.json(包根)
1184
- * ② 同包 src/service-slots.json(发布包 src 附带 / 模板 shim 链接)
1185
- * ③ 候选自身 {service-slots.json, src/service-slots.json}(local/codegen 全量副本——
1186
- * mall 生成应用主形态,不依赖 install);零缓存枚举,与 manifest 探测同机制;
1187
- * 多行业 contracts-* 天然扩展);缺席 → [](退化 demanded ∪ configured)
1188
- * 5. slotMeta:词汇 meta 节(per-service {name,description} 展示元数据——消费端兜底链
1189
- * 词汇 > demand > id,views/context resolveServiceDisplay 单源);多包发现序首声明胜出
1190
- * (与 catalog addSlots 同语义);contracts-mall 词汇锁保证 mall 域全量覆盖;缺席 → {}
1191
- * 6. ownership:service → moduleId 归属表(v6——declare.owns 聚合;install id 键控;
1192
- * 双 owner 冲突 → declarationIssues OWNERSHIP_CONFLICT + 先声明胜出)
1193
- * 7. declarationIssues:声明面诊断(OWNERSHIP_CONFLICT / OLD_MANIFEST_KEY—— 通道)
1194
- *
1195
- * **约束(FX-3/ 边界)**:目录枚举零缓存——readdir / node_modules 候选探测 / `.tbox/app.json` 读取 /
1196
- * dev-manifest 读取每次执行(枚举输入保持 fresh——agent 装卸模块下一笔即见);manifest/service-slots
1197
- * **文件内容**经 file-cache(`cache` 可选参——工厂/写内核传本实例 cache(stat 指纹自愈 + 写后失效);
1198
- * CLI 传 undefined 即全 fresh)。
1199
- * 宽松解析语义(坏文件静默 + 重复键首声明保留)零改动。
1200
- */
1201
- /** 声明面诊断(v6 通道——OWNERSHIP_CONFLICT / OLD_MANIFEST_KEY;error 级) */
1202
- type DeclarationIssue = {
1203
- severity: 'error';
1204
- code: 'OWNERSHIP_CONFLICT';
1205
- message: string;
1206
- module?: string;
1352
+ /** 厂商集成该服务的表单 schema(integration 域专属)——raw draft 2020-12 原文零转换;
1353
+ * 供给在场未声明 = null(mock 合法);解析自默认 impl。v8 拍平(唯一推荐读取位) */
1354
+ configSchema: object | null;
1355
+ /** @deprecated 0.8.0 = { configSchema }(单键包裹 v4.4 credentialSchema 删除后的残留)——
1356
+ * 双写一个窗口;0.9.0 删 */
1357
+ integrationSchemas: {
1358
+ configSchema: object | null;
1359
+ };
1360
+ }
1361
+ /** 供给判定作用域(显式请求参数——三轴同构判定的作用域声明;wire = `?scope=` 判别值 +
1362
+ * 伴随参数 `?module=` / `?service=`,不从其他参数推断)。
1363
+ * scope = 该层绑定实际作用的服务集合:app = 在册服务全集(root 级联全域可达);
1364
+ * module = 模块归属服务(declare.owns);service = 自身(任意 id 恒 200——判定非寻址)。 */
1365
+ type ProviderSupplyScope = {
1366
+ kind: 'app';
1207
1367
  } | {
1208
- severity: 'error';
1209
- code: 'OLD_MANIFEST_KEY';
1210
- message: string;
1211
- module?: string;
1368
+ kind: 'module';
1369
+ module: string;
1370
+ } | {
1371
+ kind: 'service';
1372
+ service: string;
1212
1373
  };
1213
- interface WalkManifestsResult {
1214
- /** declared 产物(install id + descriptor;demand meta 透传) */
1215
- modules: WalkModuleInfo[];
1216
- /** 富形态 catalog(providers 嵌套保真 + 需求聚合 + credentialTypes) */
1217
- catalog: WalkCatalog;
1218
- /** per-service schema 复合键表:`${provider}\u0000${service}` → schema 引用 + 包根 */
1219
- serviceSchemas: Record<string, {
1220
- configSchema?: string;
1221
- credentialSchema?: string;
1222
- packageDir: string;
1374
+ /** GET /providers/:p/supply?scope=…(静态 · 零 contracts · 永不 503)——供给判定。
1375
+ * 未保存切换预览(本端点)与已保存状态(求值轴 resolution.supplied)消费同一 catalog
1376
+ * 供给关系,旗标同名同义。surplus(作用域外供给)不表达。边界:provider ∉ catalog →
1377
+ * 404 PROVIDER_NOT_FOUND;scope=module 未装 → 404 MODULE_NOT_FOUND;已知厂商 + 不在
1378
+ * 足迹的 service → 200 + supplied:false(判定非寻址,与组合单体 SUPPLY_NOT_FOUND 404
1379
+ * 的有意分歧:combo 是表单寻址,本端点是判定查询)。 */
1380
+ interface ProviderSupplyView {
1381
+ provider: string;
1382
+ /** 作用域回显 */
1383
+ scope: ProviderSupplyScope;
1384
+ /** 作用域内逐服务判定(service 轴 = 单元素;name 走 resolveServiceDisplay 单源——恒有值) */
1385
+ services: Array<{
1386
+ service: string;
1387
+ name: string;
1388
+ supplied: boolean;
1223
1389
  }>;
1224
- /** 服务词汇 = 所有携带 service-slots.json 的已装契约包 `.slots` 键并集(缺席 → []) */
1225
- vocabulary: string[];
1226
- /** 词汇 meta 节:per-service {name,description} 展示元数据(多包首声明胜出;缺席 → {}) */
1227
- slotMeta: Record<string, SlotMeta>;
1228
- /** v6 服务归属表:service → moduleId(install id 键控——integrations modules 节键同轴;
1229
- * 双 owner 冲突 → declarationIssues + 先声明胜出;dev 通道以 manifest id 参与归属) */
1230
- ownership: Record<string, string>;
1231
- /** 声明面诊断(OWNERSHIP_CONFLICT / OLD_MANIFEST_KEY) */
1232
- declarationIssues: DeclarationIssue[];
1233
1390
  }
1234
- /** 槽位展示元数据(service-slots.json meta 节元素——宽松提取,字段皆可选;v7 词汇统一 title→name) */
1235
- interface SlotMeta {
1236
- name?: string;
1237
- description?: string;
1391
+ /** GET /credentials:绑定位全量掩码回显(应用状态轴;GET 永无真值) */
1392
+ interface CredentialsView {
1393
+ /** root 位;byInstance 键集 = 注册表 ids ∩ 有 ref(无 ref 的注册实例不出现;未注册 ref 跳过不虚报) */
1394
+ app: CredentialBindingEcho;
1395
+ /** 键集 = 已配置服务;byInstance 键集 = 节点 instances map 全键(含 '*')——键域不对称 = 文件语义忠实镜像 */
1396
+ services: Record<string, CredentialBindingEcho>;
1397
+ }
1398
+ /** 一个形状两处(镜像文件层「标量 + ByInstance」模式) */
1399
+ interface CredentialBindingEcho {
1400
+ /** 本位 credentialRef(root.credentialRef / services[s].credentialRef);ref 缺席/文件缺失 → null */
1401
+ credential: CredentialEcho | null;
1402
+ /** 覆盖位(credentialRefByInstance / instances[k].credentialRef) */
1403
+ byInstance: Record<string, CredentialEcho | null>;
1238
1404
  }
1239
- interface WalkModuleInfo {
1240
- /** install id(packages/ 目录名 / npmModules entry.id) */
1241
- id: string;
1242
- /** 模块目录(本地 packages/<id> 优先;sdk 包 = node_modules 解析位) */
1243
- dir: string;
1244
- /** 发布源包名 */
1245
- pkg: string;
1246
- descriptor: ModuleDescriptor;
1405
+ /** GET /credential-types[?provider=]:凭据结构清单(供给轴静态;?provider= 过滤语义 ≡ ?service=) */
1406
+ interface CredentialTypesView {
1407
+ types: CredentialTypeEntry[];
1247
1408
  }
1248
- /** 富形态供给条目:per-service {implementation, credentialType} 恒数组保真(H1);
1249
- * name/description = 厂商展示元数据(strict manifest descriptor 透传——多包同厂商
1250
- * 首声明胜出,与 owner 同语义;B1 walk 层传播;v7 词汇统一 title→name) */
1251
- interface WalkProviderEntry {
1409
+ interface CredentialTypeEntry {
1410
+ /** '-' = 无凭据语义(mock/local——UI 判 '-' 不渲染凭据表单) */
1411
+ credentialType: string;
1412
+ /** raw draft 2020-12 原文;未声明 = null(ExtraFields 自由键值同轨) */
1413
+ credentialSchema: object | null;
1414
+ }
1415
+ interface EffectiveBinding {
1416
+ /** custom 时 provider = 内联声明厂商名 */
1252
1417
  provider: string;
1253
1418
  implementation: string;
1254
- credentialType: string;
1255
- owner: string;
1256
- /** 厂商展示名(manifest name——多包首声明;缺席 = undefined) */
1257
- name?: string;
1258
- description?: string;
1259
- local?: boolean;
1260
- configSchema?: string;
1261
- credentialSchema?: string;
1262
- services: string[];
1419
+ config?: Record<string, unknown>;
1420
+ /** 'secret://{stem}' */
1421
+ credentialRef?: string;
1422
+ layer: BindingLayer;
1263
1423
  }
1264
- interface WalkCatalog {
1265
- providers: Record<string, Record<string, WalkProviderEntry>>;
1266
- services: Record<string, {
1267
- optional: boolean;
1268
- defaults: Array<{
1269
- provider: string;
1270
- implementation: string;
1271
- }>;
1272
- /** demand meta(name/description 首声明保留——模块 manifest demand 侧 additive;v7 title→name) */
1273
- name?: string;
1274
- description?: string;
1275
- owners: string[];
1276
- }>;
1277
- credentialTypes: Record<string, {
1278
- owner: string;
1279
- packageDir: string;
1280
- credentialSchema?: string;
1281
- }>;
1424
+ /** GET 永无真值 */
1425
+ interface CredentialEcho {
1426
+ /** credentialType(manifest 对齐) */
1427
+ type: string;
1428
+ /** 'secret://{stem}'(文件路径 = config/credentials/{stem}.json 确定性派生——stemToFilePath) */
1429
+ ref: string;
1430
+ /** 前 2 字符 + '****';≤4 字符全掩码;null = 缺字段 */
1431
+ masked: Record<string, string | null>;
1282
1432
  }
1283
- /** 词汇源条目(via 标记供 doctor 幻影槽判定——config 快照 vs 真源;walkManifests 消费忽略此字段) */
1284
- interface DiscoveredSlotSource {
1285
- dir: string;
1286
- slots: string[];
1287
- meta: Record<string, SlotMeta>;
1288
- /** ⓪ config-override(应用级快照/override)|①② package(node_modules 真源)|③ local(候选自身副本) */
1289
- via: 'config-override' | 'package' | 'local';
1433
+ interface ContractsResolution {
1434
+ version: string | null;
1435
+ evaluation: boolean;
1436
+ strictValidation: boolean;
1437
+ notes: string[];
1290
1438
  }
1291
- /** 契约包发现链(探测四跳——词汇源真实布局全覆盖,B0;跳⓪ v7 新增):
1292
- * ⓪ <appDir>/config/service-slots.json(应用级 override 层——meta 首声明胜出 = 用户改名
1293
- * per-service 覆盖;slots 并集 = 无依赖词汇引导快照。CLI seed-once 生成:仅 slots +
1294
- * $comment 指纹,meta 恒空——真源 meta 恒可穿透,用户手写才生效);
1295
- * ① <候选>/node_modules/@tbox.cn/<pkg>/service-slots.json(包根)
1296
- * ② 同包 src/service-slots.json(发布包 src 附带 / 模板 shim 链接)
1297
- * ③ 候选自身 {service-slots.json, src/service-slots.json}(local/codegen 全量副本——
1298
- * mall 生成应用主形态,stage rewriteExportsToSrc 展开后永驻 packages/*,不依赖 install)
1299
- * 词汇覆盖 = Set 并集(跳⓪ 不遮蔽真源新增);meta = 发现序首声明胜出(跳⓪ 最前 = 覆盖权)。
1300
- * 同包双在场(异常态)root 优先。slots 与 meta 单次解析同产(目录枚举零缓存,
1301
- * FX-3:文件**内容**经 file-cache)。 */
1302
- declare function discoverContractPackages(appDir: string, cache?: FileCache): DiscoveredSlotSource[];
1303
- /** walkManifests 主体(单次遍历四产物;目录枚举零缓存——每次调用执行) */
1304
- declare function walkManifests(appDir: string, cache?: FileCache): WalkManifestsResult;
1305
- interface DeclaredModuleInfo {
1306
- id: string;
1307
- /** 装配包名(codegen/local = @app/<id>;sdk = 发布包名) */
1308
- pkg: string;
1309
- mode: 'local' | 'sdk' | 'codegen';
1310
- hasServerEntry: boolean;
1311
- hasClientEntry: boolean;
1312
- hasCards: boolean;
1313
- /** declaration.moduleId(deployment 对账真源;老模块无 declaration → undefined) */
1314
- moduleId?: string;
1439
+ /** 字段级真源 = 谓词结构化输出(H7) */
1440
+ interface IntegrationIssue {
1441
+ severity: 'error' | 'warning';
1442
+ /** 枚举单源 = 谓词文件头检查族编号映射(additive-only) */
1443
+ code: string;
1444
+ message: string;
1445
+ service?: string;
1446
+ module?: string;
1447
+ instance?: string;
1315
1448
  }
1316
- /** 提取 declaration.moduleId(宽松正则——容忍任意嵌套/注释;未声明 → undefined) */
1317
- declare function extractModuleIdFromSource(source: string): string | undefined;
1318
- /**
1319
- * 计算声明集合(含 npm 清单 + 本地模块约定发现)。
1320
- * hasServerEntry/hasClientEntry 决定模块参与哪些装配文件(入口探测,非 post-hoc 修复)。
1321
- * 单源 = walkManifests(npmModules 登记 + packages/* 约定发现双通道;strict 形态进清单)。
1322
- */
1323
- declare function collectDeclaredModules(appDir: string): DeclaredModuleInfo[];
1324
1449
 
1325
1450
  /**
1326
- * 谓词装配单源(FX-2b/):CLI doctor 规则 与 toolkit 工厂(求值轴 / SaveResult.issues)
1327
- * 共用同一 I/O 装配与供给/需求聚合——「面板 issues ≡ doctor issues」的机制保证。
1451
+ * integration-services 谓词单源(integrations v4;自 CLI doctor/integration-services.ts 迁入——
1452
+ * doctor 第 19 条与 toolkit 工厂 evaluateIntegrationServices 共用此函数,单源不变)。
1453
+ * 纯函数、零副作用、零 I/O——contracts 经 input.contracts 注入(resolver 装配,版本解耦)。
1328
1454
  *
1329
- * 迁移源:cli/src/doctor/schema-reader.ts(collectVendorSchemaProfiles,105 行)
1330
- * + doctor 规则壳内联段(#1 effective stem 收集含 root ByInstance/标量兜底 + env 通道 +
1331
- * #9 realmSwitchHints + malls 注册表 + moduleResourceNeeds)。
1455
+ * 结构化输出(H7 v4.3):IntegrationIssue { severity, code, message, service?, module?, instance? }——
1456
+ * 检查逻辑零改动(~24 处 push 机械加 code/定位字段;level→severity 字段同名随 班车,
1457
+ * severity 取值恒等旧 level——doctor 门控行为等价)。
1458
+ * **code 枚举单源 = 本文件头映射表(additive-only;api.md §5 表与本表同步)**:
1459
+ * CREDENTIAL_FILE_MISSING #1 error effective credentialRef 引用凭据文件不在场
1460
+ * CREDENTIAL_TYPE_MISMATCH #2 error 凭据文件 .type 与绑定 credentialType 不一致
1461
+ * SLOT_NOT_DECLARED #3 warning 服务槽无消费方声明(拼写/需求方未安装/旧槽位词汇;
1462
+ * v6.1 归属豁免——owned 服务不报)
1463
+ * SLOT_NOT_CONFIGURED #4 warning 需求方缺口(服务槽未配置)
1464
+ * INSTANCE_SUPPLY_UNMATCHED #5 error 绑定未命中已装供给(槽级/实例级覆盖)
1465
+ * IMPL_WITHOUT_PROVIDER #5/#13 error impl-only(implementation 缺 provider 绑定组头)
1466
+ * INLINE_PROVIDER_INVALID #5 error 内联厂商声明超受控形状(槽级/实例级)
1467
+ * SCHEMA_FILE_MISSING #6 error credentialType schema 引用不存在
1468
+ * DOMAIN_CONFIG_INVALID #7 error root/modules 死配置(键 ∉ 引用厂商 schema properties;
1469
+ * api.md DOMAIN_CONFIG_UNUSED 行预留 warning 级,
1470
+ * 现行为 error 恒等旧谓词——doctor 门控等价)
1471
+ * INSTANCE_KEY_NOT_REGISTERED #8 error ByInstance 键/实例键 ∉ 注册表白名单
1472
+ * REALM_SWITCH_HINT #9 warning 实现覆盖跨厂商(凭据域切换确认)
1473
+ * WILDCARD_ALIGNMENT #10 warning 通配形态齐步提示
1474
+ * MULTI_INSTANCE_NO_DEFAULT v4 warning 多实例无 defaultInstanceId(无 scope 访问落全局会话)
1475
+ * VENDOR_NOT_INSTALLED #11 error root/modules 厂商未命中已装供给
1476
+ * BINDING_UNRESOLVED #12 error 绑定不可解析(resolveEffectiveService 求值失败)
1477
+ * IMPL_WITHOUT_PROVIDER #5/#13 error impl-only(implementation 缺 provider 绑定组头)
1478
+ * RESOURCE_TYPE_UNKNOWN #15 error modules 资源节 type ∉ 词汇表
1479
+ * RESOURCE_NOT_DECLARED #16 warning 资源键/资源 id ∉ 模块声明集
1480
+ * MODULE_CONFIG_DEAD v6 error modules[m](未安装 ∨ owns=0)携带 provider/config
1481
+ * (统一吸收原「#16 升级」特例—— 一码一义)
1482
+ * GLOBAL_FIELD_UNDECLARED #17 warning 全局层键过 #7 但 ∉ 引用厂商 x-tbox-global 并集(G 批;
1483
+ * 零声明厂商整体跳过——#7 同遍历双判定)
1484
+ * ORPHANED_CREDENTIAL 写后对账 warning 凭据文件不再被引用(toolkit 写路径产出,非本谓词)
1485
+ * (v6 退役:DOMAIN_KEY_UNMATCHED #14——domains 键随归属模型退场)
1332
1486
  *
1333
- * **装配源 = walkManifests 双通道产物**(声明性改进:sdk 模式模块(npmModules 登记、
1334
- * node_modules 消费)从 doctor 原单通道(listLocalModules = packages/* 本地扫描)的静默
1335
- * 忽略,转纳入检查面——与 toolkit 求值轴同源)。
1487
+ * 输入形状(调用方负责装载):
1488
+ * - integrations:config/integrations.json 解析产物(宽松 Record 透传——严格 zod 校验归模板 loader)
1489
+ * - suppliedProviders:已声明供给(`${vendor}\u0000${implementation}` 拼接键 → 槽集合;同源聚合)
1490
+ * - demandedServices:已声明需求(service → { optional, owners })
1491
+ * - supplies:派生查表(contracts buildSupplyLookup 产物;缺席 → #12 跳过,M3 降级兼容)
1492
+ * - malls:可选实例 id 白名单(v4 源 = root instances 注册表 ids;缺席 → ByInstance 键检查跳过)
1493
+ * - credentialSchemas:可选(credentialType → schema 文件引用路径;manifest 声明聚合)
1494
+ * - configSchemas:可选(service/slot → schema 文件引用路径)
1336
1495
  *
1337
- * env 参数注入(默认 process.env——工厂边缘):#1 的 env 通道兜底(wanda env 化形态:
1338
- * stem kebab → UPPER_SNAKE,env 键在场即视为已供给,不算缺文件)。
1496
+ * 检查族(v3):
1497
+ * #1 effective credentialRef → 档内凭据文件在场
1498
+ * #2 凭据文件 .type 与绑定 credentialType 对齐(错配 = transport 期「未知认证类型」前置暴露;
1499
+ * 继承绑定(槽级 provider 缺席)经 effective 求值取厂商——supplies 在场时)
1500
+ * #5 实例 impl-only 禁止 + 覆盖命中供给(含槽级内联形状;provider-only = 派生位,合法)
1501
+ * #6 manifest configSchema/credentialSchema 引用文件存在性(内联与 manifest 绑定同查)
1502
+ * #7 root/modules 死配置:root.config/configByInstance/modules[m].config 键 ⊆ 引用厂商(并集)
1503
+ * 各槽 schema properties——引用面 = root.provider ∪ modules.*.provider ∪ 槽级(terse 化防退化);
1504
+ * modules 层 per-module 生效厂商 = resolveModuleBinding 单源(≡ modules[m].provider ?? root.provider)
1505
+ * #8 ByInstance/实例键 ∈ malls 白名单(v4:源 = root instances 注册表 ids——参考表在场时
1506
+ * 激活;'**' 通配键豁免;注册表缺席 → 跳过;modules 键 = install id 非 instanceId,不适用)
1507
+ * #9 实现覆盖跨厂商提示(realm switch——凭据域切换确认)
1508
+ * #11 root/modules 厂商未命中已装供给(vendor 集合 = suppliedProviders 键前缀展开)
1509
+ * #12 绑定可解析性:逐 (service, instanceId) 经 contracts resolveEffectiveService 求值
1510
+ * (级联单源复用,谓词零级联实现;v6 ownerOf=ownership 显式参透传),binding-unresolved → error
1511
+ * #13 槽级/实例级 impl-only(implementation 需伴随 provider——provider 是绑定组头;
1512
+ * zod 之外的第二道防线——doctor 读裸 JSON)
1513
+ * MODULE_CONFIG_DEAD:modules[m] 携带 provider/config 且(m ∉ installedModuleIds ∨ ownership
1514
+ * 无任何 service 归属 m)→ error(键级 #16 warning 与本检查可同节点共发——键级 vs 值级不同断言面)
1515
+ * #17(G 批):与 #7 同遍历双判定——键 ∈ schema properties 但 ∉ x-tbox-global 并集 →
1516
+ * warning;引用厂商零全局声明(集空/缺席)→ 该厂商键整体跳过;检查序在 MODULE_CONFIG_DEAD 后
1517
+ * #15-#16 modules 资源节对账(v5 延续):type ∉ RESOURCE_TYPE_IDS → error;键 ∉ 已装模块 id 集 /
1518
+ * 资源 id ∉ 模块 manifest declare.resources 声明集 → warning
1339
1519
  */
1340
- interface PredicateIoInputs {
1341
- /** #1:effective 候选 stem → 缺文件(env 通道在场不算缺失) */
1342
- credentialFileMissing: Record<string, boolean>;
1343
- /** #2:凭据文件 stem → .type(无 type 则缺键) */
1344
- credentialFileType: Record<string, string | undefined>;
1345
- /** #6:credentialType → schema 引用文件缺失 */
1346
- credentialSchemaMissing: Record<string, boolean>;
1347
- /** #7:厂商 → configSchema properties 键集并集 */
1348
- vendorConfigKeys: Record<string, Set<string>>;
1349
- /** #17(G 批):厂商 → x-tbox-global 标记键集(与 vendorConfigKeys 同循环收集——零新增 IO) */
1350
- vendorGlobalConfigKeys: Record<string, Set<string>>;
1351
- /** #7:厂商 → configSchema 引用缺失(跳过该厂商死配置判定) */
1352
- vendorConfigSchemaMissing: Record<string, boolean>;
1353
- /** #9:实现覆盖跨厂商提示文案(已成形——谓词直投) */
1354
- realmSwitchHints: string[];
1355
- /** #8:root instances 注册表 ids(在场才传;缺席 → 键检查跳过) */
1356
- malls?: string[];
1357
- /** #15-#16:已装模块 id → manifest declare.resources 声明 id 集 */
1358
- moduleResourceNeeds: Record<string, ReadonlySet<string>>;
1359
- }
1360
- /** 装配全产物(= PredicateIoInputs + 供给/需求/归属聚合——喂 evaluateIntegrationServices 的
1361
- * 非 contracts/integrations 入参全集,两消费方 spread 直投,零各自组装) */
1362
- interface PredicateAssembly extends PredicateIoInputs {
1520
+
1521
+ /** contracts 注入面(resolver 装配产物运行时视图 = EvaluationExports 求值子集) */
1522
+ type PredicateContracts = Pick<EvaluationExports, 'resolveEffectiveService' | 'buildSupplyLookup' | 'normalizeInstances' | 'RESOURCE_TYPE_IDS'>;
1523
+ /** 派生查表形状(contracts buildSupplyLookup 产物;结构等价 TIER0 SupplyLookup——谓词零 contracts 静态依赖) */
1524
+ type SupplyLookup = Record<string, readonly string[]>;
1525
+ interface IntegrationServicePredicateInput {
1526
+ integrations: {
1527
+ provider?: string;
1528
+ config?: Record<string, unknown>;
1529
+ configByInstance?: Record<string, Record<string, unknown>>;
1530
+ credentialRef?: string;
1531
+ credentialRefByInstance?: Record<string, string>;
1532
+ services: Record<string, {
1533
+ provider?: string | Record<string, unknown>;
1534
+ implementation?: string;
1535
+ config?: Record<string, unknown>;
1536
+ credentialRef?: string;
1537
+ instances?: Record<string, {
1538
+ enabled?: boolean;
1539
+ provider?: unknown;
1540
+ implementation?: unknown;
1541
+ credentialRef?: string;
1542
+ }>;
1543
+ }>;
1544
+ /** v4 部署实例注册表(参考表——#8 白名单源 + 多实例无默认 warning) */
1545
+ instances?: Array<{
1546
+ id: string;
1547
+ name?: string;
1548
+ attributes?: Record<string, unknown>;
1549
+ }>;
1550
+ /** v4 默认实例(normalizeInstances 解析语义:显式 ?? 单候选唯一解) */
1551
+ defaultInstanceId?: string | null;
1552
+ /** v6 模块集成位(modules 节三键——宽松透传;严格 zod 归模板 loader) */
1553
+ modules?: Record<string, {
1554
+ provider?: string;
1555
+ config?: Record<string, unknown>;
1556
+ resources?: Record<string, {
1557
+ type?: unknown;
1558
+ }>;
1559
+ }>;
1560
+ };
1561
+ /** 已声明供给(`${vendor}\u0000${implementation}` → 槽集合;credentialType 供 #2/#6 绑定侧对齐) */
1363
1562
  suppliedProviders: Record<string, {
1364
1563
  services: string[];
1365
1564
  owner: string;
1366
1565
  credentialType?: string;
1367
1566
  }>;
1567
+ /** 已声明需求(service → { optional, owners }) */
1368
1568
  demandedServices: Record<string, {
1369
1569
  optional: boolean;
1370
1570
  owners: string[];
1371
1571
  }>;
1372
- /** v6:服务归属表 + 已装模块 id 集(MODULE_CONFIG_DEAD / #12 ownerOf 透传) */
1572
+ /** 派生查表(buildSupplyLookup 产物;缺席 → #12 跳过 + #2 继承绑定不查 credentialType) */
1573
+ supplies?: SupplyLookup;
1574
+ /** v6 服务归属表(walk.ownership——#12 ownerOf 透传 + MODULE_CONFIG_DEAD owns=0 判据;
1575
+ * 缺席 = 归属面不可判 → MODULE_CONFIG_DEAD 退化为仅「未安装」分支) */
1373
1576
  ownership?: Record<string, string>;
1577
+ /** v6 已装模块 id 集(.tbox/app.json entry.id ∪ packages/ 目录名;缺席 → 「未安装」分支跳过) */
1374
1578
  installedModuleIds?: ReadonlySet<string>;
1579
+ /** malls 白名单(deployments 控制面 extract;缺席 → ByInstance 键检查跳过) */
1580
+ malls?: string[];
1581
+ /** credentialType → schema 文件引用缺失(manifest 声明指向缺失文件;#6) */
1582
+ credentialSchemaMissing?: Record<string, boolean>;
1583
+ /** 厂商 → 槽 schema properties 键集(#7 用;调用方从 manifest configSchema 引用解析) */
1584
+ vendorConfigKeys?: Record<string, Set<string>>;
1585
+ /** G 批:厂商 → x-tbox-global 标记键集(#17 用;#7 同循环收集——零新增 IO);
1586
+ * 缺席/空集 = 该厂商零声明 → #17 对其键整体跳过 */
1587
+ vendorGlobalConfigKeys?: Record<string, Set<string>>;
1588
+ /** 厂商 → configSchema 引用文件缺失(#7 跳过该厂商——无 schema 不能判死配置) */
1589
+ vendorConfigSchemaMissing?: Record<string, boolean>;
1590
+ /** 凭据文件缺失(#1:credentialRef stem → 档内 credentials/<stem>.json 在场;域中立注入) */
1591
+ credentialFileMissing?: Record<string, boolean>;
1592
+ /** 凭据文件 .type(stem → type;#2 对齐判定——文件无 type 则缺键,跳过) */
1593
+ credentialFileType?: Record<string, string | undefined>;
1594
+ /** #9:实现覆盖跨厂商提示位(CLI 侧组装) */
1595
+ realmSwitchHints?: string[];
1596
+ /** v5:已装模块 id → manifest declare.resources 声明 id 集(值空集 = 无声明,资源级跳过;
1597
+ * 缺席 = 无需求面信息——键未知/资源未声明检查跳过,type 检查恒跑) */
1598
+ moduleResourceNeeds?: Record<string, ReadonlySet<string>>;
1375
1599
  }
1376
- /** stem → env 键(kebab → UPPER_SNAKE;与 SDK/provider-secret env 兜底同公式) */
1377
- declare function refToEnvKey(stem: string): string;
1378
- /**
1379
- * 装配谓词输入全集(供给/需求聚合 + I/O 档案)。
1380
- * @param walk 调用方已执行的 walkManifests 产物(目录枚举零缓存——每方法调用独立)
1381
- */
1382
- declare function buildPredicateAssembly(appDir: string, walk: WalkManifestsResult, integrations: Record<string, unknown>, env?: Readonly<Record<string, string | undefined>>): PredicateAssembly;
1383
-
1384
- /**
1385
- * 应用级 integrations 求值(cli-remove-prune-and-new.4):doctor integration-services 规则内
1386
- * "装配+求值"序列的单源抽取(FX-2b/ 轨迹延续——此前 buildPredicateAssembly 已单源,本函数
1387
- * 将 walk→supplies→assembly→evaluate 全序列收口)。
1388
- *
1389
- * 消费方:
1390
- * - doctor integration-services 规则(外壳保留:stale 防线/文件读取/env 展开/形状守卫/分级投射)
1391
- * - pruneIntegrationBindings(prune 判据 ≡ doctor 判据的构造性同源载体)
1392
- *
1393
- * 契约:调用方须先 `resolveContractsForApp` 并确保 `strictValidation`(本函数不再分级门控——
1394
- * doctor 的 warning/error 升级指引与 prune 的 skip 语义分属两消费方,不收口)。
1395
- */
1396
- declare function evaluateAppIntegrationIssues(appDir: string, integrations: Record<string, unknown>, contracts: ResolvedContracts, env?: Readonly<Record<string, string | undefined>>): Promise<IntegrationServiceIssue[]>;
1397
1600
 
1398
- /**
1399
- * integrations.json 死绑定清理(cli-remove-prune-and-new 核心件)。
1400
- *
1401
- * 不变式:**删除判据 ≡ doctor integration-services 报错判据(构造性同源)**——消费 doctor 同一
1402
- * 共享求值器 evaluateAppIntegrationIssues 的结构化 issue,code 白名单
1403
- * {VENDOR_NOT_INSTALLED, BINDING_UNRESOLVED, MODULE_CONFIG_DEAD} + 守卫(绑定引用链候选
1404
- * provider ∈ installedVendors 即保留,排除活厂商错配)→ 删除域严格 = "供给载体消亡"。
1405
- * v6:模块卸载 → modules[m] **整节点确定性清理**(provider+config+resources——
1406
- * 模块消亡清理 vs 集成位编辑保全不矛盾;MODULE_CONFIG_DEAD 为判据源)。
1407
- *
1408
- * 由此推论(均已实证):需求侧孤儿绑定(demand 消失、供给在场)保留——doctor 判其合法;用户
1409
- * 预配置绑定受保护;一次 remove 自愈全文件历史死债;凭据类 issue(CREDENTIAL_FILE_MISSING 等)
1410
- * 刻意不进白名单,原样保留。
1411
- *
1412
- * 写侧三防线(镜像 write core):归一化(空节点删键)→ parseIntegrationsConfig
1413
- * 严格校验(失败弃写)→ writeAtomic。凭据孤儿只报告不清理(——与 DELETE 管线现行为一致)。
1414
- * 全空(无任何存活绑定)→ 删文件——ensureMockBindings(缺席即生成)在重装供给时再生闭环。
1415
- *
1416
- * 最佳努力语义:谓词不可用(contracts 未安装/降级、env 缺失、求值 throw)→ skipped 返回 +
1417
- * 文件原样,绝不阻断 remove 本体。
1418
- */
1419
- interface PruneResult {
1420
- /** 被清除的绑定节点描述(remove 日志行,如 'root.provider=mock' / 'services.member.account') */
1421
- removed: string[];
1422
- /** 孤儿凭据(只报告不清理——reconcileOrphanCredentials 产物 message) */
1423
- orphanCredentials: string[];
1424
- /** 跳过原因(正常路径 undefined;not-configured = integrations.json 缺席,兼容态零动作) */
1425
- skipped?: 'predicate-unavailable' | 'validation-failed' | 'not-configured';
1426
- }
1427
- declare function pruneIntegrationBindings(appDir: string): Promise<PruneResult>;
1601
+ type IntegrationServiceIssue = IntegrationIssue;
1602
+ /** 内联厂商声明受控形状(v2:provider/credentialType/configSchema) */
1603
+ declare function isControlledInlineProvider(raw: unknown): boolean;
1604
+ /** #8 检查族导出(FX-2b 单源):toolkit 写路径轻量复查(registryCheck)消费——
1605
+ * 覆盖 configByInstance / credentialRefByInstance / services[s].instances 三键位;
1606
+ * malls = root instances 注册表 ids(参考表缺席 → 消费方跳过,勿传空集)。 */
1607
+ declare function checkInstanceKeys(integrations: {
1608
+ configByInstance?: Record<string, unknown>;
1609
+ credentialRefByInstance?: Record<string, unknown>;
1610
+ services?: Record<string, {
1611
+ instances?: Record<string, unknown>;
1612
+ }>;
1613
+ }, malls: readonly string[]): IntegrationServiceIssue[];
1614
+ /** 谓词主体:integrations 配置 × catalog 声明 交叉校验(error/warning 分级;contracts 注入) */
1615
+ declare function evaluateIntegrationServices(input: IntegrationServicePredicateInput & {
1616
+ contracts: PredicateContracts;
1617
+ }): IntegrationServiceIssue[];
1428
1618
 
1429
1619
  /**
1430
- * 双键寻址(v7 词汇统一):路径参数双键——id 精确优先 → 展示名唯一命中兜底 → 404
1431
- * (多命中 fail-visible,message 列候选 + 指引改用 id;复用既有 404 码零新错误码)。
1620
+ * walkManifests(appDir)——单次遍历四产物(/;ai-build)。
1432
1621
  *
1433
- * **消费边界(O1——双键语义单点)**:仅 factory.ts 控制面七方法入口接入;
1434
- * views / write-core / CLI 恒 id-only 纯函数。
1622
+ * manifest 候选路径探测(packages/<id>/tbox.module.json 优先 → node_modules/<pkg>/tbox.module.json;
1623
+ * tbox-app-dev dev 真身经 .tbox-dev.local/dev-manifest.json redirects 独立 catalog 通道直达)一次遍历同时产出:
1624
+ * 1. modules:已装模块清单(declared;demand meta name/description 透传)
1625
+ * 2. catalog(富形态):providers 嵌套(vendor→impl→entry,per-service {implementation, credentialType}
1626
+ * 保真——同厂商异构/多实现合法,/H1)+ 需求侧聚合
1627
+ * 3. serviceSchemas:per-service schema 复合键表——键 `${provider}\u0000${service}`(H2,同一服务
1628
+ * 多厂商供给各自 schema 零碰撞);多 impl 同 (provider, service) 异 schema → 声明序首个
1629
+ * 4. vocabulary:所有携带 service-slots.json 的已装契约包该文件 `.slots` 键并集(fs 直读、
1630
+ * `$comment` 忽略;探测三跳 = ① <候选>/node_modules/@tbox.cn/<pkg>/service-slots.json(包根)
1631
+ * ② 同包 src/service-slots.json(发布包 src 附带 / 模板 shim 链接)
1632
+ * ③ 候选自身 {service-slots.json, src/service-slots.json}(local/codegen 全量副本——
1633
+ * mall 生成应用主形态,不依赖 install);零缓存枚举,与 manifest 探测同机制;
1634
+ * 多行业 contracts-* 天然扩展);缺席 → [](退化 demanded ∪ configured)
1635
+ * 5. slotMeta:词汇 meta 节(per-service {name,description} 展示元数据——消费端兜底链
1636
+ * 词汇 > demand > id,views/context resolveServiceDisplay 单源);多包发现序首声明胜出
1637
+ * (与 catalog addSlots 同语义);contracts-mall 词汇锁保证 mall 域全量覆盖;缺席 → {}
1638
+ * 6. ownership:service → moduleId 归属表(v6——declare.owns 聚合;install id 键控;
1639
+ * 双 owner 冲突 → declarationIssues OWNERSHIP_CONFLICT + 先声明胜出)
1640
+ * 7. declarationIssues:声明面诊断(OWNERSHIP_CONFLICT / OLD_MANIFEST_KEY—— 通道)
1435
1641
  *
1436
- * **纯参数式**:configuredKeys 由调用方注入——零 integrations 依赖、零 IO,
1437
- * 解析输入恒为 walk 产物快照 + 调用方键集。
1438
- */
1439
- /** 模块双键解析:id 精确 → 展示名(descriptor.name ?? id)唯一命中 → 404。 */
1440
- declare function resolveModuleKey(walk: WalkManifestsResult, key: string): WalkModuleInfo;
1441
- /** 服务双键解析 → 真实 service id:服务键集(词汇 ∪ demand ∪ 供给足迹 ∪ configuredKeys ∪ 归属)
1442
- * 精确命中 → 展示名(slotMeta.name ?? catalog.services[].name)唯一命中 → 404。
1443
- * configuredKeys = 当前集成配置 services 节键集(调用方注入)。
1444
- * v6.1 += 归属键(walk.ownership——纯归属无词汇/demand/供给的 owns 合法,O6 对称)。 */
1445
- declare function resolveServiceKey(walk: WalkManifestsResult, configuredKeys: readonly string[], key: string): string;
1446
-
1447
- /**
1448
- * .tbox/app.json npmModules 读写(自 CLI manifest.ts 迁入——assembly 层目录知识单源)。
1449
- * npmModules 登记 = sdk 包双语义磁盘足迹之一(业务包 = packages/<id>/ 目录,sdk 包 = 本清单登记)。
1450
- * 本地模块(packages/module-*)不在 npmModules 登记——靠 tbox.module.json 约定发现。
1642
+ * **约束(FX-3/ 边界)**:目录枚举零缓存——readdir / node_modules 候选探测 / `.tbox/app.json` 读取 /
1643
+ * dev-manifest 读取每次执行(枚举输入保持 fresh——agent 装卸模块下一笔即见);manifest/service-slots
1644
+ * **文件内容**经 file-cache(`cache` 可选参——工厂/写内核传本实例 cache(stat 指纹自愈 + 写后失效);
1645
+ * CLI 传 undefined 即全 fresh)。
1646
+ * 宽松解析语义(坏文件静默 + 重复键首声明保留)零改动。
1451
1647
  */
1452
- type ModuleMode = 'local' | 'sdk' | 'codegen';
1453
- interface NpmModuleEntry {
1454
- /** 模块短 id(如 "module-member"),装配别名来源 */
1455
- id: string;
1456
- /** 发布源包名;codegen 的应用内身份由 id 派生为 @app/<id>,sdk 保持该包名 */
1457
- package: string;
1458
- /** 安装版本 */
1459
- version: string;
1460
- /** 分发模式 */
1461
- mode: ModuleMode;
1462
- /** 3-way merge 基线(codegen 模式) */
1463
- baseVersion?: string;
1464
- /**
1465
- * 条目类别(单一模板统一化):'ui-kit' = 壳 UI 组件包——create 全量继承后
1466
- * 不再承担保留判据(模板 manifest = 出厂装配真源);现职 = update 三方合并锚 +
1467
- * sync-agent-ui-kit 副本 identity 标记(由该脚本派生维护)。
1468
- */
1469
- kind?: 'ui-kit';
1648
+ /** 声明面诊断(v6 通道——OWNERSHIP_CONFLICT / OLD_MANIFEST_KEY;error 级) */
1649
+ type DeclarationIssue = {
1650
+ severity: 'error';
1651
+ code: 'OWNERSHIP_CONFLICT';
1652
+ message: string;
1653
+ module?: string;
1654
+ } | {
1655
+ severity: 'error';
1656
+ code: 'OLD_MANIFEST_KEY';
1657
+ message: string;
1658
+ module?: string;
1659
+ };
1660
+ interface WalkManifestsResult {
1661
+ /** declared 产物(install id + descriptor;demand meta 透传) */
1662
+ modules: WalkModuleInfo[];
1663
+ /** 富形态 catalog(providers 嵌套保真 + 需求聚合 + credentialTypes) */
1664
+ catalog: WalkCatalog;
1665
+ /** per-service schema 复合键表:`${provider}\u0000${service}` → schema 引用 + 包根 */
1666
+ serviceSchemas: Record<string, {
1667
+ configSchema?: string;
1668
+ credentialSchema?: string;
1669
+ packageDir: string;
1670
+ }>;
1671
+ /** 服务词汇 = 所有携带 service-slots.json 的已装契约包 `.slots` 键并集(缺席 → []) */
1672
+ vocabulary: string[];
1673
+ /** 词汇 meta 节:per-service {name,description} 展示元数据(多包首声明胜出;缺席 → {}) */
1674
+ slotMeta: Record<string, SlotMeta>;
1675
+ /** v6 服务归属表:service → moduleId(install id 键控——integrations modules 节键同轴;
1676
+ * 双 owner 冲突 → declarationIssues + 先声明胜出;dev 通道以 manifest id 参与归属) */
1677
+ ownership: Record<string, string>;
1678
+ /** 声明面诊断(OWNERSHIP_CONFLICT / OLD_MANIFEST_KEY) */
1679
+ declarationIssues: DeclarationIssue[];
1470
1680
  }
1471
- interface AppManifest {
1472
- templateVersion: string;
1473
- npmModules: NpmModuleEntry[];
1681
+ /** 槽位展示元数据(service-slots.json meta 节元素——宽松提取,字段皆可选;v7 词汇统一 title→name) */
1682
+ interface SlotMeta {
1683
+ name?: string;
1684
+ description?: string;
1474
1685
  }
1475
- declare function manifestPath(appDir: string): string;
1476
- /** 读应用 manifest(缺席 → null;损坏/版本非法 → null——宽松解析与 CLI 语义一致) */
1477
- declare function readAppManifest(appDir: string): AppManifest | null;
1478
- /** 写应用 manifest(目录缺席物化;同步——写核心串行队列内使用) */
1479
- declare function writeAppManifest(appDir: string, manifest: AppManifest): void;
1480
- /** 小程序容器登记项(miniapp-container init 写入;与 npmModules 正交,不参与装配/doctor) */
1481
- interface MiniappContainerEntry {
1482
- /** 平台 id:'alipay' / 'weapp'(= CLI platform 参数,展开目录名后缀) */
1686
+ interface WalkModuleInfo {
1687
+ /** install id(packages/ 目录名 / npmModules entry.id) */
1483
1688
  id: string;
1484
- /** 源包名(@tbox.cn/app-miniapp-container-*) */
1485
- package: string;
1486
- version: string;
1487
- /** 展开目录(相对应用根,如 'apps/miniapp-container-alipay') */
1689
+ /** 模块目录(本地 packages/<id> 优先;sdk 包 = node_modules 解析位) */
1488
1690
  dir: string;
1489
- }
1490
- interface AppManifestFull extends AppManifest {
1491
- /** 已初始化的小程序容器(可选——旧 manifest 无此字段,读侧归一为 []) */
1492
- miniappContainers?: MiniappContainerEntry[];
1493
- }
1494
- /** 读应用 manifest(完整面——miniappContainers 归一) */
1495
- declare function readAppManifestFull(appDir: string): AppManifestFull | null;
1496
- declare function upsertNpmModule(manifest: AppManifest, entry: NpmModuleEntry): AppManifest;
1497
- declare function removeNpmModule(manifest: AppManifest, id: string): AppManifest;
1498
- /** 登记小程序容器(按 id 去重替换;miniapp-container init 用) */
1499
- declare function upsertMiniappContainer(manifest: AppManifestFull, entry: MiniappContainerEntry): AppManifestFull;
1500
- /** 更新某模块的元数据(update 命令用:version / baseVersion) */
1501
- declare function updateNpmModule(manifest: AppManifest, id: string, patch: Partial<Pick<NpmModuleEntry, 'version' | 'baseVersion'>>): AppManifest;
1502
- /**
1503
- * 模块 id 合法性:小写字母/数字开头,单词段以单个中划线分隔(无连续/尾部中划线),
1504
- * 防路径穿越/目录注入,并保证 camelCaseId 派生别名唯一(a-b 与 a--b 不允许共存碰撞)。
1505
- */
1506
- declare function isValidModuleId(id: string): boolean;
1507
- /** 校验失败抛出(统一错误信息) */
1508
- declare function assertValidModuleId(id: string, source: string): void;
1509
-
1510
- /** 桥源形态冻结:ProviderCatalog = contracts TIER0 形状(providers/services/credentialTypes) */
1511
- interface BridgeProviderCatalog {
1512
- providers: Record<string, Record<string, {
1513
- provider: string;
1514
- implementation: string;
1515
- credentialType: string;
1516
- owner: string;
1517
- local?: boolean;
1518
- configSchema?: string;
1519
- credentialSchema?: string;
1520
- services: string[];
1521
- }>>;
1691
+ /** 发布源包名 */
1692
+ pkg: string;
1693
+ descriptor: ModuleDescriptor;
1694
+ }
1695
+ /** 富形态供给条目:per-service {implementation, credentialType} 恒数组保真(H1);
1696
+ * name/description = 厂商展示元数据(strict manifest descriptor 透传——多包同厂商
1697
+ * 首声明胜出,与 owner 同语义;B1 walk 层传播;v7 词汇统一 title→name) */
1698
+ interface WalkProviderEntry {
1699
+ provider: string;
1700
+ implementation: string;
1701
+ credentialType: string;
1702
+ owner: string;
1703
+ /** 厂商展示名(manifest name——多包首声明;缺席 = undefined) */
1704
+ name?: string;
1705
+ description?: string;
1706
+ local?: boolean;
1707
+ configSchema?: string;
1708
+ credentialSchema?: string;
1709
+ services: string[];
1710
+ }
1711
+ interface WalkCatalog {
1712
+ providers: Record<string, Record<string, WalkProviderEntry>>;
1522
1713
  services: Record<string, {
1523
1714
  optional: boolean;
1524
1715
  defaults: Array<{
1525
1716
  provider: string;
1526
1717
  implementation: string;
1527
1718
  }>;
1719
+ /** demand meta(name/description 首声明保留——模块 manifest demand 侧 additive;v7 title→name) */
1720
+ name?: string;
1721
+ description?: string;
1528
1722
  owners: string[];
1529
1723
  }>;
1530
1724
  credentialTypes: Record<string, {
1531
1725
  owner: string;
1726
+ packageDir: string;
1532
1727
  credentialSchema?: string;
1533
1728
  }>;
1534
- }
1535
- /** 富形态(工厂迁移面):walkManifests 产物直通 */
1536
- declare function loadProviderCatalogRaw(appDir: string): WalkCatalog;
1537
- /** 桥源(形态冻结):富形态 → 桥形状投影(demand meta name/description 剥离——桥面无此字段,
1538
- * additive 差异声明见 app-sdk 桥 golden) */
1539
- declare function loadProviderCatalog(appDir: string): BridgeProviderCatalog;
1540
- interface ProviderServiceSchemas {
1541
- provider: string;
1542
- service: string;
1543
- /** 恒数组(H1——通常 1;多 impl = 升级窗口) */
1544
- implementations: Array<{
1545
- implementation: string;
1546
- credentialType: string;
1729
+ /** 厂商展示元数据单源(v8——全厂商统一,slots 厂商 + `declare.providers.id` 零槽自声明同路径;
1730
+ * 首声明胜出与 owner 同语义。U6 守卫:自声明包声明外来厂商槽 → 供给照常贡献、meta 不附着)。 */
1731
+ vendorMeta: Record<string, {
1732
+ owner: string;
1733
+ name?: string;
1734
+ description?: string;
1547
1735
  }>;
1548
- integrationSchemas: {
1549
- configSchema: object | null;
1550
- credentialSchema: object | null;
1551
- };
1552
- }
1553
- type ProviderServiceSchemasResult = {
1554
- found: true;
1555
- detail: ProviderServiceSchemas;
1556
- } | {
1557
- found: false;
1558
- reason: 'provider-not-found' | 'supply-not-found';
1559
- };
1560
-
1561
- /**
1562
- * integrations.json 文件级读(read)。
1563
- * 严格校验面(≥0.9)在场 → contracts parseIntegrationsConfig(assertNoInlineSecrets →
1564
- * 旧键直切防线 → zod strict);缺席/降级 → 原文 JSON 透传(谓词宽松透传语义——
1565
- * doctor 读裸 JSON 先例;写路径门控在工厂边缘,读不阻断静态面)。
1566
- */
1567
- interface ReadIntegrationsResult {
1568
- /** 解析产物(严格 zod 产物或原文 JSON;文件缺席 → null) */
1569
- config: Record<string, unknown> | null;
1570
- /** 严格校验是否已应用(false = 原文透传——<0.9 或未解析降级态) */
1571
- strict: boolean;
1572
- contracts: ResolvedContracts;
1573
1736
  }
1574
- /** 文件级读(cache 注入优先;无 cache 直读——目录枚举零缓存约束不涉文件内容) */
1575
- declare function readIntegrationsConfig(appDir: string, cache?: FileCache): Record<string, unknown> | null;
1576
- /** 带严格校验的读(求值/写路径用——门控由工厂边缘断言,本函数按 strictValidation 分派) */
1577
- declare function readIntegrationsStrict(appDir: string, cache?: FileCache): Promise<ReadIntegrationsResult>;
1578
-
1579
- /**
1580
- * 凭据双工件·写端(credentials;FX-1c 拆分—— 定序):
1581
- * credentials / credentialsByInstance(body 唯一非文件字段)→ **纯派生 plan(零 I/O)**
1582
- * → 消费方(write.ts)ref 回填节点(先于 no-diff 判定)→ 严格校验通过后 `writeCredentialArtifacts`
1583
- * 落盘(dryRun → 零写盘 + existsSync 预览)。同 stem 已在场 → 重写 + overwrote:true。
1584
- * 孤儿凭据 = **写后对账**(扫描文件全量 credentialRef 引用 vs 凭据目录全集 →
1585
- * ORPHANED_CREDENTIAL warning——统一覆盖 DELETE 与 PUT 替换两类来源,只报告不自动清理)。
1586
- */
1587
- interface CredentialInput {
1588
- type: string;
1589
- values: Record<string, string>;
1590
- }
1591
- interface AppliedCredential {
1592
- stem: string;
1593
- ref: string;
1594
- overwrote: boolean;
1595
- }
1596
- /** 凭据工件计划项(纯派生产物——stem/ref 确定性;input 供落盘/校验消费) */
1597
- interface PlannedCredential {
1598
- /** 实例级(credentialsByInstance)时在场;应用/服务级根凭据缺席 */
1599
- instanceId?: string;
1600
- stem: string;
1601
- ref: string;
1602
- input: CredentialInput;
1737
+ /** 词汇源条目(via 标记供 doctor 幻影槽判定——config 快照 vs 真源;walkManifests 消费忽略此字段) */
1738
+ interface DiscoveredSlotSource {
1739
+ dir: string;
1740
+ slots: string[];
1741
+ meta: Record<string, SlotMeta>;
1742
+ /** ⓪ config-override(应用级快照/override)|①② package(node_modules 真源)|③ local(候选自身副本) */
1743
+ via: 'config-override' | 'package' | 'local';
1603
1744
  }
1604
- interface OrphanIssue {
1605
- severity: 'warning';
1606
- code: 'ORPHANED_CREDENTIAL';
1607
- service?: string;
1608
- instance?: string;
1609
- message: string;
1745
+ /** 契约包发现链(探测四跳——词汇源真实布局全覆盖,B0;跳⓪ v7 新增):
1746
+ * ⓪ <appDir>/config/service-slots.json(应用级 override 层——meta 首声明胜出 = 用户改名
1747
+ * per-service 覆盖;slots 并集 = 无依赖词汇引导快照。CLI seed-once 生成:仅 slots +
1748
+ * $comment 指纹,meta 恒空——真源 meta 恒可穿透,用户手写才生效);
1749
+ * ① <候选>/node_modules/@tbox.cn/<pkg>/service-slots.json(包根)
1750
+ * ② 同包 src/service-slots.json(发布包 src 附带 / 模板 shim 链接)
1751
+ * ③ 候选自身 {service-slots.json, src/service-slots.json}(local/codegen 全量副本——
1752
+ * mall 生成应用主形态,stage rewriteExportsToSrc 展开后永驻 packages/*,不依赖 install)
1753
+ * 词汇覆盖 = Set 并集(跳⓪ 不遮蔽真源新增);meta = 发现序首声明胜出(跳⓪ 最前 = 覆盖权)。
1754
+ * 同包双在场(异常态)root 优先。slots 与 meta 单次解析同产(目录枚举零缓存,
1755
+ * FX-3:文件**内容**经 file-cache)。 */
1756
+ declare function discoverContractPackages(appDir: string, cache?: FileCache): DiscoveredSlotSource[];
1757
+ /** walkManifests 主体(单次遍历四产物;目录枚举零缓存——每次调用执行) */
1758
+ declare function walkManifests(appDir: string, cache?: FileCache): WalkManifestsResult;
1759
+ interface DeclaredModuleInfo {
1760
+ id: string;
1761
+ /** 装配包名(codegen/local = @app/<id>;sdk = 发布包名) */
1762
+ pkg: string;
1763
+ mode: 'local' | 'sdk' | 'codegen';
1764
+ hasServerEntry: boolean;
1765
+ hasClientEntry: boolean;
1766
+ hasCards: boolean;
1767
+ /** declaration.moduleId(deployment 对账真源;老模块无 declaration → undefined) */
1768
+ moduleId?: string;
1610
1769
  }
1611
- /** 凭据工件在场探测(dryRun 预览与对账共用) */
1612
- declare function credentialArtifactExists(appDir: string, stem: string): boolean;
1613
- /** 孤儿凭据写后对账:凭据目录全集 − integrations.json 全量引用 = 孤儿(只报告不清理) */
1614
- declare function reconcileOrphanCredentials(appDir: string): OrphanIssue[];
1615
-
1770
+ /** 提取 declaration.moduleId(宽松正则——容忍任意嵌套/注释;未声明 → undefined) */
1771
+ declare function extractModuleIdFromSource(source: string): string | undefined;
1616
1772
  /**
1617
- * 写核心(write;FX-1c 管线重排—— 九步定序 + D-B2 语义 + 输入扩位):
1618
- * PUT = 节点全量替换(三同构——body ≡ 文件节点;三 PUT 端点无例外)。
1619
- *
1620
- * 九步定序(applyApp / applyService 同构):
1621
- * 1 输入约束(assertSafeNames 值位 + assertSafeInstanceKeys map 键位——)
1622
- * 2 合并 node → next;文件缺席 → 骨架物化(语义翻转提示入 issues)
1623
- * 3 凭据校验链(type 匹配 400 + credentialSchema ajv 字段级——schema 缺席宽松;dryRun 也跑)
1624
- * 4 凭据 stem/ref **纯派生**(plan*——零 I/O)+ ref 回填节点(**先于 no-diff**:
1625
- * node 缺 ref + 带 credentials → 节点变化 → 全量写;node 已含同 ref → 节点不变 → 纯凭据写)
1626
- * 5 noDiff(**深度结构等价**,非 stringify);hasCredentialInput
1627
- * 6 noDiff && 无凭据输入 → 短路 written:false
1628
- * 7 严格整文档校验(contracts parseIntegrationsConfig——触发 = !noDiff ∥ 有凭据输入)
1629
- * 8 凭据工件落盘(**后置于校验通过**——防「凭据已写 + zod 拒绝」不一致态;
1630
- * dryRun → writeCredentialArtifacts 零写盘 + existsSync 预览)
1631
- * 9 finalize:planned = 将触碰(files 预览单源——dryRun 响应 ≡ 同 body 真实写,files 逐字对称);
1632
- * written = 实写(!dryRun 派生,D-B2);restartScheduled = written && onApplied(凭据影响 boot 装配——
1633
- * 重启正当);写后缓存失效
1634
- * 归一化:N1 模块节点 {} → 删 domains[键];N3 服务节点 {} 不归一化(显式通配激活 = 合法 TIER0 态);
1635
- * N2 已随 ?instance= 退役。dryRun(PUT only):复读完整管线不落盘不排程。
1636
- * DELETE:节点移除 + 孤儿凭据写后对账(覆盖 DELETE 与 PUT 替换两类来源,只报告不清理——)。
1637
- * 并发:进程内串行(per-factory promise chain 由工厂持有——本模块假设单飞调用)。
1773
+ * 计算声明集合(含 npm 清单 + 本地模块约定发现)。
1774
+ * hasServerEntry/hasClientEntry 决定模块参与哪些装配文件(入口探测,非 post-hoc 修复)。
1775
+ * 单源 = walkManifests(npmModules 登记 + packages/* 约定发现双通道;strict 形态进清单)。
1638
1776
  */
1639
- interface SaveResult {
1640
- written: boolean;
1641
- restartScheduled: boolean;
1642
- files: string[];
1643
- credentials: Array<{
1644
- stem: string;
1645
- ref: string;
1646
- overwrote: boolean;
1647
- }>;
1648
- issues: IntegrationServiceIssue[];
1649
- }
1650
- interface WriteOptions {
1651
- dryRun?: boolean;
1652
- /** body 唯一非文件字段(真值直落 config/credentials/,派生 ref 回填本节点) */
1653
- credentials?: CredentialInput;
1654
- credentialsByInstance?: Record<string, CredentialInput>;
1655
- }
1656
- interface WriteCoreOptions {
1657
- onApplied?: () => void;
1658
- cache?: FileCache;
1659
- }
1660
- /** 深度结构等价(非 stringify——键序陷阱误判 diff 防线) */
1661
- declare function deepEqual(a: unknown, b: unknown): boolean;
1662
- interface WriteCore {
1663
- /** 预热(工厂创建/写前调用——严格校验缓存就绪;memoized resolver 后续 1 stat 级) */
1664
- warmup(): Promise<void>;
1665
- /** PUT /app/integration(root 节点全集) */
1666
- applyApp(node: Record<string, unknown>, opts?: WriteOptions): SaveResult;
1667
- /** PUT /modules/:module/integration(v6 modules[owner] 集成位;键集纪律见 MODULE_INTEGRATION_NODE_KEYS;
1668
- * N1 {} 清 provider/config 保 resources;moduleOwnershipWritable 写守卫单源) */
1669
- applyModule(moduleId: string, node: Record<string, unknown>, opts?: WriteOptions): SaveResult;
1670
- /** PUT /services/:service/integration(整节点含 instances map;N3 {} 不归一化;v4.4 A2 身份判据) */
1671
- applyService(service: string, node: Record<string, unknown>, opts?: WriteOptions): SaveResult;
1672
- /** DELETE /services/:service/integration(恒整节点;幂等仅判据内成员;无预演) */
1673
- deleteService(service: string): SaveResult;
1674
- }
1675
- declare function createWriteCore(appDir: string, opts?: WriteCoreOptions): WriteCore;
1777
+ declare function collectDeclaredModules(appDir: string): DeclaredModuleInfo[];
1676
1778
 
1677
1779
  /**
1678
- * mock 槽绑定生成器(自 CLI mock-bindings.ts 迁入;provider 拆包 收敛 · B 方案;integrations v4 零拓扑形态):
1679
- * 应用内 config/integrations.json 缺席时,从已装模块 manifest 的 local:true 槽派生全槽 mock 绑定。
1780
+ * 谓词装配单源(FX-2b/):CLI doctor 规则 与 toolkit 工厂(求值轴 / SaveResult.issues)
1781
+ * 共用同一 I/O 装配与供给/需求聚合——「面板 issues ≡ doctor issues」的机制保证。
1680
1782
  *
1681
- * 语义边界(零改动迁移):
1682
- * - 缺席即跳过、永不覆盖(在场文件 = 用户/素材真源,生成器零侵入);
1683
- * - 只绑 local:true 槽(真厂商 provider 永不自动绑定);
1684
- * - sync 不触发(add = 新事实进入体系,sync = 状态重放)。
1685
- * 迁移顺带修复:writeFileSync → writeAtomic(原子写;H5)。
1686
- * 模块发现改 walkManifests(单源——CLI listLocalModules 并入)。
1783
+ * 迁移源:cli/src/doctor/schema-reader.ts(collectVendorSchemaProfiles,105 行)
1784
+ * + doctor 规则壳内联段(#1 effective stem 收集含 root ByInstance/标量兜底 + env 通道 +
1785
+ * #9 realmSwitchHints + malls 注册表 + moduleResourceNeeds)。
1786
+ *
1787
+ * **装配源 = walkManifests 双通道产物**(声明性改进:sdk 模式模块(npmModules 登记、
1788
+ * node_modules 消费)从 doctor 原单通道(listLocalModules = packages/* 本地扫描)的静默
1789
+ * 忽略,转纳入检查面——与 toolkit 求值轴同源)。
1790
+ *
1791
+ * env 参数注入(默认 process.env——工厂边缘):#1 的 env 通道兜底(wanda env 化形态:
1792
+ * stem kebab → UPPER_SNAKE,env 键在场即视为已供给,不算缺文件)。
1687
1793
  */
1688
- interface MockBindingsResult {
1689
- generated: boolean;
1690
- reason: 'in-place' | 'no-local-slots' | 'generated';
1691
- /** 本次生成(或在场文件阻断时的空集)涉及的 local 槽服务名 */
1692
- services: string[];
1794
+ interface PredicateIoInputs {
1795
+ /** #1:effective 候选 stem → 缺文件(env 通道在场不算缺失) */
1796
+ credentialFileMissing: Record<string, boolean>;
1797
+ /** #2:凭据文件 stem → .type(无 type 则缺键) */
1798
+ credentialFileType: Record<string, string | undefined>;
1799
+ /** #6:credentialType → schema 引用文件缺失 */
1800
+ credentialSchemaMissing: Record<string, boolean>;
1801
+ /** #7:厂商 → configSchema properties 键集并集 */
1802
+ vendorConfigKeys: Record<string, Set<string>>;
1803
+ /** #17(G 批):厂商 → x-tbox-global 标记键集(与 vendorConfigKeys 同循环收集——零新增 IO) */
1804
+ vendorGlobalConfigKeys: Record<string, Set<string>>;
1805
+ /** #7:厂商 → configSchema 引用缺失(跳过该厂商死配置判定) */
1806
+ vendorConfigSchemaMissing: Record<string, boolean>;
1807
+ /** #9:实现覆盖跨厂商提示文案(已成形——谓词直投) */
1808
+ realmSwitchHints: string[];
1809
+ /** #8:root instances 注册表 ids(在场才传;缺席 → 键检查跳过) */
1810
+ malls?: string[];
1811
+ /** #15-#16:已装模块 id → manifest declare.resources 声明 id 集 */
1812
+ moduleResourceNeeds: Record<string, ReadonlySet<string>>;
1813
+ }
1814
+ /** 装配全产物(= PredicateIoInputs + 供给/需求/归属聚合——喂 evaluateIntegrationServices 的
1815
+ * 非 contracts/integrations 入参全集,两消费方 spread 直投,零各自组装) */
1816
+ interface PredicateAssembly extends PredicateIoInputs {
1817
+ suppliedProviders: Record<string, {
1818
+ services: string[];
1819
+ owner: string;
1820
+ credentialType?: string;
1821
+ }>;
1822
+ demandedServices: Record<string, {
1823
+ optional: boolean;
1824
+ owners: string[];
1825
+ }>;
1826
+ /** v6:服务归属表 + 已装模块 id 集(MODULE_CONFIG_DEAD / #12 ownerOf 透传) */
1827
+ ownership?: Record<string, string>;
1828
+ installedModuleIds?: ReadonlySet<string>;
1693
1829
  }
1694
- declare function ensureMockBindings(appDir: string): MockBindingsResult;
1830
+ /** stem → env 键(kebab → UPPER_SNAKE;与 SDK/provider-secret env 兜底同公式) */
1831
+ declare function refToEnvKey(stem: string): string;
1832
+ /**
1833
+ * 装配谓词输入全集(供给/需求聚合 + I/O 档案)。
1834
+ * @param walk 调用方已执行的 walkManifests 产物(目录枚举零缓存——每方法调用独立)
1835
+ */
1836
+ declare function buildPredicateAssembly(appDir: string, walk: WalkManifestsResult, integrations: Record<string, unknown>, env?: Readonly<Record<string, string | undefined>>): PredicateAssembly;
1695
1837
 
1696
1838
  /**
1697
- * 模块级联绑定单源(integrations v6 所有权模型——原 domain-binding.ts v4.4/ 重写)。
1698
- * integrations 层落位依据:谓词(同层)/ 写核(同层)/ views(下层可向上 import)三向消费
1699
- * 的唯一公共下层;import 前缀 guard 覆盖。
1839
+ * 应用级 integrations 求值(cli-remove-prune-and-new.4):doctor integration-services 规则内
1840
+ * "装配+求值"序列的单源抽取(FX-2b/ 轨迹延续——此前 buildPredicateAssembly 已单源,本函数
1841
+ * 将 walk→supplies→assembly→evaluate 全序列收口)。
1700
1842
  *
1701
- * 知识锚(module-tab note 单源锚表,v6 形态):
1702
- * 模块级联(值 + 层) = resolveModuleBinding —— 谓词 #7(per-module 生效厂商 ≡
1703
- * `modules[m].provider ?? root.provider`)/ deriveBindingLayer 模块级段 /
1704
- * buildInheritance module 段 / binding(单数)
1705
- * 归属表 = walk.ownership(单源聚合产物;buildOwnershipMap 桥直通——
1706
- * registry 显式参 / 谓词 / 写守卫 / views 四消费方零第二实现)
1707
- * 来源层四层推导 = deriveBindingLayer(views/service-resolutions,模块级段改调本文件)
1708
- * 写通道可用性 = moduleOwnershipWritable —— configEditable 读标志 / applyModule 400 守卫
1709
- * 共用(owns>0 唯一判据——多域归属合法化、共享键/多域判据随 退役)
1843
+ * 消费方:
1844
+ * - doctor integration-services 规则(外壳保留:stale 防线/文件读取/env 展开/形状守卫/分级投射)
1845
+ * - pruneIntegrationBindings(prune 判据 ≡ doctor 判据的构造性同源载体)
1846
+ *
1847
+ * 契约:调用方须先 `resolveContractsForApp` 并确保 `strictValidation`(本函数不再分级门控——
1848
+ * doctor 的 warning/error 升级指引与 prune 的 skip 语义分属两消费方,不收口)。
1710
1849
  */
1711
- /** 归属表构建(walk 单源直通——sdk 桥 re-export 消费;appDir 直入对齐 loadProviderCatalog
1712
- * 桥工效——模板装配第六行:`ownerOf: buildOwnershipMap(appDir)`)。 */
1713
- declare function buildOwnershipMap(appDir: string): Record<string, string>;
1714
- /** 模块级联绑定解析(值 + 来源层):provider 取非空字符串(模块级优先 → root 兜底;空串 = 缺席)。
1715
- * layer:modules[moduleId].provider 声明 → 'module';root 兜底 → 'app';双缺 → null(binding 双缺诚实态)。 */
1716
- declare function resolveModuleBinding(config: Record<string, unknown> | null, moduleId: string): {
1717
- provider: string | null;
1718
- layer: 'module' | 'app' | null;
1719
- };
1720
- /** 模块集成位可写性(v6 判别联合——configEditable 读标志与 applyModule 写守卫共用单源):
1721
- * owns>0 唯一判据(多域/shared-key 判据随 v6 退役——服务归属唯一真源 = declare.owns)。 */
1722
- type ModuleOwnershipWritability = {
1723
- writable: true;
1724
- ownedServices: string[];
1725
- } | {
1726
- writable: false;
1727
- reason: 'zero-ownership';
1728
- ownedServices: [];
1729
- };
1730
- declare function moduleOwnershipWritable(_walk: Pick<WalkManifestsResult, 'modules' | 'catalog' | 'ownership'>, mod: WalkModuleInfo): ModuleOwnershipWritability;
1731
- /** 供给足迹(该厂商全部供给服务并集——应用级 integrationSchemas 作用域) */
1732
- declare function providerFootprint(catalog: WalkCatalog, provider: string): string[];
1850
+ declare function evaluateAppIntegrationIssues(appDir: string, integrations: Record<string, unknown>, contracts: ResolvedContracts, env?: Readonly<Record<string, string | undefined>>): Promise<IntegrationServiceIssue[]>;
1733
1851
 
1734
1852
  /**
1735
- * AppToolkitError(领域 6 码 + 壳层 2 码分界——toolkit 只产领域码):
1736
- * VALIDATION_FAILED(400) / SERVICE_NOT_FOUND(404) / MODULE_NOT_FOUND(404) /
1737
- * PROVIDER_NOT_FOUND(404) / SUPPLY_NOT_FOUND(404) / CONTRACTS_NOT_RESOLVED(503)。
1738
- * AUTH_REQUIRED / ROUTE_NOT_FOUND 为 HTTP 层事实(壳层产生)——6 + 2 = 8(api.md §5)。
1853
+ * integrations.json 死绑定清理(cli-remove-prune-and-new 核心件)。
1739
1854
  *
1740
- * **name 约定(仓规约束①——mangle 安全真源 process note 2026-09-11-publish-dist-minify)**:
1741
- * 构造器必须字符串字面量赋值 `this.name = 'AppToolkitError'`(禁 `this.name = X.name` binding
1742
- * 形态——src 态守卫不可见、mangle 后静默漂移);守卫 = tests/error-name-safety.test.ts(C4)。
1743
- * 消费面属性分发(.httpStatus/.code/.fields——比 err.name 分发更宽裕)。
1855
+ * 不变式:**删除判据 ≡ doctor integration-services 报错判据(构造性同源)**——消费 doctor 同一
1856
+ * 共享求值器 evaluateAppIntegrationIssues 的结构化 issue,code 白名单
1857
+ * {VENDOR_NOT_INSTALLED, BINDING_UNRESOLVED, MODULE_CONFIG_DEAD} + 守卫(绑定引用链候选
1858
+ * provider ∈ installedVendors 即保留,排除活厂商错配)→ 删除域严格 = "供给载体消亡"。
1859
+ * v6:模块卸载 → modules[m] **整节点确定性清理**(provider+config+resources——
1860
+ * 模块消亡清理 vs 集成位编辑保全不矛盾;MODULE_CONFIG_DEAD 为判据源)。
1861
+ *
1862
+ * 由此推论(均已实证):需求侧孤儿绑定(demand 消失、供给在场)保留——doctor 判其合法;用户
1863
+ * 预配置绑定受保护;一次 remove 自愈全文件历史死债;凭据类 issue(CREDENTIAL_FILE_MISSING 等)
1864
+ * 刻意不进白名单,原样保留。
1865
+ *
1866
+ * 写侧三防线(镜像 write core):归一化(空节点删键)→ parseIntegrationsConfig
1867
+ * 严格校验(失败弃写)→ writeAtomic。凭据孤儿只报告不清理(——与 DELETE 管线现行为一致)。
1868
+ * 全空(无任何存活绑定)→ 删文件——ensureMockBindings(缺席即生成)在重装供给时再生闭环。
1869
+ *
1870
+ * 最佳努力语义:谓词不可用(contracts 未安装/降级、env 缺失、求值 throw)→ skipped 返回 +
1871
+ * 文件原样,绝不阻断 remove 本体。
1744
1872
  */
1745
- type AppToolkitErrorCode = 'VALIDATION_FAILED' | 'SERVICE_NOT_FOUND' | 'MODULE_NOT_FOUND' | 'PROVIDER_NOT_FOUND' | 'SUPPLY_NOT_FOUND' | 'CONTRACTS_NOT_RESOLVED';
1746
- declare class AppToolkitError extends Error {
1747
- readonly code: AppToolkitErrorCode;
1748
- readonly httpStatus: number;
1749
- readonly fields?: string[];
1750
- constructor(code: AppToolkitErrorCode, httpStatus: number, message: string, fields?: string[]);
1873
+ interface PruneResult {
1874
+ /** 被清除的绑定节点描述(remove 日志行,如 'root.provider=mock' / 'services.member.account') */
1875
+ removed: string[];
1876
+ /** 孤儿凭据(只报告不清理——reconcileOrphanCredentials 产物 message) */
1877
+ orphanCredentials: string[];
1878
+ /** 跳过原因(正常路径 undefined;not-configured = integrations.json 缺席,兼容态零动作) */
1879
+ skipped?: 'predicate-unavailable' | 'validation-failed' | 'not-configured';
1751
1880
  }
1752
- /** CONTRACTS_NOT_RESOLVED message(N1 构建指引——api.md 错误信封示例)。
1753
- * P-4:notes 优先——resolver 在全部不可解析路径均已 push 携带操作指引的 notes(导入失败/
1754
- * 产物缺失/未安装/<0.9 升级);现行 version===null 分支会把 notes 内细分指引吞成通用文案。
1755
- * 分支保留为兜底(防御性——正常路径 notes 恒非空)。
1756
- * v7:+= ownershipBindingV6 分支(标记门第四分支单源化——写门控 assertContractsUsable 与
1757
- * 读求值轴降级 statusMessage 共用同一文案;可选参向后兼容)。 */
1758
- declare function contractsNotResolvedMessage(contracts: {
1759
- version: string | null;
1760
- strictValidation: boolean;
1761
- notes: readonly string[];
1762
- ownershipBindingV6?: boolean;
1763
- }): string;
1881
+ declare function pruneIntegrationBindings(appDir: string): Promise<PruneResult>;
1764
1882
 
1765
1883
  /**
1766
- * DTO 全量(api.md §3 字段级单源落源——36 类型;演进 additive-only,铁律 #8)。
1767
- * agtcodingbox / tbox-ai-coding 经 `import type` 消费(L2 DTO 单源——API 层零类型镜像)。
1768
- * 词汇七概念:app / module / service / instance / provider / integration / resolution。
1769
- * 弃用词汇清单见 api.md §3 尾(component/slot/scope/configMode/…——防复活)。
1884
+ * 双键寻址(v7 词汇统一):路径参数双键——id 精确优先 → 展示名唯一命中兜底 → 404
1885
+ * (多命中 fail-visible,message 列候选 + 指引改用 id;复用既有 404 码零新错误码)。
1770
1886
  *
1771
- * **v7 词汇统一破例声明(一次性收敛,此后恢复 additive-only)**:标识/展示名分轴
1772
- * (id = 标识、name = 展示名、description = 描述——对齐实例轴 {id, name}),
1773
- * title 键全量退役(与 manifest name→id/title→name 同一变更);`.title` 消费方
1774
- * (外部仓 import type / 运行时读)需同窗迁移。
1887
+ * **消费边界(O1——双键语义单点)**:仅 factory.ts 控制面七方法入口接入;
1888
+ * views / write-core / CLI 恒 id-only 纯函数。
1889
+ *
1890
+ * **纯参数式**:configuredKeys 由调用方注入——零 integrations 依赖、零 IO,
1891
+ * 解析输入恒为 walk 产物快照 + 调用方键集。
1775
1892
  */
1776
- /** contracts 求值五态原样(EffectiveServiceResolution.status)+ 视图轴降级态
1777
- * (evaluation-unavailable——toolkit 视图独有,非 contracts 求值产物:contracts 不可用
1778
- * (未安装/无严格面/v6 标记缺席)时读求值轴不再 503,改投静态骨架 + 本态标记;
1779
- * 消费方按非 ok 态渲染,statusMessage 携带 N1 分支指引) */
1780
- type ServiceStatus = 'ok' | 'service-not-configured' | 'instance-not-found' | 'instance-disabled' | 'binding-unresolved' | 'evaluation-unavailable';
1781
- /** 四配置层(instance 为 map 字段层) */
1782
- type BindingLayer = 'app' | 'module' | 'service' | 'instance';
1783
- /** 纯模块清单(无 services——卡片展开走 /modules/:m);provider 家族包不在清单
1784
- * (供给/实施载体非可配置业务模块——供给轴归 /providers;判定 = install id / 包名
1785
- * basename 去 scope 后 `provider-` 前缀;已装 provider 详情 GET /modules/:m 仍 200) */
1786
- interface ModulesView {
1787
- modules: ModuleDeclaration[];
1788
- }
1789
- interface ModuleDeclaration {
1790
- /** install id(packages/ 目录名 / .tbox/app.json entry.id)——恒业务模块(provider 家族不在本清单) */
1893
+ /** 模块双键解析:id 精确 → 展示名(descriptor.name ?? id)唯一命中 → 404。 */
1894
+ declare function resolveModuleKey(walk: WalkManifestsResult, key: string): WalkModuleInfo;
1895
+ /** 服务双键解析 → 真实 service id:服务键集(词汇 ∪ demand ∪ 供给足迹 ∪ configuredKeys ∪ 归属)
1896
+ * 精确命中 → 展示名(slotMeta.name ?? catalog.services[].name)唯一命中 → 404。
1897
+ * configuredKeys = 当前集成配置 services 节键集(调用方注入)。
1898
+ * v6.1 += 归属键(walk.ownership——纯归属无词汇/demand/供给的 owns 合法,O6 对称)。 */
1899
+ declare function resolveServiceKey(walk: WalkManifestsResult, configuredKeys: readonly string[], key: string): string;
1900
+
1901
+ /**
1902
+ * .tbox/app.json npmModules 读写(自 CLI manifest.ts 迁入——assembly 层目录知识单源)。
1903
+ * npmModules 登记 = sdk 包双语义磁盘足迹之一(业务包 = packages/<id>/ 目录,sdk 包 = 本清单登记)。
1904
+ * 本地模块(packages/module-*)不在 npmModules 登记——靠 tbox.module.json 约定发现。
1905
+ */
1906
+ type ModuleMode = 'local' | 'sdk' | 'codegen';
1907
+ interface NpmModuleEntry {
1908
+ /** 模块短 id(如 "module-member"),装配别名来源 */
1791
1909
  id: string;
1792
- /** 展示名(v7 词汇统一:manifest name ?? id——恒有值) */
1793
- name: string;
1794
- description: string;
1795
- /** 隐藏模块(additive——manifest hidden === true 时携带;默认清单已过滤,本字段仅供
1796
- * ?includeHidden=true 可见时徽标呈现) */
1797
- hidden?: boolean;
1798
- }
1799
- /** 服务需求声明(模块 demand 单元 / 平台服务条目 / owned-not-consumed 投影条目——
1800
- * v4.4 双端点同型;defaults 唯一落位 ServiceDetail) */
1801
- interface ServiceDemand {
1802
- service: string;
1803
- /** manifest demand meta(v7 title→name);缺席 UI 回退 service id */
1804
- name?: string;
1805
- description?: string;
1806
- /** demand optional === false(多模块 OR 聚合见 resolution echo;平台服务条目与 owned
1807
- * 投影条目恒 false——无 demand 源) */
1808
- required: boolean;
1809
- }
1810
- /** GET /modules/:module(模块静态一站式 · PUT 读对偶) */
1811
- interface ModuleDetailView {
1812
- /** 模块展示名(v7 词汇统一:manifest name ?? id——恒有值) */
1813
- name: string;
1814
- /** B1 additive:模块 meta 描述(manifest description;兜底 '') */
1815
- description: string;
1816
- /** 隐藏模块(additive——manifest hidden === true 时携带;详情恒 200 不受清单过滤影响,
1817
- * 本字段仅供面板徽标呈现) */
1818
- hidden?: boolean;
1819
- /** v6 所有权模型:模块归属服务(declare.owns 展平,排序;零归属 = [])——
1820
- * v5 domainKeys 退役(破坏性更名;面板 presence-detection 双读义务见 api.md §3) */
1821
- ownedServices: string[];
1822
- /** modules[install id] 集成位原值(provider/config;resources 不投影——见 resources 字段);未配置 = null */
1823
- integration: ModuleIntegrationNode | null;
1824
- /** 模块资源只读镜像(N2 读半边——写侧 resources 恒保全;含 ref 台账展开态 resolvedDatasetId);
1825
- * 无模块键/无资源节 = null */
1826
- resources?: ModuleResourcesEcho | null;
1827
- /** v6 单数化(v5 providerBindings[] 退役):模块级厂商绑定解析(resolveModuleBinding 单源;
1828
- * 单值作用于全部 ownedServices) */
1829
- binding: ModuleBinding | null;
1830
- /** v6:owns.length > 0(moduleOwnershipWritable 单源——读标志与写守卫共用) */
1831
- configEditable: boolean;
1832
- /** 本模块服务面 = demand ∪ owned 去重投影(2026-09-21 服务面投影批——通用合并无 consumes
1833
- * 空判特例:consume 条目胜出[声明序原样、required = optional === false];owned-not-consumed
1834
- * 追加[ownedServices 排序序、Set 去重,required 恒 false]。卡片展开 + 编辑器静态上下文自足) */
1835
- services: ServiceDemand[];
1836
- /** v4.4 include=serviceResolutions 内嵌(v6.1 键集 = owned ∪ demand 服务过滤 ≡ 批量 ?service= 语义;<0.9/形态异常 → null——永不 503) */
1837
- serviceResolutions?: ServiceResolutionsView | null;
1838
- /** v4.4 include=integrationSchemas 层级富化(零归属/未绑定 → null) */
1839
- integrationSchemas?: LayerIntegrationSchemas | null;
1840
- /** v4.6 include=integrationFieldRegistry 集成字段注册表(null 语义镜像 integrationSchemas;
1841
- * 未知厂商/零足迹 → 非 null 空集 + unsupplied 回填—— 轴参假想计算同此) */
1842
- integrationFieldRegistry?: IntegrationFieldRegistryView | null;
1843
- }
1844
- /** 模块级厂商绑定解析(v6——静态文件事实;规则 ≡ 谓词 #7 模块层,resolveModuleBinding 单源) */
1845
- interface ModuleBinding {
1846
- /** modules[install id].provider ?? root.provider(双缺 = null) */
1847
- provider: string | null;
1848
- /** 生效来源层(双缺 = null) */
1849
- layer: 'module' | 'app' | null;
1910
+ /** 发布源包名;codegen 的应用内身份由 id 派生为 @app/<id>,sdk 保持该包名 */
1911
+ package: string;
1912
+ /** 安装版本 */
1913
+ version: string;
1914
+ /** 分发模式 */
1915
+ mode: ModuleMode;
1916
+ /** 3-way merge 基线(codegen 模式) */
1917
+ baseVersion?: string;
1918
+ /**
1919
+ * 条目类别(单一模板统一化):'ui-kit' = 壳 UI 组件包——create 全量继承后
1920
+ * 不再承担保留判据(模板 manifest = 出厂装配真源);现职 = update 三方合并锚 +
1921
+ * sync-agent-ui-kit 副本 identity 标记(由该脚本派生维护)。
1922
+ */
1923
+ kind?: 'ui-kit';
1850
1924
  }
1851
- /** 层级 config schema 计算(v4.4——静态轴富化,零 contracts) */
1852
- interface LayerIntegrationSchemas {
1853
- /** 层生效厂商(resolveModuleBinding 单源) */
1854
- provider: string;
1855
- /** 模块级 = 本模块 ownedServices ∩ 该厂商供给;应用级 = 供给足迹全量(configSchema = raw draft 2020-12 原文;供给在场未声明 = null) */
1856
- services: Record<string, {
1857
- configSchema: object | null;
1858
- }>;
1925
+ interface AppManifest {
1926
+ templateVersion: string;
1927
+ npmModules: NpmModuleEntry[];
1859
1928
  }
1860
- /** v4.6 集成字段注册表(层级表单服务端预计算——合并代数// 服务端单源;
1861
- * 消费 resolveLayerIntegrationSchemas 产物构造,禁旁路直取 serviceSchemas) */
1862
- interface IntegrationFieldRegistryView {
1863
- /** echo:本注册表计算口径(假想时 = 轴参值——) */
1864
- provider: string;
1865
- /** 作用域内 configSchema === null 的服务(UI「未提供参数模板」提示行) */
1866
- schemaless: string[];
1867
- /** module 轴 = ownedServices − 该厂商供给(v6.1 scope 随归属——loadModuleFormViews 单源,
1868
- * Set 去重保序);app 轴恒 [](结构性:足迹 ⊆ 供给) */
1869
- unsupplied: string[];
1870
- /** 作用域内全部非 null schema 的 additionalProperties 均 ≠ false(聚合;空真) */
1871
- additionalPropertiesAllowed: boolean;
1872
- /** 逐 key 合并产物(首声明插入序 = scope 遍历序:app 字母序 / module ownedServices 序) */
1873
- fields: Array<{
1874
- key: string;
1875
- /** null = 类型不可调和(/ 异构/ enum 不等——冲突折叠,客户端 RawJson 保真) */
1876
- schema: object | null;
1877
- /** required 聚合 = sources.some(s => s.required);conflict 字段照常聚合 */
1878
- sources: Array<{
1879
- service: string;
1880
- required: boolean;
1881
- }>;
1882
- /** G 批:x-tbox-global 聚合旗标(sources.some——任一来源声明即 true;app/module 轴表单
1883
- * 仅渲染 true 字段,非全局键落 ExtraFields;service 轴全量透传) */
1884
- global: boolean;
1885
- }>;
1929
+ declare function manifestPath(appDir: string): string;
1930
+ /** 读应用 manifest(缺席 → null;损坏/版本非法 → null——宽松解析与 CLI 语义一致) */
1931
+ declare function readAppManifest(appDir: string): AppManifest | null;
1932
+ /** 写应用 manifest(目录缺席物化;同步——写核心串行队列内使用) */
1933
+ declare function writeAppManifest(appDir: string, manifest: AppManifest): void;
1934
+ /** 小程序容器登记项(miniapp-container init 写入;与 npmModules 正交,不参与装配/doctor) */
1935
+ interface MiniappContainerEntry {
1936
+ /** 平台 id:'alipay' / 'weapp'(= CLI platform 参数,展开目录名后缀) */
1937
+ id: string;
1938
+ /** 源包名(@tbox.cn/app-miniapp-container-*) */
1939
+ package: string;
1940
+ version: string;
1941
+ /** 展开目录(相对应用根,如 'apps/miniapp-container-alipay') */
1942
+ dir: string;
1886
1943
  }
1887
- /** GET /app(应用静态视图:平台服务 + root 原值) */
1888
- interface AppView {
1889
- /** 平台服务(v4.4 服务词汇 − 模块占用——与模块 demand 同型 ServiceDemand[];
1890
- * title/description 缺席 = UI 回退 service id;required 恒 false——平台服务无 demand 源) */
1891
- services: ServiceDemand[];
1892
- /** root 节点原值;文件缺席 = null */
1893
- integration: AppIntegrationNode | null;
1894
- /** v4.4 include=serviceResolutions 内嵌(全量键集 ≡ 批量无参;<0.9/形态异常 → null——永不 503) */
1895
- serviceResolutions?: ServiceResolutionsView | null;
1896
- /** v4.4 include=integrationSchemas 层级富化(root.provider 缺席 → null) */
1897
- integrationSchemas?: LayerIntegrationSchemas | null;
1898
- /** v4.6 include=integrationFieldRegistry 集成字段注册表(root.provider 缺席且无轴参 → null;
1899
- * 未知厂商/零足迹 → 非 null 空集—— 轴参假想计算同此) */
1900
- integrationFieldRegistry?: IntegrationFieldRegistryView | null;
1944
+ interface AppManifestFull extends AppManifest {
1945
+ /** 已初始化的小程序容器(可选——旧 manifest 无此字段,读侧归一为 []) */
1946
+ miniappContainers?: MiniappContainerEntry[];
1901
1947
  }
1902
- /** GET /services/:service(服务静态单体) */
1903
- interface ServiceDetail extends ServiceDemand {
1904
- /** manifest 预填(唯一落位) */
1905
- defaults: Array<{
1948
+ /** 读应用 manifest(完整面——miniappContainers 归一) */
1949
+ declare function readAppManifestFull(appDir: string): AppManifestFull | null;
1950
+ declare function upsertNpmModule(manifest: AppManifest, entry: NpmModuleEntry): AppManifest;
1951
+ declare function removeNpmModule(manifest: AppManifest, id: string): AppManifest;
1952
+ /** 登记小程序容器(按 id 去重替换;miniapp-container init 用) */
1953
+ declare function upsertMiniappContainer(manifest: AppManifestFull, entry: MiniappContainerEntry): AppManifestFull;
1954
+ /** 更新某模块的元数据(update 命令用:version / baseVersion) */
1955
+ declare function updateNpmModule(manifest: AppManifest, id: string, patch: Partial<Pick<NpmModuleEntry, 'version' | 'baseVersion'>>): AppManifest;
1956
+ /**
1957
+ * 模块 id 合法性:小写字母/数字开头,单词段以单个中划线分隔(无连续/尾部中划线),
1958
+ * 防路径穿越/目录注入,并保证 camelCaseId 派生别名唯一(a-b 与 a--b 不允许共存碰撞)。
1959
+ */
1960
+ declare function isValidModuleId(id: string): boolean;
1961
+ /** 校验失败抛出(统一错误信息) */
1962
+ declare function assertValidModuleId(id: string, source: string): void;
1963
+
1964
+ /** 桥源形态冻结:ProviderCatalog = contracts TIER0 形状(providers/services/credentialTypes) */
1965
+ interface BridgeProviderCatalog {
1966
+ providers: Record<string, Record<string, {
1906
1967
  provider: string;
1907
1968
  implementation: string;
1969
+ credentialType: string;
1970
+ owner: string;
1971
+ local?: boolean;
1972
+ configSchema?: string;
1973
+ credentialSchema?: string;
1974
+ services: string[];
1975
+ }>>;
1976
+ services: Record<string, {
1977
+ optional: boolean;
1978
+ defaults: Array<{
1979
+ provider: string;
1980
+ implementation: string;
1981
+ }>;
1982
+ owners: string[];
1908
1983
  }>;
1909
- /** 文件 services[s] 逐字原值(编辑预填源);无声明 = null */
1910
- integration: ServiceIntegrationNode | null;
1911
- /** 供给该服务的厂商名单(catalog 静态切片——picker 数据源) */
1912
- suppliedBy: string[];
1913
- /** v4.7 include=integrationSchemas 生效绑定富化(三态:null 全链未绑定 /
1914
- * 绑定无可计算 schema / 含 schema;malformed 节点 → null——不放行域级联) */
1915
- integrationSchemas?: ServiceIntegrationSchemas | null;
1916
- /** G 批:include=integrationFieldRegistry 服务轴注册表(loadServiceFieldRegistry——
1917
- * 四分支链推导复用 fields = 该 schema 全部字段带 global 旗标;null 语义镜像 。
1918
- * v5.1 serviceProvider 轴参 = 假想重定向——仅表单投影按 X 计算,带非空轴参时
1919
- * registry 恒非 null(豁免链③不镜像实际态 null);同构 ≡ PUT 改写 provider 后实读) */
1920
- integrationFieldRegistry?: IntegrationFieldRegistryView | null;
1921
- }
1922
- /** 服务级生效绑定 schema(v4.7 静态轴富化——零 contracts,永不 503;实例层无条件排除:
1923
- * node 级口径 ≠ resolution 默认实例口径,api.md §4.4 注) */
1924
- interface ServiceIntegrationSchemas {
1925
- /** 生效厂商:显式(含内联声明名)?? modules[ownerOf].provider ?? root.provider;
1926
- * v5.1 serviceProvider 轴参在场时 = 假想短路值(非链解析产物) */
1927
- provider: string;
1928
- /** catalog 复合键(多 impl 声明序首个)> 内联 ref;miss(未知厂商/未供给/内联缺 ref)→ null(富化非门控) */
1929
- configSchema: object | null;
1930
- }
1931
- /** GET /service-resolutions(批量求值 · 唯一求值集合面) */
1932
- interface ServiceResolutionsView {
1933
- /** contracts echo(仅求值轴两端点携带) */
1934
- contracts: ContractsResolution;
1935
- /** 键集 = 服务词汇 ∪ 已配置 ∪ 归属(v6.1 += 归属——owned 服务恒可求值;模块/平台/孤儿全量) */
1936
- resolutions: Record<string, ServiceResolutionEntry>;
1937
- /** 谓词全量(doctor 同源;恒全量——subset 消费方客户端过滤) */
1938
- issues: IntegrationIssue[];
1939
- }
1940
- /** 求值摘要单元(行内嵌; 单一形状) */
1941
- interface ServiceResolutionEntry {
1942
- /** 默认实例口径(normalizeInstances 委托) */
1943
- status: ServiceStatus;
1944
- statusMessage?: string;
1945
- /** 最特异声明层厂商名(跨层事实) */
1946
- provider?: string;
1947
- /** v4.4:provider 来源声明层(默认实例口径,与 status 同轴);恒 = provider 字段来源层
1948
- * (ok/binding-unresolved 取声明层;未配置双缺席);≡ 单体 inheritance 链逆序首个有 provider 的层 */
1949
- layer?: BindingLayer;
1950
- /** provider 在场时在场:(provider, service) ∈ 供给关系 */
1951
- supplied?: boolean;
1952
- /** owner 模块 install id(v6.1 = walk.ownership 归属单源——install id 轴,与模块清单 id 恒可 join;
1953
- * 旧实现 demand owners[0] 为包名/@app 轴且漏 owned-not-consumed,已退役);平台服务/孤儿缺席 */
1954
- module?: string;
1955
- /** demand echo(OR 聚合);平台/孤儿恒 false;集成就绪判定单源(§7) */
1956
- required?: boolean;
1957
- }
1958
- /** 求值完整结构(extends = 列表项 ⊂ 单体的编译期保证——) */
1959
- interface ServiceResolution extends ServiceResolutionEntry {
1960
- /** 枚举规则(全实例逐一;默认实例求值 = 摘要基,不重复头部) */
1961
- instances: ResolvedInstance[];
1962
- inheritance: Array<{
1963
- layer: BindingLayer;
1964
- provider?: string;
1965
- implementation?: string;
1984
+ credentialTypes: Record<string, {
1985
+ owner: string;
1986
+ credentialSchema?: string;
1966
1987
  }>;
1967
1988
  }
1968
- /** GET /service-resolutions/:service(求值单体) */
1969
- interface ServiceResolutionDetail {
1970
- contracts: ContractsResolution;
1971
- resolution: ServiceResolution;
1972
- /** service === :service 过滤子集 */
1973
- issues: IntegrationIssue[];
1974
- }
1975
- /** root 节点 */
1976
- interface AppIntegrationNode {
1977
- /** 恒字符串(app/module 级无内联形态) */
1978
- provider?: string;
1979
- config?: Record<string, unknown>;
1980
- configByInstance?: Record<string, Record<string, unknown>>;
1981
- credentialRef?: string;
1982
- credentialRefByInstance?: Record<string, string>;
1983
- /** 整组替换(id 字符集受输入约束①) */
1984
- instances?: Array<{
1985
- id: string;
1986
- name: string;
1987
- attributes?: Record<string, unknown>;
1989
+ /** 富形态(工厂迁移面):walkManifests 产物直通 */
1990
+ declare function loadProviderCatalogRaw(appDir: string): WalkCatalog;
1991
+ /** 桥源(形态冻结):富形态 → 桥形状投影(demand meta name/description 剥离——桥面无此字段,
1992
+ * additive 差异声明见 app-sdk 桥 golden) */
1993
+ declare function loadProviderCatalog(appDir: string): BridgeProviderCatalog;
1994
+ interface ProviderServiceSchemas {
1995
+ provider: string;
1996
+ service: string;
1997
+ /** 恒数组(H1——通常 1;多 impl = 升级窗口) */
1998
+ implementations: Array<{
1999
+ implementation: string;
2000
+ credentialType: string;
1988
2001
  }>;
1989
- defaultInstanceId?: string | null;
1990
- }
1991
- /** AppIntegrationNode 键集单源(runtime const——write applyApp 全量替换白名单
1992
- * (缺席根键删除;services/modules 域不在其中;v6 domains 键退役)+ views/app 投影
1993
- * (GET 预填 ≡ PUT body,/L1——文件含 services/modules 但 root 节点投影只含本键集)) */
1994
- declare const APP_INTEGRATION_NODE_KEYS: readonly ["provider", "config", "configByInstance", "credentialRef", "credentialRefByInstance", "instances", "defaultInstanceId"];
1995
- /** 模块集成位节点(v6——provider 绑定默认 + config 级联层;resources 不投影不写——
1996
- * 集成位编辑恒保全资源节,N2) */
1997
- interface ModuleIntegrationNode {
1998
- provider?: string;
1999
- config?: Record<string, unknown>;
2000
- }
2001
- /** ModuleIntegrationNode 可写键集单源(v6——write applyModule 全量替换白名单
2002
- * (键集外 400;resources 恒随既有节点保全)+ views/modules 投影(GET ≡ PUT,三同构)) */
2003
- declare const MODULE_INTEGRATION_NODE_KEYS: readonly ["provider", "config"];
2004
- /** 模块资源回显(只读投影——N2 读半边:写侧仍仅 provider/config,resources 恒保全)。
2005
- * 原值文件镜像(L1)+ ref 台账展开态:`ref` 在场且同目录 knowledge.json 命中时
2006
- * `resolvedDatasetId` = 台账 datasetId(镜像 SDK resolveKnowledge 展开语义),未命中/台账缺失 = null。
2007
- * 路径锚定边界:视图恒读 `<appDir>/config/`(与 toolkit readIntegrationsConfig 同源——
2008
- * `TBOX_INTEGRATIONS_FILE` 为 SDK 运行时逃生舱,视图不跟随,既有分叉)。 */
2009
- interface ModuleResourceEcho {
2010
- type: 'knowledge';
2011
- /** 文件原值直填 datasetId(与 ref 互斥使用——并存时 SDK 侧 datasetId 优先) */
2012
- datasetId?: string;
2013
- /** 文件原值 ref(台账引用——knowledge.json knowledge_bases 键) */
2014
- ref?: string;
2015
- /** 展开态:datasetId 直填时 = 该值;ref 命中台账 = 台账 datasetId;ref 未命中/台账缺失 = null */
2016
- resolvedDatasetId: string | null;
2017
- topK?: number;
2018
- scoreThreshold?: number;
2019
- }
2020
- /** modules[install id].resources 只读镜像(键 = 资源 id;无模块键/无资源 = null) */
2021
- type ModuleResourcesEcho = Record<string, ModuleResourceEcho>;
2022
- /** services[s] 整节点 */
2023
- interface ServiceIntegrationNode {
2024
- /** 对象 = 自定义 API(仅槽级) */
2025
- provider?: string | InlineVendorDeclaration;
2026
- /** 内联 provider 时必填 */
2027
- implementation?: string;
2028
- config?: Record<string, unknown>;
2029
- credentialRef?: string;
2030
- /** 键 = instanceId / '*'(随节点全量替换) */
2031
- instances?: Record<string, ServiceInstanceNode>;
2032
- }
2033
- /** services[s].instances[k] 节点 */
2034
- interface ServiceInstanceNode {
2035
- /** provider 恒字符串(内联仅槽级合法) */
2036
- provider?: string;
2037
- implementation?: string;
2038
- config?: Record<string, unknown>;
2039
- credentialRef?: string;
2040
- /** 缺省 true;false → instance-disabled */
2041
- enabled?: boolean;
2002
+ integrationSchemas: {
2003
+ configSchema: object | null;
2004
+ credentialSchema: object | null;
2005
+ };
2042
2006
  }
2043
- interface InlineVendorDeclaration {
2044
- provider: string;
2045
- credentialType: string;
2046
- configSchema?: string;
2007
+ type ProviderServiceSchemasResult = {
2008
+ found: true;
2009
+ detail: ProviderServiceSchemas;
2010
+ } | {
2011
+ found: false;
2012
+ reason: 'provider-not-found' | 'supply-not-found';
2013
+ };
2014
+
2015
+ /**
2016
+ * integrations.json 文件级读(read)。
2017
+ * 严格校验面(≥0.9)在场 → contracts parseIntegrationsConfig(assertNoInlineSecrets →
2018
+ * 旧键直切防线 → zod strict);缺席/降级 → 原文 JSON 透传(谓词宽松透传语义——
2019
+ * doctor 读裸 JSON 先例;写路径门控在工厂边缘,读不阻断静态面)。
2020
+ */
2021
+ interface ReadIntegrationsResult {
2022
+ /** 解析产物(严格 zod 产物或原文 JSON;文件缺席 → null) */
2023
+ config: Record<string, unknown> | null;
2024
+ /** 严格校验是否已应用(false = 原文透传——<0.9 或未解析降级态) */
2025
+ strict: boolean;
2026
+ contracts: ResolvedContracts;
2047
2027
  }
2048
- interface CredentialValues {
2028
+ /** 文件级读(cache 注入优先;无 cache 直读——目录枚举零缓存约束不涉文件内容) */
2029
+ declare function readIntegrationsConfig(appDir: string, cache?: FileCache): Record<string, unknown> | null;
2030
+ /** 带严格校验的读(求值/写路径用——门控由工厂边缘断言,本函数按 strictValidation 分派) */
2031
+ declare function readIntegrationsStrict(appDir: string, cache?: FileCache): Promise<ReadIntegrationsResult>;
2032
+
2033
+ /**
2034
+ * 凭据双工件·写端(credentials;FX-1c 拆分—— 定序):
2035
+ * credentials / credentialsByInstance(body 唯一非文件字段)→ **纯派生 plan(零 I/O)**
2036
+ * → 消费方(write.ts)ref 回填节点(先于 no-diff 判定)→ 严格校验通过后 `writeCredentialArtifacts`
2037
+ * 落盘(dryRun → 零写盘 + existsSync 预览)。同 stem 已在场 → 重写 + overwrote:true。
2038
+ * 孤儿凭据 = **写后对账**(扫描文件全量 credentialRef 引用 vs 凭据目录全集 →
2039
+ * ORPHANED_CREDENTIAL warning——统一覆盖 DELETE 与 PUT 替换两类来源,只报告不自动清理)。
2040
+ */
2041
+ interface CredentialInput {
2049
2042
  type: string;
2050
2043
  values: Record<string, string>;
2051
2044
  }
2052
- interface ResolvedInstance {
2053
- /** 注册表 id;'*' = 通配 */
2054
- instanceId: string;
2055
- status: ServiceStatus;
2056
- /** 逐实例诊断(binding-unresolved 等直投) */
2057
- statusMessage?: string;
2058
- /** 该实例合并结果 */
2059
- effective?: EffectiveBinding;
2060
- }
2061
- /** GET /providers:厂商基本信息 */
2062
- interface ProvidersView {
2063
- providers: ProviderEntry[];
2045
+ interface AppliedCredential {
2046
+ stem: string;
2047
+ ref: string;
2048
+ overwrote: boolean;
2064
2049
  }
2065
- interface ProviderEntry {
2066
- provider: string;
2067
- /** Mock 旗标(provider 级聚合) */
2068
- local: boolean;
2069
- /** 供给声明来源包名 */
2070
- owner: string;
2071
- /** 厂商展示名(v7 title→name:manifest name——多包首声明;缺席 = undefined) */
2072
- name?: string;
2073
- description?: string;
2050
+ /** 凭据工件计划项(纯派生产物——stem/ref 确定性;input 供落盘/校验消费) */
2051
+ interface PlannedCredential {
2052
+ /** 实例级(credentialsByInstance)时在场;应用/服务级根凭据缺席 */
2053
+ instanceId?: string;
2054
+ stem: string;
2055
+ ref: string;
2056
+ input: CredentialInput;
2074
2057
  }
2075
- /** GET /providers/:provider:供给足迹 */
2076
- interface ProviderDetail {
2077
- provider: string;
2078
- local: boolean;
2079
- owner: string;
2080
- /** 厂商展示名(同 ProviderEntry——首声明透传) */
2081
- name?: string;
2082
- description?: string;
2083
- /** per (provider, service) 保真,同厂商异构合法;★ implementations 恒数组(H1——
2084
- * 多元素 = 升级窗口,UI 出 impl 选择器,PUT 显式钉版) */
2085
- services: Record<string, {
2086
- implementations: Array<{
2087
- implementation: string;
2088
- credentialType: string;
2089
- }>;
2090
- /** 服务展示名(resolveServiceDisplay——词汇 > demand > id;恒发) */
2091
- name?: string;
2092
- description?: string;
2093
- /** v4.4 include=integrationSchemas 切换态批量(纯 config——凭据结构归 /credential-types) */
2094
- integrationSchemas?: {
2095
- configSchema: object | null;
2096
- };
2097
- }>;
2058
+ interface OrphanIssue {
2059
+ severity: 'warning';
2060
+ code: 'ORPHANED_CREDENTIAL';
2061
+ service?: string;
2062
+ instance?: string;
2063
+ message: string;
2098
2064
  }
2099
- /** GET /providers/:p/services/:s:表单 schema 唯一暴露面 */
2100
- interface ProviderServiceDetail {
2101
- provider: string;
2102
- service: string;
2103
- /** ★ 恒数组(通常 1);credentialType 保留(/credential-types 寻址键) */
2104
- implementations: Array<{
2105
- implementation: string;
2106
- credentialType: string;
2065
+ /** 凭据工件在场探测(dryRun 预览与对账共用) */
2066
+ declare function credentialArtifactExists(appDir: string, stem: string): boolean;
2067
+ /** 孤儿凭据写后对账:凭据目录全集 − integrations.json 全量引用 = 孤儿(只报告不清理) */
2068
+ declare function reconcileOrphanCredentials(appDir: string): OrphanIssue[];
2069
+
2070
+ /**
2071
+ * 写核心(write;FX-1c 管线重排—— 九步定序 + D-B2 语义 + 输入扩位):
2072
+ * PUT = 节点全量替换(三同构——body ≡ 文件节点;三 PUT 端点无例外)。
2073
+ *
2074
+ * 九步定序(applyApp / applyService 同构):
2075
+ * 1 输入约束(assertSafeNames 值位 + assertSafeInstanceKeys map 键位——)
2076
+ * 2 合并 node → next;文件缺席 → 骨架物化(语义翻转提示入 issues)
2077
+ * 3 凭据校验链(type 匹配 400 + credentialSchema ajv 字段级——schema 缺席宽松;dryRun 也跑)
2078
+ * 4 凭据 stem/ref **纯派生**(plan*——零 I/O)+ ref 回填节点(**先于 no-diff**:
2079
+ * node 缺 ref + 带 credentials → 节点变化 → 全量写;node 已含同 ref → 节点不变 → 纯凭据写)
2080
+ * 5 noDiff(**深度结构等价**,非 stringify);hasCredentialInput
2081
+ * 6 noDiff && 无凭据输入 → 短路 written:false
2082
+ * 7 严格整文档校验(contracts parseIntegrationsConfig——触发 = !noDiff ∥ 有凭据输入)
2083
+ * 8 凭据工件落盘(**后置于校验通过**——防「凭据已写 + zod 拒绝」不一致态;
2084
+ * dryRun → writeCredentialArtifacts 零写盘 + existsSync 预览)
2085
+ * 9 finalize:planned = 将触碰(files 预览单源——dryRun 响应 ≡ 同 body 真实写,files 逐字对称);
2086
+ * written = 实写(!dryRun 派生,D-B2);restartScheduled = written && onApplied(凭据影响 boot 装配——
2087
+ * 重启正当);写后缓存失效
2088
+ * 归一化:N1 模块节点 {} → 删 domains[键];N3 服务节点 {} 不归一化(显式通配激活 = 合法 TIER0 态);
2089
+ * N2 已随 ?instance= 退役。dryRun(PUT only):复读完整管线不落盘不排程。
2090
+ * DELETE:节点移除 + 孤儿凭据写后对账(覆盖 DELETE 与 PUT 替换两类来源,只报告不清理——)。
2091
+ * 并发:进程内串行(per-factory promise chain 由工厂持有——本模块假设单飞调用)。
2092
+ */
2093
+ interface SaveResult {
2094
+ written: boolean;
2095
+ restartScheduled: boolean;
2096
+ files: string[];
2097
+ credentials: Array<{
2098
+ stem: string;
2099
+ ref: string;
2100
+ overwrote: boolean;
2107
2101
  }>;
2108
- /** 厂商集成该服务的表单 schema(integration 域专属)——v4.4 纯 config(credentialSchema 删净) */
2109
- integrationSchemas: {
2110
- /** raw draft 2020-12 原文零转换;供给在场未声明 = null(mock 合法);解析自默认 impl */
2111
- configSchema: object | null;
2112
- };
2113
- }
2114
- /** GET /credentials:绑定位全量掩码回显(应用状态轴;GET 永无真值) */
2115
- interface CredentialsView {
2116
- /** root 位;byInstance 键集 = 注册表 ids ∩ 有 ref(无 ref 的注册实例不出现;未注册 ref 跳过不虚报) */
2117
- app: CredentialBindingEcho;
2118
- /** 键集 = 已配置服务;byInstance 键集 = 节点 instances map 全键(含 '*')——键域不对称 = 文件语义忠实镜像 */
2119
- services: Record<string, CredentialBindingEcho>;
2102
+ issues: IntegrationServiceIssue[];
2120
2103
  }
2121
- /** 一个形状两处(镜像文件层「标量 + ByInstance」模式) */
2122
- interface CredentialBindingEcho {
2123
- /** 本位 credentialRef(root.credentialRef / services[s].credentialRef);ref 缺席/文件缺失 → null */
2124
- credential: CredentialEcho | null;
2125
- /** 覆盖位(credentialRefByInstance / instances[k].credentialRef) */
2126
- byInstance: Record<string, CredentialEcho | null>;
2104
+ interface WriteOptions {
2105
+ dryRun?: boolean;
2106
+ /** body 唯一非文件字段(真值直落 config/credentials/,派生 ref 回填本节点) */
2107
+ credentials?: CredentialInput;
2108
+ credentialsByInstance?: Record<string, CredentialInput>;
2127
2109
  }
2128
- /** GET /credential-types[?provider=]:凭据结构清单(供给轴静态;?provider= 过滤语义 ≡ ?service=) */
2129
- interface CredentialTypesView {
2130
- types: CredentialTypeEntry[];
2110
+ interface WriteCoreOptions {
2111
+ onApplied?: () => void;
2112
+ cache?: FileCache;
2131
2113
  }
2132
- interface CredentialTypeEntry {
2133
- /** '-' = 无凭据语义(mock/local——UI 判 '-' 不渲染凭据表单) */
2134
- credentialType: string;
2135
- /** 声明来源包名 */
2136
- owner: string;
2137
- /** raw draft 2020-12 原文;未声明 = null(ExtraFields 自由键值同轨) */
2138
- credentialSchema: object | null;
2114
+ /** 深度结构等价(非 stringify——键序陷阱误判 diff 防线) */
2115
+ declare function deepEqual(a: unknown, b: unknown): boolean;
2116
+ interface WriteCore {
2117
+ /** 预热(工厂创建/写前调用——严格校验缓存就绪;memoized resolver 后续 1 stat 级) */
2118
+ warmup(): Promise<void>;
2119
+ /** PUT /app/integration(root 节点全集) */
2120
+ applyApp(node: Record<string, unknown>, opts?: WriteOptions): SaveResult;
2121
+ /** PUT /modules/:module/integration(v6 modules[owner] 集成位;键集纪律见 MODULE_INTEGRATION_NODE_KEYS;
2122
+ * N1 {} 清 provider/config 保 resources;moduleOwnershipWritable 写守卫单源) */
2123
+ applyModule(moduleId: string, node: Record<string, unknown>, opts?: WriteOptions): SaveResult;
2124
+ /** PUT /services/:service/integration(整节点含 instances map;N3 {} 不归一化;v4.4 A2 身份判据) */
2125
+ applyService(service: string, node: Record<string, unknown>, opts?: WriteOptions): SaveResult;
2126
+ /** DELETE /services/:service/integration(恒整节点;幂等仅判据内成员;无预演) */
2127
+ deleteService(service: string): SaveResult;
2139
2128
  }
2140
- interface EffectiveBinding {
2141
- /** custom 时 provider = 内联声明厂商名 */
2142
- provider: string;
2143
- implementation: string;
2144
- config?: Record<string, unknown>;
2145
- /** 'secret://{stem}' */
2146
- credentialRef?: string;
2147
- layer: BindingLayer;
2129
+ declare function createWriteCore(appDir: string, opts?: WriteCoreOptions): WriteCore;
2130
+
2131
+ /**
2132
+ * mock 槽绑定生成器(自 CLI mock-bindings.ts 迁入;provider 拆包 收敛 · B 方案;integrations v4 零拓扑形态):
2133
+ * 应用内 config/integrations.json 缺席时,从已装模块 manifest 的 local:true 槽派生全槽 mock 绑定。
2134
+ *
2135
+ * 语义边界(零改动迁移):
2136
+ * - 缺席即跳过、永不覆盖(在场文件 = 用户/素材真源,生成器零侵入);
2137
+ * - 只绑 local:true 槽(真厂商 provider 永不自动绑定);
2138
+ * - sync 不触发(add = 新事实进入体系,sync = 状态重放)。
2139
+ * 迁移顺带修复:writeFileSync → writeAtomic(原子写;H5)。
2140
+ * 模块发现改 walkManifests(单源——CLI listLocalModules 并入)。
2141
+ */
2142
+ interface MockBindingsResult {
2143
+ generated: boolean;
2144
+ reason: 'in-place' | 'no-local-slots' | 'generated';
2145
+ /** 本次生成(或在场文件阻断时的空集)涉及的 local 槽服务名 */
2146
+ services: string[];
2148
2147
  }
2149
- /** GET 永无真值 */
2150
- interface CredentialEcho {
2151
- /** credentialType(manifest 对齐) */
2152
- type: string;
2153
- /** 'secret://{stem}' */
2154
- ref: string;
2155
- /** 'config/credentials/{stem}.json' */
2156
- file: string;
2157
- /** 前 2 字符 + '****';≤4 字符全掩码;null = 缺字段 */
2158
- masked: Record<string, string | null>;
2148
+ declare function ensureMockBindings(appDir: string): MockBindingsResult;
2149
+
2150
+ /**
2151
+ * 模块级联绑定单源(integrations v6 所有权模型——原 domain-binding.ts v4.4/ 重写)。
2152
+ * integrations 层落位依据:谓词(同层)/ 写核(同层)/ views(下层可向上 import)三向消费
2153
+ * 的唯一公共下层;import 前缀 guard 覆盖。
2154
+ *
2155
+ * 知识锚(module-tab note 单源锚表,v6 形态):
2156
+ * 模块级联(值 + 层) = resolveModuleBinding —— 谓词 #7(per-module 生效厂商 ≡
2157
+ * `modules[m].provider ?? root.provider`)/ deriveBindingLayer 模块级段 /
2158
+ * buildInheritance module 段 / binding(单数)
2159
+ * 归属表 = walk.ownership(单源聚合产物;buildOwnershipMap 桥直通——
2160
+ * registry 显式参 / 谓词 / 写守卫 / views 四消费方零第二实现)
2161
+ * 来源层四层推导 = deriveBindingLayer(views/service-resolutions,模块级段改调本文件)
2162
+ * 写通道可用性 = moduleOwnershipWritable —— configEditable 读标志 / applyModule 400 守卫
2163
+ * 共用(owns>0 唯一判据——多域归属合法化、共享键/多域判据随 退役)
2164
+ */
2165
+ /** 归属表构建(walk 单源直通——sdk 桥 re-export 消费;appDir 直入对齐 loadProviderCatalog
2166
+ * 桥工效——模板装配第六行:`ownerOf: buildOwnershipMap(appDir)`)。 */
2167
+ declare function buildOwnershipMap(appDir: string): Record<string, string>;
2168
+ /** 模块级联绑定解析(值 + 来源层):provider 取非空字符串(模块级优先 → root 兜底;空串 = 缺席)。
2169
+ * layer:modules[moduleId].provider 声明 → 'module';root 兜底 → 'app';双缺 → null(binding 双缺诚实态)。 */
2170
+ declare function resolveModuleBinding(config: Record<string, unknown> | null, moduleId: string): {
2171
+ provider: string | null;
2172
+ layer: 'module' | 'app' | null;
2173
+ };
2174
+ /** 模块集成位可写性(v6 判别联合——configEditable 读标志与 applyModule 写守卫共用单源):
2175
+ * owns>0 唯一判据(多域/shared-key 判据随 v6 退役——服务归属唯一真源 = declare.owns)。 */
2176
+ type ModuleOwnershipWritability = {
2177
+ writable: true;
2178
+ ownedServices: string[];
2179
+ } | {
2180
+ writable: false;
2181
+ reason: 'zero-ownership';
2182
+ ownedServices: [];
2183
+ };
2184
+ declare function moduleOwnershipWritable(_walk: Pick<WalkManifestsResult, 'modules' | 'catalog' | 'ownership'>, mod: WalkModuleInfo): ModuleOwnershipWritability;
2185
+ /** 供给足迹(该厂商全部供给服务并集——应用级 integrationSchemas 作用域) */
2186
+ declare function providerFootprint(catalog: WalkCatalog, provider: string): string[];
2187
+
2188
+ /** app 轴绑定解析:configured ≡ effective(app 无上级——清除后无回落) */
2189
+ declare function appProviderBinding(config: Record<string, unknown> | null): ProviderBinding;
2190
+ /** module 轴绑定解析:effective 复用 resolveModuleBinding 单源(谓词 #7 模块层同判);
2191
+ * inherited = 清除模块级后的 root 回落(configured 缺席时 ≡ effective——无变化语义)。 */
2192
+ declare function moduleProviderBinding(config: Record<string, unknown> | null, moduleId: string): ProviderBinding;
2193
+ /** service 轴绑定解析(node 级口径):inherited = 上级绑定(owner 模块 ?? root——无主平台槽
2194
+ * 直落 root);malformed → configured null + 级联(谓词 #5 诊断经 issues 恒可见,不静默)。 */
2195
+ declare function serviceProviderBinding(config: Record<string, unknown> | null, walk: Pick<WalkManifestsResult, 'ownership'>, service: string): ProviderBinding;
2196
+
2197
+ /**
2198
+ * AppToolkitError(领域 6 码 + 壳层 2 码分界——toolkit 只产领域码):
2199
+ * VALIDATION_FAILED(400) / SERVICE_NOT_FOUND(404) / MODULE_NOT_FOUND(404) /
2200
+ * PROVIDER_NOT_FOUND(404) / SUPPLY_NOT_FOUND(404) / CONTRACTS_NOT_RESOLVED(503)。
2201
+ * AUTH_REQUIRED / ROUTE_NOT_FOUND 为 HTTP 层事实(壳层产生)——6 + 2 = 8(api.md §5)。
2202
+ *
2203
+ * **name 约定(仓规约束①——mangle 安全真源 process note 2026-09-11-publish-dist-minify)**:
2204
+ * 构造器必须字符串字面量赋值 `this.name = 'AppToolkitError'`(禁 `this.name = X.name` binding
2205
+ * 形态——src 态守卫不可见、mangle 后静默漂移);守卫 = tests/error-name-safety.test.ts(C4)。
2206
+ * 消费面属性分发(.httpStatus/.code/.fields——比 err.name 分发更宽裕)。
2207
+ */
2208
+ type AppToolkitErrorCode = 'VALIDATION_FAILED' | 'SERVICE_NOT_FOUND' | 'MODULE_NOT_FOUND' | 'PROVIDER_NOT_FOUND' | 'SUPPLY_NOT_FOUND' | 'CONTRACTS_NOT_RESOLVED';
2209
+ declare class AppToolkitError extends Error {
2210
+ readonly code: AppToolkitErrorCode;
2211
+ readonly httpStatus: number;
2212
+ readonly fields?: string[];
2213
+ constructor(code: AppToolkitErrorCode, httpStatus: number, message: string, fields?: string[]);
2159
2214
  }
2160
- interface ContractsResolution {
2215
+ /** CONTRACTS_NOT_RESOLVED message(N1 构建指引——api.md 错误信封示例)。
2216
+ * P-4:notes 优先——resolver 在全部不可解析路径均已 push 携带操作指引的 notes(导入失败/
2217
+ * 产物缺失/未安装/<0.9 升级);现行 version===null 分支会把 notes 内细分指引吞成通用文案。
2218
+ * 分支保留为兜底(防御性——正常路径 notes 恒非空)。
2219
+ * v7:+= ownershipBindingV6 分支(标记门第四分支单源化——写门控 assertContractsUsable 与
2220
+ * 读求值轴降级 statusMessage 共用同一文案;可选参向后兼容)。 */
2221
+ declare function contractsNotResolvedMessage(contracts: {
2161
2222
  version: string | null;
2162
- evaluation: boolean;
2163
2223
  strictValidation: boolean;
2164
- notes: string[];
2165
- }
2166
- /** 字段级真源 = 谓词结构化输出(H7) */
2167
- interface IntegrationIssue {
2168
- severity: 'error' | 'warning';
2169
- /** 枚举单源 = 谓词文件头检查族编号映射(additive-only) */
2170
- code: string;
2171
- message: string;
2172
- service?: string;
2173
- module?: string;
2174
- instance?: string;
2175
- }
2224
+ notes: readonly string[];
2225
+ ownershipBindingV6?: boolean;
2226
+ }): string;
2176
2227
 
2177
2228
  /**
2178
2229
  * 视图装配共享上下文(五投影共用;目录枚举零缓存——walkManifests 每次调用执行)。
@@ -2220,24 +2271,57 @@ declare function loadAppView(snapshot: ViewSnapshot): AppView;
2220
2271
  declare function loadServiceDetailView(snapshot: ViewSnapshot, service: string): ServiceDetail;
2221
2272
 
2222
2273
  /**
2223
- * 供给轴投影(views/providers;C4)。供给关系三切片:
2224
- * 名单 = /providers(基本信息)· 足迹 = /providers/:p(implementations[] 保真)·
2225
- * 表单 = /providers/:p/services/:s(组合单体——schema 唯一暴露面)。
2274
+ * 供给轴投影(views/providers;C4)。v8 后供给面 = 名单(/providers,vendorMeta 单源含
2275
+ * 零槽自声明厂商)· 判定(/providers/:p/supply——见 provider-supply.ts)·
2276
+ * 表单(组合单体 /providers/:p/services/:s——configSchema 唯一暴露面)。
2226
2277
  * 静态端点零求值(铁律 #3)。
2227
2278
  */
2228
- /** GET /providers:厂商基本信息(供给足迹不在本端点 → /providers/:p) */
2279
+ /** GET /providers:厂商基本信息(vendorMeta 单源——slots 厂商 + 零槽自声明厂商同路径;
2280
+ * 零槽厂商 = 空 impl map + 自声明 meta(supply 判定「厂商在、供给空」语义) */
2229
2281
  declare function loadProvidersView(snapshot: ViewSnapshot): ProvidersView;
2230
- /** GET /providers/:provider:供给足迹(implementations 恒数组——H1 多实现钉版数据源;
2231
- * v4.4 include=integrationSchemas 切换态批量——services[s] += { configSchema }(纯 config)) */
2232
- declare function loadProviderDetailView(snapshot: ViewSnapshot, provider: string, include?: ReadonlySet<string>): ProviderDetail;
2233
2282
  /** 组合单体(GET /providers/:p/services/:s):catalog 供给与槽级内联声明统一解析(/) */
2234
2283
  declare function loadProviderServiceDetailView(snapshot: ViewSnapshot, provider: string, service: string): ProviderServiceDetail;
2235
2284
 
2236
- /** 单源摘要函数:/service-resolutions map 值 ≡ /service-resolutions/:s 的 resolution 摘要基 */
2237
- declare function resolveServiceSummary(service: string, snapshot: ViewSnapshot): ServiceResolutionEntry;
2285
+ /**
2286
+ * 供给判定投影(views/provider-supply;v8——切换预览唯一判定源,前端零供给关系计算)。
2287
+ * 判定关系单源 = catalog 供给关系((provider, service) ∈ 已装 provider 包槽声明 +
2288
+ * `declare.providers.id` 零槽自声明厂商——与求值轴 resolution.supplied 同一关系)。
2289
+ *
2290
+ * scope 三轴 = 该层绑定实际作用的服务集合(api.md §7):
2291
+ * app → resolutionKeys 单源(在册服务全集——root 级联全域可达,与批量求值键集恒等)
2292
+ * module → 归属服务(declare.owns 展平——moduleOwnershipWritable 单源 ≡ detail.ownedServices;
2293
+ * 跨模块消费服务不入 scope——其绑定跟随各自 owner,与本模块绑定无关)
2294
+ * service → 自身(任意 id 恒 200——判定非寻址,supplied:false 表达未供给)
2295
+ *
2296
+ * surplus(作用域外供给)不表达。判定非寻址:已知厂商 + 不在足迹的 service → 200 +
2297
+ * supplied:false(与组合单体 SUPPLY_NOT_FOUND 404 的有意分歧);厂商 ∉ catalog → 404。
2298
+ * 静态零 contracts——contracts 不可用时判定仍可用(降级态「数据来源」功能存活)。
2299
+ */
2300
+ declare function loadProviderSupplyView(snapshot: ViewSnapshot, provider: string, scope: ProviderSupplyScope): ProviderSupplyView;
2301
+
2302
+ /** 实例求值产物(摘要消费 status/provider;单体消费 effective) */
2303
+ interface InstanceEvaluation {
2304
+ status: ServiceStatus;
2305
+ statusMessage?: string;
2306
+ provider?: string;
2307
+ implementation?: string;
2308
+ effective?: EffectiveBinding;
2309
+ }
2310
+ /** 单源摘要函数:/service-resolutions map 值 ≡ /service-resolutions/:s 的 resolution 摘要基。
2311
+ * precomputed = 调用方已求值的默认实例产物(求值单体复用——消默认实例重复求值,B4)。 */
2312
+ declare function resolveServiceSummary(service: string, snapshot: ViewSnapshot, precomputed?: {
2313
+ evaluation: InstanceEvaluation;
2314
+ supplies: unknown;
2315
+ }): ServiceResolutionEntry;
2316
+ /** 批量键集(求值轴/降级轴共用单源:服务词汇 ∪ 需求侧 ∪ 已配置 ∪ 归属)。
2317
+ * v6.1 += 归属键——owned 服务恒可求值(embed 自足前置:迭代基不是 filter,
2318
+ * 缺此键则 owned ∖ 词汇服务在内嵌轴静默丢键,fail-visible 破功)。
2319
+ * v8 起导出:app 轴供给判定作用域(provider-supply)同源消费——键集恒等断言防第二实现漂移。 */
2320
+ declare function resolutionKeys(snapshot: ViewSnapshot): string[];
2238
2321
  /** 批量求值(键集 = resolutionKeys 单源:词汇 ∪ 需求侧 ∪ 已配置 ∪ 归属;?service= 过滤语义——未知键缺席;issues 恒全量) */
2239
2322
  declare function loadServiceResolutionsView(snapshot: ViewSnapshot, issues: IntegrationIssue[], filter?: string[]): ServiceResolutionsView;
2240
- /** 求值单体(完整结构 instances + inheritance + 过滤 issues; extends 结构保证) */
2323
+ /** 求值单体(完整结构 instances + inheritance + 过滤 issues; extends 结构保证)。
2324
+ * v8 B4 修复:默认实例求值结果复用入摘要(原 resolveServiceSummary 独立重算 = 重复求值)。 */
2241
2325
  declare function loadServiceResolutionDetail(service: string, snapshot: ViewSnapshot, allIssues: IntegrationIssue[]): ServiceResolutionDetail;
2242
2326
 
2243
2327
  /**
@@ -2266,13 +2350,10 @@ declare function resolveLayerIntegrationSchemas(snapshot: ViewSnapshot, provider
2266
2350
  * fields 收集零过滤(布尔/非对象子 schema 入列,判定全权归 mergeFieldSources—— 互证等式由
2267
2351
  * 收集定义结构性闭合);schemaless 仅 configSchema === null(布尔/畸形整 schema 防御跳过——
2268
2352
  * 不入 schemaless、零参与聚合; 运行时畸形,非契约面)。 */
2269
- declare function buildIntegrationFieldRegistry(layer: LayerIntegrationSchemas, o?: {
2270
- unsupplied?: string[];
2271
- }): IntegrationFieldRegistryView;
2272
- /** 生效厂商解析单源(实际/假想同径):override(非空串)?? 实际解析。
2273
- * 空串归一(I3)单点;module 轴 v6 零归属 → null(override 不豁免——预览服务于保存)。 */
2274
- declare function formProviderOf(axis: 'app' | 'module', snapshot: ViewSnapshot, moduleId?: string, override?: string): string | null;
2275
- /** app 级 loader(v4.6 委托化——签名零改动,公开面保持;假想态归 loadAppFormViews override 参) */
2353
+ declare function buildIntegrationFieldRegistry(layer: LayerIntegrationSchemas): IntegrationFieldRegistryView;
2354
+ /** 生效厂商解析单源(v8——轴参退场,纯实际解析)。module 轴 v6 零归属 → null。 */
2355
+ declare function formProviderOf(axis: 'app' | 'module', snapshot: ViewSnapshot, moduleId?: string): string | null;
2356
+ /** app 级 loader(v4.6 委托化——公开面保持) */
2276
2357
  declare function loadAppIntegrationSchemas(snapshot: ViewSnapshot): LayerIntegrationSchemas | null;
2277
2358
  /** module 级 loader(v4.6 委托化——同上;多域/零域/共享键/未绑定 → 整字段 null,表单降级 = ExtraFields) */
2278
2359
  declare function loadModuleIntegrationSchemas(snapshot: ViewSnapshot, moduleId: string): LayerIntegrationSchemas | null;
@@ -2284,26 +2365,22 @@ declare function loadModuleIntegrationSchemas(snapshot: ViewSnapshot, moduleId:
2284
2365
  * (H9 逃逸 400 照抛——readInlineSchema 共享路径)
2285
2366
  * ④ 其余(null/数组/原始值/坏对象)→ 整字段 null(≡ 谓词 #5 INLINE_PROVIDER_INVALID 同判——
2286
2367
  * 不放行域级联,防错误 schema 污染坏节点)
2287
- * v5.1 serviceProvider = 服务轴向假想绑定(缺席/空串 ≡ 按实际解析——I3 归一单点在此头部,
2288
- * registry 侧不重复归一);非空轴参 → 短路 bare 解析(镜像 formProviderOf「输入替换非分支复制」先例:
2289
- * 任一原分支改写 provider 为 X 后实读都进 bare 分支,同构承诺 by construction)。短路在节点读取之前——
2290
- * 豁免链三分支(与 四分支的有意分歧:预览与坏文件解耦):malformed(分支④)不污染假想 /
2291
- * 内联 ref 不读取(假想态无 H9 逃逸 400;catalog 命中的 manifest 声明路径照读,与节点声明的
2292
- * 用户可控路径不同性)/ 全链未绑定时假想仍非 null(服务轴恒可写,无 module 轴零归属对应物)。 */
2293
- declare function loadServiceIntegrationSchemas(snapshot: ViewSnapshot, service: string, serviceProvider?: string): ServiceIntegrationSchemas | null;
2368
+ * v8:服务轴假想绑定轴参(serviceProvider)退场——切换预览归 /providers/:p/supply,
2369
+ * 本函数纯实际解析。 */
2370
+ declare function loadServiceIntegrationSchemas(snapshot: ViewSnapshot, service: string): ServiceIntegrationSchemas | null;
2294
2371
  /** G 批:服务轴字段注册表(四分支链复用——消费 loadServiceIntegrationSchemas 单源;
2295
2372
  * 伪层 {provider, services: {[s]: {configSchema}}} → buildIntegrationFieldRegistry——
2296
2373
  * fields = 该 schema 全部字段带 global 旗标;configSchema null → schemaless=[service]
2297
2374
  * 非 null 空集;schemas 整体 null(全链未绑定/坏节点)→ registry null——镜像 语义)。
2298
- * v5.1 serviceProvider = 服务轴向假想绑定,纯透传(I1 单源——归一与短路都在链函数头部;
2299
- * 轴参仅重定向表单层投影,global 旗标全量透传语义不变)。 */
2300
- declare function loadServiceFieldRegistry(snapshot: ViewSnapshot, service: string, serviceProvider?: string): IntegrationFieldRegistryView | null;
2375
+ * v8:服务轴假想绑定轴参退场(同 loadServiceIntegrationSchemas)。 */
2376
+ declare function loadServiceFieldRegistry(snapshot: ViewSnapshot, service: string): IntegrationFieldRegistryView | null;
2301
2377
 
2302
2378
  /**
2303
2379
  * 凭据状态轴投影(views/credentials;v4.4 独立端点 GET /credentials):
2304
2380
  * 绑定位全量掩码回显——应用状态轴(随配置失效、零求值零 contracts、永不 503)。
2305
2381
  * GET 永无真值(仅 ref/masked);掩码单源 maskCredentialValues;echoForRef 自
2306
2382
  * service-resolutions 迁入共享(求值单体 instances[].credential 已删净——求值路径零凭据 I/O)。
2383
+ * v8:file 字段删净(ref → config/credentials/{stem}.json 确定性派生——stemToFilePath 公开导出)。
2307
2384
  *
2308
2385
  * 键集 = 文件语义忠实镜像(api.md §0「键域不对称」):
2309
2386
  * app.byInstance = 注册表 ids ∩ 有 ref(无 ref 的注册实例不出现;未注册 ref 跳过不虚报)
@@ -2326,11 +2403,10 @@ declare function loadCredentialsView(snapshot: ViewSnapshot): CredentialsView;
2326
2403
  declare function loadCredentialTypesView(snapshot: ViewSnapshot, provider?: string): CredentialTypesView;
2327
2404
 
2328
2405
  /**
2329
- * createAppToolkit(C4 工厂;v4.4——24 方法 = 11 读(含 credentials/credential-types 双端点)
2330
- * + 4 写 + 9 迁移面;loadApp/loadModule/loadProvider 增 include 选项;v4.6——loadApp/loadModule
2331
- * += 轴向假想绑定选项(appProvider/moduleProvider);表单双投影经 formViews 单点装配;
2332
- * v4.7——loadService 增 include 选项(服务级生效绑定 schema 单体);v5.1——loadService
2333
- * += serviceProvider 轴参(服务轴向假想绑定,三轴收口))。
2406
+ * createAppToolkit(C4 工厂;v8——24 方法 = 11 读 + 4 写 + 9 Internals(−loadProvider【B 类
2407
+ * 即删】+loadProviderSupply【供给判定端点】)。沿革:v4.4 include 选项;v4.6/v5.1 轴向假想
2408
+ * 绑定选项(v8 退场,切换预览归 /providers/:p/supply);v7 读求值轴降级;v8 三静态
2409
+ * 视图缺省携带 binding(「数据来源」状态单源)。
2334
2410
  * AppToolkit = AppToolkitRead & AppToolkitWrite & AppToolkitInternals——
2335
2411
  * Read+Write = HTTP 直通面 additive 冻结(L1 端点↔方法 1:1,L3 命名镜像:Integration=节点级 /
2336
2412
  * Config=文件级);Internals = CLI/doctor/桥消费(自由演进)。
@@ -2359,29 +2435,23 @@ interface AppToolkitRead {
2359
2435
  loadModules(o?: {
2360
2436
  includeHidden?: boolean;
2361
2437
  }): Promise<ModulesView>;
2362
- /** v4.6 moduleProvider = 轴向假想绑定(缺席/空串 ≡ 按实际配置解析;需与表单 include 键同现)。
2363
- * moduleId = 双键(id 优先、唯一展示名兜底)。 */
2438
+ /** moduleId = 双键(id 优先、唯一展示名兜底)。v8:binding 缺省携带(moduleProvider 轴参退场) */
2364
2439
  loadModule(moduleId: string, o?: {
2365
2440
  include?: string[];
2366
- moduleProvider?: string;
2367
2441
  }): Promise<ModuleDetailView>;
2368
- /** v4.6 appProvider = 轴向假想绑定(缺席/空串 ≡ 按实际配置解析;需与表单 include 键同现) */
2369
2442
  loadApp(o?: {
2370
2443
  include?: string[];
2371
- appProvider?: string;
2372
2444
  }): Promise<AppView>;
2373
- /** v5.1 serviceProvider = 服务轴向假想绑定(缺席/空串 ≡ 按实际配置解析;需与表单 include
2374
- * 键同现)——假想重定向仅表单双投影,integration/suppliedBy/defaults 恒实际态(I2) */
2375
2445
  loadService(service: string, o?: {
2376
2446
  include?: string[];
2377
- serviceProvider?: string;
2378
2447
  }): Promise<ServiceDetail>;
2379
2448
  loadServiceResolutions(services?: string[]): Promise<ServiceResolutionsView>;
2380
2449
  loadServiceResolution(service: string): Promise<ServiceResolutionDetail>;
2381
2450
  loadProviders(): Promise<ProvidersView>;
2382
- loadProvider(provider: string, o?: {
2383
- include?: string[];
2384
- }): Promise<ProviderDetail>;
2451
+ /** GET /providers/:p/supply?scope=…(v8——供给判定;切换预览唯一判定源,前端零关系计算)。
2452
+ * scope 显式判别联合;provider ∉ catalog → 404;scope=module 未装 → 404;
2453
+ * scope=service 任意 id 恒 200(判定非寻址)。 */
2454
+ loadProviderSupply(provider: string, scope: ProviderSupplyScope): Promise<ProviderSupplyView>;
2385
2455
  loadProviderService(provider: string, service: string): Promise<ProviderServiceDetail>;
2386
2456
  /** GET /credentials(v4.4——应用状态轴;零门控,永不 503) */
2387
2457
  loadCredentials(): Promise<CredentialsView>;
@@ -2439,4 +2509,4 @@ interface AppToolkitInternals {
2439
2509
  type AppToolkit = AppToolkitRead & AppToolkitWrite & AppToolkitInternals;
2440
2510
  declare function createAppToolkit(appDir: string, options?: AppToolkitOptions): AppToolkit;
2441
2511
 
2442
- export { APP_INTEGRATION_NODE_KEYS, type AppIntegrationNode, type AppManifest, type AppManifestFull, type AppToolkit, AppToolkitError, type AppToolkitErrorCode, type AppToolkitInternals, type AppToolkitOptions, type AppToolkitRead, type AppToolkitWrite, type AppView, type AppliedCredential, type BindingLayer, type BridgeProviderCatalog, type CardContrib, type ContractsResolution, type CredentialBindingEcho, type CredentialEcho, type CredentialFile, type CredentialInput, type CredentialTypeEntry, type CredentialTypesView, type CredentialValues, type CredentialsView, type DeclarationIssue, type DeclaredModuleInfo, type DiscoveredSlotSource, type EffectiveBinding, type EnvExpansionResult, type EvaluationExports, type FileCache, type InlineVendorDeclaration, type IntegrationFieldRegistryView, type IntegrationIssue, type IntegrationServiceIssue, type IntegrationServicePredicateInput, type LayerIntegrationSchemas, MODULE_INTEGRATION_NODE_KEYS, type MiniappContainerEntry, type MockBindingsResult, type ModuleBinding, type ModuleDeclaration, type ModuleDescriptor, type ModuleDetailView, type ModuleIntegrationNode, type ModuleMode, type ModuleOwnershipWritability, type ModuleResourceEcho, type ModuleResourcesEcho, type ModulesView, type NpmModuleEntry, type OrphanIssue, type ParseModuleResult, type PlannedCredential, type PredicateAssembly, type PredicateContracts, type PredicateIoInputs, type ProviderDetail, type ProviderEntry, type ProviderServiceDetail, type ProviderServiceSchemas, type ProviderServiceSchemasResult, type ProviderSlotContrib, type ProvidersView, type PruneResult, type ReadIntegrationsResult, type ResolvedContracts, type ResolvedInstance, type ResolvedModule, type ResourceNeedContrib, SAFE_NAME_PATTERN, type SaveResult, type ServiceConsumeContrib, type ServiceDemand, type ServiceDetail, type ServiceInstanceNode, type ServiceIntegrationNode, type ServiceIntegrationSchemas, type ServiceOwnContrib, type ServiceResolution, type ServiceResolutionDetail, type ServiceResolutionEntry, type ServiceResolutionsView, type ServiceStatus, type SlotMeta, type StemInput, type SupplyLookup, type ViewContext, type ViewSnapshot, type WalkCatalog, type WalkManifestsResult, type WalkModuleInfo, type WalkProviderEntry, type WriteCore, type WriteCoreOptions, type WriteOptions, assertValidModuleId, buildIntegrationFieldRegistry, buildOwnershipMap, buildPredicateAssembly, checkInstanceKeys, collectDeclaredModules, contractsNotResolvedMessage, createAppToolkit, createFileCache, createWriteCore, credentialArtifactExists, deepEqual, deriveStem, discoverContractPackages, echoForRef, ensureDir, ensureMockBindings, evaluateAppIntegrationIssues, evaluateIntegrationServices, expandEnvVars, extractModuleIdFromSource, formProviderOf, invalidateContractsResolver, isControlledInlineProvider, isValidModuleId, loadAppIntegrationSchemas, loadAppView, loadCredentialTypesView, loadCredentialsView, loadModuleDetailView, loadModuleIntegrationSchemas, loadModulesView, loadProviderCatalog, loadProviderCatalogRaw, loadProviderDetailView, loadProviderServiceDetailView, loadProvidersView, loadServiceDetailView, loadServiceFieldRegistry, loadServiceIntegrationSchemas, loadServiceResolutionDetail, loadServiceResolutionsView, manifestPath, maskCredentialValues, moduleDependencySchema, moduleDescriptorSchema, moduleOwnershipWritable, pageContribSchema, parseModuleDescriptor, providerFootprint, providerSlotContribSchema, pruneIntegrationBindings, readAppManifest, readAppManifestFull, readCredentialFile, readIntegrationsConfig, readIntegrationsStrict, reconcileOrphanCredentials, refToEnvKey, removeNpmModule, resolveContractsForApp, resolveContractsForApp as resolveContractsForAppExport, resolveLayerIntegrationSchemas, resolveModuleBinding, resolveModuleKey, resolveServiceKey, resolveServiceSummary, resourceNeedContribSchema, serviceConsumeContribSchema, serviceOwnContribSchema, stemToFilePath, stemToRef, tabContribSchema, updateNpmModule, upsertMiniappContainer, upsertNpmModule, walkManifests, writeAppManifest, writeAtomic, writeCredentialFile };
2512
+ export { APP_INTEGRATION_NODE_KEYS, type AppIntegrationNode, type AppManifest, type AppManifestFull, type AppToolkit, AppToolkitError, type AppToolkitErrorCode, type AppToolkitInternals, type AppToolkitOptions, type AppToolkitRead, type AppToolkitWrite, type AppView, type AppliedCredential, type BindingLayer, type BridgeProviderCatalog, type CardContrib, type ContractsResolution, type CredentialBindingEcho, type CredentialEcho, type CredentialFile, type CredentialInput, type CredentialTypeEntry, type CredentialTypesView, type CredentialValues, type CredentialsView, type DeclarationIssue, type DeclaredModuleInfo, type DiscoveredSlotSource, type EffectiveBinding, type EnvExpansionResult, type EvaluationExports, type FileCache, type InlineVendorDeclaration, type IntegrationFieldRegistryView, type IntegrationIssue, type IntegrationServiceIssue, type IntegrationServicePredicateInput, type LayerIntegrationSchemas, MODULE_INTEGRATION_NODE_KEYS, type MiniappContainerEntry, type MockBindingsResult, type ModuleBinding, type ModuleDeclaration, type ModuleDescriptor, type ModuleDetailView, type ModuleIntegrationNode, type ModuleMode, type ModuleOwnershipWritability, type ModuleResourceEcho, type ModuleResourcesEcho, type ModulesView, type NpmModuleEntry, type OrphanIssue, type ParseModuleResult, type PlannedCredential, type PredicateAssembly, type PredicateContracts, type PredicateIoInputs, type ProviderBinding, type ProviderEntry, type ProviderServiceDetail, type ProviderServiceSchemas, type ProviderServiceSchemasResult, type ProviderSlotContrib, type ProviderSupplyScope, type ProviderSupplyView, type ProvidersView, type PruneResult, type ReadIntegrationsResult, type ResolvedContracts, type ResolvedInstance, type ResolvedModule, type ResolvedProvider, type ResourceNeedContrib, SAFE_NAME_PATTERN, type SaveResult, type ServiceConsumeContrib, type ServiceDemand, type ServiceDetail, type ServiceInstanceNode, type ServiceIntegrationNode, type ServiceIntegrationSchemas, type ServiceOwnContrib, type ServiceResolution, type ServiceResolutionDetail, type ServiceResolutionEntry, type ServiceResolutionsView, type ServiceStatus, type SlotMeta, type StemInput, type SupplyLookup, type ViewContext, type ViewSnapshot, type WalkCatalog, type WalkManifestsResult, type WalkModuleInfo, type WalkProviderEntry, type WriteCore, type WriteCoreOptions, type WriteOptions, appProviderBinding, assertValidModuleId, buildIntegrationFieldRegistry, buildOwnershipMap, buildPredicateAssembly, checkInstanceKeys, collectDeclaredModules, contractsNotResolvedMessage, createAppToolkit, createFileCache, createWriteCore, credentialArtifactExists, deepEqual, deriveStem, discoverContractPackages, echoForRef, ensureDir, ensureMockBindings, evaluateAppIntegrationIssues, evaluateIntegrationServices, expandEnvVars, extractModuleIdFromSource, formProviderOf, invalidateContractsResolver, isControlledInlineProvider, isValidModuleId, loadAppIntegrationSchemas, loadAppView, loadCredentialTypesView, loadCredentialsView, loadModuleDetailView, loadModuleIntegrationSchemas, loadModulesView, loadProviderCatalog, loadProviderCatalogRaw, loadProviderServiceDetailView, loadProviderSupplyView, loadProvidersView, loadServiceDetailView, loadServiceFieldRegistry, loadServiceIntegrationSchemas, loadServiceResolutionDetail, loadServiceResolutionsView, manifestPath, maskCredentialValues, moduleDependencySchema, moduleDescriptorSchema, moduleOwnershipWritable, moduleProviderBinding, pageContribSchema, parseModuleDescriptor, providerFootprint, providerSlotContribSchema, pruneIntegrationBindings, readAppManifest, readAppManifestFull, readCredentialFile, readIntegrationsConfig, readIntegrationsStrict, reconcileOrphanCredentials, refToEnvKey, removeNpmModule, resolutionKeys, resolveContractsForApp, resolveContractsForApp as resolveContractsForAppExport, resolveLayerIntegrationSchemas, resolveModuleBinding, resolveModuleKey, resolveServiceKey, resolveServiceSummary, resourceNeedContribSchema, serviceConsumeContribSchema, serviceOwnContribSchema, serviceProviderBinding, stemToFilePath, stemToRef, tabContribSchema, updateNpmModule, upsertMiniappContainer, upsertNpmModule, walkManifests, writeAppManifest, writeAtomic, writeCredentialFile };