@tbox.cn/app-toolkit 0.1.0

package/src/core/contracts-resolver.ts

@@ -0,0 +1,274 @@
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { ResolvedModule } from './contracts-expected.js';
+import { createFileCache, type FileCache } from './file-cache.js';
+
+/**
+ * contracts 动态解析器（方案心脏，D3）：`resolveContractsForApp(appDir)`——
+ * 成员扫描 + 包根定位。沙箱内 toolkit 与目标应用版本解耦：求值与校验双面由
+ * 应用自己的 @tbox.cn/app-contracts 版本驱动。
+ *
+ * 解析算法：
+ *   候选目录序（越靠前越优）：
+ *     1. appDir/node_modules/@tbox.cn/app-contracts              （npm 平铺 / 应用根直装）
+ *     2. appDir/apps/server/node_modules/…                       （pnpm 成员级——运行时消费方优先）
+ *     3. appDir/apps/<各成员>/node_modules/…（其余成员，字母序去重）
+ *     4. appDir/packages/<各包>/node_modules/…（codegen 模块包）
+ *   每候选：existsSync → realpathSync（解 pnpm symlink 至 store 真实路径）
+ *     → 探测 <根>/dist/runtime.js（构建/发布/验证态）｜<根>/src/runtime.ts（workspace link 态，TS-host 前提）
+ *     → 读 **候选路径**（symlink 原路径）package.json version——版本轻探测：pnpm 升级换 store 目标
+ *       可觉察（realpath 缓存路径旧 version 恒旧，读候选路径修正——真 bug 候选防线）
+ *     → await import(探测命中文件) → 逐命名导出存在性检查（contracts-expected EvaluationExports）
+ *   首个命中即返回（候选序即优先级）；全候选缺席/导入拒绝 → 未解析（**绝不 throw**）。
+ *
+ * **红线**：禁 createRequire().resolve（contracts 发布面 exports 仅 types+import 双条件、
+ * 无 require/default——必抛 ERR_PACKAGE_PATH_NOT_EXPORTED）；动态 import 路径运行时计算
+ * （pathToFileURL——打包器不得字面量折叠，README 打包纪律）。
+ *
+ * memoize：per appDir 记忆 { promise, version }；每次 resolve 轻探测候选路径 version——
+ * 变更 → 重走候选链 + 动态 import（Node import 缓存按路径天然去重；升级契约自动生效，
+ * 不依赖事件广播——node_modules 被 FileWatcher IGNORED_DIRS 过滤，自愈设计不依赖广播）。
+ */
+
+export interface ResolvedContracts {
+  /** 候选包 package.json version（未安装 → null） */
+  version: string | null;
+  /** 求值面可用（resolveEffectiveService 等命名导出在场） */
+  evaluation: boolean;
+  /** 严格 zod 面可用（parseIntegrationsConfig 在场——≥0.9 门控判据） */
+  strictValidation: boolean;
+  /** 动态 import 产物（命名导出子集——Partial<EvaluationExports>） */
+  module: ResolvedModule;
+  /** 解析诊断（N1 构建指引 message 三分支的输入：未安装 / 版本 <0.9 / 源码态未构建） */
+  notes: string[];
+}
+
+/** 求值面必需具名导出（在场 → evaluation: true） */
+const EVALUATION_EXPORT_NAMES = [
+  'resolveEffectiveService',
+  'buildSupplyLookup',
+  'moduleDomainOf',
+  'normalizeInstances',
+  'RESOURCE_TYPE_IDS',
+] as const;
+
+/** 严格校验面具名导出（在场 → strictValidation: true；0.9+） */
+const STRICT_EXPORT_NAME = 'parseIntegrationsConfig';
+
+const UNRESOLVED: ResolvedContracts = {
+  version: null,
+  evaluation: false,
+  strictValidation: false,
+  module: {},
+  notes: [],
+};
+
+/** 候选目录序（server 优先——运行时消费方；其余字母序；packages/ 为 codegen 模块包） */
+function candidateDirs(appDir: string): string[] {
+  const dirs: string[] = [appDir];
+  for (const sub of ['apps', 'packages']) {
+    const parent = join(appDir, sub);
+    if (!existsSync(parent)) continue;
+    const entries = readdirSync(parent, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+    if (sub === 'apps') {
+      // server 运行时消费方优先，其余字母序
+      entries.sort((a, b) => {
+        if (a === 'server') return -1;
+        if (b === 'server') return 1;
+        return a.localeCompare(b);
+      });
+    } else {
+      entries.sort((a, b) => a.localeCompare(b));
+    }
+    for (const name of entries) dirs.push(join(parent, name));
+  }
+  return dirs;
+}
+
+/** 轻探测单候选快照（F9）：路径 + version（file-cache）+ 产物态——memo 命中判定指纹的原子单元 */
+interface CandidateProbe {
+  /** package.json 路径（轻探测读路径——symlink 原路径，pnpm 换 store 目标可觉察） */
+  pkgPath: string;
+  /** 候选包根（node_modules/@tbox.cn/app-contracts——symlink 原路径，产物态探测基准） */
+  candidateDir: string;
+  version: string | null;
+  /** dist（构建/发布态）｜ src（workspace link 态）｜ none（无产物——待构建）｜ gone（候选缺席） */
+  artifact: 'dist' | 'src' | 'none' | 'gone';
+}
+
+interface MemoEntry {
+  promise: Promise<ResolvedContracts>;
+  /** 解析时首个在册候选（候选序变化/修复/新候选出现可觉察） */
+  first: CandidateProbe | null;
+  /** 解析实际命中候选（unresolved → null；版本变更/产物物化/候选消失可觉察——F9 两处 stale 边缘同修） */
+  resolved: CandidateProbe | null;
+}
+
+const memo = new Map<string, MemoEntry>();
+const versionProbeCache: FileCache = createFileCache();
+
+/** 版本读取（候选路径——经 file-cache；文件缺席 → null） */
+function readCandidateVersion(pkgPath: string): string | null {
+  return (
+    versionProbeCache.read(pkgPath, (raw) => {
+      const parsed = JSON.parse(raw) as { version?: string };
+      return typeof parsed.version === 'string' ? parsed.version : null;
+    }) ?? null
+  );
+}
+
+/** 候选产物态（realpath 解 symlink 后探测 dist/src；候选缺席 → 'gone'） */
+function artifactStateOf(candidateDir: string): CandidateProbe['artifact'] {
+  if (!existsSync(candidateDir)) return 'gone';
+  let root: string;
+  try {
+    root = realpathSync(candidateDir);
+  } catch {
+    root = candidateDir;
+  }
+  if (existsSync(join(root, 'dist', 'runtime.js'))) return 'dist';
+  if (existsSync(join(root, 'src', 'runtime.ts'))) return 'src';
+  return 'none';
+}
+
+/** 指定候选路径探测（命中候选复探——与候选序扫描解耦） */
+function probeCandidatePath(candidateDir: string): CandidateProbe {
+  const pkgPath = join(candidateDir, 'package.json');
+  return { pkgPath, candidateDir, version: readCandidateVersion(pkgPath), artifact: artifactStateOf(candidateDir) };
+}
+
+/** 候选序首个在册候选（1 候选序扫描 + 1 版本读（cache）+ 1-2 产物 existsSync） */
+function probeFirstCandidate(appDir: string): CandidateProbe | null {
+  for (const dir of candidateDirs(appDir)) {
+    const candidateDir = join(dir, 'node_modules', '@tbox.cn', 'app-contracts');
+    const pkgPath = join(candidateDir, 'package.json');
+    if (!existsSync(pkgPath)) continue;
+    return { pkgPath, candidateDir, version: readCandidateVersion(pkgPath), artifact: artifactStateOf(candidateDir) };
+  }
+  return null;
+}
+
+function candidateFingerprint(p: CandidateProbe | null): string {
+  return p === null ? 'none' : `${p.pkgPath}|${p.version ?? 'null'}|${p.artifact}`;
+}
+
+/** memo 命中判定（F9）：首个在册候选指纹稳定（序/版本/产物态）+ 命中候选指纹稳定（版本/产物态）。
+ *  同指纹即等价——unresolved（resolved=null）仅需首个候选稳定。 */
+function memoHit(appDir: string, entry: MemoEntry): boolean {
+  const first = probeFirstCandidate(appDir);
+  if (candidateFingerprint(first) !== candidateFingerprint(entry.first)) return false;
+  if (entry.resolved === null) return true;
+  const resolvedNow =
+    first !== null && first.candidateDir === entry.resolved.candidateDir ? first : probeCandidatePath(entry.resolved.candidateDir);
+  return candidateFingerprint(resolvedNow) === candidateFingerprint(entry.resolved);
+}
+
+/** 探测单候选：返回已解析产物或 null（该候选不可用——缺席/导入拒绝） */
+async function probeCandidate(
+  candidate: string,
+  notes: string[],
+): Promise<ResolvedContracts | null> {
+  if (!existsSync(candidate)) return null;
+  // realpathSync 解 pnpm symlink 至 store 真实路径（探测/导入以包根为基准）
+  let packageRoot: string;
+  try {
+    packageRoot = realpathSync(candidate);
+  } catch {
+    return null;
+  }
+  // 探测链：dist/runtime.js（构建/发布/验证态）优先 → src/runtime.ts（workspace link 态，TS-host 前提）
+  const probes = [join(packageRoot, 'dist', 'runtime.js'), join(packageRoot, 'src', 'runtime.ts')];
+  const probeFile = probes.find((p) => existsSync(p));
+  // version 轻探测读**候选路径**（symlink 原路径）——非 realpath 缓存路径（pnpm 重装换 store 目标可觉察）
+  const version = versionProbeCache.read(join(candidate, 'package.json'), (raw) => {
+    const parsed = JSON.parse(raw) as { version?: string };
+    return typeof parsed.version === 'string' ? parsed.version : null;
+  }) ?? null;
+
+  if (probeFile === undefined) {
+    notes.push(
+      `contracts ${version ?? '(版本未知)'} 探测命中但无构建产物（dist/runtime.js 缺失）——workspace 源码态未构建：执行 pnpm --filter @tbox.cn/app-contracts build 后重试`,
+    );
+    return null;
+  }
+  try {
+    // 动态 import 路径运行时计算（pathToFileURL——Windows 安全 + 打包器禁折叠）。
+    // version query cache-bust：Node ESM import 缓存按完整 URL 去重——版本不变命中缓存
+    // （dedup 保留），版本变更 → 新 URL → 强制重 import（新版本语义生效，W4；覆盖
+    // symlink 换 store 目标与候选包原地 bump 两种升级形态）。
+    const versionQuery = version !== null ? `?v=${encodeURIComponent(version)}` : '';
+    const mod = (await import(pathToFileURL(probeFile).href + versionQuery)) as Record<string, unknown>;
+    const evaluation = EVALUATION_EXPORT_NAMES.every((name) => mod[name] !== undefined);
+    const strictValidation = mod[STRICT_EXPORT_NAME] !== undefined;
+    return {
+      version,
+      evaluation,
+      strictValidation,
+      module: mod as ResolvedModule,
+      notes: evaluation
+        ? []
+        : [`${probeFile} 命中但求值面具名导出缺席（${EVALUATION_EXPORT_NAMES.join('/')}）——契约包形态异常`],
+    };
+  } catch (err) {
+    // import 拒绝一律视为「未解析」（绝不 throw）——N1 构建指引 message 分支输入
+    notes.push(
+      `contracts ${version ?? '(版本未知)'} 构建产物导入失败（${err instanceof Error ? err.message : String(err)}）——workspace 源码态未构建或产物损坏：执行 pnpm --filter @tbox.cn/app-contracts build 后重试`,
+    );
+    return null;
+  }
+}
+
+/** 解析应用自己的 contracts（memoize + 轻探测指纹；绝不 throw——全缺席 → 未解析产物）。
+ *  F9：命中判定 = 首个在册候选 + 命中候选双指纹（版本变更 / dist 物化 / 候选序变化 / 候选消失
+ *  全面可觉察——覆盖「build 后重试」长生命周期宿主与多候选走位两处 stale 边缘）。 */
+export function resolveContractsForApp(appDir: string): Promise<ResolvedContracts> {
+  // 轻探测：双指纹与 memoized 比对（1 候选序扫描 + 版本读（cache）+ 产物 existsSync）
+  const hit = memo.get(appDir);
+  if (hit && memoHit(appDir, hit)) return hit.promise;
+
+  // in-flight 共享：resolved 未知——暂按首个在册候选估算（同指纹并发调用共享单次解析；
+  // 解决后按实际命中候选覆写；候选稳定期内的并发调用恒命中本 promise）
+  const provisional = probeFirstCandidate(appDir);
+  const entry: MemoEntry = {
+    promise: Promise.resolve({ ...UNRESOLVED }),
+    first: provisional,
+    resolved: provisional,
+  };
+  entry.promise = (async (): Promise<ResolvedContracts> => {
+    const notes: string[] = [];
+    for (const dir of candidateDirs(appDir)) {
+      const candidate = join(dir, 'node_modules', '@tbox.cn', 'app-contracts');
+      const resolved = await probeCandidate(candidate, notes);
+      if (resolved) {
+        if (resolved.version !== null && !resolved.strictValidation) {
+          // 注：push 进 resolved.notes（probeCandidate 返回体自带 notes 字段——调用侧 notes 仅供 null 路径聚合）
+          resolved.notes.push(
+            `contracts ${resolved.version} 无严格校验面（需 ≥0.9）——升级应用 @tbox.cn/app-contracts 依赖后可用`,
+          );
+        }
+        // 实际命中候选覆写（多候选走位可觉察——后续命中判定以命中候选为基准；F9）
+        entry.resolved = probeCandidatePath(candidate);
+        return resolved;
+      }
+    }
+    // 全候选缺席/不可用：unresolved 记录（首个候选指纹稳定即保持；其产物物化/版本变更/消失触发重扫）
+    entry.resolved = null;
+    // 全候选缺席：区分「未安装」与「探测命中但不可用」——notes 已带细分（导入拒绝/产物缺失）
+    if (notes.length === 0) {
+      notes.push('contracts 不可解析（未安装）——检查应用依赖安装后重试');
+    }
+    return { ...UNRESOLVED, notes };
+  })();
+
+  memo.set(appDir, entry);
+  return entry.promise;
+}
+
+/** 逃生舱（测试/宿主特殊场景——正常路径无需调用，Freshness Contract 自动；invalidate 逃生舱标注） */
+export function invalidateContractsResolver(appDir?: string): void {
+  if (appDir === undefined) memo.clear();
+  else memo.delete(appDir);
+}

package/src/core/credential-format.ts

@@ -0,0 +1,98 @@
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * 凭据双工件·文件格式与 stem 派生（写端/读端共用格式单源）。
+ *
+ * 凭据文件 `config/credentials/<stem>.json` = `{ type, ...values }`（真值工件）；
+ * integrations.json 恒持 `secret://<stem>` 引用（ref），任何 GET 路径无真值。
+ *
+ * stem 三形（服务端单源派生；与既有自由 stem 兼容）：
+ *   服务级  `${provider}-${service}`
+ *   实例级  `${provider}-${instanceId}-${domain}`（domain = service 首点段）
+ *   应用级  `${provider}-global` / `${provider}-${instanceId}-global`
+ *
+ * 安全（纵深防御第二道）：deriveStem 对任一输入含 `/`、`\`、`..` 直接 throw——
+ * 第一道为 descriptor/节点 zod 的字符集 pattern（module-schema SAFE_NAME_PATTERN）。
+ */
+import { maskCredentialValues } from './credential-mask.js';
+
+export { maskCredentialValues };
+
+export interface CredentialFile {
+  type: string;
+  values: Record<string, string>;
+}
+
+/** 凭据 stem 派生输入（service 级 / instance 级 / app 级三形由调用方按层选择字段） */
+export interface StemInput {
+  provider: string;
+  service?: string;
+  instanceId?: string;
+  domain?: string;
+}
+
+function assertSafeSegment(kind: string, value: string | undefined): void {
+  if (value === undefined) return;
+  if (value.includes('/') || value.includes('\\') || value.includes('..')) {
+    // 纵深防御断言：zod pattern 为第一道，此处兜底敌对输入（测试 O15 钉死）
+    throw new Error(`凭据 stem 派生输入含路径敌对字符（${kind}）——拒绝派生`);
+  }
+}
+
+/** stem 单源派生（三形；输入含 / \ .. → throw——断言防线） */
+export function deriveStem(input: StemInput): string {
+  assertSafeSegment('provider', input.provider);
+  assertSafeSegment('service', input.service);
+  assertSafeSegment('instanceId', input.instanceId);
+  assertSafeSegment('domain', input.domain);
+  if (input.instanceId !== undefined) {
+    // 实例级：${provider}-${instanceId}-${domain}（domain 缺省 = 'global'——应用级实例位）
+    const domain = input.domain ?? input.service ?? 'global';
+    return `${input.provider}-${input.instanceId}-${domain}`;
+  }
+  if (input.service !== undefined) {
+    // 服务级：${provider}-${service}
+    return `${input.provider}-${input.service}`;
+  }
+  // 应用级：${provider}-global
+  return `${input.provider}-global`;
+}
+
+/** stem → ref（'secret://<stem>'） */
+export function stemToRef(stem: string): string {
+  return `secret://${stem}`;
+}
+
+/** stem → 凭据文件相对路径（'config/credentials/<stem>.json'） */
+export function stemToFilePath(stem: string): string {
+  return `config/credentials/${stem}.json`;
+}
+
+/** 读凭据文件（真值工件；缺席 → null） */
+export function readCredentialFile(appDir: string, stem: string): CredentialFile | null {
+  const file = join(appDir, stemToFilePath(stem));
+  if (!existsSync(file)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(file, 'utf8')) as { type?: string } & Record<string, unknown>;
+    if (typeof raw.type !== 'string') return null;
+    const { type, ...rest } = raw;
+    const values: Record<string, string> = {};
+    for (const [k, v] of Object.entries(rest)) {
+      if (typeof v === 'string') values[k] = v;
+    }
+    return { type, values };
+  } catch {
+    return null;
+  }
+}
+
+/** 写凭据工件（真值；写前 ensureDir 物化父目录——credentials 目录首次写物化）。
+ *  返回 overwrote（同 stem 已在场 = 重写）。调用方负责先跑凭据校验链（type 匹配 + ajv 字段级）。 */
+export function writeCredentialFile(appDir: string, stem: string, file: CredentialFile): boolean {
+  const path = join(appDir, stemToFilePath(stem));
+  const overwrote = existsSync(path);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ type: file.type, ...file.values }, null, 2)}\n`, 'utf8');
+  return overwrote;
+}

package/src/core/credential-mask.ts

@@ -0,0 +1,19 @@
+/**
+ * 凭据掩码算法（GET 路径永无真值——CredentialEcho.masked 单源）。
+ * 独立小模块：integrations/credentials.ts（读端掩码）与测试共用，避免 credential-format
+ * 的写端 fs 依赖被读端连带拉起（views 层零 fs 依赖约束的前置拆分）。
+ */
+
+/** 掩码规则：每字段前 2 字符 + '****'；≤4 字符退化全 '****'；缺字段 → null。
+ *  序列化后零真值断言由测试 O4 钉死。 */
+export function maskCredentialValues(values: Record<string, string>): Record<string, string | null> {
+  const out: Record<string, string | null> = {};
+  for (const [k, v] of Object.entries(values)) {
+    if (typeof v !== 'string') {
+      out[k] = null;
+      continue;
+    }
+    out[k] = v.length <= 4 ? '****' : `${v.slice(0, 2)}****`;
+  }
+  return out;
+}

package/src/core/env-expansion.ts

@@ -0,0 +1,51 @@
+/**
+ * 配置 JSON 环境变量占位展开（纯数据形态——自 app-sdk env-expansion.ts 迁入改造）。
+ *
+ * 语法（与 SDK 版语义逐字一致，共享向量 test-fixtures/env-expansion-cases.json 防漂移）：
+ *   ${NAME}     占位引用；NAME 限定 [A-Z][A-Z0-9_]*（UPPER_SNAKE，最小化与正文 `${...}` 误碰）
+ *   $${NAME}   转义为字面量 ${NAME}（原样保留一次 $）
+ *
+ * 语义（评审 N1 钉死，壳层各自包装 throw/report）：
+ *   - 单遍非递归：env 值内若含 `${OTHER}` 不被二次展开（注入防线）；String.replace 回调形态天然单遍。
+ *   - 值经 JSON 字符串转义注入；不做数值/布尔强制转换。
+ *   - **本版为纯数据返回形态** `{ text?: string; missing: string[] }`——缺变量不 throw，
+ *     由壳层（CLI doctor 壳 / app-sdk 桥 throw 壳 / 沙箱宿主）决定 fail-fast 还是降级：
+ *     SDK 桥壳 missing 非空即 throw（错误文案逐字等价 SDK 旧版）；CLI 壳同款。
+ *   - 无 ${ 的文本快速路径：text 原文返回，零替换零开销。
+ */
+
+/** 占位匹配：$ 或 $$ 后接 {[A-Z][A-Z0-9_]*}（$$ 形态同匹配，展开期判首字符去留） */
+const ENV_VAR_RE = /\$\$?\{([A-Z][A-Z0-9_]*)\}/g;
+
+/** JSON 字符串字面量转义（值 → 可直接置于 "..." 内的安全文本）——
+ * 基于 JSON.stringify 切片：引号/反斜杠/控制字符（\b/\n/\r/\t/\f）转义语义与 JSON 精确一致 */
+function jsonEscape(value: string): string {
+  return JSON.stringify(value).slice(1, -1);
+}
+
+export interface EnvExpansionResult {
+  /** 展开后文本；存在缺失变量时缺席（调用方按 missing 处理，正文不半展开） */
+  text?: string;
+  /** 缺失变量清单（不回显 env 值——机密不进日志） */
+  missing: string[];
+}
+
+/** 展开配置文本（纯数据）；缺失变量 → `{ missing }`（text 缺席），由壳层决定 throw/降级 */
+export function expandEnvVars(
+  text: string,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): EnvExpansionResult {
+  const missing: string[] = [];
+  // 单遍替换：回调返回值不回扫（非递归语义；$${} 转义在回调内消去一个 $）
+  const out = text.replace(ENV_VAR_RE, (raw, name: string) => {
+    if (raw.startsWith('$$')) return raw.slice(1);
+    const v = env[name];
+    if (v === undefined) {
+      missing.push(name);
+      return raw; // 占位保留（纯数据形态：missing 上报，不 throw）
+    }
+    return jsonEscape(v);
+  });
+  if (missing.length > 0) return { missing };
+  return { text: out, missing: [] };
+}

package/src/core/errors.ts

@@ -0,0 +1,46 @@
+/**
+ * AppToolkitError（领域 6 码 + 壳层 2 码分界——toolkit 只产领域码）：
+ * VALIDATION_FAILED(400) / SERVICE_NOT_FOUND(404) / MODULE_NOT_FOUND(404) /
+ * PROVIDER_NOT_FOUND(404) / SUPPLY_NOT_FOUND(404) / CONTRACTS_NOT_RESOLVED(503)。
+ * AUTH_REQUIRED / ROUTE_NOT_FOUND 为 HTTP 层事实（壳层产生）——6 + 2 = 8（api.md §5）。
+ *
+ * **name 约定（仓规约束①——mangle 安全真源 process note 2026-09-11-publish-dist-minify）**：
+ * 构造器必须字符串字面量赋值 `this.name = 'AppToolkitError'`（禁 `this.name = X.name` binding
+ * 形态——src 态守卫不可见、mangle 后静默漂移）；守卫 = tests/error-name-safety.test.ts（C4）。
+ * 消费面属性分发（.httpStatus/.code/.fields——比 err.name 分发更宽裕）。
+ */
+
+export type AppToolkitErrorCode =
+  | 'VALIDATION_FAILED'
+  | 'SERVICE_NOT_FOUND'
+  | 'MODULE_NOT_FOUND'
+  | 'PROVIDER_NOT_FOUND'
+  | 'SUPPLY_NOT_FOUND'
+  | 'CONTRACTS_NOT_RESOLVED';
+
+export class AppToolkitError extends Error {
+  readonly code: AppToolkitErrorCode;
+  readonly httpStatus: number;
+  readonly fields?: string[];
+
+  constructor(code: AppToolkitErrorCode, httpStatus: number, message: string, fields?: string[]) {
+    super(message);
+    // 字面量赋值（禁 binding 形态——minify mangle 安全，README 打包纪律三件套）
+    this.name = 'AppToolkitError';
+    this.code = code;
+    this.httpStatus = httpStatus;
+    this.fields = fields;
+  }
+}
+
+/** CONTRACTS_NOT_RESOLVED 三分支 message（N1 构建指引——api.md 错误信封示例） */
+export function contractsNotResolvedMessage(contracts: { version: string | null; strictValidation: boolean; notes: readonly string[] }): string {
+  if (contracts.version === null) {
+    return 'contracts 不可解析（未安装）——检查应用依赖安装后重试';
+  }
+  if (!contracts.strictValidation) {
+    return `contracts ${contracts.version} 无严格校验面（需 ≥0.9）——升级应用 @tbox.cn/app-contracts 依赖后可用`;
+  }
+  // 版本达标但解析态异常（notes 携带细分——导入拒绝/产物缺失）
+  return contracts.notes[0] ?? 'contracts workspace 源码态未构建——执行 pnpm --filter @tbox.cn/app-contracts build 后重试';
+}

package/src/core/file-cache.ts

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+
+/**
+ * 统一文件读原语：stat 指纹（mtimeMs+size）+ parse 产物缓存 + 写后失效协议（D26）。
+ *
+ * Freshness Contract 机制载体（README 单源引用）：
+ * - 外部写自愈：每笔读 stat 指纹比对——不命中即重读重 parse（外部写下一笔即见）；
+ * - read-your-writes：写核心成功后调用 invalidate（本实例即刻失效，不依赖 mtime 粒度——
+ *   同毫秒连写兜底，W1 钉死）；
+ * - 缓存对象 = 文件**内容/parse 产物**；目录枚举不经此原语（walkManifests 每次执行——零缓存约束）。
+ *
+ * parse 失败不缓存（下一笔重试——坏文件短暂窗口自愈）；read 前存在性由调用方判定或捕获。
+ */
+
+interface CacheEntry {
+  fingerprint: string;
+  value: unknown;
+}
+
+export interface FileCache {
+  /** 读文件并 parse（指纹命中返回缓存产物；miss 重读）。文件缺席 → undefined（不缓存缺席态） */
+  read<T>(absolutePath: string, parse: (raw: string) => T): T | undefined;
+  /** 写后失效协议：paths 缺省全失效；指定路径仅失效对应条目 */
+  invalidate(paths?: readonly string[]): void;
+  /** 测试观测：parse 执行计数（W6 缓存命中不重 parse 断言用） */
+  readonly parseCount: number;
+}
+
+export function createFileCache(): FileCache {
+  const cache = new Map<string, CacheEntry>();
+  let parseCount = 0;
+
+  function fingerprintOf(path: string): string | null {
+    if (!existsSync(path)) return null;
+    const st = statSync(path);
+    return `${st.mtimeMs}:${st.size}`;
+  }
+
+  return {
+    read<T>(absolutePath: string, parse: (raw: string) => T): T | undefined {
+      const fp = fingerprintOf(absolutePath);
+      if (fp === null) {
+        // 文件缺席：清除旧条目（删除自愈），缺席态不缓存
+        cache.delete(absolutePath);
+        return undefined;
+      }
+      const hit = cache.get(absolutePath);
+      if (hit && hit.fingerprint === fp) return hit.value as T;
+      parseCount += 1;
+      const value = parse(readFileSync(absolutePath, 'utf8'));
+      cache.set(absolutePath, { fingerprint: fp, value });
+      return value;
+    },
+    invalidate(paths?: readonly string[]): void {
+      if (paths === undefined) {
+        cache.clear();
+        return;
+      }
+      for (const p of paths) cache.delete(p);
+    },
+    get parseCount(): number {
+      return parseCount;
+    },
+  };
+}

package/src/core/fskit.ts

@@ -0,0 +1,21 @@
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * 原子写原语（自 CLI dev.ts 私有 writeAtomic 提升为导出——CLI/写核心/凭据工件三消费方单源）。
+ * temp+rename：rename 在同文件系统内原子；半写状态只会停留在 tmp（孤儿 tmp 无害）。
+ * 写前 ensureDir（递归 mkdir -p）——credentials 等目录首次写物化（H5）。
+ */
+
+/** 原子写文本文件：写前 ensureDir 父目录 + temp（pid+ts 后缀防碰撞）+ rename */
+export function writeAtomic(file: string, content: string): void {
+  ensureDir(dirname(file));
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, content, 'utf8');
+  renameSync(tmp, file);
+}
+
+/** 递归物化目录（mkdir -p 语义；已存在静默） */
+export function ensureDir(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+}