@logictan/dsh-config-manager 0.1.60

package/src/core/phase3-host.ts

@@ -0,0 +1,411 @@
+/**
+ * Phase 3 Host Recovery 集成助手。
+ *
+ * 职责（最小、保守）：
+ *  - 持有 JournalStore + 内存 SAFE MODE 标志（isBlocked 同步谓词，供 env-lock 注入）。
+ *  - `startup(lockState)`：启动时**只读**扫描 + 锁状态判定 → 设 SAFE MODE / RECOVERY_REQUIRED（durable）。
+ *    **不自动 recover stale lock**（Rev 3 P1-NEW-2）。
+ *  - 保守 reconcile hooks：任何无法证明的 step → needs-attention → SAFE MODE（绝不自动恢复/回滚）。
+ *
+ * 引擎级 WAL / 指纹（import/restore 逐 step 插桩）为 Phase 3 v1 之外（§33 不要临时扩大）——
+ * 本助手提供保守的「operation intent + crash 判定」基础，供宿主在各 destructive 入口包 Coordinator。
+ */
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import fssync from 'node:fs';
+import {
+  JournalStore, environmentFingerprint as computeFingerprint, SAFE_MODE_MARKER,
+  generateOperationId, createJournalEntry, transitionJournalState, isTerminalState,
+} from './journal.ts';
+import type { OperationJournal } from './journal.ts';
+import { inspectStartup, type ReconcileProbeHooks, type ReconcileEnv } from './reconcile.ts';
+import { OWNERSHIP_FILE, type LockState, type MutationLockContext } from '../utils/env-lock.ts';
+import { sha256Hex } from '../utils/hashing.ts';
+import type { JournalStepRecord } from './types.ts';
+
+/** 存在未收敛的 active transaction → 拒绝创建第二个（active≤1）。 */
+export class TransactionRecoveryRequiredError extends Error {
+  constructor(opId: string) {
+    super(`active transaction ${opId} 未收敛（待 recover / reconcile），拒绝创建新 transaction`)
+    this.name = 'TransactionRecoveryRequiredError'
+  }
+}
+
+/**
+ * Phase 4 生产 journal↔snapshot 绑定 API（deferred 模式）：
+ *  fn 收到此 ctx，在【首个 destructive side effect 前】：
+ *   - 用 plan 创建 op-bound snapshot（operationId/operationType/environmentFingerprint/ownerInstanceId）
+ *   - `bindSnapshot(id)`：journal 记录 snapshotId，CREATED→SNAPSHOT_CREATED
+ *   - 首个 mutation 前 `markApplying()`：SNAPSHOT_CREATED→APPLYING
+ *  保证「快照 durable+verified 且 journal 已知」先于任何写。显式 ctx，无 process-global reentrancy。
+ */
+export interface JournalRunContext {
+  operationId: string;
+  operationType: string;
+  environmentFingerprint: string;
+  ownerInstanceId: string;
+  /** 记录 journal.snapshotId 并推进 CREATED→SNAPSHOT_CREATED（或幂等）。 */
+  bindSnapshot: (snapshotId: string) => Promise<void>;
+  /** 首个 destructive side effect 前调用：SNAPSHOT_CREATED/CREATED→APPLYING。 */
+  markApplying: () => Promise<void>;
+  /** 逐计划项 WAL step 记录（P2-B，Phase 8）：文件类带 fp，非文件类 external=true。 */
+  recordStep: (step: JournalStepRecord) => Promise<void>;
+}
+
+/** 把环境锁分类映射到 startup 判定：ACQUIRED 视同 LOCKED（有活跃 owner），IO/PERMISSION 保守 LOCKED。 */
+export function mapLockStateForStartup(state: LockState): 'LOCKED' | 'STALE_LOCK_DETECTED' | 'UNKNOWN_STATE' | 'FREE' {
+  if (state === 'STALE_LOCK_DETECTED') return 'STALE_LOCK_DETECTED';
+  if (state === 'UNKNOWN_STATE') return 'UNKNOWN_STATE';
+  return 'LOCKED'; // ACQUIRED / LOCKED / LOCK_IO_ERROR / PERMISSION_ERROR → 保守 LOCKED
+}
+
+export interface Phase3RecoveryOptions {
+  dataDir: string;
+  packageVersion: string;
+  /** 覆盖环境指纹（测试） */
+  environmentFingerprint?: string;
+  /** 环境指纹持久化 token 目录（缺省 dataDir） */
+  fingerprintDataDir?: string;
+  /**
+   * Phase 4 F21/F11 生产正向校验：校验 journal 引用的 snapshot 是否「存在 + READY + verified +
+   * op/env/owner binding 匹配」。缺省 = 保守 false（无法证明存在 → 不强推回滚）。
+   * 宿主注入 FileSnapshotStore + verifySnapshot + manifest binding 校验实现。
+   */
+  snapshotExists?: (snapshotId: string | null, binding?: SnapshotBindingRef) => Promise<boolean>;
+}
+
+/** journal↔snapshot binding 引用（与 reconcile ReconcileProbeHooks.snapshotExists 的 binding 一致）。 */
+export interface SnapshotBindingRef {
+  operationId?: string;
+  ownerInstanceId?: string;
+  environmentFingerprint?: string;
+}
+
+export class Phase3Recovery {
+  readonly store: JournalStore;
+  readonly packageVersion: string;
+  private readonly dataDir: string;
+  private readonly fingerprintDataDir: string;
+  private environmentFingerprint: string;
+  private readonly snapshotExistsFn: Phase3RecoveryOptions['snapshotExists'];
+
+  /** 内存 SAFE MODE 标志（isBlocked 同步谓词用） */
+  safeModeActive = false;
+
+  constructor(opts: Phase3RecoveryOptions) {
+    this.dataDir = opts.dataDir;
+    this.fingerprintDataDir = opts.fingerprintDataDir ?? opts.dataDir;
+    this.store = new JournalStore({ transactionsDir: path.join(opts.dataDir, 'transactions') });
+    this.packageVersion = opts.packageVersion;
+    this.environmentFingerprint = opts.environmentFingerprint ?? 'unknown';
+    this.snapshotExistsFn = opts.snapshotExists;
+  }
+
+  /** 计算环境指纹（持久化 token；跨启动稳定）。在 startup 前调用一次。 */
+  async initFingerprint(): Promise<string> {
+    try {
+      await fs.mkdir(this.fingerprintDataDir, { recursive: true });
+      this.environmentFingerprint = await computeFingerprint(this.fingerprintDataDir);
+    } catch {
+      this.environmentFingerprint = 'unknown';
+    }
+    return this.environmentFingerprint;
+  }
+
+  /** isBlocked 同步谓词（供 withMutationLock / runWithMutationLock 注入；env-lock 只问 blocked?） */
+  isBlocked(): boolean {
+    return this.safeModeActive;
+  }
+
+  /** 刷新 SAFE MODE 标志（读 durable 标记） */
+  async refreshSafeMode(): Promise<void> {
+    this.safeModeActive = await this.store.readSafeMode().catch(() => false);
+  }
+
+  /** 同步探测 durable SAFE MODE 标记（宿主 apply() 同步阶段、scheduler.start() 前调用，保证先阻断）。 */
+  probeSafeModeSync(): boolean {
+    const p = path.join(this.dataDir, 'transactions', SAFE_MODE_MARKER);
+    try {
+      const text = fssync.existsSync(p) ? fssync.readFileSync(p, 'utf8') : '';
+      const blocked = /blocked|true/i.test(text);
+      this.safeModeActive = blocked;
+      return blocked;
+    } catch {
+      return false;
+    }
+  }
+
+  /** 保守 hooks：无法证明默认 needs-attention（绝不自动恢复/回滚）。snapshotExists 用宿主注入的正向校验（若提供）。 */
+  private conservativeHooks(): ReconcileProbeHooks {
+    const snapshotExists = this.snapshotExistsFn;
+    return {
+      // P2-B（Phase 8）：对带 afterFp/beforeFp 的本地文件 step 做真实磁盘指纹判定。
+      // 这使「可安全判定已应用」的整文件项在 crash 后判 recovered；无指纹项（external /
+      // before/after 均 null）→ unable（保守）。**不放松**「不可信/不可指纹 → needs-attention」边界。
+      verifyStepFingerprint: async (step) => {
+        if (step.external === true) return 'unable';
+        if (step.beforeFp === null && step.afterFp === null) return 'unable';
+        if (step.ref === '') return 'unable';
+        let data: Buffer;
+        try {
+          data = await fs.readFile(step.ref);
+        } catch {
+          // 目标不存在：若已记录 afterFp（期望存在）→ 未应用；否则无法判定。
+          return step.afterFp !== null && step.beforeFp === null ? 'before-match' : 'none';
+        }
+        const fp = sha256Hex(data);
+        if (step.afterFp !== null && fp === step.afterFp) return 'after-match';
+        if (step.beforeFp !== null && fp === step.beforeFp) return 'before-match';
+        return 'none';
+      },
+      probeExternal: async () => 'unknown',
+      snapshotExists: async (snapshotId, binding) => {
+        if (snapshotExists === undefined) return false; // 未注入 → 保守 false
+        return snapshotExists(snapshotId, binding);
+      },
+    };
+  }
+
+  /**
+   * 启动只读 reconcile：返回是否需 SAFE MODE / RECOVERY_REQUIRED，并写 durable 标记。
+   * @param lockState 宿主 EnvironmentLockManager 的 inspectLockState 结果（只分类，不自动 recover）
+   * @param expectedOwnershipInstanceId 若在显式 recovery 前已捕获 stale ownership 的 owner.instanceId，传入以做 P1-A binding 校验
+   */
+  async startup(lockState: LockState, expectedOwnershipInstanceId?: string | null): Promise<{ safeModeRequired: boolean; recoveryRequired: boolean }> {
+    const env: ReconcileEnv = {
+      environmentFingerprint: this.environmentFingerprint || 'unknown',
+      isLiveOwner: async () => false,
+      ...(expectedOwnershipInstanceId ? { expectedOwnershipInstanceId } : {}),
+    };
+    const insp = await inspectStartup(this.store, this.conservativeHooks(), env, {}, mapLockStateForStartup(lockState));
+    if (insp.safeModeRequired) this.safeModeActive = true;
+    return { safeModeRequired: insp.safeModeRequired, recoveryRequired: insp.recoveryRequired };
+  }
+
+  /** P1-A：读取 crashed stale ownership 的 owner.instanceId（environment.lock 的 owner 证据；不可用返回 null）。 */
+  async captureStaleOwnershipInstanceId(): Promise<string | null> {
+    try {
+      const p = path.join(this.dataDir, 'locks', OWNERSHIP_FILE);
+      const text = await fs.readFile(p, 'utf8');
+      const rec = JSON.parse(text) as { owner?: { instanceId?: unknown } };
+      return typeof rec?.owner?.instanceId === 'string' && rec.owner.instanceId !== ''
+        ? rec.owner.instanceId
+        : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** 用户确认恢复后清除 SAFE MODE（清空 durable 标记 + 内存标志） */
+  async clearSafeMode(): Promise<void> {
+    this.safeModeActive = false;
+    await this.store.writeSafeMode(false);
+  }
+
+  /** 保守 reconcile hooks（供启动 barrier / inspect 用） */
+  get recoveryHooks(): ReconcileProbeHooks { return this.conservativeHooks(); }
+  /** 环境指纹（供启动 barrier 用） */
+  get recoveryEnvFingerprint(): string { return this.environmentFingerprint || 'unknown'; }
+
+  /**
+   * 生产 journal 包装（关闭 P0-A）：在【已持 GLOBAL 锁】下，为该 destructive operation
+   * 创建 durable journal（CREATED → snapshot → APPLYING → 执行真实引擎 → COMMITTED → 规整）。
+   *
+   *  - active≤1（§14）：创建前扫描 active/；存在非 terminal 残留（非当前 live owner）→ 抛错阻断，不建第二个 journal。
+   *  - Journal→Lock 绑定（§15/P1-A）：ownerInstanceId = lockCtx.token.instanceId（= Phase 2 activeInstanceId，
+   *      acquisition-specific）；lockId = 同一 ownership epoch identity（ownerInstanceId）。recovery 时强制校验。
+   *  - 不 double-acquire（§6）：调用方（host gate）已持锁，本方法只负责 journal 生命周期，不 re-acquire、不 release（release 由 gate 负责）。
+   *  - 异常 → NEEDS_ATTENTION + durable SAFE MODE + rethrow（不破坏既有错误/响应流）。
+   *  - 返回 { operationId, result }。
+   *
+   *  Phase 4 snapshot 两种模式：
+   *   - `snapshotProvider`（pre-fn）：journal CREATED → 调用 provider 创建并 verify snapshot → 绑定 snapshotId
+   *     → SNAPSHOT_CREATED → APPLYING → fn（适合 provider 不依赖请求体 plan 的场景）。
+   *   - `deferredSnapshot`（推荐，F20 生产接线）：plan 只在 handler 解析请求体后可用，因此 journal 停留在 CREATED，
+   *     fn 收到 `ctx`（含 `bindSnapshot` / `markApplying`）。引擎在【首个 destructive side effect 前】用 plan 创建
+   *     op-bound snapshot → ctx.bindSnapshot(id)（CREATED→SNAPSHOT_CREATED，记录 snapshotId）→ 首个 mutation 前
+   *     ctx.markApplying()（SNAPSHOT_CREATED→APPLYING）。保证「快照 durable+verified 且 journal 已知」先于任何写。
+   */
+  async runJournaled<T>(opts: {
+    operationType: string;
+    lockCtx: MutationLockContext;
+    /** 可选：真实 pre-operation snapshot（回滚点），返回 snapshotId（pre-fn 模式）。 */
+    snapshotProvider?(): Promise<string | null>;
+    /** 可选：deferred 绑定模式——journal 停留 CREATED，fn 收到 ctx 自行 bindSnapshot/markApplying。 */
+    deferredSnapshot?: boolean;
+    fn: (ctx?: JournalRunContext) => Promise<T>;
+  }): Promise<{ operationId: string; result: T }> {
+    const { operationType, lockCtx, snapshotProvider, deferredSnapshot, fn } = opts;
+    const ownerInstanceId = (lockCtx?.token?.instanceId ?? 'unknown').toString();
+    // P1-A：ownership epoch identity = 真实 acquisition-specific ownerInstanceId（来自 lockCtx，
+    // 即 Phase 2 activeInstanceId；跨进程/跨持有不同）。不再用环境稳定合成串。
+    const ownershipIdentity = ownerInstanceId;
+
+    // active≤1：存在非 terminal 残留 → 阻断（不创建第二个 journal）
+    const activeIds = await this.store.scanActive();
+    for (const opId of activeIds) {
+      const j = await this.store.loadActive(opId);
+      if (j === null) continue;
+      const ts = ['COMMITTED', 'ROLLED_BACK', 'RECOVERED', 'NEEDS_ATTENTION'] as const;
+      if (!(ts as readonly string[]).includes(j.state)) {
+        throw new TransactionRecoveryRequiredError(opId);
+      }
+    }
+
+    const opId = generateOperationId();
+    const base = {
+      operationId: opId, ownerInstanceId, lockId: ownershipIdentity,
+      packageVersion: this.packageVersion, environmentFingerprint: this.environmentFingerprint || 'unknown',
+    };
+    await this.store.create(createJournalEntry(operationType, base, new Date().toISOString()));
+    let fnCompleted = false;
+    let terminalPersistAttempted = false;
+
+    // Phase 4 deferred 模式：把 journal 绑定 API 暴露给 fn（引擎在第一个 destructive side effect 前调用）。
+    // bindSnapshot：记录 snapshotId 并 CREATED→SNAPSHOT_CREATED；markApplying：SNAPSHOT_CREATED→APPLYING。
+    // 这些只在该 op 的同一 journal 上生效，杜绝 process-global reentrancy。
+    const journalCtx: JournalRunContext = {
+      operationId: opId,
+      operationType,
+      environmentFingerprint: this.environmentFingerprint || 'unknown',
+      ownerInstanceId,
+      bindSnapshot: async (snapshotId: string) => {
+        if (snapshotId === null || snapshotId === '') throw new Error('bindSnapshot: snapshotId 为空');
+        // Reviewer A P2①：持久化失败必须传播（fail-closed）——若 journal 无法 durable 绑定 SNAPSHOT_CREATED，
+        // 引擎的 await bindSnapshot 抛错 → fn 抛错 → runJournaled catch（NEEDS_ATTENTION），mutation 绝不在无绑定下继续。
+        await this.store.update(opId, (j) => {
+          let next = { ...j, snapshotId } as OperationJournal;
+          if (next.state === 'CREATED') next = transitionJournalState(next, 'SNAPSHOT_CREATED');
+          else if (next.state === 'SNAPSHOT_CREATED') { /* 幂等：已绑定 */ }
+          else if (next.state === 'APPLYING') { /* 允许：绑定已晚但幂等记录 */ }
+          else throw new Error(`bindSnapshot 非法 state: ${next.state}`);
+          return next;
+        });
+      },
+      markApplying: async () => {
+        // Reviewer A P2①：同 fail-closed——SNAPSHOT_CREATED→APPLYING 持久化失败须传播，不得在未 APPLYING durable 下 mutation。
+        await this.store.update(opId, (j) => {
+          let next = j;
+          if (next.state === 'SNAPSHOT_CREATED') next = transitionJournalState(next, 'APPLYING');
+          else if (next.state === 'CREATED') next = transitionJournalState(next, 'APPLYING');
+          return next;
+        });
+      },
+      // P2-B（Phase 8）：逐计划项 WAL step 记录（文件类带 fp；非文件类 external=true）。
+      // 与 bindSnapshot/markApplying 同一 fail-closed：持久化失败传播 → fn 抛错 → NEEDS_ATTENTION。
+      recordStep: async (rec) => {
+        const step: import('./journal.ts').JournalStep = {
+          adapter: rec.adapter,
+          ref: rec.ref,
+          kind: rec.kind,
+          external: rec.external === true,
+          beforeFp: rec.beforeFp ?? null,
+          afterFp: rec.afterFp ?? null,
+          status: rec.status ?? (rec.external === true ? 'attention' : 'planned'),
+          appliedAt: new Date().toISOString(),
+          message: rec.message ?? null,
+        };
+        await this.store.update(opId, (j) => {
+          const plannedSteps = j.plannedSteps.includes(rec.id)
+            ? j.plannedSteps
+            : [...j.plannedSteps, rec.id];
+          return { ...j, plannedSteps, steps: { ...j.steps, [rec.id]: step } };
+        });
+      },
+    };
+
+    try {
+      if (deferredSnapshot !== true && snapshotProvider !== undefined) {
+        const snapId = await snapshotProvider();
+        // P1-2 修复：snapshotProvider 返回 null 表示快照创建失败 → 显式 abort（不得在无快照下继续 mutation）
+        if (snapId === null) {
+          throw new Error(`snapshotProvider 返回 null（快照创建失败），abort operation ${operationType}`);
+        }
+        await journalCtx.bindSnapshot(snapId);
+      } else if (deferredSnapshot !== true) {
+        await this.store.update(opId, (j) => transitionJournalState(j, 'APPLYING'));
+      }
+      // deferred 模式：保持 CREATED，fn 自行 bindSnapshot + markApplying（首个 destructive side effect 前）
+      const result = await fn(journalCtx);
+      fnCompleted = true;
+      // 尾操作：从任意 pre-commit 状态推进到 COMMITTED（合法链 CREATED/SNAPSHOT_CREATED→APPLYING→VALIDATING→COMMITTED）
+      await this.store.update(opId, (j) => {
+        let next = j;
+        if (next.state === 'CREATED') next = transitionJournalState(next, 'APPLYING');
+        if (next.state === 'SNAPSHOT_CREATED') next = transitionJournalState(next, 'APPLYING');
+        if (next.state === 'APPLYING') next = transitionJournalState(next, 'VALIDATING');
+        next = transitionJournalState(next, 'COMMITTED');
+        return { ...next, commit: { at: new Date().toISOString(), validated: true, validationWarnings: [] } };
+      });
+      terminalPersistAttempted = true;
+      await this.store.moveToCompleted(opId).catch(() => undefined);
+      return { operationId: opId, result };
+    } catch (err) {
+      this.safeModeActive = true;
+      await this.store.writeSafeMode(true).catch(() => undefined);
+      if (fnCompleted && !terminalPersistAttempted) {
+        // 真实事务副作用已完成，但 terminal 持久化失败 → RECOVERY_REQUIRED（不伪造终态，保持非终态 journal）
+        // （此处保持 journal 非终态：apply 已成功、COMMITTED 未 durable —— 由下一轮显式 recovery 决定。
+        //   SAFE MODE 已设；不额外写 NEEDS_ATTENTION，避免把「无法 durable 记录 outcome」误报成「已分类 NEEDS_ATTENTION」。）
+      } else if (!fnCompleted) {
+        // fn / side effect 阶段失败：op 已开始但 outcome 不确定 → NEEDS_ATTENTION（durable 分类）
+        const j = await this.store.loadActive(opId);
+        if (j !== null && !isTerminalState(j.state)) {
+          await this.store.update(opId, (cur) => transitionJournalState(cur, 'NEEDS_ATTENTION')).catch(() => undefined);
+        }
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * 轻量 operation 包装（意图 journal，供外部/不可证明操作如 sync-push / reinstall 用）：
+   *   创建 CREATED → APPLYING（含 external intent step）→ 执行 → COMMITTED；异常 → NEEDS_ATTENTION + SAFE MODE。
+   */
+  async runExternalIntent<T>(opts: {
+    operationType: string;
+    lockCtx: MutationLockContext;
+    intent: { adapter: string; ref: string; kind: string };
+    fn: (ctx?: { operationId: string }) => Promise<T>;
+  }): Promise<{ operationId: string; result: T }> {
+    const { operationType, lockCtx, intent, fn } = opts;
+    const ownerInstanceId = (lockCtx?.token?.instanceId ?? 'unknown').toString();
+    // P1-A：ownership epoch identity = 真实 acquisition-specific ownerInstanceId（非环境稳定串）
+    const ownershipIdentity = ownerInstanceId;
+    const opId = generateOperationId();
+    const base = {
+      operationId: opId, ownerInstanceId, lockId: ownershipIdentity,
+      packageVersion: this.packageVersion, environmentFingerprint: this.environmentFingerprint || 'unknown',
+    };
+    await this.store.create(createJournalEntry(operationType, base, new Date().toISOString()));
+    try {
+      await this.store.update(opId, (j) => {
+        const extStep: import('./journal.ts').JournalStep = { adapter: intent.adapter, ref: intent.ref, kind: intent.kind, external: true, beforeFp: null, afterFp: null, status: 'planned', appliedAt: null };
+        const withStep = {
+          ...j, plannedSteps: ['ext'], steps: { ext: extStep },
+        };
+        return transitionJournalState(withStep, 'APPLYING');
+      });
+      // Phase 4 F29/F30：把 operationId 暴露给 fn，使调用方（如 CLI reinstall）能在首个 destructive
+      // side effect 前写 durably-bound recovery point（operationId + 环境/版本元数据）。
+      const result = await fn({ operationId: opId });
+      await this.store.update(opId, (j) => {
+        let next = j;
+        if (next.state === 'SNAPSHOT_CREATED') next = transitionJournalState(next, 'APPLYING');
+        if (next.state === 'APPLYING') next = transitionJournalState(next, 'VALIDATING');
+        next = transitionJournalState(next, 'COMMITTED');
+        return { ...next, commit: { at: new Date().toISOString(), validated: true, validationWarnings: [] } };
+      });
+      await this.store.moveToCompleted(opId).catch(() => undefined);
+      return { operationId: opId, result };
+    } catch (err) {
+      const j = await this.store.loadActive(opId);
+      if (j !== null && !isTerminalState(j.state)) {
+        await this.store.update(opId, (cur) => transitionJournalState(cur, 'NEEDS_ATTENTION')).catch(() => undefined);
+      }
+      this.safeModeActive = true;
+      await this.store.writeSafeMode(true).catch(() => undefined);
+      throw err;
+    }
+  }
+}

package/src/core/phase3-p1.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Phase 3 P1-A（ownership binding 强制校验）+ P1-B（startup recovery barrier）的 targeted tests。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fssync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { JournalStore, createJournalEntry, type OperationJournal } from './journal.ts';
+import { reconcileActive } from './reconcile.ts';
+import { StartupRecoveryController, classifyStartup } from './startup-barrier.ts';
+import { Phase3Recovery } from './phase3-host.ts';
+import type { ReconcileProbeHooks, ReconcileEnv } from './reconcile.ts';
+import type { JournalStore as JS } from './journal.ts';
+import fs from 'node:fs/promises';
+
+function tmp(t: test.TestContext): string {
+  const dir = fssync.mkdtempSync(path.join(os.tmpdir(), 'p1-'));
+  t.after(() => fssync.rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+function mkStore(dir: string): JS { return new JournalStore({ transactionsDir: path.join(dir, 'transactions') }); }
+
+function incompleteJournal(id: string, ownerInstanceId: string, lockId: string): OperationJournal {
+  const j = createJournalEntry('import-apply', { operationId: id, ownerInstanceId, lockId, packageVersion: '0.1.54', environmentFingerprint: 'fp' }, 'x');
+  j.state = 'APPLYING';
+  j.plannedSteps = ['s1'];
+  j.steps = { s1: { adapter: 'settings', ref: 'ns', kind: 'Update', external: false, beforeFp: 'b', afterFp: null, status: 'planned', appliedAt: null } };
+  return j;
+}
+
+const hooks: ReconcileProbeHooks = {
+  verifyStepFingerprint: async () => 'after-match',
+  probeExternal: async () => 'not-installed',
+  snapshotExists: async () => true,
+};
+function env(over: Partial<ReconcileEnv> = {}): ReconcileEnv {
+  return { environmentFingerprint: 'fp', isLiveOwner: async () => false, ...over };
+}
+
+// ---------- P1-A：ownership binding 强制校验 ----------
+
+test('P1-A Test A：journal.ownerInstanceId != stale ownership → needs-attention，不作 trusted 恢复', async (t) => {
+  const dir = tmp(t); const store = mkStore(dir); const id = '00000000-0000-4000-8000-00000000a001';
+  await store.create(incompleteJournal(id, 'owner-A', 'owner-A'));
+  const out = await reconcileActive(store, hooks, env({ expectedOwnershipInstanceId: 'owner-B' }));
+  assert.equal(out.decisions[0]!.kind, 'needs-attention');
+  assert.equal(out.safeModeRequired, true);
+  assert.ok(await store.loadActive(id) !== null, 'binding mismatch 不得规整/回滚');
+});
+
+test('P1-A Test B：journal.lockId != expected（伪造/跨 epoch）→ needs-attention', async (t) => {
+  const dir = tmp(t); const store = mkStore(dir); const id = '00000000-0000-4000-8000-00000000a002';
+  await store.create(incompleteJournal(id, 'owner-A', 'lock-forged')); // ownerInstanceId 对，lockId 伪装
+  const out = await reconcileActive(store, hooks, env({ expectedOwnershipInstanceId: 'owner-A' }));
+  assert.equal(out.decisions[0]!.kind, 'needs-attention', 'lockId 与 ownerInstanceId 不一致（epoch identity 不符）→ 拒绝');
+  assert.equal(out.safeModeRequired, true);
+});
+
+test('P1-A Test C：ownerInstanceId + lockId 都 match → 允许 reconcile（explicit recovery 可继续）', async (t) => {
+  const dir = tmp(t); const store = mkStore(dir); const id = '00000000-0000-4000-8000-00000000a003';
+  await store.create(incompleteJournal(id, 'owner-A', 'owner-A'));
+  const out = await reconcileActive(store, hooks, env({ expectedOwnershipInstanceId: 'owner-A' }));
+  // binding 通过 → 不被 binding 阻断（非 binding-mismatch needs-attention）；据步证据决定 recovered/noop/rollback-recommended
+  assert.ok(['recovered', 'noop', 'rollback-recommended', 'needs-attention'].includes(out.decisions[0]!.kind));
+  if (out.decisions[0]!.kind === 'needs-attention') {
+    assert.ok(!out.decisions[0]!.reason.includes('binding'), 'binding 匹配时不得因 binding mismatch 判 needs-attention');
+  }
+});
+
+test('P1-A Test D：新 recovery 锁 instanceId != 旧 journal instanceId 是预期（不算 mismatch）', async (t) => {
+  // classifyStartup(lockState='STALE') + expectedOwnership=旧 journal 的 instanceId；
+  // 即便当前 recovery 进程的锁 instanceId 是新值，只要 journal 匹配 crashed 旧 instanceId 即通过。
+  const dir = tmp(t); const store = mkStore(dir); const id = '00000000-0000-4000-8000-00000000a004';
+  await store.create(incompleteJournal(id, 'crashed-owner', 'crashed-owner'));
+  const cls = classifyStartup({ store, hooks, env: env({ expectedOwnershipInstanceId: 'crashed-owner' }), lockState: 'STALE_LOCK_DETECTED' });
+  const { state } = await cls.classify();
+  // crashed journal 与 stale 匹配 → 不因「recovery 锁是新 instance」而误 rejects；有 unresolved → RECOVERY_REQUIRED
+  // （binding OK，只是待用户显式 recovery）
+  assert.ok(state.kind === 'RECOVERY_REQUIRED' || state.kind === 'NEEDS_ATTENTION', `binding 通过但 unresolved，实际=${state.kind}`);
+});
+
+test('P1-A 跨 transaction mixup / forged ownership → 拒绝（不同 ownerInstanceId/lockId）', async (t) => {
+  const dir = tmp(t); const store = mkStore(dir); const id = '00000000-0000-4000-8000-00000000a005';
+  // 伪造 journal 指向「另一个 transaction B」的 owner
+  await store.create(incompleteJournal(id, 'owner-B', 'owner-B'));
+  const out = await reconcileActive(store, hooks, env({ expectedOwnershipInstanceId: 'owner-A' }));
+  assert.equal(out.decisions[0]!.kind, 'needs-attention', '跨 transaction 的 journal 不作 trusted 恢复');
+  assert.equal(out.safeModeRequired, true);
+});
+
+// ---------- P1-A 生产级：captureStaleOwnershipInstanceId 读取真实 environment.lock + classifyStartup binding ----------
+
+async function writeStaleOwnership(dataDir: string, instanceId: string): Promise<void> {
+  await fs.mkdir(path.join(dataDir, 'locks'), { recursive: true });
+  await fs.writeFile(path.join(dataDir, 'locks', 'environment.lock'), JSON.stringify({ schemaVersion: 1, owner: { instanceId }, acquiredAt: Date.now(), op: 'crashed', target: 'x', lockVersion: '0.1.54', journalId: null }));
+}
+
+test('P1-A 生产：stale ownership 捕获 + 匹配 journal → binding 通过（非 binding-mismatch needs-attention）', async (t) => {
+  const dir = tmp(t); const store = mkStore(dir); const id = '00000000-0000-4000-8000-00000000a006';
+  await writeStaleOwnership(dir, 'stale-owner');
+  await store.create(incompleteJournal(id, 'stale-owner', 'stale-owner'));
+  const recovery = new Phase3Recovery({ dataDir: dir, packageVersion: '0.1.54', environmentFingerprint: 'fp' });
+  const captured = await recovery.captureStaleOwnershipInstanceId();
+  assert.equal(captured, 'stale-owner', 'captureStaleOwnership 读到真实 environment.lock 的 owner.instanceId');
+  const cls = classifyStartup({ store, hooks, env: env({ expectedOwnershipInstanceId: captured! }), lockState: 'STALE_LOCK_DETECTED' });
+  const { state, safeModeRequired } = await cls.classify();
+  // binding 匹配 → 不被 binding 拒绝（RECOVERY_REQUIRED 是「待用户显式恢复」，非 binding-mismatch）
+  assert.ok(state.kind === 'RECOVERY_REQUIRED', `binding 通过 → RECOVERY_REQUIRED，实际=${state.kind}`);
+  void safeModeRequired;
+});
+
+test('P1-A 生产：stale ownerInstanceId mismatch → binding 拒绝（needs-attention）', async (t) => {
+  const dir = tmp(t); const store = mkStore(dir); const id = '00000000-0000-4000-8000-00000000a007';
+  await writeStaleOwnership(dir, 'stale-owner');
+  await store.create(incompleteJournal(id, 'other-owner', 'other-owner')); // journal 不属于该 stale ownership
+  const recovery = new Phase3Recovery({ dataDir: dir, packageVersion: '0.1.54', environmentFingerprint: 'fp' });
+  const captured = await recovery.captureStaleOwnershipInstanceId();
+  assert.equal(captured, 'stale-owner');
+  const cls = classifyStartup({ store, hooks, env: env({ expectedOwnershipInstanceId: captured! }), lockState: 'STALE_LOCK_DETECTED' });
+  const { state, safeModeRequired } = await cls.classify();
+  // binding 拒绝 → journal 不被 trusted（unresolved 残留）；STALE 下 classify 归为 RECOVERY_REQUIRED + SAFE MODE（不自动恢复/不 trusted）
+  assert.ok(state.kind === 'RECOVERY_REQUIRED' || state.kind === 'NEEDS_ATTENTION', `ownership mismatch → 非 trusted 恢复态，实际=${state.kind}`);
+  assert.equal(safeModeRequired, true, 'binding 拒绝 → SAFE MODE');
+  // 该 journal 确为 binding-mismatch 决策（非 trusted rollback/resume）
+  const out = await reconcileActive(store, hooks, env({ expectedOwnershipInstanceId: captured! }));
+  const dec = out.decisions.find((d) => d.operationId === id);
+  assert.equal(dec!.kind, 'needs-attention');
+  assert.ok(dec!.reason.includes('binding'), '拒绝原因为 ownership binding 不匹配');
+});
+
+// ---------- P1-B：startup recovery barrier ----------
+
+test('P1-B race：classify pending → schedulers 未启动；NORMAL → start 恰一次', async (t) => {
+  let startCount = 0;
+  let release: () => void = () => {};
+  const gate = new Promise<void>((r) => { release = r; });
+  let started = false;
+  const controller = new StartupRecoveryController({
+    async classify() {
+      await gate; // injectable barrier：挂起
+      return { state: { kind: 'NORMAL' }, safeModeRequired: false, recoveryRequired: false };
+    },
+  }, { start: () => { startCount++; } });
+  started = controller.startSchedulersIfAllowed();
+  assert.equal(started, false, 'classification 完成前调度器不得启动');
+  assert.equal(startCount, 0, '等待期间 start 计数=0');
+  release();
+  const st = await controller.run();
+  assert.equal(st.kind, 'NORMAL');
+  assert.equal(controller.startSchedulersIfAllowed(), true, 'NORMAL 下启动');
+  assert.equal(controller.startSchedulersIfAllowed(), false, '幂等：二次调用不重复启动');
+  assert.equal(startCount, 1, 'start 恰一次');
+});
+
+test('P1-B：RECOVERY_REQUIRED → schedulers 永不启动', async () => {
+  let startCount = 0;
+  const controller = new StartupRecoveryController({
+    async classify() { return { state: { kind: 'RECOVERY_REQUIRED', operationId: 'x' }, safeModeRequired: true, recoveryRequired: true }; },
+  }, { start: () => { startCount++; } });
+  const st = await controller.run();
+  assert.equal(st.kind, 'RECOVERY_REQUIRED');
+  assert.equal(controller.startSchedulersIfAllowed(), false);
+  assert.equal(startCount, 0);
+});
+
+test('P1-B：UNKNOWN_STATE → schedulers 永不启动', async () => {
+  let startCount = 0;
+  const controller = new StartupRecoveryController({
+    async classify() { return { state: { kind: 'UNKNOWN_STATE', reason: 'no identity' }, safeModeRequired: true, recoveryRequired: false }; },
+  }, { start: () => { startCount++; } });
+  await controller.run();
+  assert.equal(controller.startSchedulersIfAllowed(), false);
+  assert.equal(startCount, 0);
+});
+
+test('P1-B fail-closed：classify 抛错 → RECOVERY_REQUIRED，调度器不启动（不默认 NORMAL）', async () => {
+  let startCount = 0;
+  const controller = new StartupRecoveryController({
+    async classify() { throw new Error('inspect boom'); },
+  }, { start: () => { startCount++; } });
+  const st = await controller.run();
+  assert.equal(st.kind, 'RECOVERY_REQUIRED', 'inspect 抛错不得默认 NORMAL');
+  assert.equal(controller.startSchedulersIfAllowed(), false);
+  assert.equal(startCount, 0);
+});
+
+test('P1-B：已有 safe-mode marker → startup 观察 → 调度器不启动（destructive blocked）', async (t) => {
+  const dir = tmp(t); const store = mkStore(dir);
+  await store.writeSafeMode(true);
+  const cls = classifyStartup({ store, hooks, env: env(), lockState: 'FREE' });
+  const { state } = await cls.classify();
+  let startCount = 0;
+  const controller = new StartupRecoveryController(cls, { start: () => { startCount++; } });
+  await controller.run();
+  assert.equal(startCount, 0, 'safe-mode marker 已存在 → destructive scheduler 不启动');
+  void state;
+});
+
+test('P1-B：corrupt journal startup → 分类为 needs-attention/quarantine，调度器不启动', async (t) => {
+  const dir = tmp(t); const store = mkStore(dir);
+  await store.ensureDirs();
+  const badId = '00000000-0000-4000-8000-00000000f0a0';
+  await import('node:fs/promises').then((fs) => fs.writeFile(path.join(dir, 'transactions', 'active', `${badId}.json`), 'not-json'));
+  const cls = classifyStartup({ store, hooks, env: env(), lockState: 'FREE' });
+  const { state } = await cls.classify();
+  assert.ok(state.kind === 'NEEDS_ATTENTION' || state.kind === 'RECOVERY_REQUIRED', `corrupt → ${state.kind}`);
+  let startCount = 0;
+  const controller = new StartupRecoveryController(cls, { start: () => { startCount++; } });
+  await controller.run();
+  assert.equal(startCount, 0, 'corrupt journal 分类完成前调度器不得启动（不 race classification）');
+});