@tbox.cn/app-toolkit 0.5.0 → 0.7.0

package/src/factory.ts

@@ -18,7 +18,13 @@ import { loadViewSnapshotSync } from './views/context.js';
 import { loadModulesView, loadModuleDetailView } from './views/modules.js';
 import { loadAppView } from './views/app.js';
 import { loadServiceDetailView } from './views/service-detail.js';
-import { loadServiceResolutionsView, loadServiceResolutionDetail } from './views/service-resolutions.js';
+import {
+  loadServiceResolutionsView,
+  loadServiceResolutionDetail,
+  loadServiceResolutionsDegradeView,
+  loadServiceResolutionDegradeDetail,
+  contractsEvaluable,
+} from './views/service-resolutions.js';
 import { loadAppFormViews, loadModuleFormViews, loadServiceIntegrationSchemas, loadServiceFieldRegistry } from './views/integration-schemas.js';
 import { loadCredentialsView } from './views/credentials.js';
 import { loadCredentialTypesView } from './views/credential-types.js';
@@ -45,16 +51,19 @@ import type {
  * createAppToolkit（C4 工厂；v4.4——24 方法 = 11 读（含 credentials/credential-types 双端点）
  * + 4 写 + 9 迁移面；loadApp/loadModule/loadProvider 增 include 选项；v4.6——loadApp/loadModule
  * += 轴向假想绑定选项（appProvider/moduleProvider，D37）；表单双投影经 formViews 单点装配；
- * v4.7——loadService 增 include 选项（服务级生效绑定 schema 单体））。
+ * v4.7——loadService 增 include 选项（服务级生效绑定 schema 单体）；v5.1 D39——loadService
+ * += serviceProvider 轴参（服务轴向假想绑定，三轴收口））。
  * AppToolkit = AppToolkitRead & AppToolkitWrite & AppToolkitInternals——
  * Read+Write = HTTP 直通面 additive 冻结（L1 端点↔方法 1:1，L3 命名镜像：Integration=节点级 /
  * Config=文件级）；Internals = CLI/doctor/桥消费（自由演进）。
  *
- * **门控断言单点（policy at edge）**：求值（2）+ 写（4）+ ensureMockBindings / writeIntegrationsConfig /
- * evaluateIntegrationServices 入口 assertContractsUsable——strictValidation === false → 503
- * CONTRACTS_NOT_RESOLVED；静态方法不门控（永不 503——铁律 #3）；**include 装配为条件分支非门控**
- * （D31——serviceResolutions 按 evaluation && strictValidation 双条件装配，<0.9/形态异常 → null，
- * 静态端点永不 503；integrationSchemas 纯静态轴零 contracts）；integrations/ views/ 机制层保持纯函数。
+ * **门控断言单点（policy at edge——v7 读求值轴退役后范围 = 写 + 迁移面）**：写（4）+
+ * ensureMockBindings / writeIntegrationsConfig / evaluateIntegrationServices 入口
+ * assertContractsUsable——strictValidation === false → 503 CONTRACTS_NOT_RESOLVED；静态方法不门控
+ * （永不 503——铁律 #3）；**读求值轴（loadServiceResolutions/loadServiceResolution 及 include 装配）
+ * v7 起不再 503**——contracts 不可用 → 200 降级骨架（evaluation-unavailable，doctor 分级/D31 先例
+ * 对齐；依据链与裁决见 Agent Note evaluation-axis-degrade）；**include 装配为条件分支非门控**
+ * （D31 null 分支退役——三条件门 + 内嵌轴同步降级，四面统一骨架）；integrations/ views/ 机制层保持纯函数。
  *
  * 并发：进程内写串行（per-factory promise chain）+ 原子写 + 写后本实例缓存即刻失效（D26）。
  * onApplied（D7）：toolkit 判定「需要重启」（实际落盘且非 dryRun/no-diff）→ 调用一次 +
@@ -98,9 +107,10 @@ function validateInclude(kind: keyof typeof INCLUDE_WHITELIST, include?: string[
 const FORM_INCLUDE_KEYS = ['integrationSchemas', 'integrationFieldRegistry'] as const;
 
 /** v4.6 D37 轴参严检（400 先于 404——镜像输入校验先行）：非空轴参需与表单 include 键同现；
- *  缺席/空串 ≡ 按实际配置解析（I3——不触发严检）；错轴参数由壳层按名读取，天然静默忽略。 */
+ *  缺席/空串 ≡ 按实际配置解析（I3——不触发严检）；错轴参数由壳层按名读取，天然静默忽略。
+ *  v5.1 D39：联合类型 += serviceProvider（service 轴同律）。 */
 function assertAxisProviderUsable(
-  paramName: 'appProvider' | 'moduleProvider',
+  paramName: 'appProvider' | 'moduleProvider' | 'serviceProvider',
   value: string | undefined,
   include: ReadonlySet<string>,
 ): void {
@@ -119,13 +129,16 @@ function assertAxisProviderUsable(
  *  **双键契约（v7 词汇统一）**：资源路径参数双键寻址（id 优先、唯一展示名兜底——resolve-key
  *  单点；多命中 404 带候选）；query 过滤参数（loadServiceResolutions services?）恒 id-only。 */
 export interface AppToolkitRead {
-  loadModules(): Promise<ModulesView>;
+  /** GET /modules：hidden 模块默认过滤（includeHidden = true 可见——对齐 ?dryRun 布尔参数先例） */
+  loadModules(o?: { includeHidden?: boolean }): Promise<ModulesView>;
   /** v4.6 D37：moduleProvider = 轴向假想绑定（缺席/空串 ≡ 按实际配置解析；需与表单 include 键同现）。
    *  moduleId = 双键（id 优先、唯一展示名兜底）。 */
   loadModule(moduleId: string, o?: { include?: string[]; moduleProvider?: string }): Promise<ModuleDetailView>;
   /** v4.6 D37：appProvider = 轴向假想绑定（缺席/空串 ≡ 按实际配置解析；需与表单 include 键同现） */
   loadApp(o?: { include?: string[]; appProvider?: string }): Promise<AppView>;
-  loadService(service: string, o?: { include?: string[] }): Promise<ServiceDetail>;
+  /** v5.1 D39：serviceProvider = 服务轴向假想绑定（缺席/空串 ≡ 按实际配置解析；需与表单 include
+   *  键同现）——假想重定向仅表单双投影，integration/suppliedBy/defaults 恒实际态（I2） */
+  loadService(service: string, o?: { include?: string[]; serviceProvider?: string }): Promise<ServiceDetail>;
   loadServiceResolutions(services?: string[]): Promise<ServiceResolutionsView>;
   loadServiceResolution(service: string): Promise<ServiceResolutionDetail>;
   loadProviders(): Promise<ProvidersView>;
@@ -188,11 +201,8 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
       throw new AppToolkitError('CONTRACTS_NOT_RESOLVED', 503, contractsNotResolvedMessage(contracts));
     }
     if (!contracts.ownershipBindingV6) {
-      throw new AppToolkitError(
-        'CONTRACTS_NOT_RESOLVED',
-        503,
-        `contracts ${contracts.version ?? '(版本未知)'} 不支持 v6 modules 绑定形状（OWNERSHIP_BINDING_V6 标记缺席）——升级应用 @tbox.cn/app-contracts 依赖后可用`,
-      );
+      // v6 标记门第四分支（文案单源 = contractsNotResolvedMessage——降级轴 statusMessage 同源）
+      throw new AppToolkitError('CONTRACTS_NOT_RESOLVED', 503, contractsNotResolvedMessage(contracts));
     }
   }
 
@@ -242,9 +252,9 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
   }
 
   const read = {
-    async loadModules() {
+    async loadModules(o?: { includeHidden?: boolean }) {
       const contracts = await resolveContractsForApp(appDir);
-      return loadModulesView(snapshot(contracts));
+      return loadModulesView(snapshot(contracts), o);
     },
     // v4.4 D31：门控与内嵌分离——静态方法零门控分支；include=serviceResolutions 按
     // evaluation && strictValidation 双条件装配（<0.9/形态异常 → null，永不 503——技术方案 §2.4：
@@ -258,10 +268,12 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
       const mod = resolveModuleKey(snap.walk, moduleId);
       const view = loadModuleDetailView(snap, mod.id);
       if (include.has('serviceResolutions')) {
-        view.serviceResolutions = contracts.evaluation && contracts.strictValidation
+        // v7：三条件门 + 内嵌轴同步降级（P14 (b) 四面统一骨架——D31 null 分支退役：
+        // include 请求了即恒返回视图；老消费方 null 分支保留为兼容死码）
+        view.serviceResolutions = contractsEvaluable(contracts)
           ? await predicateIssues().then((issues) =>
               loadServiceResolutionsView(snap, issues, view.services.map((s) => s.service)))
-          : null; // module = demand 服务过滤（≡ 批量 ?service= 语义；issues 恒全量）
+          : loadServiceResolutionsDegradeView(snap, contracts, view.services.map((s) => s.service)); // module = demand 服务过滤（≡ 批量 ?service= 语义）
       }
       if (include.has('integrationSchemas') || include.has('integrationFieldRegistry')) {
         // v4.6 D37：表单层双投影同源一次计算（双取单算 + I1——假想重定向天然同步）
@@ -278,9 +290,10 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
       const snap = snapshot(contracts);
       const view = loadAppView(snap);
       if (include.has('serviceResolutions')) {
-        view.serviceResolutions = contracts.evaluation && contracts.strictValidation
+        // v7：内嵌轴同步降级（同 loadModule——D31 null 退役，app = 全量键集）
+        view.serviceResolutions = contractsEvaluable(contracts)
           ? await predicateIssues().then((issues) => loadServiceResolutionsView(snap, issues)) // app = 全量键集
-          : null;
+          : loadServiceResolutionsDegradeView(snap, contracts);
       }
       if (include.has('integrationSchemas') || include.has('integrationFieldRegistry')) {
         const form = loadAppFormViews(snap, o?.appProvider); // 双取单算 + I1（同 loadModule）
@@ -291,32 +304,39 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
     },
     // v4.7 D38：include 镜像 loadModule 三段式——① 输入校验 400 先于 404 ② 视图 ③ 静态富化（永不 503）
     // G 批：service 轴 += integrationFieldRegistry（loadServiceFieldRegistry——D38 四分支链复用）
-    async loadService(service: string, o?: { include?: string[] }): Promise<ServiceDetail> {
+    // v5.1 D39：loadService += serviceProvider 轴参（三段式序对齐 loadModule——①' 严检先于 resolveContracts，
+    //   即先于 404 也先于 503；I1 双投影同源一次计算经单源链透传）
+    async loadService(service: string, o?: { include?: string[]; serviceProvider?: string }): Promise<ServiceDetail> {
       const include = validateInclude('service', o?.include);
+      assertAxisProviderUsable('serviceProvider', o?.serviceProvider, include); // ①' D39 轴参严检（先于 404）
       const contracts = await resolveContractsForApp(appDir);
       const snap = snapshot(contracts); // 单快照——detail 与 include 装配共享
       // 双键寻址（v7）：id 优先、唯一展示名兜底 → 真实 service id（404 面）
       const serviceId = resolveServiceKey(snap.walk, configuredServiceKeys(snap), service);
       const view = loadServiceDetailView(snap, serviceId);
       if (include.has('integrationSchemas')) {
-        view.integrationSchemas = loadServiceIntegrationSchemas(snap, serviceId);
+        view.integrationSchemas = loadServiceIntegrationSchemas(snap, serviceId, o?.serviceProvider);
       }
       if (include.has('integrationFieldRegistry')) {
-        view.integrationFieldRegistry = loadServiceFieldRegistry(snap, serviceId);
+        view.integrationFieldRegistry = loadServiceFieldRegistry(snap, serviceId, o?.serviceProvider);
       }
       return view;
     },
     async loadServiceResolutions(services?: string[]) {
       const contracts = await resolveContractsForApp(appDir);
-      assertContractsUsable(contracts);
+      const snap = snapshot(contracts);
+      // v7 读求值轴降级门（policy-at-edge 读轴退役）：contracts 不可用 → 200 静态骨架 +
+      // evaluation-unavailable（fail-visible 保留在数据内；写路径 503 门控不变）
+      if (!contractsEvaluable(contracts)) return loadServiceResolutionsDegradeView(snap, contracts, services);
       const issues = await predicateIssues();
-      return loadServiceResolutionsView(snapshot(contracts), issues, services);
+      return loadServiceResolutionsView(snap, issues, services);
     },
     async loadServiceResolution(service: string) {
       const contracts = await resolveContractsForApp(appDir);
-      assertContractsUsable(contracts);
       const snap = snapshot(contracts);
       const serviceId = resolveServiceKey(snap.walk, configuredServiceKeys(snap), service);
+      // v7 降级门同批量端点（三条件与；降级单体携带声明实例枚举 + inheritance 静态投影）
+      if (!contractsEvaluable(contracts)) return loadServiceResolutionDegradeDetail(serviceId, snap, contracts);
       const issues = await predicateIssues();
       return loadServiceResolutionDetail(serviceId, snap, issues);
     },

package/src/index.ts

@@ -64,10 +64,10 @@ export { pruneIntegrationBindings } from './integrations/prune-bindings.js';
 export type { PruneResult } from './integrations/prune-bindings.js';
 
 // ── assembly 层（目录知识——walkManifests 四产物 + catalog 双形态 + 组合单体装配）──
-export { walkManifests } from './assembly/walk-manifests.js';
+export { walkManifests, discoverContractPackages } from './assembly/walk-manifests.js';
 // 双键寻址（v7 词汇统一——factory 七方法入口单点消费的解析 helper；纯参数式零 IO）
 export { resolveModuleKey, resolveServiceKey } from './assembly/resolve-key.js';
-export type { WalkManifestsResult, WalkModuleInfo, WalkCatalog, WalkProviderEntry, DeclarationIssue, SlotMeta } from './assembly/walk-manifests.js';
+export type { WalkManifestsResult, WalkModuleInfo, WalkCatalog, WalkProviderEntry, DeclarationIssue, SlotMeta, DiscoveredSlotSource } from './assembly/walk-manifests.js';
 export { readAppManifest, writeAppManifest, manifestPath } from './assembly/app-manifest.js';
 export type { AppManifest, NpmModuleEntry, ModuleMode } from './assembly/app-manifest.js';
 export { loadProviderCatalog, loadProviderCatalogRaw } from './assembly/provider-catalog.js';
@@ -129,6 +129,8 @@ export type {
   ServiceResolutionDetail,
   AppIntegrationNode,
   ModuleIntegrationNode,
+  ModuleResourceEcho,
+  ModuleResourcesEcho,
   ServiceIntegrationNode,
   ServiceInstanceNode,
   InlineVendorDeclaration,

package/src/integrations/write.ts

@@ -261,6 +261,10 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
       cache?.invalidate([join(appDir, INTEGRATIONS_FILE)]);
     }
     const written = integrationsWritten || credentialsWritten;
+    // 孤儿凭据写后对账（api.md §4.13 承诺追平——「覆盖 DELETE 与 PUT 替换两类来源」；三 PUT 写路径
+    // finalize 单点收口，未来第四写方法自动继承）。dryRun（written 蕴含 !dryRun）与 no-diff
+    // （finalize 前短路 return）天然跳过；applyModule modules 节无凭据键——对账恒零新增，无害捎带。
+    if (written) issues.push(...reconcileOrphanCredentials(appDir));
     const restartScheduled = written && onApplied !== undefined;
     if (restartScheduled) onApplied?.();
     const files: string[] = [];

package/src/views/context.ts

@@ -19,6 +19,8 @@ export interface ViewSnapshot {
   catalog: WalkCatalog;
   integrations: Record<string, unknown> | null;
   contracts: ResolvedContracts;
+  /** 文件读原语透传（可选——resources 台账惰性读等 stat 指纹缓存消费；缺席 = 调用方直读） */
+  cache?: FileCache;
 }
 
 /** 读取视图输入快照（每方法调用独立——Freshness Contract 单位 = 方法调用） */
@@ -27,14 +29,14 @@ export async function loadViewSnapshot(ctx: ViewContext): Promise<ViewSnapshot>
   const integrations = await readIntegrationsConfig(ctx.appDir, ctx.cache);
   const { resolveContractsForApp } = await import('../core/contracts-resolver.js');
   const contracts = await resolveContractsForApp(ctx.appDir);
-  return { appDir: ctx.appDir, walk, catalog: walk.catalog, integrations, contracts };
+  return { appDir: ctx.appDir, walk, catalog: walk.catalog, integrations, contracts, ...(ctx.cache ? { cache: ctx.cache } : {}) };
 }
 
 /** 同步快照（调用方已持有 contracts 时——避免重复解析） */
 export function loadViewSnapshotSync(ctx: ViewContext, contracts: ResolvedContracts): ViewSnapshot {
   const walk = walkManifests(ctx.appDir, ctx.cache);
   const integrations = readIntegrationsConfig(ctx.appDir, ctx.cache);
-  return { appDir: ctx.appDir, walk, catalog: walk.catalog, integrations, contracts };
+  return { appDir: ctx.appDir, walk, catalog: walk.catalog, integrations, contracts, ...(ctx.cache ? { cache: ctx.cache } : {}) };
 }
 
 /** 模块占用服务集（v6——demand ∪ supply ∪ owns：归属模型下「平台服务」= 无主服务；

package/src/views/integration-schemas.ts

@@ -229,11 +229,22 @@ function serviceLevelBindingProvider(snapshot: ViewSnapshot, service: string): s
  *  ③ 受控内联（isControlledInlineProvider 单源）→ 名 = p.provider；catalog 复合键 > p.configSchema ref
  *     （H9 逃逸 400 照抛——readInlineSchema 共享路径）
  *  ④ 其余（null/数组/原始值/坏对象）→ 整字段 null（≡ 谓词 #5 INLINE_PROVIDER_INVALID 同判——
- *     不放行域级联，防错误 schema 污染坏节点） */
+ *     不放行域级联，防错误 schema 污染坏节点）
+ *  v5.1 D39：serviceProvider = 服务轴向假想绑定（缺席/空串 ≡ 按实际解析——I3 归一单点在此头部，
+ *  registry 侧不重复归一）；非空轴参 → 短路 bare 解析（镜像 formProviderOf「输入替换非分支复制」先例：
+ *  任一原分支改写 provider 为 X 后实读都进 bare 分支，同构承诺 by construction）。短路在节点读取之前——
+ *  豁免链三分支（D39 与 D38 四分支的有意分歧：预览与坏文件解耦）：malformed（分支④）不污染假想 /
+ *  内联 ref 不读取（假想态无 H9 逃逸 400；catalog 命中的 manifest 声明路径照读，与节点声明的
+ *  用户可控路径不同性）/ 全链未绑定时假想仍非 null（服务轴恒可写，无 module 轴零归属对应物）。 */
 export function loadServiceIntegrationSchemas(
   snapshot: ViewSnapshot,
   service: string,
+  serviceProvider?: string,
 ): ServiceIntegrationSchemas | null {
+  const ovr = typeof serviceProvider === 'string' && serviceProvider.length > 0 ? serviceProvider : undefined;
+  if (ovr !== undefined) {
+    return { provider: ovr, configSchema: resolveServiceConfigSchema(snapshot, ovr, service) };
+  }
   const p = (snapshot.integrations as { services?: Record<string, { provider?: unknown }> } | null)
     ?.services?.[service]?.provider;
   if (p === undefined || p === '') {
@@ -255,12 +266,15 @@ export function loadServiceIntegrationSchemas(
 /** G 批：服务轴字段注册表（D38 四分支链复用——消费 loadServiceIntegrationSchemas 单源；
  *  伪层 {provider, services: {[s]: {configSchema}}} → buildIntegrationFieldRegistry——
  *  fields = 该 schema 全部字段带 global 旗标；configSchema null → schemaless=[service]
- *  非 null 空集；schemas 整体 null（全链未绑定/坏节点）→ registry null——镜像 D38 语义） */
+ *  非 null 空集；schemas 整体 null（全链未绑定/坏节点）→ registry null——镜像 D38 语义）。
+ *  v5.1 D39：serviceProvider = 服务轴向假想绑定，纯透传（I1 单源——归一与短路都在链函数头部；
+ *  轴参仅重定向表单层投影，global 旗标全量透传语义不变）。 */
 export function loadServiceFieldRegistry(
   snapshot: ViewSnapshot,
   service: string,
+  serviceProvider?: string,
 ): IntegrationFieldRegistryView | null {
-  const schemas = loadServiceIntegrationSchemas(snapshot, service);
+  const schemas = loadServiceIntegrationSchemas(snapshot, service, serviceProvider);
   if (schemas === null) return null;
   const layer: LayerIntegrationSchemas = {
     provider: schemas.provider,

package/src/views/modules.ts

@@ -1,4 +1,6 @@
-import type { ModuleDeclaration, ModuleBinding, ModuleDetailView, ServiceDemand } from '../dto.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ModuleDeclaration, ModuleBinding, ModuleDetailView, ModuleResourceEcho, ModuleResourcesEcho, ServiceDemand } from '../dto.js';
 import { AppToolkitError } from '../core/errors.js';
 import { moduleOwnershipWritable, resolveModuleBinding } from '../integrations/module-binding.js';
 import { resolveServiceDisplay, type ViewSnapshot } from './context.js';
@@ -8,11 +10,62 @@ import { resolveServiceDisplay, type ViewSnapshot } from './context.js';
  * 无 resolution/issues/contracts 键，永不 503）。
  * v6 所有权模型：ownedServices（declare.owns 展平）/ binding 单数（resolveModuleBinding）/
  * configEditable = owns>0（moduleOwnershipWritable 单源）；integration = modules[install id]
- * 集成位投影（provider/config；resources 不投影——N2）。v5 domainKeys/providerBindings 退役。
+ * 集成位投影（provider/config；resources 走独立只读字段，见投影 resourcesOf——N2 读半边）。
+ * v5 domainKeys/providerBindings 退役。
  * 2026-09-16 双缺陷批：loadModulesView 排除 provider 家族包（供给/实施载体非可配置
  * 业务模块）——walk 声明集与 loadModuleDetailView 不变（装包仍合法，详情保持 200）。
  */
 
+/** knowledge.json 台账路径（与 toolkit readIntegrationsConfig 同源锚定 appDir/config/——
+ *  TBOX_INTEGRATIONS_FILE 为 SDK 运行时逃生舱，视图不跟随，既有分叉见 dto ModuleResourceEcho 注） */
+const KNOWLEDGE_REGISTRY_FILE = join('config', 'knowledge.json');
+
+/**
+ * modules[install id].resources 只读投影（N2 读半边；文件镜像 L1 + ref 台账展开态）：
+ * - 无模块键/无资源节 → null（DTO null 语义：无资源 ≠ 空表）；
+ * - `datasetId` 直填 → resolvedDatasetId = 该值（镜像 SDK resolveKnowledge：并存时 datasetId 优先）；
+ * - `ref` → 同目录 knowledge.json 台账命中 = 台账 datasetId；未命中/台账缺失/解析失败 = null
+ *   （镜像 SDK resolveKnowledge miss-warn 降级语义，资源缺席走模块占位回退）；
+ * - 非 knowledge 型资源（未来 additive）原样透传 type，resolvedDatasetId = null。
+ */
+function resourcesOf(snapshot: ViewSnapshot, moduleId: string, modulesNode: Record<string, unknown>): ModuleResourcesEcho | null {
+  const raw = modulesNode[moduleId] as { resources?: Record<string, unknown> } | undefined;
+  const resources = raw?.resources;
+  if (!resources || typeof resources !== 'object' || Array.isArray(resources)) return null;
+  const registryPath = join(snapshot.appDir, KNOWLEDGE_REGISTRY_FILE);
+  // 台账惰性读（stat 指纹缓存；缺席/坏文件 = 空表——展开态 null，与 SDK loadKnowledgeRegistry fail-soft 同语义）
+  let bases: Record<string, { datasetId?: unknown }> = {};
+  if (existsSync(registryPath)) {
+    try {
+      const parsed = (snapshot.cache?.read(registryPath, (raw: string) => JSON.parse(raw) as unknown) ?? JSON.parse(readFileSync(registryPath, 'utf8'))) as {
+        knowledge_bases?: Record<string, { datasetId?: unknown }>;
+      };
+      bases = parsed.knowledge_bases ?? {};
+    } catch {
+      bases = {};
+    }
+  }
+  const out: ModuleResourcesEcho = {};
+  for (const [id, spec] of Object.entries(resources)) {
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec)) continue;
+    const s = spec as Record<string, unknown>;
+    const type = s.type === 'knowledge' ? 'knowledge' : String(s.type ?? 'knowledge');
+    const direct = typeof s.datasetId === 'string' && s.datasetId !== '' ? s.datasetId : undefined;
+    const ref = typeof s.ref === 'string' && s.ref !== '' ? s.ref : undefined;
+    const resolved = direct ?? (ref !== undefined && typeof bases[ref]?.datasetId === 'string' ? (bases[ref].datasetId as string) : null);
+    const echo: ModuleResourceEcho = {
+      type: type as ModuleResourceEcho['type'],
+      ...(direct !== undefined ? { datasetId: direct } : {}),
+      ...(ref !== undefined ? { ref } : {}),
+      resolvedDatasetId: resolved,
+      ...(typeof s.topK === 'number' ? { topK: s.topK } : {}),
+      ...(typeof s.scoreThreshold === 'number' ? { scoreThreshold: s.scoreThreshold } : {}),
+    };
+    out[id] = echo;
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
 /** 家族名归一（cli deriveModuleId 同源语义——依赖方向禁 import，故内联）：
  *  `@tbox.cn/app-provider-x` / `@app/provider-y` / `provider-z` → `provider-*` */
 function familyName(s: string): string {
@@ -27,15 +80,21 @@ function isProviderFamily(mod: { id: string; pkg: string }): boolean {
   return familyName(mod.id).startsWith('provider-') || familyName(mod.pkg).startsWith('provider-');
 }
 
-/** GET /modules：纯模块清单（demand 不在——卡片展开 = GET /modules/:m；provider 家族包不在清单） */
-export function loadModulesView(snapshot: ViewSnapshot): { modules: ModuleDeclaration[] } {
+/** GET /modules：纯模块清单（demand 不在——卡片展开 = GET /modules/:m；provider 家族包不在清单；
+ *  hidden 模块默认过滤——includeHidden = true 可见并携带 hidden: true 徽标） */
+export function loadModulesView(
+  snapshot: ViewSnapshot,
+  opts: { includeHidden?: boolean } = {},
+): { modules: ModuleDeclaration[] } {
   const modules: ModuleDeclaration[] = snapshot.walk.modules
     .filter((mod) => !isProviderFamily(mod))
+    .filter((mod) => opts.includeHidden === true || mod.descriptor.hidden !== true)
     .map((mod) => ({
       id: mod.id,
       // v7 词汇统一：name = 展示名（manifest name；兜底 id——恒有值）
       name: mod.descriptor.name ?? mod.descriptor.id,
       description: mod.descriptor.description ?? '',
+      ...(mod.descriptor.hidden === true ? { hidden: true } : {}),
     }))
     .sort((a, b) => a.id.localeCompare(b.id));
   return { modules };
@@ -75,9 +134,12 @@ export function loadModuleDetailView(snapshot: ViewSnapshot, moduleId: string):
     // v7 词汇统一：name = 展示名（兜底与 /modules 同语义——manifest name ?? id）
     name: mod.descriptor.name ?? mod.descriptor.id,
     description: mod.descriptor.description ?? '',
+    ...(mod.descriptor.hidden === true ? { hidden: true } : {}),
     // v6：ownedServices（declare.owns 展平排序）——N13：展示名走 resolveServiceDisplay 链，不重复携带
     ownedServices: w.ownedServices,
     integration,
+    // 模块资源只读镜像（N2 读半边——knowledge.json 台账 ref 展开态随行）
+    resources: resourcesOf(snapshot, moduleId, modulesNode),
     binding: { provider: binding.provider, layer: binding.layer },
     configEditable: w.writable,
     services,

package/src/views/service-resolutions.ts

@@ -10,7 +10,7 @@ import type {
   ServiceResolutionDetail,
   ServiceStatus,
 } from '../dto.js';
-import { AppToolkitError } from '../core/errors.js';
+import { AppToolkitError, contractsNotResolvedMessage } from '../core/errors.js';
 import { resolveModuleBinding } from '../integrations/module-binding.js';
 import type { ResolvedContracts } from '../core/contracts-resolver.js';
 import type { WalkCatalog } from '../assembly/walk-manifests.js';
@@ -83,6 +83,10 @@ function evaluateInstance(
     service,
     instanceId,
     supplies as never,
+    // v6 ownerOf：服务归属表（walk.ownership——buildOwnershipMap 同源产物）显式参。
+    // 缺席 + 文件含 modules 级绑定/配置 → contracts v6 fail-visible（binding-unresolved），
+    // root/modules 级联全断——视图轴与谓词轴同源透传，勿再遗漏（bug 复盘：fef9a71a 漏改点）。
+    snapshot.walk.ownership as Record<string, string>,
   );
   if (r.status === 'ok' && r.effective) {
     const raw: unknown = r.effective.provider;
@@ -124,6 +128,7 @@ function evaluationContracts(snapshot: ViewSnapshot) {
       service: string,
       instanceId: string,
       supplies?: never,
+      ownerOf?: Record<string, string>,
     ) => EffectiveResolutionShape;
     normalizeInstances: (input: unknown) => { instances: Array<{ id: string }>; defaultInstanceId: string | null };
     buildSupplyLookup: (catalog: unknown) => unknown;
@@ -205,18 +210,22 @@ function isSuppliedCheck(catalog: WalkCatalog, provider: string, service: string
   return isSupplied(catalog, provider, service);
 }
 
+/** 批量键集（求值轴/降级轴共用单源：服务词汇 ∪ 需求侧 ∪ 已配置） */
+function resolutionKeys(snapshot: ViewSnapshot): string[] {
+  const keys = new Set<string>([...snapshot.walk.vocabulary, ...Object.keys(snapshot.catalog.services)]);
+  const configured = (snapshot.integrations as { services?: Record<string, unknown> } | null)?.services ?? {};
+  for (const k of Object.keys(configured)) keys.add(k);
+  return [...keys].sort();
+}
+
 /** 批量求值（键集 = 服务词汇 ∪ 已配置；?service= 过滤语义——未知键缺席；issues 恒全量） */
 export function loadServiceResolutionsView(
   snapshot: ViewSnapshot,
   issues: IntegrationIssue[],
   filter?: string[],
 ): ServiceResolutionsView {
-  const keys = new Set<string>([...snapshot.walk.vocabulary, ...Object.keys(snapshot.catalog.services)]);
-  const configured = (snapshot.integrations as { services?: Record<string, unknown> } | null)?.services ?? {};
-  for (const k of Object.keys(configured)) keys.add(k);
-
   const resolutions: Record<string, ServiceResolutionEntry> = {};
-  for (const service of [...keys].sort()) {
+  for (const service of resolutionKeys(snapshot)) {
     if (filter && !filter.includes(service)) continue;
     resolutions[service] = resolveServiceSummary(service, snapshot);
   }
@@ -238,20 +247,12 @@ export function loadServiceResolutionDetail(
   });
 
   // P4 枚举规则：root 注册表 id 逐一 + 显式 '*' 条目（若在）；无注册表且节点通配激活 → 单 '*' 合成；
-  // 无注册表无节点 → []
+  // 无注册表无节点 → []（枚举单源 = enumerateInstanceIds——降级轴声明实例投影共用）
   const declaredIds = normalized.instances.map((i) => i.id);
   const slot = (snapshot.integrations as { services?: Record<string, { instances?: Record<string, unknown> }> } | null)
     ?.services?.[service];
   const slotKeys = slot?.instances ? Object.keys(slot.instances) : undefined;
-  let instanceIds: string[];
-  if (declaredIds.length > 0) {
-    instanceIds = [...declaredIds];
-    if (slotKeys?.includes('*')) instanceIds.push('*');
-  } else if (slotKeys !== undefined && slotKeys.length > 0) {
-    instanceIds = slotKeys.includes('*') ? ['*'] : slotKeys;
-  } else {
-    instanceIds = [];
-  }
+  const instanceIds = enumerateInstanceIds(slotKeys, declaredIds);
 
   // 默认实例口径（摘要 status = 默认实例求值——不重复头部；原 defaultEval 死代码已删 FX-2c）
 
@@ -267,7 +268,7 @@ export function loadServiceResolutionDetail(
   });
 
   // inheritance 四层（app → module → service → instance——effective 链声明位投影）
-  const inheritance = buildInheritance(snapshot, service);
+  const inheritance = buildInheritance(snapshot, service, normalized.defaultInstanceId ?? '*');
 
   const summary = resolveServiceSummary(service, snapshot);
   const resolution: ServiceResolution = {
@@ -283,24 +284,31 @@ export function loadServiceResolutionDetail(
   };
 }
 
+/** P4 实例枚举单源（求值轴/降级轴共用）：root 注册表 id 逐一 + 显式 '*' 条目（若在）；
+ *  无注册表且节点通配激活 → 单 '*' 合成；无注册表无节点 → []。 */
+function enumerateInstanceIds(slotKeys: string[] | undefined, declaredIds: string[]): string[] {
+  if (declaredIds.length > 0) {
+    const ids = [...declaredIds];
+    if (slotKeys?.includes('*')) ids.push('*');
+    return ids;
+  }
+  if (slotKeys !== undefined && slotKeys.length > 0) return slotKeys.includes('*') ? ['*'] : slotKeys;
+  return [];
+}
+
 /** inheritance 投影：四层各取该层声明 provider/implementation（缺席层 = 继承位，provider 缺席）。
- *  实例层 = **默认实例口径**（FX-2c 修——与摘要 status 同轴：normalizeInstances 委托解析
- *  defaultInstanceId ?? '*'；原实现取 Object.keys[0] 任意实例）。 */
+ *  实例层 = **默认实例口径**（FX-2c 修——与摘要 status 同轴）；defaultInstanceId 由调用方解析
+ *  （求值轴 = normalizeInstances 委托；降级轴 = 原始直读——本函数零 contracts 依赖，双轴共用单源）。 */
 function buildInheritance(
   snapshot: ViewSnapshot,
   service: string,
+  defaultInstanceId: string,
 ): ServiceResolution['inheritance'] {
   const integrations = snapshot.integrations as {
     provider?: string;
     services?: Record<string, { provider?: unknown; implementation?: string; instances?: Record<string, { provider?: string; implementation?: string }> }>;
   } | null;
   const slot = integrations?.services?.[service];
-  const cfg = snapshot.integrations as { instances?: unknown; defaultInstanceId?: unknown } | null;
-  const normalized = evaluationContracts(snapshot).normalizeInstances({
-    instances: cfg?.instances,
-    defaultInstanceId: cfg?.defaultInstanceId,
-  });
-  const defaultInstanceId = normalized.defaultInstanceId ?? '*';
   const defaultInstance = slot?.instances?.[defaultInstanceId] ?? slot?.instances?.['*'];
   // module 段消费 resolveModuleBinding 单源（v6——与 binding / 谓词 #7 同源；ownerOf=walk.ownership）
   const owner = snapshot.walk.ownership[service];
@@ -328,3 +336,83 @@ function buildInheritance(
 
 /** 谓词全量 issues 装配（写路径/求值轴共用——工厂经 evaluateIntegrationServices 装配后传入） */
 export type { IntegrationIssue };
+
+// ── 降级轴（v7——policy-at-edge 读求值轴退役）──
+// contracts 不可用（未安装 / 无严格面 / 求值面缺席 / v6 标记缺席）时，读求值轴不再 503，
+// 改投静态骨架（walk + integrations 纯文件投影，零 contracts 依赖）+ evaluation-unavailable 标记。
+// 依据链：doctor 分级先例（未安装 = warning 正常态）+ D31 include→null 先例；fail-visible 语义
+// 保留在数据内（status + statusMessage N1 分支文案），写路径与 internals 门控不变。
+
+/** 读求值轴可用判据（三条件与——降级门单源；写路径 assertContractsUsable 另有 503 语义，不复用） */
+export function contractsEvaluable(contracts: ResolvedContracts): boolean {
+  return contracts.evaluation && contracts.strictValidation && contracts.ownershipBindingV6;
+}
+
+/** 降级单条目（静态可算字段：module = owners 首 / required = OR 聚合；provider/layer 不投——
+ *  保持「求值产物」语义纯净，layer 单独在场违 D31 孤儿层口径） */
+function degradeEntry(snapshot: ViewSnapshot, service: string, message: string): ServiceResolutionEntry {
+  const demand = snapshot.catalog.services[service];
+  return {
+    status: 'evaluation-unavailable',
+    statusMessage: message,
+    ...(demand?.owners[0] !== undefined ? { module: demand.owners[0] } : {}),
+    ...(demand !== undefined ? { required: !demand.optional } : {}),
+  };
+}
+
+/** 批量降级视图（键集与求值轴同源 resolutionKeys；?service= 过滤语义一致；issues 恒 []——
+ *  谓词与求值同源缺席；声明面诊断走 declarationIssues 通道不在此混装） */
+export function loadServiceResolutionsDegradeView(
+  snapshot: ViewSnapshot,
+  contracts: ResolvedContracts,
+  filter?: string[],
+): ServiceResolutionsView {
+  const message = contractsNotResolvedMessage(contracts);
+  const resolutions: Record<string, ServiceResolutionEntry> = {};
+  for (const service of resolutionKeys(snapshot)) {
+    if (filter && !filter.includes(service)) continue;
+    resolutions[service] = degradeEntry(snapshot, service, message);
+  }
+  return { contracts: toContractsResolution(contracts), resolutions, issues: [] };
+}
+
+/** 单体降级视图（P14 extends 结构保证——摘要基 + instances 声明枚举 + inheritance 四层静态投影） */
+export function loadServiceResolutionDegradeDetail(
+  service: string,
+  snapshot: ViewSnapshot,
+  contracts: ResolvedContracts,
+): ServiceResolutionDetail {
+  const message = contractsNotResolvedMessage(contracts);
+  const resolution: ServiceResolution = {
+    ...degradeEntry(snapshot, service, message),
+    instances: degradeInstances(snapshot, service),
+    inheritance: buildInheritance(snapshot, service, degradeDefaultInstanceId(snapshot)),
+  };
+  return { contracts: toContractsResolution(contracts), resolution, issues: [] };
+}
+
+/** 声明实例投影（原始数据——root instances[].id ∪ slot 实例键，P4 枚举单源共用；
+ *  非 normalizeInstances 派生语义，单源不破）。逐实例同标记，statusMessage 不重复携带
+ *  （resolution 顶层已携带）。 */
+function degradeInstances(snapshot: ViewSnapshot, service: string): ResolvedInstance[] {
+  const slot = (snapshot.integrations as { services?: Record<string, { instances?: Record<string, unknown> }> } | null)
+    ?.services?.[service];
+  const cfg = snapshot.integrations as { instances?: unknown } | null;
+  const declaredIds = Array.isArray(cfg?.instances)
+    ? (cfg.instances as Array<{ id?: unknown }>)
+        .map((i) => (i && typeof i === 'object' ? i.id : undefined))
+        .filter((id): id is string => typeof id === 'string')
+    : [];
+  const slotKeys = slot?.instances ? Object.keys(slot.instances) : undefined;
+  return enumerateInstanceIds(slotKeys, declaredIds).map((id) => ({
+    instanceId: id,
+    status: 'evaluation-unavailable' as const,
+  }));
+}
+
+/** 降级默认实例口径（近似声明）：defaultInstanceId 原始直读，缺席 → '*' 通配位。
+ *  normalizeInstances 的「单候选唯一解」推导不可复制（求值面单源）——近似口径见 api 契约。 */
+function degradeDefaultInstanceId(snapshot: ViewSnapshot): string {
+  const cfg = snapshot.integrations as { defaultInstanceId?: unknown } | null;
+  return typeof cfg?.defaultInstanceId === 'string' && cfg.defaultInstanceId.length > 0 ? cfg.defaultInstanceId : '*';
+}