@sanqianx/project-knowledge 5.0.23 → 5.0.25

package/_site/_test/helpers/logging-ui-fixture.js

@@ -0,0 +1,131 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../../lib/storage-layout');
+const { SettingsStore } = require('../../lib/settings-store');
+const { ProjectRegistryStore } = require('../../lib/project-registry-store');
+const { ProjectStore } = require('../../lib/project-store');
+const { Logger } = require('../../lib/structured-logger');
+const { makeRepo } = require('../fixtures/make-git-repos');
+
+async function createLoggingUiFixture(options = {}) {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "pk-logging-ui-" + process.pid + "-"));
+  if (options.freshProduct) require('../../lib/product-data').initializeProductData(dataDir);
+  const knowledgeRoot = path.join(dataDir, "knowledge-root");
+  fs.mkdirSync(knowledgeRoot, { recursive: true });
+  const repo = makeRepo({ kind: "one-commit" });
+  const layout = new StorageLayout({ dataDir });
+  const settingsStore = new SettingsStore({ layout });
+  const registryStore = new ProjectRegistryStore({ layout });
+  const projectStore = new ProjectStore({ layout });
+  const projectId = "visual-project";
+  const knowledgePath = path.join(knowledgeRoot, projectId);
+  fs.mkdirSync(knowledgePath, { recursive: true });
+
+  await settingsStore.initialize({
+    knowledge: { rootPath: knowledgeRoot },
+    logging: {
+      levels: ["trace", "debug", "info", "warn", "error", "fatal"],
+      retentionDays: 365,
+      maxTotalSizeMB: 2048,
+    },
+  });
+  await registryStore.initialize();
+  await projectStore.create(projectId, {
+    displayName: "视觉检测知识库",
+    storageName: projectId,
+    repoPath: repo.path,
+    knowledgePath,
+  }, {
+    trackingStartCommit: repo.headCommit,
+    lastAnalyzedCommit: repo.headCommit,
+    hook: { managedVersion: 2, migrationVersion: 2, lastVerifiedAt: new Date().toISOString() },
+    index: { dirty: false, generation: 7 },
+  });
+  await registryStore.add(projectId, { displayName: "视觉检测知识库" });
+
+  const logger = new Logger({
+    layout,
+    settingsProvider: () => settingsStore.read().logging,
+  });
+  const total = Number(options.totalLogs || 64);
+  const levels = ["trace", "debug", "info", "warn", "error", "fatal"];
+  for (let index = 0; index < total; index += 1) {
+    const level = levels[index % levels.length];
+    const operationId = index < 4 ? "op-flow-visual" : "op-" + String(index).padStart(3, "0");
+    const input = {
+      component: index % 2 ? "commit-reconciler" : "knowledge-promotion",
+      projectId: index === 7 ? "deleted-project" : projectId,
+      projectDisplayName: index === 7 ? "已删除的旧项目" : "视觉检测知识库",
+      projectDeleted: index === 7,
+      operationId,
+      runId: "run-" + Math.floor(index / 4),
+      commitSha: repo.headCommit,
+      phase: ["scanning", "claim.created", "markdown.promoted", "index.applied"][index % 4],
+      attempt: index % 3,
+      durationMs: 17 + index * 13,
+      context: {
+        repoPath: index === 6 ? "C:\\Users\\Example User\\Documents\\very-long-workspace\\机器视觉项目\\source" : repo.path,
+        fixture: index === 5 ? "<img src=x onerror=window.__xss=1>" : "safe",
+      },
+    };
+    if (index === 3) {
+      const validationError = Object.assign(new Error("模型输出校验失败 <script>window.__xss=1</script>"), { code: "VALIDATION_FAILED" });
+      validationError.stack += "\n" + Array.from({ length: 24 }, (_, line) => "    at promotionStep" + line + " (C:\\Users\\Example User\\Documents\\very-long-workspace\\机器视觉项目\\promotion.js:" + (line + 10) + ":7)").join("\n");
+      input.error = validationError;
+    }
+    await logger.log(level, "fixture.phase." + index, index === 5 ? "<img src=x onerror=window.__xss=1>" : "诊断事件 " + index, input);
+  }
+  await logger.close();
+
+  if (Number(options.conversationTurns || 0) > 0) {
+    const { ConversationStore } = require('../../lib/conversation-store');
+    const conversationStore = new ConversationStore({ layout, projectStore });
+    const turnCount = Number(options.conversationTurns);
+    const repoIdentity = { repoId: 'visual-project-repo' };
+    const baseTime = new Date();
+    baseTime.setHours(9, 0, 0, 0);
+    const captured = [];
+    for (let index = 0; index < turnCount; index += 1) {
+      const turnId = `visual-turn-${index + 1}`;
+      const promptAt = new Date(baseTime.getTime() + index * 120000).toISOString();
+      const replyAt = new Date(baseTime.getTime() + index * 120000 + 30000).toISOString();
+      const longToken = index === 1 ? ` ${'D:\\deep-project\\'.repeat(40)}README.md` : '';
+      const prompt = `请检查第 ${index + 1} 个视觉工作流。${longToken}`;
+      const reply = `已完成第 ${index + 1} 个工作流的检查。${longToken}`;
+      const user = (await conversationStore.appendEvent(projectId, {
+        eventId: `visual-user-${index + 1}`, sequence: index * 2 + 1, source: 'codex', eventType: 'user_prompt', role: 'user', content: prompt,
+        sessionId: 'visual-session', turnId, repoIdentity, projectPath: repo.path, branch: 'main', headAtCapture: repo.headCommit,
+        capturedAt: promptAt, identityConfidence: 'high', captureStatus: 'captured',
+      })).event;
+      const assistant = (await conversationStore.appendEvent(projectId, {
+        eventId: `visual-assistant-${index + 1}`, sequence: index * 2 + 2, source: 'codex', eventType: 'assistant_response', role: 'assistant', content: reply,
+        sessionId: 'visual-session', turnId, repoIdentity, projectPath: repo.path, branch: 'main', headAtCapture: repo.headCommit,
+        capturedAt: replyAt, identityConfidence: 'high', captureStatus: 'captured',
+      })).event;
+      captured.push({ turnId, user, assistant });
+    }
+    const projectEvent = event => ({ eventId: event.eventId, sequence: event.sequence, content: event.content, contentHash: event.contentHash, capturedAt: event.capturedAt });
+    if (captured[0]) conversationStore.writeSnapshot(projectId, {
+      commitSha: '1'.repeat(40), repoIdentity, parentSha: null, boundaryStartCursor: 0, boundaryEndCursor: 2, status: 'available',
+      turns: [{ turnId: captured[0].turnId, source: 'codex', sessionId: 'visual-session', bindingKind: 'direct', userEvents: [projectEvent(captured[0].user)], assistantEvents: [projectEvent(captured[0].assistant)] }],
+    });
+    if (captured[1]) conversationStore.writeSnapshot(projectId, {
+      commitSha: '2'.repeat(40), repoIdentity, parentSha: '1'.repeat(40), boundaryStartCursor: 2, boundaryEndCursor: 4, status: 'available',
+      turns: [{ turnId: captured[1].turnId, source: 'codex', sessionId: 'visual-session', bindingKind: 'shared-spanning', userEvents: [projectEvent(captured[1].user)], assistantEvents: [projectEvent(captured[1].assistant)] }],
+    });
+  }
+
+  return {
+    dataDir,
+    layout,
+    projectId,
+    repo,
+    cleanup() {
+      try { repo.cleanup(); } catch {}
+      try { fs.rmSync(dataDir, { recursive: true, force: true }); } catch {}
+    },
+  };
+}
+
+module.exports = { createLoggingUiFixture };

package/_site/_test/helpers/module-fixture.js

@@ -0,0 +1,282 @@
+// _site/_test/helpers/module-fixture.js
+//
+// Test-only services for the product's module boundary.
+//
+// Three kinds of helper live here, and each one is a real HTTP service the
+// product talks to over the network:
+//
+//   createModuleFixture   a standalone module service (terminal / vector-hub
+//                         / event-bridge) that keeps the registration state
+//                         the product writes into it, can be switched offline
+//                         (503) and records every request it receives.
+//
+//   createUpstreamProxy    a pass-through proxy in front of a real upstream
+//                         (the vendored knowledge-engine module). It can hold
+//                         the upstream offline with 503, and it can rewrite
+//                         the runtime Authorization header so the product's
+//                         own per-instance token reaches an engine that was
+//                         started outside the product supervisor. Bodies and
+//                         responses are forwarded verbatim.
+//
+//   createProductProxy     a pass-through proxy in front of the product
+//                         server. It injects transport faults: a held
+//                         response (late read) or a failed response.
+//
+// The proxies never fabricate a module answer: everything they return comes
+// from the upstream service they front.
+
+'use strict';
+
+const http = require('node:http');
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', chunk => chunks.push(chunk));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+function sendJson(res, status, payload) {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+async function listen(server) {
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  return `http://127.0.0.1:${server.address().port}`;
+}
+
+/**
+ * A standalone module service. `kind` selects the contract subset the
+ * product's module bridge uses for that module.
+ */
+function createModuleFixture({ kind, tag = kind }) {
+  const state = { online: true, projects: [], requests: [] };
+  let nextId = 1;
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    const raw = await readBody(req);
+    let body = null;
+    if (raw.length) { try { body = JSON.parse(raw.toString('utf8')); } catch { body = null; } }
+    state.requests.push({ method: req.method, path: url.pathname + url.search, body, at: Date.now() });
+    if (!state.online) {
+      sendJson(res, 503, { ok: false, error: { code: 'MODULE_OFFLINE', message: `验收中的离线 ${kind} 模块` } });
+      return;
+    }
+    if (kind === 'terminal') {
+      if (req.method === 'GET' && url.pathname === '/api/claude-workbench/v1/projects') {
+        sendJson(res, 200, { projects: state.projects });
+        return;
+      }
+      if (req.method === 'POST' && url.pathname === '/api/claude-workbench/v1/projects') {
+        const id = `terminal-${nextId++}`;
+        state.projects.push({ id, name: body?.name || id, rootPath: body?.rootPath || '' });
+        sendJson(res, 201, { id, name: body?.name || id, rootPath: body?.rootPath || '' });
+        return;
+      }
+      if (req.method === 'DELETE' && url.pathname.startsWith('/api/claude-workbench/v1/projects/')) {
+        const id = decodeURIComponent(url.pathname.split('/').pop());
+        state.projects = state.projects.filter(project => project.id !== id);
+        res.writeHead(204); res.end();
+        return;
+      }
+    }
+    if (kind === 'vectorHub') {
+      if (req.method === 'GET' && url.pathname === '/api/projects') { sendJson(res, 200, { projects: state.projects }); return; }
+      if (req.method === 'POST' && url.pathname === '/api/import') {
+        state.projects.push({ name: body?.projectName || '', sourceDir: body?.sourceDir || '', hasIndex: true });
+        sendJson(res, 200, { ok: true, project: body?.projectName || '' });
+        return;
+      }
+      if (req.method === 'DELETE' && url.pathname === '/api/project') {
+        const name = url.searchParams.get('name');
+        state.projects = state.projects.filter(project => project.name !== name);
+        sendJson(res, 200, { ok: true });
+        return;
+      }
+    }
+    if (kind === 'eventBridge') {
+      if (req.method === 'GET' && url.pathname === '/api/projects') { sendJson(res, 200, { projects: state.projects }); return; }
+      if (req.method === 'POST' && url.pathname === '/api/projects') {
+        const id = `bridge-${nextId++}`;
+        state.projects.push({ id, path: body?.path || '', auto: false, store: body?.store || '' });
+        sendJson(res, 201, { project: { id, path: body?.path || '' } });
+        return;
+      }
+      if (req.method === 'DELETE' && url.pathname === '/api/projects') {
+        const id = url.searchParams.get('id');
+        state.projects = state.projects.filter(project => project.id !== id);
+        sendJson(res, 200, { ok: true });
+        return;
+      }
+    }
+    sendJson(res, 404, { ok: false, error: { code: 'NOT_FOUND', message: '未实现的模块接口' } });
+  });
+
+  return {
+    kind,
+    tag,
+    state,
+    url: null,
+    requests: state.requests,
+    async start() { this.url = await listen(server); return this.url; },
+    setOnline(online) { state.online = online; },
+    countRequests(method, pathPrefix) {
+      return state.requests.filter(entry => entry.method === method && (!pathPrefix || entry.path.startsWith(pathPrefix))).length;
+    },
+    async close() { server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); },
+  };
+}
+
+/**
+ * Pass-through proxy in front of a real upstream service.
+ *
+ * - `offline` short-circuits every request with 503 (the upstream is never
+ *   contacted), which is how the product observes an offline module.
+ * - `token` rewrites the Authorization header so the product's per-instance
+ *   runtime token is replaced by the token the upstream was started with.
+ *
+ * The proxy streams both directions, so a server-sent event stream that the
+ * browser opens against the product stays a real event stream.
+ */
+function createUpstreamProxy({ target, token, offline = false, tag = 'upstream' }) {
+  const state = { online: !offline, requests: [] };
+  const upstream = new URL(target);
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    const raw = await readBody(req);
+    let body = null;
+    if (raw.length) { try { body = JSON.parse(raw.toString('utf8')); } catch { body = null; } }
+    const entry = { method: req.method, path: url.pathname + url.search, body, at: Date.now(), status: null };
+    state.requests.push(entry);
+    if (!state.online) {
+      entry.status = 503;
+      sendJson(res, 503, { ok: false, error: { code: 'MODULE_OFFLINE', message: `验收中的离线 ${tag} 模块` } });
+      return;
+    }
+    const headers = { 'Content-Type': req.headers['content-type'] || 'application/json', 'Content-Length': String(raw.length) };
+    if (token) headers.Authorization = `Bearer ${token}`;
+    else if (req.headers.authorization) headers.Authorization = req.headers.authorization;
+    const upstreamRequest = http.request({
+      hostname: upstream.hostname,
+      port: upstream.port,
+      path: url.pathname + url.search,
+      method: req.method,
+      headers,
+    }, upstreamResponse => {
+      entry.status = upstreamResponse.statusCode;
+      res.writeHead(upstreamResponse.statusCode, upstreamResponse.headers);
+      upstreamResponse.pipe(res);
+    });
+    upstreamRequest.on('error', error => {
+      entry.status = 502;
+      if (!res.headersSent) sendJson(res, 502, { ok: false, error: { code: 'UPSTREAM_UNREACHABLE', message: String(error.message || error) } });
+      else res.destroy();
+    });
+    if (raw.length) upstreamRequest.write(raw);
+    upstreamRequest.end();
+  });
+
+  return {
+    tag,
+    state,
+    requests: state.requests,
+    url: null,
+    setOnline(online) { state.online = online; },
+    countRequests(method, pathPrefix) {
+      return state.requests.filter(entry => entry.method === method && (!pathPrefix || entry.path.startsWith(pathPrefix))).length;
+    },
+    async start() { this.url = await listen(server); return this.url; },
+    async close() { server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); },
+  };
+}
+
+/**
+ * Pass-through proxy in front of the product server that injects transport
+ * faults. `hold` keeps a matching response pending (a late read); `fail`
+ * answers a matching request with a transport error (a failed refresh).
+ */
+function createProductProxy({ target, tag = 'product' }) {
+  const state = { requests: [], held: [], faults: [] };
+  const upstream = new URL(target);
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    const raw = await readBody(req);
+    let body = null;
+    if (raw.length) { try { body = JSON.parse(raw.toString('utf8')); } catch { body = null; } }
+    const entry = { method: req.method, path: url.pathname + url.search, body, at: Date.now(), status: null };
+    state.requests.push(entry);
+
+    const fault = state.faults.find(item => !item.used && item.match(entry));
+    if (fault && fault.once) fault.used = true;
+    if (fault && fault.kind === 'fail') {
+      entry.status = fault.status;
+      sendJson(res, fault.status, { ok: false, error: { code: 'TRANSPORT_FAULT', message: fault.message || '注入的传输故障' } });
+      return;
+    }
+
+    const headers = { 'Content-Type': req.headers['content-type'] || 'application/json', 'Content-Length': String(raw.length) };
+    if (req.headers.authorization) headers.Authorization = req.headers.authorization;
+    const upstreamRequest = http.request({
+      hostname: upstream.hostname,
+      port: upstream.port,
+      path: url.pathname + url.search,
+      method: req.method,
+      headers,
+    }, upstreamResponse => {
+      entry.status = upstreamResponse.statusCode;
+      entry.respondedAt = Date.now();
+      if (fault && fault.kind === 'hold') {
+        const chunks = [];
+        upstreamResponse.on('data', chunk => chunks.push(chunk));
+        upstreamResponse.on('end', () => {
+          state.held.push({ response: res, entry, status: upstreamResponse.statusCode, headers: upstreamResponse.headers, payload: Buffer.concat(chunks) });
+        });
+        return;
+      }
+      res.writeHead(upstreamResponse.statusCode, upstreamResponse.headers);
+      upstreamResponse.pipe(res);
+    });
+    upstreamRequest.on('error', error => {
+      entry.status = 502;
+      if (!res.headersSent) sendJson(res, 502, { ok: false, error: { code: 'UPSTREAM_UNREACHABLE', message: String(error.message || error) } });
+      else res.destroy();
+    });
+    if (raw.length) upstreamRequest.write(raw);
+    upstreamRequest.end();
+  });
+
+  return {
+    tag,
+    state,
+    requests: state.requests,
+    url: null,
+    /** Hold the response of every request that matches the predicate. */
+    hold(match, { once = false } = {}) { state.faults.push({ kind: 'hold', match, once }); },
+    /** Fail every matching request at the transport level. */
+    fail(match, status = 503, message = '注入的传输故障', { once = false } = {}) { state.faults.push({ kind: 'fail', match, status, message, once }); },
+    clearFaults() { state.faults = []; },
+    heldCount() { return state.held.length; },
+    /** Deliver every held response to the browser that is still waiting. */
+    releaseHeld() {
+      const held = state.held.splice(0);
+      for (const item of held) {
+        try {
+          item.response.writeHead(item.status, item.headers);
+          item.response.end(item.payload);
+        } catch {}
+      }
+      return held.length;
+    },
+    async start() { this.url = await listen(server); return this.url; },
+    async close() { state.held.length = 0; server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); },
+  };
+}
+
+module.exports = { createModuleFixture, createUpstreamProxy, createProductProxy };

package/_site/_test/helpers/parallel-engine-advanced-engine-child.js

@@ -0,0 +1,45 @@
+'use strict';
+
+// P-ENG-ADVANCED engine child wrapper. Runs in its own process with a scrubbed,
+// isolated environment and starts the VENDORED knowledge-engine server module
+// (byte-identical to source e5573bb) in debug mode so the documented debug
+// fault-injection surface (POST /api/runs with simulateFailure) is available.
+// The analyzer is the lane's declarative stand-in - real staged bytes, no real
+// model output. Vendored engine code is never modified.
+
+const { createEngineServer } = require('../../../_modules/knowledge-engine/src/server.js');
+const { createStandinAnalyzer } = require('./parallel-engine-advanced-standin-analyzer.js');
+
+async function main() {
+  const dataDir = process.env.ENGADV_DATA_DIR;
+  const vectorUrl = process.env.ENGADV_VECTOR_URL || 'http://127.0.0.1:9';
+  const planFile = process.env.ENGADV_PLAN_FILE;
+  const eventsFile = process.env.ENGADV_EVENTS_FILE;
+  const concurrency = process.env.ENGADV_CONCURRENCY ? Number(process.env.ENGADV_CONCURRENCY) : undefined;
+  const analyzer = createStandinAnalyzer({ planFile, eventsFile });
+  const runtime = createEngineServer({
+    dataDir,
+    debug: true,
+    analyzer,
+    vectorUrl,
+    consume: false,
+    managed: false,
+    ...(concurrency !== undefined ? { concurrency } : {}),
+  });
+  await runtime.ready;
+  const { server } = runtime;
+  const stop = async () => {
+    try { await runtime.close(); process.exitCode = 0; } catch { process.exitCode = 1; }
+    if (process.connected) process.disconnect();
+  };
+  for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, stop);
+  process.on('message', message => { if (message?.type === 'kb:shutdown') stop(); });
+  server.listen(0, '127.0.0.1', () => {
+    process.stdout.write(`ENGADV-READY ${JSON.stringify({ base: `http://127.0.0.1:${server.address().port}`, pid: process.pid })}\n`);
+  });
+}
+
+main().catch(error => {
+  console.error(`[engadv-child] ${error.code || 'START_FAILED'}: ${error.message}`);
+  process.exit(1);
+});

package/_site/_test/helpers/parallel-engine-advanced-fault-writer.js

@@ -0,0 +1,171 @@
+'use strict';
+
+// P-ENG-ADVANCED ENG-009 fault-point writer/child.
+//
+// Exercises the VENDORED KnowledgePromotionService (byte-identical to source
+// e5573bb) using its production `fault` constructor hook - the class's own
+// sanctioned interruption point - to hard-exit the process at exact promotion
+// phases. A separate process then runs the same vendored service's
+// recoverAll(), which is exactly what EngineCoordinator.initialize() calls on
+// every startup. The analyzer here is the same declarative stand-in (no real
+// model output). The project state container is a real atomic JSON file with
+// the runtime shape the promotion service reads/writes.
+//
+// Usage: node parallel-engine-advanced-fault-writer.js <mode> <workDir>
+//   mode crash-prepared    - exit hard at fault point journal-prepared
+//   mode crash-mid-apply   - exit hard at fault point operation-applied:0
+//   mode crash-after-apply - exit hard at fault point promotion-verified
+//                             (journal already persisted as awaiting-state-advance)
+//   mode recover           - run recoverAll() and report recovery + final state
+//   mode complete          - control: full processClaim without injected crash
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { RuntimeLayout } = require('../../../_modules/knowledge-engine/src/runtime/layout.js');
+const { KnowledgePromotionService } = require('../../../_modules/knowledge-engine/src/runtime/knowledge-promotion.js');
+const AtomicFile = require('../../../_modules/knowledge-engine/src/runtime/atomic-file.js');
+
+const PROJECT_ID = 'project-eng009-fault';
+const COMMIT_SHA = 'a'.repeat(40); // fixture identity; not a real repo commit - promotion only needs claim identity + hashes
+const RUN_ID = 'run-11111111-2222-3333-4444-555555555555';
+const FINGERPRINT = `sha256:${'f'.repeat(64)}`;
+
+function hashBuffer(value) {
+  return `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
+}
+
+function workPaths(workDir) {
+  return {
+    dataDir: path.join(workDir, 'engine-data'),
+    knowledgePath: path.join(workDir, 'knowledge'),
+    stateFile: path.join(workDir, 'project-state.json'),
+    output: path.join(workDir, 'fault-result.json'),
+  };
+}
+
+function initialState() {
+  return {
+    lastAnalyzedCommit: null,
+    analysis: { status: 'idle', activeClaim: {
+      schema: 'commit-claim/v1', projectId: PROJECT_ID, commitSha: COMMIT_SHA, runId: RUN_ID,
+      fingerprint: FINGERPRINT, patchHash: `sha256:${'p'.repeat(64)}`, promptHash: `sha256:${'q'.repeat(64)}`,
+      evidenceHash: `sha256:${'e'.repeat(64)}`, evidenceManifestHash: `sha256:${'m'.repeat(64)}`,
+      retrievalManifestHash: `sha256:${'r'.repeat(64)}`, knowledgePath: null, phase: 'evidence.prepared', attempt: 1,
+    }, lastError: null },
+    index: { generation: 0, dirty: false, status: 'pending', sinceCommit: null, lastError: null },
+  };
+}
+
+function makeProjectStore(stateFile, knowledgePath) {
+  const read = () => AtomicFile.readJsonStrict(stateFile, { category: 'engadv-project-state', allowMissing: true, defaultValue: initialState() });
+  return {
+    readConfig: () => ({ projectId: PROJECT_ID, knowledgePath, repoPath: null, displayName: 'eng009-fault' }),
+    readState: () => read(),
+    updateState: async (id, fn) => {
+      const draft = read();
+      fn(draft);
+      AtomicFile.writeJsonAtomic(stateFile, draft);
+      return draft;
+    },
+  };
+}
+
+function standinAnalyzer({ knowledgePath }) {
+  return {
+    sourceReadMode: 'isolated-frozen-evidence',
+    async runClaim(input) {
+      const newReadme = `# eng009 fixture knowledge (replaced)\n\nPromoted for run ${input.claim.runId}.\n`;
+      const changeRel = `changes/${input.claim.runId.slice(4, 16)}.md`;
+      const changeContent = `# Change record eng009\n\nCommit ${input.claim.commitSha} via stand-in analyzer (no real model output).\n`;
+      AtomicFile.writeFileAtomic(path.join(input.stagingPath, 'files', 'README.md'), newReadme);
+      AtomicFile.writeFileAtomic(path.join(input.stagingPath, 'files', ...changeRel.split('/')), changeContent);
+      const refs = [
+        `commit:${input.claim.commitSha}`,
+        `patch:${input.claim.patchHash}`,
+        `conversation:${input.claim.conversationSnapshotHash}`,
+        `retrieval:${input.claim.retrievalManifestHash}`,
+      ];
+      AtomicFile.writeJsonAtomic(input.manifestPath, {
+        schema: 'knowledge-staging-manifest/v1',
+        projectId: input.projectId,
+        runId: input.claim.runId,
+        commitSha: input.claim.commitSha,
+        operations: [
+          { path: 'README.md', operation: 'replace', sha256: hashBuffer(newReadme), reason: 'Fixture replace for crash injection', evidenceReferences: refs },
+          { path: changeRel, operation: 'create', sha256: hashBuffer(changeContent), reason: 'Fixture create for crash injection', evidenceReferences: refs },
+        ],
+      });
+      return { ok: true };
+    },
+  };
+}
+
+async function main() {
+  const mode = process.argv[2];
+  const workDir = process.argv[3];
+  if (!mode || !workDir) throw new Error('usage: fault-writer <mode> <workDir>');
+  const { dataDir, knowledgePath, stateFile, output } = workPaths(workDir);
+  fs.mkdirSync(dataDir, { recursive: true });
+  fs.mkdirSync(knowledgePath, { recursive: true });
+  if (!fs.existsSync(stateFile)) AtomicFile.writeJsonAtomic(stateFile, initialState());
+  if (!fs.existsSync(path.join(knowledgePath, 'README.md'))) {
+    AtomicFile.writeFileAtomic(path.join(knowledgePath, 'README.md'), '# eng009 fixture knowledge (original)\n\nPre-crash content.\n');
+  }
+  const layout = new RuntimeLayout(dataDir);
+  const projectStore = makeProjectStore(stateFile, knowledgePath);
+  const claim = {
+    schema: 'commit-claim/v1', projectId: PROJECT_ID, commitSha: COMMIT_SHA, runId: RUN_ID, fingerprint: FINGERPRINT,
+    patchHash: `sha256:${'p'.repeat(64)}`, promptHash: `sha256:${'q'.repeat(64)}`,
+    conversationSnapshotHash: `sha256:${'c'.repeat(64)}`, retrievalManifestHash: `sha256:${'r'.repeat(64)}`,
+  };
+  const fault = phase => {
+    if (mode === 'crash-prepared' && phase === 'journal-prepared') {
+      process.exit(137);
+    }
+    if (mode === 'crash-mid-apply' && phase === 'operation-applied:0') {
+      process.exit(137);
+    }
+    if (mode === 'crash-after-apply' && phase === 'promotion-verified') {
+      process.exit(137);
+    }
+  };
+  const service = new KnowledgePromotionService({ layout, projectStore, analyzer: standinAnalyzer({ knowledgePath }), fault });
+  const config = projectStore.readConfig();
+
+  if (mode === 'recover') {
+    const results = await service.recoverAll();
+    const state = projectStore.readState();
+    const readmeHash = hashBuffer(fs.readFileSync(path.join(knowledgePath, 'README.md')));
+    const changesDir = path.join(knowledgePath, 'changes');
+    AtomicFile.writeJsonAtomic(output, {
+      mode,
+      recoverAll: results,
+      lastAnalyzedCommit: state.lastAnalyzedCommit,
+      activeClaimRunId: state.analysis.activeClaim?.runId || null,
+      indexDirty: state.index.dirty,
+      indexGeneration: state.index.generation,
+      readmeHash,
+      changesFiles: fs.existsSync(changesDir) ? fs.readdirSync(changesDir) : [],
+    });
+    process.stdout.write(`ENGADV-FAULT-RECOVER ${JSON.stringify(results)}\n`);
+    return;
+  }
+
+  const result = await service.processClaim({ projectId: PROJECT_ID, config, claim, operationId: 'engadv-fault-op' });
+  const state = projectStore.readState();
+  AtomicFile.writeJsonAtomic(output, {
+    mode,
+    processClaim: { ok: result.ok, stateAdvanced: result.stateAdvanced === true, operations: result.operations },
+    lastAnalyzedCommit: state.lastAnalyzedCommit,
+    activeClaimRunId: state.analysis.activeClaim?.runId || null,
+    indexDirty: state.index.dirty,
+  });
+  process.stdout.write(`ENGADV-FAULT-COMPLETE ok=${result.ok}\n`);
+}
+
+main().catch(error => {
+  // A rejection still means the process is alive; crash modes exit via the fault hook.
+  process.stderr.write(`[engadv-fault] ${error.code || 'FAULT_FAILED'}: ${error.message}\n`);
+  process.exit(1);
+});