@logictan/dsh-config-manager 0.1.60

package/src/core/phase3-p2b-fingerprint.test.ts

@@ -0,0 +1,189 @@
+/**
+ * P2-B（Phase 8）：逐计划项 before/after 指纹 + reconcile 判精度测试。
+ *
+ * 验证：
+ *  - Phase3Recovery.recoveryHooks.verifyStepFingerprint 对本地文件 step 做真实磁盘指纹判定
+ *    （after-match / before-match / before-match(缺失) / none / unable）；
+ *  - runJournaled 的 journalCtx.recordStep 把文件/外部 step 持久化进 journal；
+ *  - reconcile：全部文件项 done + afterFp 可验 → recovered（降低「已应用误判 needs-attention」保守率）
+ *  - reconcile：任一外部/不可指纹 step → needs-attention（安全边界不放宽）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import fssync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { JournalStore, createJournalEntry, generateOperationId } from './journal.ts';
+import { Phase3Recovery } from './phase3-host.ts';
+import { reconcileActive } from './reconcile.ts';
+import type { ReconcileEnv } from './reconcile.ts';
+import { sha256Hex } from '../utils/hashing.ts';
+import type { MutationLockContext } from '../utils/env-lock.ts';
+
+function tmp(t: test.TestContext): string {
+  const dir = fssync.mkdtempSync(path.join(os.tmpdir(), 'p2bfp-'));
+  t.after(() => fssync.rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+function lk(instance = 'owner-p2b'): MutationLockContext {
+  return { token: { tokenId: 't', managerId: 'm', instanceId: instance, acquiredAt: Date.now() } };
+}
+
+async function makeRecovery(dir: string): Promise<Phase3Recovery> {
+  const r = new Phase3Recovery({ dataDir: dir, packageVersion: '0.1.54', environmentFingerprint: 'fp-p2b' });
+  await r.store.ensureDirs();
+  return r;
+}
+
+// ---------- 1. verifyStepFingerprint 指纹判定 ----------
+
+test('verifyStepFingerprint：本地文件 step 真实磁盘指纹判定', async (t) => {
+  const dir = tmp(t);
+  const recovery = await makeRecovery(dir);
+  const fx = path.join(dir, 'target.yaml');
+  await fssync.writeFileSync(fx, 'content-A');
+  const fpA = sha256Hex(Buffer.from('content-A'));
+  await fssync.writeFileSync(fx, 'content-B');
+  const fpB = sha256Hex(Buffer.from('content-B'));
+
+  const hooks = recovery.recoveryHooks;
+  const local = (ref: string, beforeFp: string | null, afterFp: string | null, status: import('./journal.ts').JournalStep['status'] = 'done') => ({
+    adapter: 'skills', ref, kind: 'Update', external: false, beforeFp, afterFp, status, appliedAt: null,
+  });
+
+  // after 匹配 → 已应用
+  assert.equal(await hooks.verifyStepFingerprint(local(fx, fpA, fpB)), 'after-match');
+  // 磁盘 == beforeFp 且无 afterFp → before-match（未应用）
+  assert.equal(await hooks.verifyStepFingerprint(local(fx, fpB, null)), 'before-match');
+  // 内容与 before/after 均不符 → none
+  assert.equal(await hooks.verifyStepFingerprint(local(fx, fpA, sha256Hex(Buffer.from('other')))), 'none');
+  // 文件缺失 + 仅有 afterFp（期望存在）→ 视作未应用
+  const missing = path.join(dir, 'nope.yaml');
+  assert.equal(await hooks.verifyStepFingerprint(local(missing, null, fpB)), 'before-match');
+  // 无指纹 → unable（不可判定）
+  assert.equal(await hooks.verifyStepFingerprint(local(fx, null, null)), 'unable');
+  // external step → unable（reconcile 走 probeExternal 保守）
+  assert.equal(await hooks.verifyStepFingerprint({ adapter: 'plugins', ref: 'plugin:@x', kind: 'Install', external: true, beforeFp: null, afterFp: null, status: 'planned', appliedAt: null }), 'unable');
+});
+
+// ---------- 2. recordStep 持久化 ----------
+
+test('runJournaled journalCtx.recordStep：文件/外部 step 落 journal', async (t) => {
+  const dir = tmp(t);
+  const recovery = await makeRecovery(dir);
+  const { operationId } = await recovery.runJournaled({
+    operationType: 'import-apply', lockCtx: lk(), deferredSnapshot: true,
+    fn: async (ctx) => {
+      await ctx?.recordStep({ id: 'skills:a.md', adapter: 'skills', kind: 'Update', ref: '/abs/skills/a.md', external: false, status: 'done', beforeFp: null, afterFp: 'fp-after' });
+      await ctx?.recordStep({ id: 'plugins:pkg', adapter: 'plugins', kind: 'Install', ref: '', external: true, status: 'attention' });
+      // issue #35：结论文案必须落盘——否则事后审计只能看到 status，无法区分
+      // 「安装失败」与「用户主动跳过」。
+      await ctx?.recordStep({
+        id: 'plugin:broken', adapter: 'plugins', kind: 'Install', ref: '', external: true,
+        status: 'attention', message: '插件安装失败：Failed to read patch file',
+      });
+      return 1;
+    },
+  });
+  const j = await recovery.store.load(operationId!);
+  assert.ok(j);
+  assert.equal(j!.steps['skills:a.md']?.afterFp, 'fp-after');
+  assert.equal(j!.steps['skills:a.md']?.external, false);
+  assert.equal(j!.steps['plugins:pkg']?.external, true);
+  assert.ok(j!.plannedSteps.includes('skills:a.md'));
+  assert.ok(j!.plannedSteps.includes('plugins:pkg'));
+  assert.equal(j!.steps['plugin:broken']?.status, 'attention');
+  assert.equal(j!.steps['plugin:broken']?.message, '插件安装失败：Failed to read patch file');
+});
+
+// ---------- 3. reconcile 集成 ----------
+
+/** 预置一个 APPLYING 的 active journal（模拟 crash 残留），带指定 steps。 */
+async function seedJournal(store: JournalStore, steps: import('./journal.ts').JournalStep[], opts: { state?: import('./journal.ts').JournalState; ownerInstanceId?: string } = {}): Promise<string> {
+  const opId = generateOperationId();
+  const owner = opts.ownerInstanceId ?? 'owner-p2b';
+  await store.create(createJournalEntry('import-apply',
+    { operationId: opId, ownerInstanceId: owner, lockId: owner, packageVersion: '0.1.54', environmentFingerprint: 'fp-p2b' },
+    new Date().toISOString()));
+  await store.update(opId, (j) => {
+    const ids = steps.map((_, i) => `s${i}`);
+    const stepsObj: Record<string, import('./journal.ts').JournalStep> = {};
+    ids.forEach((id, i) => { stepsObj[id] = steps[i]!; });
+    return { ...j, state: opts.state ?? 'APPLYING', plannedSteps: ids, steps: stepsObj };
+  });
+  return opId;
+}
+
+function env(): ReconcileEnv {
+  // 不传 expectedOwnershipInstanceId → 跳过 P1-A binding（本测试聚焦指纹行为）
+  return { environmentFingerprint: 'fp-p2b', isLiveOwner: async () => false };
+}
+
+test('reconcile：全部文件项 done + afterFp 可验 → recovered（降低误判 needs-attention）', async (t) => {
+  const dir = tmp(t);
+  const recovery = await makeRecovery(dir);
+  // 两个已应用文件（磁盘 == afterFp）
+  const f1 = path.join(dir, 'f1.yaml'); await fssync.writeFileSync(f1, 'one');
+  const f2 = path.join(dir, 'f2.md'); await fssync.writeFileSync(f2, 'two');
+  const step = (ref: string, afterFp: string): import('./journal.ts').JournalStep => ({
+    adapter: 'skills', ref, kind: 'Update', external: false,
+    beforeFp: null, afterFp, status: 'done', appliedAt: new Date().toISOString(),
+  });
+  const opId = await seedJournal(recovery.store, [
+    step(f1, sha256Hex(Buffer.from('one'))),
+    step(f2, sha256Hex(Buffer.from('two'))),
+  ]);
+  const out = await reconcileActive(recovery.store, recovery.recoveryHooks, env());
+  // 只处理该 journal
+  const dec = out.decisions.find((d) => d.operationId === opId);
+  assert.ok(dec, 'decision 存在');
+  assert.equal(dec!.kind, 'recovered', `全文件项可验应判 recovered，实际=${dec!.kind}`);
+  assert.equal(out.safeModeRequired, false);
+  // 已规整出 active
+  assert.ok(!(await recovery.store.scanActive()).includes(opId));
+});
+
+test('reconcile：任一外部/不可指纹 step → needs-attention（安全边界不放宽）', async (t) => {
+  const dir = tmp(t);
+  const recovery = await makeRecovery(dir);
+  const f1 = path.join(dir, 'f1.yaml'); await fssync.writeFileSync(f1, 'one');
+  const fileStep: import('./journal.ts').JournalStep = {
+    adapter: 'skills', ref: f1, kind: 'Update', external: false,
+    beforeFp: null, afterFp: sha256Hex(Buffer.from('one')), status: 'done', appliedAt: new Date().toISOString(),
+  };
+  const extStep: import('./journal.ts').JournalStep = {
+    adapter: 'plugins', ref: 'plugin:@x', kind: 'Install', external: true,
+    beforeFp: null, afterFp: null, status: 'attention', appliedAt: null,
+  };
+  const opId = await seedJournal(recovery.store, [fileStep, extStep]);
+  const out = await reconcileActive(recovery.store, recovery.recoveryHooks, env());
+  const dec = out.decisions.find((d) => d.operationId === opId);
+  assert.ok(dec, 'decision 存在');
+  assert.equal(dec!.kind, 'needs-attention', `外部步骤不得判 recovered（安全边界），实际=${dec!.kind}`);
+  assert.equal(out.safeModeRequired, true);
+});
+
+test('reconcile：部分文件项 applied（其余 planned 未应用）→ 不判 recovered（保守）', async (t) => {
+  const dir = tmp(t);
+  const recovery = await makeRecovery(dir);
+  const f1 = path.join(dir, 'f1.yaml'); await fssync.writeFileSync(f1, 'one');
+  // f2 未写（planned，beforeFp=null，afterFp=null → unable → 不可证 → needs-attention 保守）
+  const f2 = path.join(dir, 'f2.md');
+  const doneStep: import('./journal.ts').JournalStep = {
+    adapter: 'skills', ref: f1, kind: 'Update', external: false,
+    beforeFp: null, afterFp: sha256Hex(Buffer.from('one')), status: 'done', appliedAt: new Date().toISOString(),
+  };
+  const plannedStep: import('./journal.ts').JournalStep = {
+    adapter: 'skills', ref: f2, kind: 'Update', external: false,
+    beforeFp: null, afterFp: null, status: 'planned', appliedAt: null,
+  };
+  const opId = await seedJournal(recovery.store, [doneStep, plannedStep]);
+  const out = await reconcileActive(recovery.store, recovery.recoveryHooks, env());
+  const dec = out.decisions.find((d) => d.operationId === opId);
+  assert.ok(dec, 'decision 存在');
+  assert.notEqual(dec!.kind, 'recovered', '部分未应用（planned 不可证）不得判 recovered');
+  assert.equal(dec!.kind, 'needs-attention');
+});

package/src/core/phase3-prod-child.ts

@@ -0,0 +1,36 @@
+/**
+ * 生产路径 child crash harness：用真实 Phase3Recovery.runJournaled（生产接线所用的助手）
+ * 执行一个 operation；在 fn（真实 side effect 写磁盘）后、COMMITTED 前 SIGKILL。
+ * 用于 phase3-production-integration.test.ts 验证「真实操作 crash → 残留非终态 journal → 可 reconcile」。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Phase3Recovery } from './phase3-host.ts';
+
+const txDir = process.argv[2]!;
+const dataDir = path.dirname(txDir);
+const sideEffect = path.join(dataDir, 'side-effect.txt');
+const FP = 'fp-prod';
+
+async function main(): Promise<void> {
+  const recovery = new Phase3Recovery({ dataDir, packageVersion: '0.1.54', environmentFingerprint: FP });
+  await recovery.store.ensureDirs();
+  const lockCtx = { token: { tokenId: 't', managerId: 'm', instanceId: 'child-prod', acquiredAt: Date.now() } };
+  try {
+    await recovery.runJournaled({
+      operationType: 'import-apply',
+      lockCtx,
+      fn: async () => {
+        // 真实 side effect：写磁盘文件
+        await fs.writeFile(sideEffect, 'side-effect-content');
+        // side effect 已完成、step done 尚未落 journal 前 crash
+        process.kill(process.pid, 'SIGKILL');
+      },
+    });
+  } catch {
+    // 被杀不会到这；若执行完则正常退出（测试用 before-step 场景）
+  }
+  process.exit(0);
+}
+
+main().catch((err) => { process.stderr.write(String(err)); process.exit(2); });

package/src/core/phase3-production-integration.test.ts

@@ -0,0 +1,286 @@
+/**
+ * Phase 3 生产集成测试（P0-A 关闭验证）。
+ * 直接测生产路径助手 `Phase3Recovery.runJournaled` / `runExternalIntent`（Web gate / restore / model-tools 均经它）：
+ *  - 建 journal + Journal→Lock 绑定（ownerInstanceId/lockId）+ operationType + COMMITTED 规整
+ *  - active≤1：残留非终态 → TransactionRecoveryRequiredError，不建第二个 journal
+ *  - fn 异常 → NEEDS_ATTENTION + durable SAFE MODE
+ *  - COMMITTED 持久化失败 → 保持非终态 + SAFE MODE（RECOVERY_REQUIRED 语义，lock 层不发明终态）
+ *  - runExternalIntent 记录 external step
+ *  - 真实 child crash（runJournaled fn 中被 SIGKILL → 残留非终态 journal → reconcile 判定）
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import fssync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { JournalStore } from './journal.ts';
+import { Phase3Recovery, TransactionRecoveryRequiredError } from './phase3-host.ts';
+import { reconcileActive } from './reconcile.ts';
+import { createSnapshot, FileSnapshotStore, verifySnapshot } from './backup.ts';
+import type { Snapshot } from './types.ts';
+import { makeContext } from '../adapters/test-helpers.ts';
+import type { MutationLockContext } from '../utils/env-lock.ts';
+
+function tmp(t: test.TestContext): string {
+  const dir = fssync.mkdtempSync(path.join(os.tmpdir(), 'p3prod-'));
+  t.after(() => fssync.rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+const here = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url));
+
+function lk(instance = 'owner-prod'): MutationLockContext {
+  return { token: { tokenId: 't', managerId: 'm', instanceId: instance, acquiredAt: Date.now() } };
+}
+
+async function makeRecovery(dir: string): Promise<Phase3Recovery> {
+  const r = new Phase3Recovery({ dataDir: dir, packageVersion: '0.1.54', environmentFingerprint: 'fp-prod' });
+  await r.store.ensureDirs();
+  return r;
+}
+
+test('P0-A：runJournaled 建 journal（绑定 + operationType + COMMITTED 规整）', async (t) => {
+  const dir = tmp(t);
+  const recovery = await makeRecovery(dir);
+  const { operationId, result } = await recovery.runJournaled<number>({ operationType: 'import-apply', lockCtx: lk(), fn: async () => 42 });
+  assert.equal(result, 42);
+  const j = await recovery.store.load(operationId);
+  assert.ok(j);
+  assert.equal(j!.operationType, 'import-apply');
+  assert.equal(j!.ownerInstanceId, 'owner-prod'); // Journal→Lock 绑定（真实 lockCtx token instanceId）
+  assert.equal(j!.lockId, 'owner-prod'); // lockId = 同 ownership epoch identity（P1-A 真实捕获，非环境稳定串）
+  assert.equal(j!.state, 'COMMITTED');
+  assert.equal('journalId' in j, false, 'Journal→Lock 单向，不回写 environment.lock');
+  assert.deepEqual(await recovery.store.scanActive(), [], 'COMMITTED 后已规整到 completed');
+});
+
+test('P0-A：active≤1 → 残留非终态阻断第二 journal', async (t) => {
+  const dir = tmp(t);
+  const recovery = await makeRecovery(dir);
+  // 第一次 run 在 fn 中抛错 → journal 留 NEEDS_ATTENTION（terminal，非终态残留不阻塞）…
+  // 用手动预置一个「非终态」active journal（模拟未 reconcile 的 crash residue）
+  const { generateOperationId, createJournalEntry } = await import('./journal.ts');
+  const opId = generateOperationId();
+  await recovery.store.create(createJournalEntry('import-apply', { operationId: opId, ownerInstanceId: 'old', lockId: 'old', packageVersion: '0', environmentFingerprint: 'fp-prod' }, new Date().toISOString()));
+  await recovery.store.update(opId, (j) => ({ ...j, state: 'APPLYING' }));
+  // 第二次 run（新 transaction）→ 应被 active≤1 阻断
+  await assert.rejects(
+    () => recovery.runJournaled({ operationType: 'import-apply', lockCtx: lk(), fn: async () => 1 }),
+    TransactionRecoveryRequiredError,
+    '残留 active 应阻断新 transaction（active≤1）',
+  );
+  // 只有一个 journal
+  assert.equal((await recovery.store.scanActive()).length, 1);
+});
+
+test('P0-A：fn 异常 → NEEDS_ATTENTION + durable SAFE MODE + rethrow', async (t) => {
+  const dir = tmp(t);
+  const recovery = await makeRecovery(dir);
+  await assert.rejects(
+    () => recovery.runJournaled({ operationType: 'import-apply', lockCtx: lk(), fn: async () => { throw new Error('boom'); } }),
+    /boom/,
+  );
+  assert.equal(await recovery.store.readSafeMode(), true);
+  assert.equal(recovery.safeModeActive, true);
+  const ops = await recovery.store.scanActive();
+  // fn 异常后 journal 进入 NEEDS_ATTENTION（terminal）→ moveToCompleted 可规整，但 SAFE MODE 已 durable
+  assert.equal(await recovery.store.readSafeMode(), true);
+});
+
+test('P0-A：COMMITTED 持久化失败 → 保持非终态 + SAFE MODE（RECOVERY_REQUIRED，lock 不发明终态）', async (t) => {
+  const dir = tmp(t);
+  let failCommit = false;
+  const store = new JournalStore({
+    transactionsDir: path.join(dir, 'transactions'),
+    io: {
+      mkdir: async (d) => { await fs.mkdir(d, { recursive: true }); },
+      readFileText: async (p) => (await fs.readFile(p, 'utf8')).toString(),
+      writeAll: async (target, content) => {
+        // 注入：仅 COMMITTED 状态写失败（terminal 持久化失败用例）
+        if (failCommit && content.includes('"COMMITTED"')) throw new Error('injected commit write fail');
+        await fs.writeFile(target, content, { mode: 0o600 });
+      },
+      rename: async (a, b) => fs.rename(a, b),
+      readdirNames: async (d) => { try { return await fs.readdir(d); } catch { return []; } },
+      readdirEntries: async (d) => { try { return await fs.readdir(d, { withFileTypes: true }); } catch { return []; } },
+      lstat: async (p) => { try { return await fs.lstat(p); } catch { return null; } },
+      rm: async (p, o) => fs.rm(p, o as never),
+      exists: async (p) => { try { await fs.access(p); return true; } catch { return false; } },
+    },
+  });
+  const recovery = new Phase3Recovery({ dataDir: dir, packageVersion: '0.1.54', environmentFingerprint: 'fp-prod' });
+  (recovery as unknown as { store: JournalStore }).store = store;
+  failCommit = true;
+  // runJournaled 在 COMMITTED 阶段会多次 update；首个 update 失败 → rethrow，journal 留非终态（或缺失）
+  await assert.rejects(() => recovery.runJournaled({ operationType: 'import-apply', lockCtx: lk(), fn: async () => 1 }));
+  assert.equal(await store.readSafeMode().catch(() => true), true, 'SAFE MODE 已设置（lock 层不发明终态）');
+});
+
+test('P0-A：runExternalIntent 记录 external step + COMMITTED', async (t) => {
+  const dir = tmp(t);
+  const recovery = await makeRecovery(dir);
+  const { operationId, result } = await recovery.runExternalIntent({
+    operationType: 'sync-push', lockCtx: lk(), intent: { adapter: 'sync', ref: 'git', kind: 'Push' },
+    fn: async () => ({ ok: true }),
+  });
+  assert.equal((result as { ok: boolean }).ok, true);
+  const j = await recovery.store.load(operationId);
+  assert.ok(j);
+  assert.equal(j!.steps['ext']?.external, true);
+  assert.equal(j!.state, 'COMMITTED');
+  assert.deepEqual(await recovery.store.scanActive(), []);
+});
+
+// ---------- 真实 child crash：runJournaled fn 中被 SIGKILL → 残留非终态 journal → reconcile ----------
+test('P0-A：真实 child crash（fn 中 SIGKILL）→ 残留非终态 journal 可 reconcile（不自动恢复）', async (t) => {
+  const dir = tmp(t);
+  const txDir = path.join(dir, 'transactions');
+  const childPath = path.join(here, 'phase3-prod-child.ts');
+  await new Promise<void>((resolve) => {
+    const child = spawn(process.execPath, [childPath, txDir], { stdio: 'ignore' });
+    child.on('close', () => resolve()); // child 在 fn 中被 SIGKILL（crash）是目的；任何退出码都算已完成
+  });
+  // child 在 runJournaled 的 fn 中写 side effect 后 SIGKILL（finally 未执行）→ journal 残留非终态
+  const store = new JournalStore({ transactionsDir: txDir });
+  await store.ensureDirs();
+  const active = await store.scanActive();
+  assert.equal(active.length, 1, 'child crash 后应残留 1 个 active journal');
+  const j = await store.loadActive(active[0]!);
+  assert.ok(j);
+  assert.notEqual(['COMMITTED', 'ROLLED_BACK', 'RECOVERED', 'NEEDS_ATTENTION'].includes(j!.state), true, 'crash 后非终态');
+  // reconcile：fn 已执行 side effect（磁盘 afterFp）→ after-match → recovered；不自动恢复外部不适用
+  const out = await reconcileActive(store, {
+    verifyStepFingerprint: async () => 'after-match',
+    probeExternal: async () => 'not-installed',
+    snapshotExists: async () => false,
+  }, { environmentFingerprint: 'fp-prod', isLiveOwner: async () => false });
+  assert.ok(['recovered', 'noop', 'needs-attention', 'rollback-continue'].includes(out.decisions[0]!.kind));
+});
+
+// ---------- Phase 4：deferred snapshot 生产接线（F20）---------- 
+
+/** 模拟生产引擎：runJournaled({ deferredSnapshot:true }) 内，用 plan 创建 op-bound snapshot →
+ *  bindSnapshot（SNAPSHOT_CREATED）→ markApplying（APPLYING）→ 执行副作用。 */
+async function runDeferredApply(
+  dir: string,
+  opts: { operationType?: string; doBind?: boolean; doMark?: boolean; throwInApply?: boolean },
+): Promise<{ recovery: Phase3Recovery; operationId: string | null; thrown: unknown }> {
+  const { operationType = 'import-apply', doBind = true, doMark = true, throwInApply = false } = opts;
+  const recovery = new Phase3Recovery({ dataDir: dir, packageVersion: '0.1.54', environmentFingerprint: 'fp-prod' });
+  await recovery.store.ensureDirs();
+  const snapDir = path.join(dir, 'snapshots');
+  await fssync.mkdirSync(snapDir, { recursive: true });
+  const ctx = makeContext('win32', path.join(dir, 'home'), 'web');
+  ctx.settings.ns.set('general', { value: { theme: 'dark' }, revision: 1, secrets: [] });
+  await ctx.fs.writeFile('settings.yaml', Buffer.from('general:\n  theme: dark\n', 'utf8'));
+  const store = new FileSnapshotStore({ dir: snapDir });
+  const plan = { items: [{ id: 'settings:general', kind: 'Update' as const, adapter: 'settings' as const, description: 'u', severity: 'info' as const, target: { adapter: 'settings' as const, ref: 'general' } }], globalStrategy: 'replace' as const, pathMappings: [], missingSecrets: [], needsRestart: false, estimatedActions: {} as import('./types.ts').ImportPlan['estimatedActions'] };
+  try {
+    const { operationId } = await recovery.runJournaled({
+      operationType,
+      lockCtx: lk(),
+      deferredSnapshot: true,
+      fn: async (journalCtx) => {
+        const snapshot: Snapshot = await createSnapshot({
+          ctx,
+          plan,
+          sourceZip: 'x.zip',
+          store,
+          adapters: [],
+          operationId: journalCtx?.operationId,
+          operationType: journalCtx?.operationType,
+          environmentFingerprint: journalCtx?.environmentFingerprint,
+          ownerInstanceId: journalCtx?.ownerInstanceId,
+        });
+        if (doBind) await journalCtx?.bindSnapshot(snapshot.id);
+        if (doMark) await journalCtx?.markApplying();
+        if (throwInApply) throw new Error('injected apply failure');
+        return snapshot.id;
+      },
+    });
+    return { recovery, operationId, thrown: null };
+  } catch (err) {
+    // fn 抛错被 runJournaled 重新抛出；recovery 仍可用以读 journal 状态
+    return { recovery, operationId: null, thrown: err };
+  }
+}
+
+test('Phase4: deferredSnapshot 生产接线 → journal 记录 snapshotId + op-bound binding + COMMITTED', async (t) => {
+  const dir = tmp(t);
+  const { recovery, operationId } = await runDeferredApply(dir, {});
+  assert.ok(operationId);
+  const j = await recovery.store.load(operationId!);
+  assert.ok(j);
+  assert.ok(j!.snapshotId, 'journal 应记录 snapshotId（F20 生产接线）');
+  const snap = await new FileSnapshotStore({ dir: path.join(dir, 'snapshots') }).load(j!.snapshotId!);
+  assert.equal(snap.operationId, operationId, 'snapshot.operationId === journal.operationId');
+  assert.equal(snap.operationType, 'import-apply');
+  assert.equal(snap.environmentFingerprint, 'fp-prod');
+  assert.equal(snap.ownerInstanceId, 'owner-prod');
+  assert.equal(snap.readiness, 'READY', '部署快照应为 READY');
+  assert.equal(j!.state, 'COMMITTED');
+});
+
+test('Phase4: deferredSnapshot 未 bindSnapshot → journal 无 snapshotId（引擎未接线时保守）', async (t) => {
+  const dir = tmp(t);
+  const { recovery, operationId } = await runDeferredApply(dir, { doBind: false });
+  assert.ok(operationId);
+  const j = await recovery.store.load(operationId!);
+  assert.ok(j);
+  assert.equal(j!.snapshotId, null, '引擎未 bindSnapshot 时 journal.snapshotId 保持 null');
+  assert.equal(j!.state, 'COMMITTED');
+});
+
+test('Phase4: deferredSnapshot + fn 抛错（mutation 未完成）→ NEEDS_ATTENTION + SAFE MODE', async (t) => {
+  const dir = tmp(t);
+  const { recovery } = await runDeferredApply(dir, { throwInApply: true });
+  // fn 抛错 → runJournaled rethrow，返回无 operationId；扫描 active 定位 NEEDS_ATTENTION journal
+  const ids = await recovery.store.scanActive();
+  let j: import('./journal.ts').OperationJournal | null = null;
+  for (const id of ids) {
+    const x = await recovery.store.loadActive(id);
+    if (x) { j = x; break; }
+  }
+  assert.ok(j, 'journal 已创建（操作开始后才抛错）');
+  assert.equal(j!.state, 'NEEDS_ATTENTION');
+  assert.equal(await recovery.store.readSafeMode(), true);
+  assert.equal(recovery.safeModeActive, true);
+});
+
+// ---------- Phase 4：F21/F11 production snapshotExists 正向校验 ----------
+
+test('Phase4: snapshotExists 注入后正向校验（存在+READY+binding 匹配→true）', async (t) => {
+  const dir = tmp(t);
+  const snapDir = path.join(dir, 'snapshots');
+  await fssync.mkdirSync(snapDir, { recursive: true });
+  const ctx = makeContext('win32', path.join(dir, 'home'), 'web');
+  ctx.settings.ns.set('general', { value: { theme: 'dark' }, revision: 1, secrets: [] });
+  await ctx.fs.writeFile('settings.yaml', Buffer.from('general:\n  theme: dark\n', 'utf8'));
+  const store = new FileSnapshotStore({ dir: snapDir });
+  const plan = { items: [{ id: 'settings:general', kind: 'Update' as const, adapter: 'settings' as const, description: 'u', severity: 'info' as const, target: { adapter: 'settings' as const, ref: 'general' } }], globalStrategy: 'replace' as const, pathMappings: [], missingSecrets: [], needsRestart: false, estimatedActions: {} as import('./types.ts').ImportPlan['estimatedActions'] };
+  const snap = await createSnapshot({ ctx, plan, sourceZip: 'x', store, adapters: [], operationId: 'op-1', operationType: 'import-apply', environmentFingerprint: 'fp', ownerInstanceId: 'owner' });
+  // 未注入 → 保守 false
+  const noInj = new Phase3Recovery({ dataDir: path.join(dir, 'nohooks'), packageVersion: '0', environmentFingerprint: 'fp' });
+  await noInj.store.ensureDirs();
+  assert.equal(await noInj.recoveryHooks.snapshotExists(snap.id, { operationId: 'op-1' }), false, '未注入 snapshotExists → 保守 false');
+  // 注入后校验存在+就绪+binding
+  const inj = new Phase3Recovery({
+    dataDir: path.join(dir, 'hooks'), packageVersion: '0', environmentFingerprint: 'fp',
+    snapshotExists: async (id, binding) => {
+      if (id === null || id === '') return false;
+      const v = await verifySnapshot(snapDir, id);
+      if (!v.ok) return false;
+      const s = await store.load(id);
+      if (s.readiness !== 'READY') return false;
+      if (binding?.operationId !== undefined && s.operationId !== binding.operationId) return false;
+      return true;
+    },
+  });
+  await inj.store.ensureDirs();
+  assert.equal(await inj.recoveryHooks.snapshotExists(snap.id, { operationId: 'op-1' }), true, 'READY + binding 匹配 → true');
+  assert.equal(await inj.recoveryHooks.snapshotExists(snap.id, { operationId: 'WRONG' }), false, 'operationId 不匹配 → false（防伪造快照）');
+  assert.equal(await inj.recoveryHooks.snapshotExists('bad..id', {}), false, '非法 snapshotId → false');
+  assert.equal(await inj.recoveryHooks.snapshotExists(null, {}), false, 'null → false');
+});

package/src/core/phase4-crash-child.ts

@@ -0,0 +1,101 @@
+/**
+ * Phase 4 crash-injection child harness：用真实 Phase3Recovery.runJournaled({ deferredSnapshot:true })
+ * 执行一个 op-bound snapshot + mutation，随后在指定 crash point SIGKILL 自己。
+ *
+ * 用法（argv）：
+ *   argv[2] = workDir（写入 transactions/ 与 snapshots/ 的根）
+ *   argv[3] = crashPoint（C1..C10，见 phase4-crash-injection.test.ts）
+ *
+ * 每个 crash point 在流程的指定边界 SIGKILL，验证「journal 状态 + snapshot 是否存在」反映该点。
+ * 用真实磁盘 FileSnapshotStore（manifest + READY），非 throw 替代。
+ */
+import fs from 'node:fs/promises';
+import fssync from 'node:fs';
+import path from 'node:path';
+import { Phase3Recovery } from './phase3-host.ts';
+import { createSnapshot, FileSnapshotStore } from './backup.ts';
+
+const workDir = process.argv[2]!;
+const crashPoint = process.argv[3]!;
+const dataDir = path.join(workDir, 'data');
+const snapDir = path.join(dataDir, 'snapshots');
+const txDir = path.join(dataDir, 'transactions');
+const FP = 'fp-crash';
+const sideEffect = path.join(workDir, 'home', 'side-effect.txt');
+
+function die(): never { process.kill(process.pid, 'SIGKILL'); throw new Error('unreachable'); }
+
+async function main(): Promise<void> {
+  // 用真实磁盘 FileSnapshotStore（manifest+READY）与真实 plan
+  fssync.mkdirSync(dataDir, { recursive: true });
+  const recovery = new Phase3Recovery({ dataDir, packageVersion: '0.1.54', environmentFingerprint: FP });
+  await recovery.store.ensureDirs();
+  const store = new FileSnapshotStore({ dir: snapDir });
+  const lockCtx = { token: { tokenId: 't', managerId: 'm', instanceId: 'crash-child', acquiredAt: Date.now() } };
+
+  const plan = {
+    items: [{ id: 'settings:general', kind: 'Update' as const, adapter: 'settings' as const, description: 'u', severity: 'info' as const, target: { adapter: 'settings' as const, ref: 'general' } }],
+    globalStrategy: 'replace' as const, pathMappings: [], missingSecrets: [], needsRestart: false,
+    estimatedActions: {} as Record<string, number>,
+  };
+
+  // 构造内存 ctx：engineSnapshotEntry 需要 settings.describe；hostFile 备份需要 settings.yaml
+  // 这里不复用 makeContext（子进程需独立构造，无 import 依赖测试 helper）。
+  const ctx: any = {
+    homeDir: path.join(workDir, 'home'),
+    platform: 'win32',
+    arch: 'x64',
+    dshVersion: '0.1.54',
+    profile: 'web',
+    fs: {
+      readFile: async (p: string) => Buffer.from('settings.yaml-content', 'utf8'),
+    },
+    settings: {
+      describe: async (ref: string) => ({ value: { theme: 'dark' }, revision: 1, secrets: [] }),
+    },
+    credentials: { describe: async () => ({ configured: false }) },
+    plugins: { listInstalled: async () => [] },
+    workspace: { listRecords: async () => [] },
+    patchFile: { readPatchLines: async () => [] },
+    log: { warn: () => {} },
+  };
+
+  try {
+    await recovery.runJournaled({
+      operationType: 'import-apply',
+      lockCtx,
+      deferredSnapshot: true,
+      fn: async (journalCtx) => {
+        if (crashPoint === 'C1') die(); // after journal CREATED, before snapshot
+        const snap = await createSnapshot({
+          ctx, plan, sourceZip: 'crash.zip', store, adapters: [],
+          operationId: journalCtx?.operationId, operationType: journalCtx?.operationType,
+          environmentFingerprint: journalCtx?.environmentFingerprint, ownerInstanceId: journalCtx?.ownerInstanceId,
+        });
+        if (crashPoint === 'C2') die(); // during/after snapshot write, before bind
+        await journalCtx?.bindSnapshot(snap.id);
+        if (crashPoint === 'C3') die(); // after journal binding (SNAPSHOT_CREATED), before APPLYING
+        await journalCtx?.markApplying();
+        if (crashPoint === 'C4') die(); // after APPLYING, before mutation
+        // 真实 local file mutation
+        await fs.mkdir(path.dirname(sideEffect), { recursive: true });
+        await fs.writeFile(sideEffect, 'mutated');
+        if (crashPoint === 'C5') die(); // after first local file mutation
+        if (crashPoint === 'C6') die(); // mid-mutation
+        if (crashPoint === 'C7') die(); // after mutation, before COMMITTED
+        // 业务成功
+      },
+    });
+    if (crashPoint === 'C8' || crashPoint === 'C9' || crashPoint === 'C10') {
+      // 已到 COMMITTED（runJournaled 返回），C8=C9=C10 视为「COMMITTED 后不应 rollback」的探针
+      process.exit(0);
+    }
+    // 未指定 crash point → 正常完成不 kill
+    process.exit(0);
+  } catch {
+    // 被杀不会到这
+    process.exit(0);
+  }
+}
+
+main().catch(() => process.exit(2));