@tbox.cn/app-toolkit 0.1.0

package/src/integrations/write.ts

@@ -0,0 +1,448 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import Ajv from 'ajv';
+import { resolveContractsForApp } from '../core/contracts-resolver.js';
+import type { FileCache } from '../core/file-cache.js';
+import { writeAtomic } from '../core/fskit.js';
+import { SAFE_NAME_PATTERN } from '../core/module-schema.js';
+import { walkManifests } from '../assembly/walk-manifests.js';
+import { APP_INTEGRATION_NODE_KEYS } from '../dto.js';
+import {
+  planAppCredentialArtifacts,
+  planServiceCredentialArtifacts,
+  reconcileOrphanCredentials,
+  writeCredentialArtifacts,
+  type AppliedCredential,
+  type CredentialInput,
+} from './credentials.js';
+import type { IntegrationServiceIssue } from './predicate.js';
+import { checkInstanceKeys } from './predicate.js';
+import { AppToolkitError } from '../core/errors.js';
+
+/**
+ * 写核心（C3-4 write；FX-1c 管线重排——F3 九步定序 + D-B2 语义 + F4 输入扩位）：
+ * PUT = 节点全量替换（三同构——body ≡ 文件节点；三 PUT 端点无例外）。
+ *
+ * 九步定序（applyApp / applyService 同构）：
+ *  1 输入约束（assertSafeNames 值位 + assertSafeInstanceKeys map 键位——F4）
+ *  2 合并 node → next；文件缺席 → 骨架物化（R13 语义翻转提示入 issues）
+ *  3 凭据校验链（type 匹配 400 + credentialSchema ajv 字段级——schema 缺席宽松；dryRun 也跑）
+ *  4 凭据 stem/ref **纯派生**（plan*——零 I/O）+ ref 回填节点（**先于 no-diff**：
+ *    node 缺 ref + 带 credentials → 节点变化 → 全量写；node 已含同 ref → 节点不变 → 纯凭据写）
+ *  5 noDiff（**深度结构等价**，非 stringify）；hasCredentialInput
+ *  6 noDiff && 无凭据输入 → 短路 written:false
+ *  7 严格整文档校验（contracts parseIntegrationsConfig——触发 = !noDiff ∥ 有凭据输入）
+ *  8 凭据工件落盘（**后置于校验通过**——防「凭据已写 + zod 拒绝」不一致态；
+ *    dryRun → writeCredentialArtifacts 零写盘 + existsSync 预览）
+ *  9 finalize：written = integrations 实写 ∥ 凭据实写（**D-B2**）；files 分列两类路径；
+ *    restartScheduled = written && onApplied（凭据影响 boot 装配——重启正当）；写后缓存失效
+ * 归一化：N1 模块节点 {} → 删 domains[键]；N3 服务节点 {} 不归一化（显式通配激活 = 合法 TIER0 态）；
+ * N2 已随 ?instance= 退役。dryRun（PUT only）：复读完整管线不落盘不排程。
+ * DELETE：节点移除 + 孤儿凭据写后对账（覆盖 DELETE 与 PUT 替换两类来源，只报告不清理——D9）。
+ * 并发：进程内串行（per-factory promise chain 由工厂持有——本模块假设单飞调用）。
+ */
+
+export interface SaveResult {
+  written: boolean;
+  restartScheduled: boolean;
+  files: string[];
+  credentials: Array<{ stem: string; ref: string; overwrote: boolean }>;
+  issues: IntegrationServiceIssue[];
+}
+
+export interface WriteOptions {
+  dryRun?: boolean;
+  /** body 唯一非文件字段（真值直落 config/credentials/，派生 ref 回填本节点） */
+  credentials?: CredentialInput;
+  credentialsByInstance?: Record<string, CredentialInput>;
+}
+
+export interface WriteCoreOptions {
+  onApplied?: () => void;
+  cache?: FileCache;
+}
+
+const INTEGRATIONS_FILE = join('config', 'integrations.json');
+
+/** 深度结构等价（非 stringify——键序陷阱误判 diff 防线） */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (a && b && typeof a === 'object' && typeof b === 'object') {
+    const ka = Object.keys(a as Record<string, unknown>);
+    const kb = Object.keys(b as Record<string, unknown>);
+    if (ka.length !== kb.length) return false;
+    return ka.every((k) => deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]));
+  }
+  return false;
+}
+
+/** 输入约束①（安全钉子，F4 扩位）：node 内 provider/instanceId 值位 + map 键位字符集校验
+ *  （第一道；deriveStem 断言为第二道）。违例 → 400 + fields 指向。 */
+function assertSafeNames(value: unknown, path: string): void {
+  if (typeof value === 'string') return;
+  if (value && typeof value === 'object') {
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if ((k === 'provider' || k === 'instanceId') && typeof v === 'string' && !SAFE_NAME_PATTERN.test(v)) {
+        throw new AppToolkitError(
+          'VALIDATION_FAILED',
+          400,
+          `${k} 名含非法字符（需 /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/）`,
+          [`${path}.${k}`],
+        );
+      }
+      assertSafeNames(v, `${path}.${k}`);
+    }
+  }
+}
+
+/** F4 map 键位校验：进凭据 stem 派生的 map 键（instances 覆盖位 / ByInstance 位 / credentialsByInstance 选项）。
+ *  通配键：instances map 的 '*'/'**' 豁免（TIER0 通配激活合法态——合法性归 zod/谓词 #8）；
+ *  ByInstance 层与 credentialsByInstance 无通配语义（TIER0 精确键）→ '*' 亦拒。 */
+function assertSafeMapKeys(map: unknown, where: string, wildcardOk: boolean): void {
+  if (!map || typeof map !== 'object' || Array.isArray(map)) return;
+  for (const k of Object.keys(map as Record<string, unknown>)) {
+    if (wildcardOk && (k === '*' || k === '**')) continue;
+    if (!SAFE_NAME_PATTERN.test(k)) {
+      throw new AppToolkitError(
+        'VALIDATION_FAILED',
+        400,
+        `${where} 键 ${k} 含非法字符（需 /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/）——进凭据 stem 派生，防路径逃逸`,
+        [where],
+      );
+    }
+  }
+}
+
+/** F4 调用面：按节点形态分派 map 键位校验（applyApp root / applyService slot / credentialsByInstance 选项） */
+function assertSafeInstanceKeys(node: Record<string, unknown>, writeOpts: WriteOptions, kind: 'root' | 'slot'): void {
+  if (kind === 'root') {
+    // root.instances[].id（注册表 id——谓词 #8 白名单与实例键检查的同一空间）
+    const instances = node.instances;
+    if (Array.isArray(instances)) {
+      instances.forEach((entry, i) => {
+        const id = entry && typeof entry === 'object' ? (entry as { id?: unknown }).id : undefined;
+        if (typeof id === 'string' && !SAFE_NAME_PATTERN.test(id)) {
+          throw new AppToolkitError(
+            'VALIDATION_FAILED',
+            400,
+            `instances[${i}].id 含非法字符（需 /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/）`,
+            [`root.instances[${i}].id`],
+          );
+        }
+      });
+    }
+    assertSafeMapKeys(node.configByInstance, 'root.configByInstance', false);
+    assertSafeMapKeys(node.credentialRefByInstance, 'root.credentialRefByInstance', false);
+  } else {
+    assertSafeMapKeys(node.instances, 'services.instances', true);
+  }
+  assertSafeMapKeys(writeOpts.credentialsByInstance, 'credentialsByInstance', false);
+}
+
+/** 写时读当前配置（cache 优先；缺席 → null——调用方决定骨架物化） */
+function loadConfig(appDir: string, cache?: FileCache): Record<string, unknown> | null {
+  const file = join(appDir, INTEGRATIONS_FILE);
+  const parse = (raw: string): Record<string, unknown> => JSON.parse(raw) as Record<string, unknown>;
+  if (cache) return cache.read(file, parse) ?? null;
+  if (!existsSync(file)) return null;
+  try {
+    return parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** 轻量复查 #8（写路径——谓词 checkInstanceKeys 单源，FX-2b）：malls = root instances
+ *  注册表 ids；参考表缺席 → 跳过（谓词 #8 同语义；fail-visible——422 退役） */
+function registryCheck(config: Record<string, unknown>): IntegrationServiceIssue[] {
+  const registryIds = ((config.instances as Array<{ id: string }> | undefined) ?? []).map((i) => i.id);
+  if (registryIds.length === 0) return [];
+  return checkInstanceKeys(config as never, registryIds);
+}
+
+/** (provider, service) → 声明 credentialType（catalog 槽供给声明序首个；内联声明由调用方先行覆盖） */
+function declaredCredentialType(appDir: string, provider: string, service: string | undefined, cache?: FileCache): string | undefined {
+  const { catalog } = walkManifests(appDir, cache);
+  const vendorImpls = catalog.providers[provider];
+  if (!vendorImpls) return undefined;
+  const types = new Set<string>();
+  for (const entry of Object.values(vendorImpls)) {
+    if (service === undefined || entry.services.includes(service)) types.add(entry.credentialType);
+  }
+  return types.size === 1 ? [...types][0] : undefined; // 歧义/缺席 → undefined（跳过 type 校验）
+}
+
+/** 凭据校验链（H8）：type 匹配 400 + credentialSchema ajv 字段级 400 + schema 缺席跳过 */
+function validateCredential(
+  appDir: string,
+  provider: string,
+  service: string | undefined,
+  credentials: CredentialInput,
+  inlineCredentialType: string | undefined,
+  cache?: FileCache,
+): void {
+  // ① type 匹配（内联声明优先；catalog 槽供给次之；均缺席 → 跳过——宽松与 P11 对齐）
+  const expectedType = inlineCredentialType ?? declaredCredentialType(appDir, provider, service, cache);
+  if (expectedType !== undefined && expectedType !== '-' && credentials.type !== expectedType) {
+    throw new AppToolkitError(
+      'VALIDATION_FAILED',
+      400,
+      `凭据 type=${credentials.type} 与绑定 credentialType ${expectedType} 不一致`,
+      ['credentials.type'],
+    );
+  }
+  // ② credentialSchema ajv 字段级（schema 缺席 → 跳过；坏文件 → 跳过——#6 归谓词）
+  if (service === undefined) return;
+  const { serviceSchemas } = walkManifests(appDir, cache);
+  const entry = serviceSchemas[`${provider}\u0000${service}`];
+  if (!entry?.credentialSchema) return;
+  const schemaFile = resolve(entry.packageDir, entry.credentialSchema);
+  if (!existsSync(schemaFile)) return;
+  try {
+    const ajv = new Ajv({ allErrors: true });
+    const validate = ajv.compile(JSON.parse(readFileSync(schemaFile, 'utf8')) as object);
+    if (!validate({ type: credentials.type, ...credentials.values })) {
+      const fields = (validate.errors ?? []).map(
+        (e) => `credentials.values.${String(e.instancePath || e.params?.missingProperty || '').replace(/^\//, '')}`,
+      );
+      throw new AppToolkitError('VALIDATION_FAILED', 400, `凭据字段校验失败（ajv 字段级）`, fields);
+    }
+  } catch (err) {
+    if (err instanceof AppToolkitError) throw err;
+    // schema 坏文件 → 跳过 ajv（宽松）
+  }
+}
+
+export interface WriteCore {
+  /** 预热（工厂创建/写前调用——严格校验缓存就绪；memoized resolver 后续 1 stat 级） */
+  warmup(): Promise<void>;
+  /** PUT /app/integration（root 节点全集） */
+  applyApp(node: Record<string, unknown>, opts?: WriteOptions): SaveResult;
+  /** PUT /modules/:module/integration（domains 换算；N1 {} 删域键） */
+  applyModule(moduleId: string, node: Record<string, unknown>, opts?: WriteOptions): SaveResult;
+  /** PUT /services/:service/integration（整节点含 instances map；N3 {} 不归一化） */
+  applyService(service: string, node: Record<string, unknown>, opts?: WriteOptions): SaveResult;
+  /** DELETE /services/:service/integration（恒整节点；幂等；无预演） */
+  deleteService(service: string): SaveResult;
+  /** 模块服务域键（module → domains 键 = 服务集派生域键集 upsert 位） */
+  moduleDomainKey(moduleId: string): string | undefined;
+}
+
+export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): WriteCore {
+  const { onApplied, cache } = opts;
+
+  function finalize(
+    next: Record<string, unknown> | null,
+    appliedCredentials: AppliedCredential[],
+    issues: IntegrationServiceIssue[],
+    dryRun: boolean | undefined,
+    credentialsWritten: boolean,
+  ): SaveResult {
+    // D-B2：written ⟺ 任一文件实写；files 分列（integrations.json + 凭据路径）；
+    // restartScheduled 跟随 written（凭据文件影响 boot 装配——重启正当）
+    const integrationsWritten = !dryRun && next !== null;
+    if (integrationsWritten) {
+      writeAtomic(join(appDir, INTEGRATIONS_FILE), `${JSON.stringify(next, null, 2)}\n`);
+      cache?.invalidate([join(appDir, INTEGRATIONS_FILE)]);
+    }
+    const written = integrationsWritten || credentialsWritten;
+    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`));
+    return {
+      written,
+      restartScheduled,
+      files,
+      credentials: appliedCredentials,
+      issues,
+    };
+  }
+
+  let strictContracts: Awaited<ReturnType<typeof resolveContractsForApp>> | undefined;
+
+  async function warmup(): Promise<void> {
+    strictContracts = await resolveContractsForApp(appDir);
+  }
+
+  function runStrictValidation(next: Record<string, unknown>, issues: IntegrationServiceIssue[]): void {
+    const strict = strictContracts;
+    if (!strict || !strict.strictValidation || !strict.module.parseIntegrationsConfig) {
+      throw new AppToolkitError(
+        'CONTRACTS_NOT_RESOLVED',
+        503,
+        'contracts 严格校验面不可用（需 ≥0.9）——写路径门控失败（工厂边缘断言应先行拦截）',
+      );
+    }
+    void issues;
+    strict.module.parseIntegrationsConfig(next);
+  }
+
+  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');
+      assertSafeInstanceKeys(node, writeOpts, 'root');
+      const issues: IntegrationServiceIssue[] = [];
+      const current = loadConfig(appDir, cache);
+      const base: Record<string, unknown> = current ?? { services: {} };
+      if (current === null) {
+        issues.push({
+          severity: 'warning',
+          code: 'SKELETON_MATERIALIZED',
+          message: 'config/integrations.json 缺席——已物化骨架（写时自动初始化；R13 语义翻转提示）',
+        });
+      }
+      // root 全量替换（D14 无例外语义）：缺席根键删除（services/domains/modules 域不在根键集——随 base 保留），
+      // node 全键置入（未知键交严格 zod 拒——fail-visible；B10：原实现 spread+merge 残留 stale 根键）
+      const next: Record<string, unknown> = { ...base };
+      for (const k of APP_INTEGRATION_NODE_KEYS) if (!(k in node)) delete next[k];
+      for (const [k, v] of Object.entries(node)) next[k] = v;
+      // 凭据纯派生 + 校验链（dryRun 也跑——彩排语义）
+      const provider = typeof next.provider === 'string' ? next.provider : 'app';
+      const plan = planAppCredentialArtifacts(provider, writeOpts.credentials, writeOpts.credentialsByInstance);
+      for (const p of plan) validateCredential(appDir, provider, undefined, p.input, undefined, cache);
+      // ref 回填（先于 no-diff：node 缺 ref + 带 credentials → 节点变化 → 全量写）
+      const rootArtifact = plan.find((p) => p.instanceId === undefined);
+      if (writeOpts.credentials && rootArtifact) next.credentialRef = rootArtifact.ref;
+      if (writeOpts.credentialsByInstance) {
+        const byInstance = { ...((next.credentialRefByInstance as Record<string, string>) ?? {}) };
+        for (const p of plan) {
+          if (p.instanceId !== undefined) byInstance[p.instanceId] = p.ref;
+        }
+        next.credentialRefByInstance = byInstance;
+      }
+      const hasCredentialInput = writeOpts.credentials !== undefined || writeOpts.credentialsByInstance !== undefined;
+      const noDiff = deepEqual(current, next);
+      if (noDiff && !hasCredentialInput) {
+        return { written: false, restartScheduled: false, files: [], credentials: [], 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);
+    },
+
+    applyModule(moduleId: string, node: Record<string, unknown>, writeOpts: WriteOptions = {}): SaveResult {
+      assertSafeNames(node, 'root');
+      const issues: IntegrationServiceIssue[] = [];
+      const current = loadConfig(appDir, cache);
+      if (current === null && Object.keys(node).length === 0) {
+        // 空文件清空域 = no-op（N1 幂等）
+        return { written: false, restartScheduled: false, files: [], credentials: [], issues };
+      }
+      if (current === null) {
+        issues.push({
+          severity: 'warning',
+          code: 'SKELETON_MATERIALIZED',
+          message: 'config/integrations.json 缺席——已物化骨架（写时自动初始化；R13 语义翻转提示）',
+        });
+      }
+      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[键]（清域）；其余 = 域键全量替换
+      if (Object.keys(node).length === 0) delete domains[domainKey];
+      else domains[domainKey] = { ...node };
+      if (deepEqual(current, next)) {
+        return { written: false, restartScheduled: false, files: [], credentials: [], issues };
+      }
+      runStrictValidation(next, issues);
+      issues.push(...registryCheck(next));
+      return finalize(next, [], issues, writeOpts.dryRun, false);
+    },
+
+    applyService(service: string, node: Record<string, unknown>, writeOpts: WriteOptions = {}): SaveResult {
+      assertSafeNames(node, 'root');
+      assertSafeInstanceKeys(node, writeOpts, 'slot');
+      const issues: IntegrationServiceIssue[] = [];
+      const current = loadConfig(appDir, cache);
+      if (current === null) {
+        issues.push({
+          severity: 'warning',
+          code: 'SKELETON_MATERIALIZED',
+          message: 'config/integrations.json 缺席——已物化骨架（写时自动初始化；R13 语义翻转提示）',
+        });
+      }
+      const base: Record<string, unknown> = current ?? { services: {} };
+      const services = { ...((base.services as Record<string, unknown>) ?? {}) };
+      const next: Record<string, unknown> = { ...base, services };
+      // N3：服务节点 {} 不归一化（显式通配激活 = 合法 TIER0 态，与键缺席两义）——原样落位
+      services[service] = { ...node };
+      // 凭据纯派生 + 校验链（dryRun 也跑；内联声明 credentialType 为校验链输入）
+      const providerRaw = node.provider;
+      const inlineProvider = providerRaw !== null && typeof providerRaw === 'object' ? (providerRaw as Record<string, unknown>) : undefined;
+      const providerName = typeof providerRaw === 'string' ? providerRaw : typeof inlineProvider?.provider === 'string' ? inlineProvider.provider : 'app';
+      const domain = service.includes('.') ? service.slice(0, service.indexOf('.')) : service;
+      const plan = planServiceCredentialArtifacts(providerName, service, domain, writeOpts.credentials, writeOpts.credentialsByInstance);
+      for (const p of plan) {
+        validateCredential(appDir, providerName, service, p.input, typeof inlineProvider?.credentialType === 'string' ? inlineProvider.credentialType : undefined, cache);
+      }
+      // ref 回填本节点（先于 no-diff；credentials 在场覆盖 body ref；仅传 ref 原样透传）
+      const slotNode = services[service] as Record<string, unknown>;
+      const rootArtifact = plan.find((p) => p.instanceId === undefined);
+      if (writeOpts.credentials && rootArtifact) slotNode.credentialRef = rootArtifact.ref;
+      if (writeOpts.credentialsByInstance) {
+        const instances = { ...((slotNode.instances as Record<string, Record<string, unknown>>) ?? {}) };
+        for (const p of plan) {
+          if (p.instanceId === undefined) continue;
+          const inst = { ...(instances[p.instanceId] ?? {}) };
+          inst.credentialRef = p.ref;
+          instances[p.instanceId] = inst;
+        }
+        slotNode.instances = instances;
+      }
+      const hasCredentialInput = writeOpts.credentials !== undefined || writeOpts.credentialsByInstance !== undefined;
+      const noDiff = deepEqual(current, next);
+      if (noDiff && !hasCredentialInput) {
+        return { written: false, restartScheduled: false, files: [], credentials: [], 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);
+    },
+
+    deleteService(service: string): SaveResult {
+      const issues: IntegrationServiceIssue[] = [];
+      const current = loadConfig(appDir, cache);
+      const services = { ...((current?.services as Record<string, unknown>) ?? {}) };
+      if (!(service in services)) {
+        // 幂等：清不存在的节点 → written:false（无 409；无预演）
+        return { written: false, restartScheduled: false, files: [], credentials: [], issues };
+      }
+      delete services[service];
+      const next: Record<string, unknown> = { ...(current ?? { services: {} }), services };
+      writeAtomic(join(appDir, INTEGRATIONS_FILE), `${JSON.stringify(next, null, 2)}\n`);
+      cache?.invalidate([join(appDir, INTEGRATIONS_FILE)]);
+      // 孤儿凭据写后对账（D9——覆盖 DELETE 与 PUT 替换两类来源）
+      issues.push(...reconcileOrphanCredentials(appDir));
+      const restartScheduled = onApplied !== undefined;
+      if (restartScheduled) onApplied?.();
+      return { written: true, restartScheduled, files: [INTEGRATIONS_FILE], credentials: [], issues };
+    },
+  };
+}

package/src/views/app.ts

@@ -0,0 +1,28 @@
+import type { AppView } 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）；
+ * 平台服务状态不在此（→ /service-resolutions）；模块服务不在此（→ /modules/:m）。
+ * integration = **root 节点投影**（APP_INTEGRATION_NODE_KEYS——D21/L1：GET 预填 ≡ PUT body；
+ * 文件另含 services/domains/modules 域键，不进 root 节点投影——原实现整文件透传，
+ * PUT 回会级联写回域键）；文件缺席 = null，文件在场 → 投影对象（可为空）。
+ */
+
+export function loadAppView(snapshot: ViewSnapshot): AppView {
+  const occupied = moduleOccupiedServices(snapshot.walk);
+  const services = snapshot.walk.vocabulary.filter((s) => !occupied.has(s));
+  const config = snapshot.integrations;
+  let integration: AppView['integration'] = null;
+  if (config) {
+    const node: Record<string, unknown> = {};
+    for (const k of APP_INTEGRATION_NODE_KEYS) {
+      if (k in config) node[k] = config[k];
+    }
+    integration = node as AppView['integration'];
+  }
+  return { services, integration };
+}

package/src/views/context.ts

@@ -0,0 +1,70 @@
+import { readIntegrationsConfig } from '../integrations/read.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 依赖）。
+ */
+
+export interface ViewContext {
+  appDir: string;
+  cache?: FileCache;
+}
+
+export interface ViewSnapshot {
+  appDir: string;
+  walk: WalkManifestsResult;
+  catalog: WalkCatalog;
+  integrations: Record<string, unknown> | null;
+  contracts: ResolvedContracts;
+}
+
+/** 域前缀换算（本地 helper——静态面零 contracts 依赖前提） */
+export function domainOfService(service: string): string {
+  const i = service.indexOf('.');
+  return i === -1 ? service : service.slice(0, i);
+}
+
+/** 读取视图输入快照（每方法调用独立——Freshness Contract 单位 = 方法调用） */
+export async function loadViewSnapshot(ctx: ViewContext): Promise<ViewSnapshot> {
+  const walk = walkManifests(ctx.appDir, ctx.cache);
+  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 };
+}
+
+/** 同步快照（调用方已持有 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 };
+}
+
+/** 模块占用服务集（demand 侧——平台服务 = 词汇 − 本集） */
+export function moduleOccupiedServices(walk: WalkManifestsResult): Set<string> {
+  const occupied = new Set<string>();
+  for (const mod of walk.modules) {
+    for (const need of mod.descriptor.contributes.services ?? []) occupied.add(need.service);
+    for (const slot of mod.descriptor.contributes.providers?.slots ?? []) occupied.add(slot.service);
+  }
+  return occupied;
+}
+
+/** 供给关系点查：(provider, service) ∈ 供给关系 */
+export function isSupplied(catalog: WalkCatalog, provider: string, service: string): boolean {
+  const impls = catalog.providers[provider];
+  if (!impls) return false;
+  return Object.values(impls).some((entry) => entry.services.includes(service));
+}
+
+/** 供给厂商名单（suppliedBy——picker 数据源；catalog 静态切片） */
+export function suppliedByVendors(catalog: WalkCatalog, service: string): string[] {
+  const vendors: string[] = [];
+  for (const [vendor, impls] of Object.entries(catalog.providers)) {
+    if (Object.values(impls).some((entry) => entry.services.includes(service))) vendors.push(vendor);
+  }
+  return vendors.sort();
+}

package/src/views/modules.ts

@@ -0,0 +1,48 @@
+import type { ModuleDeclaration, ModuleDetailView, ServiceDemand } from '../dto.js';
+import { AppToolkitError } from '../core/errors.js';
+import { domainOfService, type ViewSnapshot } from './context.js';
+
+/**
+ * 需求轴/模块静态投影（views/modules；C4）。静态端点结构性零求值（铁律 #3——
+ * 无 resolution/issues/contracts 键，永不 503）。
+ */
+
+/** GET /modules：纯模块清单（demand 不在——卡片展开 = GET /modules/:m） */
+export function loadModulesView(snapshot: ViewSnapshot): { modules: ModuleDeclaration[] } {
+  const modules: ModuleDeclaration[] = snapshot.walk.modules
+    .map((mod) => ({
+      id: mod.id,
+      name: mod.descriptor.name,
+      // 模块级 title/description：manifest 无模块级 meta 字段（demand meta 属 per-service）——
+      // 一期回退 install id / 空描述（UI 侧按词汇表或 demand meta 增强）
+      title: mod.descriptor.name,
+      description: '',
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+  return { modules };
+}
+
+/** 域键换算（模块服务集派生域键集；单域 = 该域，多域/零域 = 模块 id——与 write.moduleDomainKey 同约定） */
+export function moduleDomainKeyOf(services: ServiceDemand[], moduleId: string): string {
+  const domainKeys = new Set(services.map((s) => domainOfService(s.service)));
+  return domainKeys.size === 1 ? [...domainKeys][0] : moduleId;
+}
+
+/** GET /modules/:module：模块静态一站式（integration 节点原值 + demand；PUT 读对偶） */
+export function loadModuleDetailView(snapshot: ViewSnapshot, moduleId: string): ModuleDetailView {
+  const mod = snapshot.walk.modules.find((m) => m.id === moduleId);
+  if (!mod) {
+    throw new AppToolkitError('MODULE_NOT_FOUND', 404, `模块 ${moduleId} 非已装模块`);
+  }
+  const services: ServiceDemand[] = (mod.descriptor.contributes.services ?? []).map((need) => ({
+    service: need.service,
+    ...(need.title ? { title: need.title } : {}),
+    ...(need.description ? { description: need.description } : {}),
+    required: need.optional !== false,
+  }));
+  const domains = (snapshot.integrations as { domains?: Record<string, unknown> } | null)?.domains ?? {};
+  const domainKey = moduleDomainKeyOf(services, moduleId);
+  // integration = domains[换算键] 节点原值（D21 编辑预填源）；未配置 = null
+  const integration = (domains[domainKey] as ModuleDetailView['integration']) ?? null;
+  return { integration, services };
+}