@tbox.cn/app-toolkit 0.1.0 → 0.3.0

package/src/integrations/read.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveContractsForApp, type ResolvedContracts } from '../core/contracts-resolver.js';
+import { AppToolkitError } from '../core/errors.js';
 import type { FileCache } from '../core/file-cache.js';
 
 /**
@@ -45,9 +46,28 @@ export async function readIntegrationsStrict(
   const raw = readIntegrationsConfig(appDir, cache);
   if (raw === null) return { config: null, strict: false, contracts };
   if (contracts.strictValidation && contracts.module.parseIntegrationsConfig) {
-    // 严格链：assertNoInlineSecrets → 旧键直切防线 → zod strict（contracts 单源）
-    const parsed = contracts.module.parseIntegrationsConfig(raw);
-    return { config: parsed as unknown as Record<string, unknown>, strict: true, contracts };
+    // 严格链：assertNoInlineSecrets → 旧键直切防线 → zod strict（contracts 单源）；
+    // 失败转换（A1——裸 ZodError/Error 穿透 500 的同族缺口）：zod → 400 + fields（原始路径——
+    // 文件级读无节点上下文）；普通 Error → 400 直通。结构性判定同 write.runStrictValidation。
+    try {
+      const parsed = contracts.module.parseIntegrationsConfig(raw);
+      return { config: parsed as unknown as Record<string, unknown>, strict: true, contracts };
+    } catch (err) {
+      if (err instanceof Error && Array.isArray((err as { issues?: unknown }).issues)) {
+        const fields = ((err as unknown as { issues: Array<{ path?: unknown }> }).issues)
+          .filter((i) => Array.isArray(i.path))
+          .map((i) => (i.path as Array<string | number>).map(String).join('.'))
+          .filter((p) => p.length > 0);
+        throw new AppToolkitError('VALIDATION_FAILED', 400, 'integrations.json 校验失败', fields.length > 0 ? fields : undefined);
+      }
+      throw new AppToolkitError('VALIDATION_FAILED', 400, err instanceof Error ? err.message : String(err));
+    }
   }
   return { config: raw, strict: false, contracts };
 }
+
+/** P9 服务身份判据单源（A2）：GET/PUT/DELETE 共用「词汇 ∪ 已配置」——service-detail 判据逐字冻结
+ *  （api.md P9 的「demanded 退化」口径为文档层 nuance，现行实现与 GET 均不含 demanded——冻结现状即单源） */
+export function isKnownService(vocabulary: readonly string[], configuredKeys: readonly string[], service: string): boolean {
+  return vocabulary.includes(service) || configuredKeys.includes(service);
+}

package/src/integrations/write.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import Ajv from 'ajv';
 import { resolveContractsForApp } from '../core/contracts-resolver.js';
+import { stemToFilePath } from '../core/credential-format.js';
 import type { FileCache } from '../core/file-cache.js';
 import { writeAtomic } from '../core/fskit.js';
 import { SAFE_NAME_PATTERN } from '../core/module-schema.js';
@@ -17,6 +18,8 @@ import {
 } from './credentials.js';
 import type { IntegrationServiceIssue } from './predicate.js';
 import { checkInstanceKeys } from './predicate.js';
+import { isKnownService } from './read.js';
+import { displayOwnerName, moduleDomainWritable } from './domain-binding.js';
 import { AppToolkitError } from '../core/errors.js';
 
 /**
@@ -34,8 +37,9 @@ import { AppToolkitError } from '../core/errors.js';
  *  7 严格整文档校验（contracts parseIntegrationsConfig——触发 = !noDiff ∥ 有凭据输入）
  *  8 凭据工件落盘（**后置于校验通过**——防「凭据已写 + zod 拒绝」不一致态；
  *    dryRun → writeCredentialArtifacts 零写盘 + existsSync 预览）
- *  9 finalize：written = integrations 实写 ∥ 凭据实写（**D-B2**）；files 分列两类路径；
- *    restartScheduled = written && onApplied（凭据影响 boot 装配——重启正当）；写后缓存失效
+ *  9 finalize（D35）：planned = 将触碰（files 预览单源——dryRun 响应 ≡ 同 body 真实写，files 逐字对称）；
+ *    written = 实写（!dryRun 派生，D-B2）；restartScheduled = written && onApplied（凭据影响 boot 装配——
+ *    重启正当）；写后缓存失效
  * 归一化：N1 模块节点 {} → 删 domains[键]；N3 服务节点 {} 不归一化（显式通配激活 = 合法 TIER0 态）；
  * N2 已随 ?instance= 退役。dryRun（PUT only）：复读完整管线不落盘不排程。
  * DELETE：节点移除 + 孤儿凭据写后对账（覆盖 DELETE 与 PUT 替换两类来源，只报告不清理——D9）。
@@ -185,6 +189,11 @@ function validateCredential(
   inlineCredentialType: string | undefined,
   cache?: FileCache,
 ): void {
+  // ⓪ type 在场性（A1 无条件前置）：缺 type 的凭据输入原会以 { type: undefined, ...values }
+  //   落盘（JSON.stringify 静默丢键）→ 无 type 文件 + GET 回显静默缺席——收紧为显式 400
+  if (typeof credentials.type !== 'string' || credentials.type.length === 0) {
+    throw new AppToolkitError('VALIDATION_FAILED', 400, '凭据 type 缺失或为空字符串', ['credentials.type']);
+  }
   // ① type 匹配（内联声明优先；catalog 槽供给次之；均缺席 → 跳过——宽松与 P11 对齐）
   const expectedType = inlineCredentialType ?? declaredCredentialType(appDir, provider, service, cache);
   if (expectedType !== undefined && expectedType !== '-' && credentials.type !== expectedType) {
@@ -222,14 +231,12 @@ export interface WriteCore {
   warmup(): Promise<void>;
   /** PUT /app/integration（root 节点全集） */
   applyApp(node: Record<string, unknown>, opts?: WriteOptions): SaveResult;
-  /** PUT /modules/:module/integration（domains 换算；N1 {} 删域键） */
+  /** PUT /modules/:module/integration（domains 换算；N1 {} 删域键；v4.4 D34 写守卫单源） */
   applyModule(moduleId: string, node: Record<string, unknown>, opts?: WriteOptions): SaveResult;
-  /** PUT /services/:service/integration（整节点含 instances map；N3 {} 不归一化） */
+  /** PUT /services/:service/integration（整节点含 instances map；N3 {} 不归一化；v4.4 A2 身份判据） */
   applyService(service: string, node: Record<string, unknown>, opts?: WriteOptions): SaveResult;
-  /** DELETE /services/:service/integration（恒整节点；幂等；无预演） */
+  /** DELETE /services/:service/integration（恒整节点；幂等仅判据内成员；无预演） */
   deleteService(service: string): SaveResult;
-  /** 模块服务域键（module → domains 键 = 服务集派生域键集 upsert 位） */
-  moduleDomainKey(moduleId: string): string | undefined;
 }
 
 export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): WriteCore {
@@ -240,11 +247,13 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
     appliedCredentials: AppliedCredential[],
     issues: IntegrationServiceIssue[],
     dryRun: boolean | undefined,
-    credentialsWritten: boolean,
   ): SaveResult {
-    // D-B2：written ⟺ 任一文件实写；files 分列（integrations.json + 凭据路径）；
-    // restartScheduled 跟随 written（凭据文件影响 boot 装配——重启正当）
-    const integrationsWritten = !dryRun && next !== null;
+    // D35 双轴派生：planned = 将触碰（files 预览单源——dryRun 响应 ≡ 同 body 真实写，files 逐字对称）；
+    // written = 实际落盘（!dryRun 派生——D-B2）；restartScheduled 跟随 written（凭据文件影响 boot 装配——重启正当）
+    const integrationsPlanned = next !== null;
+    const credentialsPlanned = appliedCredentials.length > 0;
+    const integrationsWritten = !dryRun && integrationsPlanned;
+    const credentialsWritten = !dryRun && credentialsPlanned;
     if (integrationsWritten) {
       writeAtomic(join(appDir, INTEGRATIONS_FILE), `${JSON.stringify(next, null, 2)}\n`);
       cache?.invalidate([join(appDir, INTEGRATIONS_FILE)]);
@@ -253,8 +262,8 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
     const restartScheduled = written && onApplied !== undefined;
     if (restartScheduled) onApplied?.();
     const files: string[] = [];
-    if (integrationsWritten) files.push(INTEGRATIONS_FILE);
-    if (credentialsWritten) files.push(...appliedCredentials.map((a) => `config/credentials/${a.stem}.json`));
+    if (integrationsPlanned) files.push(INTEGRATIONS_FILE);
+    if (credentialsPlanned) files.push(...appliedCredentials.map((a) => stemToFilePath(a.stem)));
     return {
       written,
       restartScheduled,
@@ -270,7 +279,23 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
     strictContracts = await resolveContractsForApp(appDir);
   }
 
-  function runStrictValidation(next: Record<string, unknown>, issues: IntegrationServiceIssue[]): void {
+  /** zod issues → 节点相对 fields（A1）：字面量前缀剥离——service 名含点号，禁按段数切分；
+   *  无前缀命中的文档级路径（如 'services'）原样保留；空 path（文档根级形态）→ 滤除
+   *  （fields 直指字段名——空串指向不存在）。 */
+  function toNodeFields(issues: Array<{ path?: unknown }>, prefix: string): string[] {
+    return issues
+      .filter((i) => Array.isArray(i.path))
+      .map((i) => {
+        const p = (i.path as Array<string | number>).map(String).join('.');
+        return prefix !== '' && p.startsWith(prefix) && p.length > prefix.length ? p.slice(prefix.length) : p;
+      })
+      .filter((p) => p.length > 0);
+  }
+
+  /** 严格整文档校验（A1 单点转换）：zod → 400 + fields（节点相对）；普通 Error（旧键直切/
+   *  内联密钥防线——contracts parseIntegrationsConfig 内部 assert 族）→ 同族 400 message 直通。
+   *  结构性 ZodError 判定（禁 instanceof——contracts 动态 import，类身份跨模块实例不可靠）。 */
+  function runStrictValidation(next: Record<string, unknown>, issues: IntegrationServiceIssue[], prefix: string): void {
     const strict = strictContracts;
     if (!strict || !strict.strictValidation || !strict.module.parseIntegrationsConfig) {
       throw new AppToolkitError(
@@ -280,20 +305,23 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
       );
     }
     void issues;
-    strict.module.parseIntegrationsConfig(next);
+    try {
+      strict.module.parseIntegrationsConfig(next);
+    } catch (err) {
+      if (err instanceof Error && Array.isArray((err as { issues?: unknown }).issues)) {
+        throw new AppToolkitError(
+          'VALIDATION_FAILED',
+          400,
+          '节点 schema 校验失败',
+          toNodeFields((err as unknown as { issues: Array<{ path?: unknown }> }).issues, prefix),
+        );
+      }
+      throw new AppToolkitError('VALIDATION_FAILED', 400, err instanceof Error ? err.message : String(err));
+    }
   }
 
   return {
     warmup,
-    moduleDomainKey(moduleId: string): string | undefined {
-      const { modules } = walkManifests(appDir, cache);
-      const mod = modules.find((m) => m.id === moduleId);
-      if (!mod) return undefined;
-      const services = mod.descriptor.contributes.services ?? [];
-      const domains = new Set(services.map((s) => (s.service.includes('.') ? s.service.slice(0, s.service.indexOf('.')) : s.service)));
-      // 单域模块 → 该域键；多域/零域 → 模块 id 兜底键（domains 换算层约定）
-      return domains.size === 1 ? [...domains][0] : moduleId;
-    },
 
     applyApp(node: Record<string, unknown>, writeOpts: WriteOptions = {}): SaveResult {
       assertSafeNames(node, 'root');
@@ -332,16 +360,43 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
       if (noDiff && !hasCredentialInput) {
         return { written: false, restartScheduled: false, files: [], credentials: [], issues };
       }
-      runStrictValidation(next, issues);
+      runStrictValidation(next, issues, '');
       // 凭据工件落盘（后置于校验通过；dryRun 零写盘 + existsSync 预览）
       const dryRun = writeOpts.dryRun === true;
       const applied = writeCredentialArtifacts(appDir, plan, dryRun);
       issues.push(...registryCheck(next));
-      return finalize(noDiff ? null : next, applied, issues, writeOpts.dryRun, !dryRun && plan.length > 0);
+      return finalize(noDiff ? null : next, applied, issues, writeOpts.dryRun);
     },
 
     applyModule(moduleId: string, node: Record<string, unknown>, writeOpts: WriteOptions = {}): SaveResult {
       assertSafeNames(node, 'root');
+      // D34 写守卫（v4.4，moduleDomainWritable 单源）：404（模块在册）→ 400（多域/零域/共享键
+      // 三分支）→ 既有管线。守卫先于 no-op 短路——多域/零域/共享键模块 PUT {} 清域同 400
+      // （「写路径拒绝歧义操作」含清除；P13/P17）。
+      const { modules, catalog } = walkManifests(appDir, cache);
+      const mod = modules.find((m) => m.id === moduleId);
+      if (!mod) {
+        throw new AppToolkitError('MODULE_NOT_FOUND', 404, `模块 ${moduleId} 非已装模块`);
+      }
+      const w = moduleDomainWritable({ modules, catalog }, mod);
+      if (!w.writable) {
+        if (w.reason === 'multi-domain') {
+          throw new AppToolkitError(
+            'VALIDATION_FAILED',
+            400,
+            `模块 ${moduleId} 跨 ${w.domainKeys.length} 个域（${w.domainKeys.join('、')}）——模块级统一配置仅支持单域模块，请按服务级配置（编辑各服务行）`,
+          );
+        }
+        if (w.reason === 'zero-domain') {
+          throw new AppToolkitError('VALIDATION_FAILED', 400, `模块 ${moduleId} 无服务需求声明，无域配置位`);
+        }
+        throw new AppToolkitError(
+          'VALIDATION_FAILED',
+          400,
+          `域键 ${w.domainKey} 由 ${w.coOwners.map((o) => displayOwnerName(modules, o)).join('、')} 共用——写通道拒绝歧义操作，请按服务级配置`,
+        );
+      }
+      const domainKey = w.domainKey;
       const issues: IntegrationServiceIssue[] = [];
       const current = loadConfig(appDir, cache);
       if (current === null && Object.keys(node).length === 0) {
@@ -356,10 +411,6 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
         });
       }
       const base: Record<string, unknown> = current ?? { services: {} };
-      const domainKey = this.moduleDomainKey(moduleId);
-      if (domainKey === undefined) {
-        throw new AppToolkitError('MODULE_NOT_FOUND', 404, `模块 ${moduleId} 非已装模块`);
-      }
       const domains = { ...((base.domains as Record<string, unknown>) ?? {}) };
       const next: Record<string, unknown> = { ...base, domains };
       // N1：模块节点 {} → 删 domains[键]（清域）；其余 = 域键全量替换
@@ -368,9 +419,9 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
       if (deepEqual(current, next)) {
         return { written: false, restartScheduled: false, files: [], credentials: [], issues };
       }
-      runStrictValidation(next, issues);
+      runStrictValidation(next, issues, `domains.${domainKey}.`);
       issues.push(...registryCheck(next));
-      return finalize(next, [], issues, writeOpts.dryRun, false);
+      return finalize(next, [], issues, writeOpts.dryRun);
     },
 
     applyService(service: string, node: Record<string, unknown>, writeOpts: WriteOptions = {}): SaveResult {
@@ -378,6 +429,10 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
       assertSafeInstanceKeys(node, writeOpts, 'slot');
       const issues: IntegrationServiceIssue[] = [];
       const current = loadConfig(appDir, cache);
+      // P9 服务身份判据单源（A2）：写入集 = 词汇 ∪ 已配置——未知服务（含 typo）404（api.md §5）
+      if (!isKnownService(walkManifests(appDir, cache).vocabulary, Object.keys((current?.services as Record<string, unknown> | undefined) ?? {}), service)) {
+        throw new AppToolkitError('SERVICE_NOT_FOUND', 404, `服务 ${service} 不在服务词汇（已装契约包 ∪ 已配置）`);
+      }
       if (current === null) {
         issues.push({
           severity: 'warning',
@@ -418,17 +473,21 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
       if (noDiff && !hasCredentialInput) {
         return { written: false, restartScheduled: false, files: [], credentials: [], issues };
       }
-      runStrictValidation(next, issues);
+      runStrictValidation(next, issues, `services.${service}.`);
       // 凭据工件落盘（后置于校验通过；dryRun 零写盘 + existsSync 预览）
       const dryRun = writeOpts.dryRun === true;
       const applied = writeCredentialArtifacts(appDir, plan, dryRun);
       issues.push(...registryCheck(next));
-      return finalize(noDiff ? null : next, applied, issues, writeOpts.dryRun, !dryRun && plan.length > 0);
+      return finalize(noDiff ? null : next, applied, issues, writeOpts.dryRun);
     },
 
     deleteService(service: string): SaveResult {
       const issues: IntegrationServiceIssue[] = [];
       const current = loadConfig(appDir, cache);
+      // P9 服务身份判据单源（A2）：判据外未知服务 404；判据内缺席节点维持幂等 written:false
+      if (!isKnownService(walkManifests(appDir, cache).vocabulary, Object.keys((current?.services as Record<string, unknown> | undefined) ?? {}), service)) {
+        throw new AppToolkitError('SERVICE_NOT_FOUND', 404, `服务 ${service} 不在服务词汇（已装契约包 ∪ 已配置）`);
+      }
       const services = { ...((current?.services as Record<string, unknown>) ?? {}) };
       if (!(service in services)) {
         // 幂等：清不存在的节点 → written:false（无 409；无预演）

package/src/views/app.ts

@@ -1,11 +1,11 @@
-import type { AppView } from '../dto.js';
+import type { AppView, ServiceDemand } from '../dto.js';
 import { APP_INTEGRATION_NODE_KEYS } from '../dto.js';
 import { moduleOccupiedServices, type ViewSnapshot } from './context.js';
 
 /**
- * 应用静态投影（views/app；C4；FX-1c B10——root 节点投影修）。
- * /app = 平台服务 + root 节点原值（纯静态，D12）：
- * services = 服务词汇 − 模块占用（裸 string[]——owner/标题 UI 按首点段派生，F2）；
+ * 应用静态投影（views/app；C4；FX-1c B10——root 节点投影修；v4.4 D29——services 双端点同型）。
+ * /app = 平台服务 + root 节点原值（纯静态）：services = 服务词汇 − 模块占用
+ * （ServiceDemand[]——平台条目 required 恒 false、title/description 缺席，D29）；
  * 平台服务状态不在此（→ /service-resolutions）；模块服务不在此（→ /modules/:m）。
  * integration = **root 节点投影**（APP_INTEGRATION_NODE_KEYS——D21/L1：GET 预填 ≡ PUT body；
  * 文件另含 services/domains/modules 域键，不进 root 节点投影——原实现整文件透传，
@@ -14,7 +14,9 @@ import { moduleOccupiedServices, type ViewSnapshot } from './context.js';
 
 export function loadAppView(snapshot: ViewSnapshot): AppView {
   const occupied = moduleOccupiedServices(snapshot.walk);
-  const services = snapshot.walk.vocabulary.filter((s) => !occupied.has(s));
+  const services: ServiceDemand[] = snapshot.walk.vocabulary
+    .filter((s) => !occupied.has(s))
+    .map((s) => ({ service: s, required: false }));
   const config = snapshot.integrations;
   let integration: AppView['integration'] = null;
   if (config) {

package/src/views/context.ts

@@ -1,11 +1,12 @@
 import { readIntegrationsConfig } from '../integrations/read.js';
+import { domainOfService } from '../integrations/domain-binding.js';
 import { walkManifests, type WalkCatalog, type WalkManifestsResult } from '../assembly/walk-manifests.js';
 import type { FileCache } from '../core/file-cache.js';
 import type { ResolvedContracts } from '../core/contracts-resolver.js';
 
 /**
  * 视图装配共享上下文（五投影共用；目录枚举零缓存——walkManifests 每次调用执行）。
- * 域前缀换算（service → 首点段）= 本地一行 helper（文件格式词汇，静态面零 contracts 依赖）。
+ * 域前缀换算（service → 首点段）自 v4.4 F1 迁 integrations/domain-binding.ts（本文件 re-export 保导入路径）。
  */
 
 export interface ViewContext {
@@ -21,11 +22,7 @@ export interface ViewSnapshot {
   contracts: ResolvedContracts;
 }
 
-/** 域前缀换算（本地 helper——静态面零 contracts 依赖前提） */
-export function domainOfService(service: string): string {
-  const i = service.indexOf('.');
-  return i === -1 ? service : service.slice(0, i);
-}
+export { domainOfService };
 
 /** 读取视图输入快照（每方法调用独立——Freshness Contract 单位 = 方法调用） */
 export async function loadViewSnapshot(ctx: ViewContext): Promise<ViewSnapshot> {

package/src/views/credential-types.ts

@@ -0,0 +1,28 @@
+import type { CredentialTypesView } from '../dto.js';
+import type { ViewSnapshot } from './context.js';
+import { readSchemaRef } from './providers.js';
+
+/**
+ * 供给轴凭据结构清单（views/credential-types；v4.4 D33 独立端点 GET /credential-types[?provider=]）：
+ * 结构按 credentialType 键（wanda 全部槽共享同一 type 同一 schema 文件——(provider, service)
+ * 组合寻址是错位键）；源 = catalog.credentialTypes（既有聚合产物零新读取路径，聚合条目携
+ * packageDir 供 schema 文件解析）。静态轴（稳定可缓存、永不 503）。
+ * ?provider= 过滤 ≡ ?service= 先例（过滤非寻址；未知 provider → 空 types 不 404）。
+ * '-' = 无凭据语义（mock/local——UI 判 '-' 不渲染凭据表单）；credentialSchema null = 未声明。
+ */
+export function loadCredentialTypesView(snapshot: ViewSnapshot, provider?: string): CredentialTypesView {
+  const types =
+    provider === undefined
+      ? Object.keys(snapshot.catalog.credentialTypes)
+      : [...new Set(Object.values(snapshot.catalog.providers[provider] ?? {}).map((e) => e.credentialType))];
+  return {
+    types: types.sort().map((t) => {
+      const entry = snapshot.catalog.credentialTypes[t];
+      return {
+        credentialType: t,
+        owner: entry?.owner ?? '',
+        credentialSchema: entry ? readSchemaRef(snapshot.appDir, entry.packageDir, entry.credentialSchema) : null,
+      };
+    }),
+  };
+}

package/src/views/credentials.ts

@@ -0,0 +1,57 @@
+import type { CredentialBindingEcho, CredentialEcho, CredentialsView } from '../dto.js';
+import { maskCredentialValues, readCredentialFile, stemToFilePath } from '../core/credential-format.js';
+import type { ViewSnapshot } from './context.js';
+
+/**
+ * 凭据状态轴投影（views/credentials；v4.4 D33 独立端点 GET /credentials）：
+ * 绑定位全量掩码回显——应用状态轴（随配置失效、零求值零 contracts、永不 503）。
+ * GET 永无真值（仅 ref/masked）；掩码单源 maskCredentialValues；echoForRef 自
+ * service-resolutions 迁入共享（求值单体 instances[].credential 已删净——求值路径零凭据 I/O）。
+ *
+ * 键集 = 文件语义忠实镜像（api.md §0「键域不对称」）：
+ *   app.byInstance        = 注册表 ids ∩ 有 ref（无 ref 的注册实例不出现；未注册 ref 跳过不虚报）
+ *   services[s].byInstance = 节点 instances map 全键（含 '*'，无 ref 亦在场 → null）
+ * null 语义：credential/byInstance 值 = 「未就绪」（ref 缺席或文件缺失）——缺失诊断归谓词 #1
+ * （CREDENTIAL_FILE_MISSING），echo = 状态回显、issues = 诊断定位（P16 分工）。
+ */
+
+/** 凭据文件掩码回显（ref 非 secret:// 或文件缺席 → undefined——调用方映射 null） */
+export function echoForRef(appDir: string, ref: string | undefined): CredentialEcho | undefined {
+  if (ref === undefined || !ref.startsWith('secret://')) return undefined;
+  const stem = ref.slice('secret://'.length);
+  const file = readCredentialFile(appDir, stem);
+  if (!file) return undefined;
+  return { type: file.type, ref, file: stemToFilePath(stem), masked: maskCredentialValues(file.values) };
+}
+
+export function loadCredentialsView(snapshot: ViewSnapshot): CredentialsView {
+  const cfg = snapshot.integrations as {
+    credentialRef?: unknown;
+    credentialRefByInstance?: Record<string, string>;
+    instances?: Array<{ id: string }>;
+    services?: Record<string, { credentialRef?: string; instances?: Record<string, { credentialRef?: string }> }>;
+  } | null;
+
+  const app: CredentialBindingEcho = {
+    credential: echoForRef(snapshot.appDir, typeof cfg?.credentialRef === 'string' ? cfg.credentialRef : undefined) ?? null,
+    byInstance: {},
+  };
+  for (const { id } of cfg?.instances ?? []) {
+    const ref = cfg?.credentialRefByInstance?.[id];
+    if (ref === undefined) continue; // 无 ref 的注册实例不出现（api.md §4.9a 实证）
+    app.byInstance[id] = echoForRef(snapshot.appDir, ref) ?? null;
+  }
+
+  const services: Record<string, CredentialBindingEcho> = {};
+  for (const [s, node] of Object.entries(cfg?.services ?? {})) {
+    const slot: CredentialBindingEcho = {
+      credential: echoForRef(snapshot.appDir, node.credentialRef) ?? null,
+      byInstance: {},
+    };
+    for (const [k, inst] of Object.entries(node.instances ?? {})) {
+      slot.byInstance[k] = echoForRef(snapshot.appDir, inst.credentialRef) ?? null;
+    }
+    services[s] = slot;
+  }
+  return { app, services };
+}