@sanqianx/project-knowledge 5.0.24 → 5.0.25

package/_site/_test/parallel-engine-advanced-eng007-reconcile-test.js

@@ -0,0 +1,231 @@
+'use strict';
+
+// P-ENGINE-REVIEW-R2 ENG-007 boundary re-check: what exactly does 启动对账 cover?
+//
+// Contract verified against the current docs and the real implementation
+// BEFORE this driver was written:
+//   * README.md (触发面): "消费 event-bridge journal 的 commit boundary 与关联
+//     会话事件 -> CommitReconciler 对账/认领" - the reconciliation source is the
+//     JOURNAL, not Git history.
+//   * README.md:119: "未启动服务时，Hook 已捕获的事件保留于 journal，服务消费后
+//     才生成分析任务" - retention/compensation scope is events the hook captured.
+//   * src/coordinator.js consumeJournal(): the only compensation path reads
+//     journal events from cursor+1; there is no git-log scan anywhere.
+//   * src/runtime/commit-reconciler.js:173: "failed SHA is never retried,
+//     scanned, or inferred from history."
+// => The startup reconciliation contract is JOURNAL RECOVERY. A commit whose
+//    hook never wrote a boundary event is outside that contract (uncovered
+//    boundary, honestly stated - not papered over as "compensated").
+//
+// This driver pins BOTH SHAs of the offline window and answers the Leader's
+// question directly:
+//   commit A - broken hook (no boundary event)  -> NOT found back by any Git
+//             reconcile (no such mechanism exists).
+//   commit B - working hook (boundary event)    -> compensated by the startup
+//             journal drain (the ONLY recovery path).
+//   Then, decisively: a REAL boundary event for A is delivered after the fact
+//   with the real bridge CLI. The event is consumed, but B's success moved
+//   lastAnalyzedCommit to shaB, so the already-analysed-ancestor guard skips A
+//   (A is B's parent in real Git history): A is skipped over by B even when
+//   its evidence is handed to the engine explicitly. A is not analysed, no run
+//   is created - the guarantee "已完成SHA不重跑" extends to ancestors of the
+//   analysed head.
+//
+// Not repeated here (already green in engine-final/eng007, untouched): the
+// duplicate-B replay and the restart-no-rerun saga.
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const {
+  makeLaneDir, buildFixtureRepo, installPostCommitHook, startBridge, startVector,
+  startEngine, waitUntil, git, gitRun, readJsonl, saveEvidence, isolatedEnv, BRIDGE_CLI,
+} = require('./helpers/parallel-engine-final-harness.js');
+const { createStandinAnalyzer } = require('./helpers/parallel-engine-final-standin-analyzer.js');
+
+const ARTIFACTS = process.env.PK_TEST_EVIDENCE_ROOT
+  ? path.join(process.env.PK_TEST_EVIDENCE_ROOT, 'eng007reconcile')
+  : path.resolve(__dirname, '../../qa-autopilot/artifacts/parallel-20261023/engine-review-r3/reruns/eng007reconcile');
+const PROJECT_ID = 'project-eng007r2';
+
+function findJournalFiles(root) {
+  const out = [];
+  const walk = dir => {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const absolute = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(absolute);
+      else if (entry.name === 'events.jsonl') out.push(absolute);
+    }
+  };
+  walk(root);
+  return out;
+}
+function boundaryEvents(...roots) {
+  const events = [];
+  for (const file of roots.flatMap(root => findJournalFiles(root))) {
+    for (const line of fs.readFileSync(file, 'utf8').split('\n').filter(Boolean)) {
+      const event = JSON.parse(line);
+      if (event.schema === 'git-commit-boundary/v1') events.push(event);
+    }
+  }
+  return events;
+}
+
+async function main() {
+  const lane = makeLaneDir('eng007r2');
+  const commands = [];
+  const evidence = {
+    caseId: 'ENG-007 (R2 boundary re-check: startup reconciliation contract scope, both SHAs)',
+    laneDir: lane,
+    contract: {
+      source: 'README.md 触发面 + README.md:119 + src/coordinator.js consumeJournal (journal events are the only compensation source; no git-log scan) + src/runtime/commit-reconciler.js:173 (failed SHA never retried/scanned/inferred from history)',
+      scope: 'startup reconciliation = JOURNAL RECOVERY only; commits whose hook never wrote a boundary event are NOT covered (uncovered boundary, by design and by docs)',
+    },
+    phases: {},
+    commands,
+  };
+
+  const fixture = buildFixtureRepo(lane, 'eng007r2', []);
+  const knowledgePath = path.join(lane, 'knowledge-eng007r2');
+  const storePath = path.join(knowledgePath, 'dev-conversations');
+  fs.mkdirSync(storePath, { recursive: true });
+  const home = path.join(lane, 'bridge-home');
+  const dataDir = path.join(lane, 'engine-data');
+  const vectorRoot = path.join(lane, 'vector-root');
+  const eventsFile = path.join(lane, 'analyzer-events.jsonl');
+
+  const bridge = startBridge(home);
+  let engine = null;
+  let vector = null;
+  const analyzer = createStandinAnalyzer({ eventsFile });
+  const invocationsFor = sha => readJsonl(eventsFile).filter(entry => entry.kind === 'start' && entry.commitSha === sha).length;
+
+  try {
+    const bridgeUrl = await bridge.listen();
+    vector = await startVector(vectorRoot);
+    const registered = await bridge.projectRegistry.addProject({ home, path: fixture.repoPath, store: storePath });
+    const { repoIdentity } = await bridge.resolveRepoContext(fixture.repoPath);
+
+    // Register the project (consumer off), then stop the engine - the offline window begins.
+    engine = await startEngine({ dataDir, bridgeUrl, vectorUrl: vector.url, analyzer, consume: false });
+    await engine.listen();
+    engine.runtime.store.addProject({
+      projectId: PROJECT_ID, repoPath: fixture.repoPath, knowledgePath,
+      trackingStartCommit: fixture.baseline, repoIdentity, journalId: registered.id, conversationBaselineCursor: 0,
+    });
+    await engine.close();
+    engine = null;
+    commands.push('engine lifecycle 0: project registered (consumer off), engine stopped - offline window begins');
+
+    // ----- commit A: BROKEN hook (engine down, no boundary event) -----
+    installPostCommitHook(fixture.repoPath, { home, mode: 'broken' });
+    fs.writeFileSync(path.join(fixture.repoPath, 'offline-a.txt'), `offline feature A\n${'a'.repeat(64)}\n`);
+    git(fixture.repoPath, ['add', '.']);
+    const commitA = gitRun(fixture.repoPath, ['commit', '-qm', 'offline feature A']);
+    assert.equal(commitA.code, 0, `Git must not be blocked by the failing hook (exit ${commitA.code})`);
+    const shaA = git(fixture.repoPath, ['rev-parse', 'HEAD']);
+    assert.match(commitA.stderr, /commit-boundary\.missing\.js/, 'the hook really failed');
+
+    // ----- commit B: WORKING hook (engine down, boundary event on disk) -----
+    installPostCommitHook(fixture.repoPath, { home, mode: 'ok' });
+    fs.writeFileSync(path.join(fixture.repoPath, 'offline-b.txt'), `offline feature B\n${'b'.repeat(64)}\n`);
+    git(fixture.repoPath, ['add', '.']);
+    const commitB = gitRun(fixture.repoPath, ['commit', '-qm', 'offline feature B']);
+    assert.equal(commitB.code, 0);
+    const shaB = git(fixture.repoPath, ['rev-parse', 'HEAD']);
+    const boundariesOffline = boundaryEvents(home, storePath);
+    assert.equal(boundariesOffline.filter(e => e.commitSha === shaB).length, 1, 'B wrote exactly one boundary event while the engine was down');
+    assert.equal(boundariesOffline.filter(e => e.commitSha === shaA).length, 0, 'A wrote no boundary event');
+
+    // A really is B's parent in real Git history (the "skipped over by B" precondition).
+    const aIsAncestorOfB = gitRun(fixture.repoPath, ['merge-base', '--is-ancestor', shaA, shaB]);
+    assert.equal(aIsAncestorOfB.code, 0, 'A must be an ancestor of B in the fixture history');
+
+    // ----- restart: startup drain compensates B only -----
+    engine = await startEngine({ dataDir, bridgeUrl, vectorUrl: vector.url, analyzer, consume: true });
+    await engine.listen();
+    const runB = await waitUntil(async () => {
+      const run = engine.runtime.store.listRuns(PROJECT_ID).find(r => r.commitSha === shaB);
+      return run && run.state === 'succeeded' ? run : null;
+    }, 60000, 'startup drain compensates B');
+    await new Promise(resolve => setTimeout(resolve, 2000)); // let the drain settle fully before judging A
+    const runsAfterStart = engine.runtime.store.listRuns(PROJECT_ID);
+    const ledgerA = path.join(dataDir, 'runtime', 'processed-commits', PROJECT_ID, `${shaA}.json`);
+    const ledgerB = path.join(dataDir, 'runtime', 'processed-commits', PROJECT_ID, `${shaB}.json`);
+    const lastAnalyzed = engine.runtime.store.getProject(PROJECT_ID)?.runtime?.lastAnalyzedCommit || null;
+    evidence.phases.offlineWindow = {
+      commitA: { sha: shaA, subject: 'offline feature A', hook: 'broken (missing CLI)', gitExit: commitA.code, boundaryEvents: 0 },
+      commitB: { sha: shaB, subject: 'offline feature B', hook: 'working (real bridge CLI)', gitExit: commitB.code, boundaryEvents: 1 },
+      aIsAncestorOfB: aIsAncestorOfB.code === 0,
+      startupCompensation: {
+        runForB: { runId: runB.runId, trigger: runB.trigger, state: runB.state, indexState: runB.indexState },
+        runsForA: runsAfterStart.filter(r => r.commitSha === shaA).length,
+        totalRuns: runsAfterStart.length,
+        analyzerInvocations: { forA: invocationsFor(shaA), forB: invocationsFor(shaB) },
+        ledgerAExists: fs.existsSync(ledgerA),
+        ledgerBStatus: fs.existsSync(ledgerB) ? JSON.parse(fs.readFileSync(ledgerB, 'utf8')).status : null,
+        lastAnalyzedCommit: lastAnalyzed,
+      },
+    };
+    assert.equal(runB.trigger, 'git-hook');
+    assert.equal(invocationsFor(shaB), 1, 'B compensated exactly once');
+    assert.equal(runsAfterStart.filter(r => r.commitSha === shaA).length, 0, 'A has no run: the startup drain found nothing for A (no boundary event, no Git-history scan)');
+    assert.equal(invocationsFor(shaA), 0, 'A was never analysed');
+    assert.equal(fs.existsSync(ledgerA), false, 'A is not in the processing ledger');
+    assert.equal(lastAnalyzed, shaB, 'B\'s success moved lastAnalyzedCommit to shaB');
+    commands.push(`restart -> drain compensated B (${shaB.slice(0, 8)}) only; A (${shaA.slice(0, 8)}) has no run/ledger/analysis`);
+
+    // ----- decisive check: hand A's boundary event to the engine AFTER the fact -----
+    const cursorBefore = engine.runtime.store.state.journalCursors[registered.id] || 0;
+    const replayA = spawnSync(process.execPath, [BRIDGE_CLI, '--home', home, '--cwd', fixture.repoPath, '--sha', shaA], {
+      cwd: fixture.repoPath, windowsHide: true, encoding: 'utf8', env: isolatedEnv(),
+    });
+    assert.equal(replayA.status, 0, `replaying A's boundary event failed: ${replayA.stderr}`);
+    await waitUntil(async () => (engine.runtime.store.state.journalCursors[registered.id] || 0) > cursorBefore, 20000, 'A\'s after-the-fact boundary event is consumed');
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    const runsAfterReplayA = engine.runtime.store.listRuns(PROJECT_ID);
+    evidence.phases.afterTheFactBoundaryForA = {
+      replay: { ok: JSON.parse(replayA.stdout).ok, commitSha: shaA },
+      journalCursorBefore: cursorBefore,
+      journalCursorAfter: engine.runtime.store.state.journalCursors[registered.id] || 0,
+      runsForA: runsAfterReplayA.filter(r => r.commitSha === shaA).length,
+      totalRuns: runsAfterReplayA.length,
+      analyzerInvocationsForA: invocationsFor(shaA),
+      ledgerAExists: fs.existsSync(ledgerA),
+      verdict: 'A\'s evidence IS consumed (cursor advanced, boundary projection written) but the already-analysed-ancestor guard (baseline=lastAnalyzedCommit=shaB) skips A: no run, no analysis. A is skipped over by B; it is not "found back" by any Git reconcile - and none exists in the engine.',
+    };
+    assert.equal(runsAfterReplayA.filter(r => r.commitSha === shaA).length, 0, 'even with its boundary event delivered after the fact, A must not be re-analysed (ancestor guard)');
+    assert.equal(invocationsFor(shaA), 0, 'the analyzer was never invoked for A');
+    assert.equal(runsAfterReplayA.length, 1, 'the run set stays at exactly B\'s run');
+    commands.push(`A's boundary event delivered after the fact -> consumed (cursor ${cursorBefore}->${evidence.phases.afterTheFactBoundaryForA.journalCursorAfter}), ancestor guard skipped A (no run, no analysis)`);
+
+    evidence.verdict = {
+      'question A是否被Git reconcile找回': 'NO - the engine has no Git-history reconciliation at all; the only compensation source is the bridge journal (README 触发面 + README:119, src/coordinator.js consumeJournal, src/runtime/commit-reconciler.js:173)',
+      'question A是否被B越过': 'YES - B\'s promotion moved lastAnalyzedCommit to shaB; even when A\'s boundary event was delivered after the fact with the real CLI, the already-analysed-ancestor guard skipped A (consumed, projected, never enqueued)',
+      'contract scope (honest)': '启动对账 = journal 恢复：只有成功写入 boundary 事件的提交会被补回。无 boundary 事件的提交（hook 故障）不在契约内，本 driver 将其作为未覆盖边界显式记录，不计入"已补偿"',
+      'expected1 Git不被Hook故障阻塞': 'PASS (commit A exit 0 with a failing hook; commit exists)',
+      'expected2 启动对账补漏': 'PASS within the journal-recovery contract (B compensated via startup drain; A uncovered by design - stated, not claimed)',
+      'expected3 已完成SHA不重跑': 'PASS (B analysed once; ledger + ancestor guards held; A skipped as analysed-ancestor)',
+      boundary: 'unchanged paths (duplicate-B replay, restart-no-rerun) stay covered by engine-final/eng007 first-round evidence; they were not re-run here',
+      analyzerStandin: 'deterministic stand-in - NO real model output covered; vector-hub real with deterministic test embeddings - paid embedding API NOT covered',
+    };
+    await engine.close();
+    await vector.close();
+    await bridge.close();
+    saveEvidence(ARTIFACTS, 'eng007-reconcile-evidence.json', evidence);
+    console.log('ENG-007 R2 reconcile re-check PASS');
+    process.exit(0);
+  } catch (error) {
+    evidence.verdict = { failed: String((error && error.stack) || error) };
+    try { await engine?.close(); } catch {}
+    try { await vector?.close(); } catch {}
+    try { await bridge.close(); } catch {}
+    saveEvidence(ARTIFACTS, 'eng007-reconcile-evidence.json', evidence);
+    console.error(`ENG-007 R2 reconcile re-check FAIL: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/_site/_test/parallel-engine-advanced-eng009-test.js

@@ -0,0 +1,208 @@
+'use strict';
+
+// P-ENG-ADVANCED ENG-009 晋升中断恢复 (promotion interruption recovery) acceptance driver.
+//
+// Case (qa-autopilot/config/test-cases.json ENG-009, P0):
+//   steps:    在许可的故障注入点中断测试writer，再重启。
+//   expected: 1) journal恢复一致。 2) 不留下半晋升的假成功。 3) pointer顺序正确。
+//
+// Layer A (server-level real crash): the vendored engine child is HARD-KILLED
+// (uncatchable SIGKILL on POSIX, TerminateProcess on Windows - no graceful
+// cleanup) while a real run is mid-analysis, then a second engine child starts
+// on the same data directory - exercising the real single-writer stale-lock
+// break, initialize() recoverAll(), run recovery (running -> queued/recovering),
+// and claim retry semantics.
+//
+// Layer B (fault-point crashes): the vendored KnowledgePromotionService's own
+// production `fault` constructor hook hard-exits a child process at three
+// permitted phases (journal-prepared / operation-applied:0 / promotion-verified,
+// journal already persisted as awaiting-state-advance), then a fresh process
+// runs the same recoverAll() the coordinator runs at every startup.
+//
+// Analyzer = declarative stand-in (NO real model output). Vector endpoint =
+// loopback double.
+
+const assert = require('node:assert/strict');
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const {
+  makeLaneDir, buildFixtureRepo, waitUntil, callJson, startVectorDouble,
+  startEngineChild, readEventsFile, writePlan, saveEvidence, isolatedEnv,
+} = require('./helpers/parallel-engine-advanced-harness.js');
+
+const ARTIFACTS = process.env.PK_TEST_EVIDENCE_ROOT
+  ? path.join(process.env.PK_TEST_EVIDENCE_ROOT, 'eng009')
+  : path.resolve(__dirname, '../../qa-autopilot/artifacts/parallel-20261023/engine-review-r3/reruns/eng009');
+const FAULT_WRITER = path.join(__dirname, 'helpers', 'parallel-engine-advanced-fault-writer.js');
+const PROJECT_ID = 'project-eng009';
+
+function runFaultWriter(mode, workDir) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(process.execPath, [FAULT_WRITER, mode, workDir], { windowsHide: true, env: isolatedEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+    let stderr = '';
+    proc.stderr.on('data', chunk => { stderr += chunk; });
+    proc.on('error', reject);
+    proc.on('close', code => resolve({ mode, code, stderr: stderr.slice(0, 500) }));
+  });
+}
+
+function hashFile(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex').slice(0, 16);
+}
+
+async function main() {
+  const lane = makeLaneDir('eng009');
+  const commands = [];
+  const evidence = { caseId: 'ENG-009', laneDir: lane, phases: {}, commands };
+
+  // ---------- Layer A: hard crash of a live engine child, then restart ----------
+  const fixture = buildFixtureRepo(lane, 'eng009', ['X']);
+  const knowledgePath = path.join(lane, 'knowledge-eng009');
+  fs.mkdirSync(knowledgePath, { recursive: true });
+  const planFile = path.join(lane, 'analyzer-plan.json');
+  const eventsFile = path.join(lane, 'analyzer-events.jsonl');
+  writePlan(planFile, { default: {}, rules: [{ projectId: PROJECT_ID, commitSha: fixture.shas.X, delayMs: 5000 }] });
+
+  const vector = await startVectorDouble();
+  const dataDir = path.join(lane, 'engine-data');
+  const engine1 = await startEngineChild({ label: 'eng009', dataDir, vectorUrl: vector.url, planFile, eventsFile });
+  commands.push('LayerA: POST /api/runs X (analyzer stall 5s)', 'LayerA: hard-kill engine child mid-analysis', 'LayerA: restart engine child on same dataDir');
+
+  try {
+    assert.equal((await callJson(engine1.base, '/api/projects', {
+      projectId: PROJECT_ID, name: 'eng009', repoPath: fixture.repoPath, knowledgePath, trackingStartCommit: fixture.baseline,
+    })).status, 200);
+    const runX = (await callJson(engine1.base, '/api/runs', { projectId: PROJECT_ID, commitSha: fixture.shas.X })).body.run;
+    await waitUntil(() => readEventsFile(eventsFile).some(e => e.kind === 'start' && e.commitSha === fixture.shas.X), 20000, 'analyzer started X');
+
+    const killCode = await engine1.killHard();
+    const stateRaw = JSON.parse(fs.readFileSync(path.join(dataDir, 'engine-state.json'), 'utf8'));
+    const crashedRun = stateRaw.runs.find(r => r.runId === runX.runId);
+    const lockFile = path.join(dataDir, 'engine-runtime.lock');
+    const lockOwner = JSON.parse(fs.readFileSync(lockFile, 'utf8'));
+    const promotionsDir = path.join(dataDir, 'runtime', 'promotions', PROJECT_ID);
+    evidence.phases.layerACrash = {
+      killExitCode: killCode,
+      killSignal: engine1.proc.signalCode,
+      killWasUncatchable: engine1.proc.signalCode === 'SIGKILL' || process.platform === 'win32',
+      runStateOnDiskAfterKill: { state: crashedRun.state, phase: crashedRun.phase },
+      lockOwnerPid: lockOwner.pid,
+      lockOwnerPidWasEngineChild: lockOwner.pid === engine1.proc.pid,
+      promotionJournalsOnDisk: fs.existsSync(promotionsDir) ? fs.readdirSync(promotionsDir) : [],
+      pointerAtCrash: stateRaw.projects.find(p => p.projectId === PROJECT_ID).runtime.lastAnalyzedCommit,
+    };
+    assert.equal(crashedRun.state, 'running', 'run was live when the writer was interrupted');
+    assert.equal(lockOwner.pid, engine1.proc.pid, 'single-writer lock belonged to the killed engine');
+    assert.equal(evidence.phases.layerACrash.pointerAtCrash, fixture.baseline, 'pointer untouched before durable promotion');
+
+    // Restart on the same dataDir: stale lock must break via dead owner pid.
+    const engine2 = await startEngineChild({ label: 'eng009-restart', dataDir, vectorUrl: vector.url, planFile, eventsFile });
+    try {
+      const recovered = await waitUntil(async () => {
+        const runs = (await callJson(engine2.base, `/api/runs?projectId=${PROJECT_ID}`)).body.runs;
+        return runs.length === 1 && runs[0].state === 'succeeded' ? runs[0] : null;
+      }, 45000, 'restarted engine completes the interrupted run');
+      const events = readEventsFile(eventsFile);
+      const starts = events.filter(e => e.kind === 'start' && e.commitSha === fixture.shas.X);
+      const runtime = (await callJson(engine2.base, `/api/snapshot?projectId=${PROJECT_ID}`)).body.projects.find(p => p.projectId === PROJECT_ID).runtime;
+      const knowledgeFiles = fs.readdirSync(path.join(knowledgePath, 'changes'));
+      const journalFiles = fs.readdirSync(promotionsDir);
+      const journal = JSON.parse(fs.readFileSync(path.join(promotionsDir, journalFiles[0]), 'utf8'));
+      evidence.phases.layerARecovery = {
+        runId: recovered.runId,
+        sameRunIdAsBeforeCrash: recovered.runId === runX.runId,
+        state: recovered.state,
+        promotedAt: recovered.promotedAt,
+        analyzerStartsForX: starts.length,
+        attemptEvidence: 'crash before durable state advance -> engine re-runs analysis (attempt 2) rather than faking success',
+        lastAnalyzedCommit: runtime.lastAnalyzedCommit,
+        knowledgeChangesFiles: knowledgeFiles,
+        journalPhase: journal.phase,
+        journalOperationsApplied: journal.operations.map(op => ({ path: op.path, applied: op.applied })),
+        lockFileRecreatedByRestart: JSON.parse(fs.readFileSync(lockFile, 'utf8')).pid === engine2.proc.pid,
+      };
+      assert.equal(recovered.runId, runX.runId, 'no duplicate run created by recovery');
+      assert.equal(starts.length, 2, 'analyzer ran once pre-crash and once after restart (no fake success)');
+      assert.equal(runtime.lastAnalyzedCommit, fixture.shas.X, 'pointer advanced exactly to X after recovery');
+      assert.deepEqual(knowledgeFiles, [`${fixture.shas.X.slice(0, 12)}.md`], 'exactly one promoted knowledge file');
+      assert.equal(journal.phase, 'completed', 'promotion journal reaches terminal completed phase');
+      assert.ok(journal.operations.every(op => op.applied), 'all journal operations applied');
+      await engine2.stop();
+    } catch (error) {
+      try { await engine2.stop(); } catch {}
+      throw error;
+    }
+
+    // ---------- Layer B: fault-point crashes through the promotion service's own hook ----------
+    const scenarios = [
+      { mode: 'crash-prepared', expect: 'rolled-back' },
+      { mode: 'crash-mid-apply', expect: 'rolled-back' },
+      { mode: 'crash-after-apply', expect: 'completed' },
+    ];
+    evidence.phases.layerB = {};
+    for (const scenario of scenarios) {
+      const workDir = path.join(lane, `fault-${scenario.mode}`);
+      const crash = await runFaultWriter(scenario.mode, workDir);
+      commands.push(`LayerB ${scenario.mode}: fault-writer exit ${crash.code}`);
+      assert.equal(crash.code, 137, `${scenario.mode} child hard-exited at the fault point (got ${crash.code}, stderr: ${crash.stderr})`);
+      const recover = await runFaultWriter('recover', workDir);
+      assert.equal(recover.code, 0, `${scenario.mode} recovery process succeeded (${recover.stderr})`);
+      const result = JSON.parse(fs.readFileSync(path.join(workDir, 'fault-result.json'), 'utf8'));
+      const readme = fs.readFileSync(path.join(workDir, 'knowledge', 'README.md'), 'utf8');
+      const changesDir = path.join(workDir, 'knowledge', 'changes');
+      const recoverAgain = await runFaultWriter('recover', workDir);
+      const againResult = JSON.parse(fs.readFileSync(path.join(workDir, 'fault-result.json'), 'utf8'));
+      evidence.phases.layerB[scenario.mode] = {
+        crashExitCode: crash.code,
+        recoverAll: result.recoverAll,
+        lastAnalyzedCommit: result.lastAnalyzedCommit,
+        activeClaimRunId: result.activeClaimRunId,
+        readmeStartsWith: readme.slice(0, 40),
+        changesFiles: result.changesFiles,
+        indexDirty: result.indexDirty,
+        indexGeneration: result.indexGeneration,
+        secondRecoverAll: againResult.recoverAll,
+      };
+      if (scenario.expect === 'rolled-back') {
+        assert.equal(result.recoverAll[0].phase, 'rolled-back', `${scenario.mode}: journal rolled back consistently`);
+        assert.ok(readme.startsWith('# eng009 fixture knowledge (original)'), `${scenario.mode}: knowledge restored - no half-promoted state`);
+        assert.deepEqual(result.changesFiles, [], `${scenario.mode}: created file removed by rollback`);
+        assert.equal(result.lastAnalyzedCommit, null, `${scenario.mode}: pointer NOT advanced`);
+        assert.equal(result.activeClaimRunId, 'run-11111111-2222-3333-4444-555555555555', `${scenario.mode}: claim retained for explicit retry, not silently faked`);
+      } else {
+        assert.equal(result.recoverAll[0].phase, 'completed', 'after-apply: journal completed forward');
+        assert.ok(readme.startsWith('# eng009 fixture knowledge (replaced)'), 'after-apply: both operations final');
+        assert.equal(result.changesFiles.length, 1, 'after-apply: created file present');
+        assert.equal(result.lastAnalyzedCommit, 'a'.repeat(40), 'after-apply: pointer advanced exactly once via recovery');
+        assert.equal(result.activeClaimRunId, null, 'after-apply: active claim cleared');
+        assert.equal(result.indexDirty, true, 'after-apply: index marked dirty for repair');
+        assert.equal(result.indexGeneration, 1, 'after-apply: index generation advanced once');
+      }
+      assert.ok(againResult.recoverAll.every(r => r.skipped === true || r.phase === 'rolled-back' || r.phase === 'completed'), 'second recovery is idempotent (skipped)');
+    }
+
+    evidence.verdict = {
+      'expected1 journal恢复一致(终端相位+二次恢复幂等)': 'PASS',
+      'expected2 不留下半晋升的假成功(mid-apply回滚/after-apply完整推进/崩溃后重分析而非假成功)': 'PASS',
+      'expected3 pointer顺序正确(仅经journal完成推进, 基线→X单一序列)': 'PASS',
+      injectionPoints: 'Layer A: real process hard-kill mid-analysis; Layer B: vendored KnowledgePromotionService production fault hook (journal-prepared / operation-applied:0 / promotion-verified)',
+      analyzerStandin: 'declarative stand-in - NO real model output covered',
+      vectorDouble: 'loopback HTTP double - vector-hub itself not covered',
+    };
+    await vector.close();
+    saveEvidence(ARTIFACTS, 'eng009-evidence.json', evidence);
+    console.log('ENG-009 PASS');
+    process.exitCode = 0;
+  } catch (error) {
+    evidence.verdict = { failed: String(error && error.stack || error) };
+    try { await engine1.stop(); } catch {}
+    try { await vector.close(); } catch {}
+    saveEvidence(ARTIFACTS, 'eng009-evidence.json', evidence);
+    console.error(`ENG-009 FAIL: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+main();

package/_site/_test/parallel-engine-advanced-eng010-test.js

@@ -0,0 +1,213 @@
+'use strict';
+
+// P-ENG-ADVANCED ENG-010 索引独立失败 (independent index failure) acceptance driver.
+//
+// Case (qa-autopilot/config/test-cases.json ENG-010, P1):
+//   steps:    Markdown晋升成功后令向量服务失败。
+//   expected: 1) 知识已更新/索引待修复分开。
+//             2) 不回滚Markdown、不重复付费分析。
+//
+// Real behavior under test: vendored knowledge-engine child process, real
+// promotion to the project knowledge tree on disk, then the vector endpoint
+// (loopback double scripted to HTTP 503 EMBEDDING_UNAVAILABLE) failing exactly
+// at index time. Verified via coordinator.index() semantics (src/coordinator.js):
+// promotedAt is persisted BEFORE index(); an index failure moves the run to
+// state 'index-pending' with error INDEX_FAILED “知识已更新，索引待修复。”
+// while the Markdown promotion stays on disk; retry()/restart re-enter
+// execute()'s promotedAt fast-path (line 219) which only re-indexes.
+//
+// Analyzer = declarative stand-in (NO real model output). Vector endpoint =
+// loopback double (vector-hub itself not covered).
+
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  makeLaneDir, buildFixtureRepo, waitUntil, callJson, startVectorDouble,
+  startEngineChild, readEventsFile, writePlan, saveEvidence,
+} = require('./helpers/parallel-engine-advanced-harness.js');
+
+const ARTIFACTS = process.env.PK_TEST_EVIDENCE_ROOT
+  ? path.join(process.env.PK_TEST_EVIDENCE_ROOT, 'eng010')
+  : path.resolve(__dirname, '../../qa-autopilot/artifacts/parallel-20261023/engine-review-r3/reruns/eng010');
+const PROJECT_ID = 'project-eng010';
+const VECTOR_FAILURE = { kind: 'fail', httpStatus: 503, code: 'EMBEDDING_UNAVAILABLE', message: 'embedding backend unavailable (scripted)' };
+
+function hashFile(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex').slice(0, 16);
+}
+
+function readRunFromDisk(dataDir, runId) {
+  const state = JSON.parse(fs.readFileSync(path.join(dataDir, 'engine-state.json'), 'utf8'));
+  return { state, run: state.runs.find(r => r.runId === runId) };
+}
+
+async function main() {
+  const lane = makeLaneDir('eng010');
+  const commands = [];
+  const evidence = { caseId: 'ENG-010', laneDir: lane, phases: {}, commands };
+  const fixture = buildFixtureRepo(lane, 'eng010', ['X', 'Y']);
+  const knowledgePath = path.join(lane, 'knowledge-eng010');
+  fs.mkdirSync(knowledgePath, { recursive: true });
+  const planFile = path.join(lane, 'analyzer-plan.json');
+  const eventsFile = path.join(lane, 'analyzer-events.jsonl');
+  writePlan(planFile, { default: { delayMs: 300 }, rules: [] });
+
+  const vector = await startVectorDouble();
+  vector.setMode(VECTOR_FAILURE);
+  const dataDir = path.join(lane, 'engine-data');
+  const engine1 = await startEngineChild({ label: 'eng010', dataDir, vectorUrl: vector.url, planFile, eventsFile });
+  commands.push('POST /api/runs X while vector double scripted 503 EMBEDDING_UNAVAILABLE', 'POST /api/runs/X retry after vector double restored', 'stop engine, re-fail vector, POST /api/runs Y -> index-pending', 'restart engine with vector restored (initialize() auto-retry)');
+
+  const changesDir = path.join(knowledgePath, 'changes');
+  const fileFor = sha => path.join(changesDir, `${sha.slice(0, 12)}.md`);
+  const startsFor = sha => readEventsFile(eventsFile).filter(e => e.kind === 'start' && e.commitSha === sha).length;
+  const runById = async (engine, runId) => (await callJson(engine.base, `/api/runs?projectId=${PROJECT_ID}`)).body.runs.find(r => r.runId === runId);
+  const runtimeOf = async engine => (await callJson(engine.base, `/api/snapshot?projectId=${PROJECT_ID}`)).body.projects.find(p => p.projectId === PROJECT_ID).runtime;
+
+  try {
+    assert.equal((await callJson(engine1.base, '/api/projects', {
+      projectId: PROJECT_ID, name: 'eng010', repoPath: fixture.repoPath, knowledgePath, trackingStartCommit: fixture.baseline,
+    })).status, 200);
+    const runX = (await callJson(engine1.base, '/api/runs', { projectId: PROJECT_ID, commitSha: fixture.shas.X })).body.run;
+
+    // --- Expected 1: 知识已更新 / 索引待修复 分开 ---
+    const stuck = await waitUntil(async () => {
+      const run = await runById(engine1, runX.runId);
+      return run?.state === 'index-pending' ? run : null;
+    }, 30000, 'run reaches index-pending (promotion done, index failed)');
+    const runtime1 = await runtimeOf(engine1);
+    const fileX = fileFor(fixture.shas.X);
+    const hashX = hashFile(fileX);
+    const diskX = readRunFromDisk(dataDir, runX.runId);
+    evidence.phases.indexFailure = {
+      run: { state: stuck.state, phase: stuck.phase, indexState: stuck.indexState, promotedAt: stuck.promotedAt, error: stuck.error },
+      runtime: { lastAnalyzedCommit: runtime1.lastAnalyzedCommit, indexDirty: runtime1.index.dirty, indexStatus: runtime1.index.status },
+      knowledgeFile: { path: path.basename(fileX), bytes: fs.statSync(fileX).size, hash: hashX },
+      analyzerStartsForX: startsFor(fixture.shas.X),
+      vectorSyncRequests: vector.requests.filter(r => r.url === '/api/sync').length,
+      diskIndexAttempts: diskX.run.indexAttempts,
+      diskState: diskX.run.state,
+    };
+    assert.equal(stuck.state, 'index-pending', 'index failure is a SEPARATE state, not failed');
+    assert.equal(stuck.phase, 'index-pending');
+    assert.equal(stuck.indexState, 'failed');
+    assert.ok(stuck.promotedAt, 'promotion timestamp recorded - knowledge IS updated');
+    assert.equal(stuck.error.code, 'INDEX_FAILED');
+    assert.equal(stuck.error.message, '知识已更新，索引待修复。');
+    assert.equal(stuck.error.retryable, true);
+    assert.equal(stuck.error.details.failureKind, 'HTTP_ERROR');
+    assert.equal(stuck.error.details.httpStatus, 503);
+    assert.equal(stuck.error.details.upstreamCode, 'EMBEDDING_UNAVAILABLE');
+    assert.equal(stuck.error.details.attempt, 1);
+    assert.equal(runtime1.lastAnalyzedCommit, fixture.shas.X, 'pointer advanced - Markdown promotion committed');
+    assert.equal(runtime1.index.dirty, true, 'runtime index marked dirty while knowledge is current');
+    assert.ok(fs.existsSync(fileX), 'promoted Markdown exists on disk');
+    assert.ok(fs.statSync(fileX).size > 0, 'promoted Markdown has real bytes');
+    assert.equal(startsFor(fixture.shas.X), 1, 'analyzer ran exactly once');
+    assert.equal(diskX.run.indexAttempts, 1, 'disk state records exactly one index attempt');
+
+    // --- Expected 2 (part 1): explicit retry repairs the index only ---
+    const promotedAtX = stuck.promotedAt;
+    vector.setMode({ kind: 'ok' });
+    const retried = await callJson(engine1.base, `/api/runs/${encodeURIComponent(runX.runId)}/retry`, {});
+    assert.equal(retried.status, 200, `retry failed: ${JSON.stringify(retried.body)}`);
+    const healed = await waitUntil(async () => {
+      const run = await runById(engine1, runX.runId);
+      return run?.state === 'succeeded' ? run : null;
+    }, 30000, 'retried run succeeds after vector restored');
+    const runtime2 = await runtimeOf(engine1);
+    const diskX2 = readRunFromDisk(dataDir, runX.runId);
+    evidence.phases.explicitRetry = {
+      run: { state: healed.state, phase: healed.phase, indexState: healed.indexState, promotedAt: healed.promotedAt, error: healed.error },
+      promotedAtUnchanged: healed.promotedAt === promotedAtX,
+      knowledgeFileHashAfterRetry: hashFile(fileX),
+      knowledgeFileHashBefore: hashX,
+      analyzerStartsForX: startsFor(fixture.shas.X),
+      diskIndexAttempts: diskX2.run.indexAttempts,
+      vectorSyncRequests: vector.requests.filter(r => r.url === '/api/sync').length,
+      runtime: { indexDirty: runtime2.index.dirty, indexStatus: runtime2.index.status },
+    };
+    assert.equal(healed.phase, 'ready');
+    assert.equal(healed.indexState, 'succeeded');
+    assert.equal(healed.error, null);
+    assert.equal(healed.promotedAt, promotedAtX, 'promotion timestamp untouched by index retry');
+    assert.equal(hashFile(fileX), hashX, 'Markdown bytes NOT rolled back or rewritten by index retry');
+    assert.equal(startsFor(fixture.shas.X), 1, 'no second analyzer run - no duplicate paid analysis');
+    assert.equal(diskX2.run.indexAttempts, 2, 'second index attempt recorded on disk');
+    assert.equal(vector.requests.filter(r => r.url === '/api/sync').length, 2, 'one failed + one successful sync request');
+    assert.equal(runtime2.index.dirty, false, 'index repaired: dirty cleared');
+    assert.equal(runtime2.index.status, 'ready');
+
+    // --- Expected 2 (part 2): restart auto-repairs index-pending without re-analysis ---
+    vector.setMode(VECTOR_FAILURE);
+    const runY = (await callJson(engine1.base, '/api/runs', { projectId: PROJECT_ID, commitSha: fixture.shas.Y })).body.run;
+    const stuckY = await waitUntil(async () => {
+      const run = await runById(engine1, runY.runId);
+      return run?.state === 'index-pending' ? run : null;
+    }, 30000, 'second run also reaches index-pending');
+    const promotedAtY = stuckY.promotedAt;
+    const fileY = fileFor(fixture.shas.Y);
+    const hashY = hashFile(fileY);
+    const startsYBeforeRestart = startsFor(fixture.shas.Y);
+    await engine1.stop();
+    const diskY = readRunFromDisk(dataDir, runY.runId);
+    evidence.phases.restartSetup = {
+      runY: { state: diskY.run.state, phase: diskY.run.phase, promotedAt: diskY.run.promotedAt, diskIndexAttempts: diskY.run.indexAttempts },
+      knowledgeFileY: { hash: hashY, analyzerStarts: startsYBeforeRestart },
+    };
+    assert.equal(diskY.run.state, 'index-pending', 'index-pending persisted across shutdown');
+
+    vector.setMode({ kind: 'ok' });
+    const engine2 = await startEngineChild({ label: 'eng010-restart', dataDir, vectorUrl: vector.url, planFile, eventsFile });
+    try {
+      const autoHealed = await waitUntil(async () => {
+        const run = await runById(engine2, runY.runId);
+        return run?.state === 'succeeded' ? run : null;
+      }, 45000, 'restart auto-retries index-pending run at initialize()');
+      const diskY2 = readRunFromDisk(dataDir, runY.runId);
+      const runtime3 = await runtimeOf(engine2);
+      evidence.phases.restartAutoRetry = {
+        runY: { state: autoHealed.state, phase: autoHealed.phase, indexState: autoHealed.indexState, promotedAt: autoHealed.promotedAt, error: autoHealed.error },
+        promotedAtUnchanged: autoHealed.promotedAt === promotedAtY,
+        knowledgeFileYHashAfterRestart: hashFile(fileY),
+        knowledgeFileYHashBefore: hashY,
+        analyzerStartsForYTotal: startsFor(fixture.shas.Y),
+        diskIndexAttempts: diskY2.run.indexAttempts,
+        runtime: { indexDirty: runtime3.index.dirty, indexStatus: runtime3.index.status },
+        syncsForY: vector.requests.filter(r => r.url === '/api/sync' && r.body.project === PROJECT_ID).length,
+      };
+      assert.equal(autoHealed.promotedAt, promotedAtY, 'restart did not re-promote');
+      assert.equal(hashFile(fileY), hashY, 'Markdown bytes unchanged across restart auto-repair');
+      assert.equal(startsFor(fixture.shas.Y), startsYBeforeRestart, 'restart auto-repair did NOT run the analyzer again');
+      assert.equal(diskY2.run.indexAttempts, 2, 'restart performed exactly one more index attempt');
+      assert.equal(runtime3.index.dirty, false, 'index clean after auto-repair');
+      await engine2.stop();
+    } catch (error) {
+      try { await engine2.stop(); } catch {}
+      throw error;
+    }
+
+    evidence.verdict = {
+      'expected1 知识已更新/索引待修复分开(index-pending独立状态+INDEX_FAILED可重试+指针已推进+dirty标记)': 'PASS',
+      'expected2 不回滚Markdown、不重复付费分析(字节hash不变/analyzer恰好1次/promotedAt不变/重试只补索引)': 'PASS',
+      extraRestartAutoRetry: 'PASS - initialize() automatically retries persisted index-pending without re-analysis',
+      analyzerStandin: 'declarative stand-in - NO real model output covered',
+      vectorDouble: 'loopback HTTP double scripted 503 EMBEDDING_UNAVAILABLE - vector-hub itself not covered',
+    };
+    await vector.close();
+    saveEvidence(ARTIFACTS, 'eng010-evidence.json', evidence);
+    console.log('ENG-010 PASS');
+    process.exitCode = 0;
+  } catch (error) {
+    evidence.verdict = { failed: String(error && error.stack || error) };
+    try { await engine1.stop(); } catch {}
+    try { await vector.close(); } catch {}
+    saveEvidence(ARTIFACTS, 'eng010-evidence.json', evidence);
+    console.error(`ENG-010 FAIL: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+main();