@xioflow/kernel 0.2.0 → 0.4.0

package/dist/testing/contract-suite.js

@@ -2,8 +2,10 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { spawn } from 'node:child_process';
-import { ExecutionDomain, SqliteStore, ProcessSupervisor, RecoveryEngine, ResourceConflictError, UnsupportedCapabilityError, EpochFencedError, OperationNotActiveError, DuplicateOperationError, } from '../index.js';
+import util from 'node:util';
+import { spawn, execFile } from 'node:child_process';
+const execFileAsync = util.promisify(execFile);
+import { ExecutionDomain, SqliteStore, ProcessSupervisor, RecoveryEngine, ResourceConflictError, UnsupportedCapabilityError, EpochFencedError, OperationNotActiveError, DuplicateOperationError, OperationIdConflictError, RecoveryRequiredError, computeInputFingerprint, normalizeResourceName, CapabilityViolationError, } from '../index.js';
 function ensureTaskAndRun(domain, taskId, runId) {
     const store = domain.getStore();
     if (!store.getTask(taskId)) {
@@ -421,6 +423,8 @@ export function defineContractTestSuite(consumerName, createContext) {
                 }
                 catch { }
                 expect(escapedAliveBefore).toBe(true);
+                // 等待采样轮询器（每 35ms 周期）至少完成一次后代树捕获
+                await new Promise((r) => setTimeout(r, 200));
                 // 调用停止流水线：NodePlatformDriver 真实后代树扫描探测到逃逸残留
                 const cancelRes = await supervisor.cancelOperation('op-c10-escape', 1000);
                 // 真实上报 stopped: cannot_determine，且 residualPids 包含逃逸孤儿 PID
@@ -985,6 +989,748 @@ export function defineContractTestSuite(consumerName, createContext) {
             expect(pruneResult.retained).toContain(activeFile);
             expect(fs.existsSync(activeFile)).toBe(true);
         });
+        it('契约 45: 同 opId 同指纹重放返回已记录结果，不产生新进程，写 OPERATION_REPLAYED', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            ensureTaskAndRun(domain, 'task-c45', 'run-c45');
+            const counterFile = path.join(tempDir, 'counter-c45.log');
+            const options = {
+                runId: 'run-c45',
+                opId: 'op-c45-recorded',
+                name: 'op-c45',
+                requiredResources: [],
+                command: {
+                    execPath: process.execPath,
+                    args: ['-e', `require('fs').appendFileSync(process.argv[1], '1\\n'); console.log('c45-out');`, counterFile],
+                    cwd: tempDir,
+                },
+            };
+            const res1 = await supervisor.executeProcess(options);
+            expect(res1.status).toBe('succeeded');
+            expect(res1.replayed).toBeUndefined();
+            expect(res1.stdout).toContain('c45-out');
+            const res2 = await supervisor.executeProcess(options);
+            expect(res2.status).toBe('succeeded');
+            expect(res2.replayed).toBe(true);
+            expect(res2.stdout).toContain('c45-out');
+            // 验证副作用仅发生 1 次
+            const lines = fs.readFileSync(counterFile, 'utf8').trim().split('\n');
+            expect(lines.length).toBe(1);
+            // journal 记录 OPERATION_REPLAYED
+            const events = domain.getStore().getJournalEvents(domain.domainId);
+            const replayEvt = events.find((e) => e.type === 'OPERATION_REPLAYED' && e.operationId === 'op-c45-recorded');
+            expect(replayEvt).toBeDefined();
+            expect(replayEvt?.payload.mode).toBe('recorded');
+        });
+        it('契约 46: 同 opId 不同指纹 => OperationIdConflictError，不改动已有 op 的任何事实', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            ensureTaskAndRun(domain, 'task-c46', 'run-c46');
+            const options1 = {
+                runId: 'run-c46',
+                opId: 'op-c46-conflict',
+                name: 'op-c46-orig',
+                requiredResources: [],
+                command: {
+                    execPath: process.execPath,
+                    args: ['-e', 'console.log("c46-orig");'],
+                    cwd: tempDir,
+                },
+            };
+            const res1 = await supervisor.executeProcess(options1);
+            expect(res1.status).toBe('succeeded');
+            const options2 = {
+                runId: 'run-c46',
+                opId: 'op-c46-conflict',
+                name: 'op-c46-conflict',
+                requiredResources: [],
+                command: {
+                    execPath: process.execPath,
+                    args: ['-e', 'console.log("c46-diff");'], // 不同 args
+                    cwd: tempDir,
+                },
+            };
+            await expect(supervisor.executeProcess(options2)).rejects.toThrow(OperationIdConflictError);
+            const op = domain.getStore().getOperation('op-c46-conflict');
+            expect(op?.status).toBe('done');
+            expect(op?.result?.status).toBe('succeeded');
+        });
+        it('契约 47: 重放命中在飞 op => 两个调用拿到同一结果，进程只启动一次', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            ensureTaskAndRun(domain, 'task-c47', 'run-c47');
+            const counterFile = path.join(tempDir, 'counter-c47.log');
+            const options = {
+                runId: 'run-c47',
+                opId: 'op-c47-inflight',
+                name: 'op-c47',
+                requiredResources: [],
+                command: {
+                    execPath: process.execPath,
+                    args: ['-e', `require('fs').appendFileSync(process.argv[1], '1\\n'); setTimeout(() => console.log('c47-out'), 300);`, counterFile],
+                    cwd: tempDir,
+                },
+            };
+            const [res1, res2] = await Promise.all([
+                supervisor.executeProcess(options),
+                supervisor.executeProcess(options),
+            ]);
+            expect(res1.status).toBe('succeeded');
+            expect(res2.status).toBe('succeeded');
+            expect(res2.replayed).toBe(true);
+            const lines = fs.readFileSync(counterFile, 'utf8').trim().split('\n');
+            expect(lines.length).toBe(1);
+            const events = domain.getStore().getJournalEvents(domain.domainId);
+            const replayEvt = events.find((e) => e.type === 'OPERATION_REPLAYED' && e.operationId === 'op-c47-inflight');
+            expect(replayEvt?.payload.mode).toBe('joined');
+        });
+        it('契约 48: 重放命中 indeterminate => 原样返回，不重跑，租约保持', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            ensureTaskAndRun(domain, 'task-c48', 'run-c48');
+            const opId = 'op-c48-indet';
+            const store = domain.getStore();
+            const options = {
+                runId: 'run-c48',
+                opId,
+                name: 'test-indet',
+                requiredResources: ['res:c48'],
+                command: {
+                    execPath: process.execPath,
+                    args: ['-e', 'process.exit(0)'],
+                    cwd: tempDir,
+                },
+            };
+            store.registerOperationIntent({
+                id: opId,
+                runId: 'run-c48',
+                kind: 'process',
+                name: 'test-indet',
+                inputFingerprint: computeInputFingerprint(options),
+                requiredResources: ['res:c48'],
+                status: 'pending',
+            }, domain.domainId);
+            const indetResult = {
+                kind: 'process',
+                status: 'indeterminate',
+                exitCode: null,
+                signal: null,
+                stdout: '',
+                stderr: 'indeterminate residual',
+                isTruncated: false,
+                identityVerification: 'cannot_determine',
+                durationMs: 50,
+                completedAt: new Date().toISOString(),
+            };
+            store.recordOperationResult(opId, indetResult, false);
+            const res = await supervisor.executeProcess(options);
+            expect(res.status).toBe('indeterminate');
+            expect(res.replayed).toBe(true);
+            const leases = store.getPersistedResourceLeases(domain.domainId);
+            expect(leases.some((l) => l.operationId === opId && l.resourceId === 'res:c48')).toBe(true);
+        });
+        it('契约 49: 有意图无身份的崩溃现场：未恢复时提交抛 RecoveryRequiredError；恢复后结清重放命中已记录事实', async () => {
+            const { supervisor, domain, driver, tempDir } = ctx;
+            ensureTaskAndRun(domain, 'task-c49', 'run-c49');
+            const opId = 'op-c49-unrecovered';
+            const store = domain.getStore();
+            const options = {
+                runId: 'run-c49',
+                opId,
+                name: 'test-unrecovered',
+                requiredResources: [],
+                command: {
+                    execPath: process.execPath,
+                    args: ['-e', 'console.log(1)'],
+                    cwd: tempDir,
+                },
+            };
+            // 构造崩溃残留：intent_registered 且不在内存活跃表中
+            store.registerOperationIntent({
+                id: opId,
+                runId: 'run-c49',
+                kind: 'process',
+                name: 'test-unrecovered',
+                inputFingerprint: computeInputFingerprint(options),
+                requiredResources: [],
+                status: 'intent_registered',
+            }, domain.domainId);
+            // 未调用 recover() 前调用，抛 RecoveryRequiredError
+            await expect(supervisor.executeProcess(options)).rejects.toThrow(RecoveryRequiredError);
+            // 执行崩溃恢复
+            const recoveryEngine = new RecoveryEngine(domain, driver);
+            await recoveryEngine.recover();
+            // 恢复后该意图被收敛为 failed(never spawned)，新 Run 再次发起重放应命中已记录结果
+            ensureTaskAndRun(domain, 'task-c49', 'run-c49-new');
+            const replayOptions = {
+                ...options,
+                runId: 'run-c49-new',
+            };
+            const res = await supervisor.executeProcess(replayOptions);
+            expect(res.status).toBe('failed');
+            expect(res.replayed).toBe(true);
+            expect(res.runId).toBe('run-c49');
+        });
+        it('契约 50: service 实例 stdinMode: "stream" 双向通信；stdout 直通不进内存保留；停止走标准流水线', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            const runId = 'run-c50';
+            ensureTaskAndRun(domain, 'task-c50', runId);
+            const script = `
+        const readline = require('readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+        rl.on('line', (line) => console.log('REPLY:' + line));
+      `;
+            const handle = await supervisor.startService({
+                serviceId: 'service-c50',
+                runId,
+                command: {
+                    execPath: process.execPath,
+                    args: ['-e', script],
+                    cwd: tempDir,
+                },
+                readiness: 'spawned',
+            });
+            expect(handle.currentInstanceOpId).toBe('service-c50#1');
+            await handle.ready;
+            // 验证双向 stdin/stdout 流式交互
+            const receivedLines = [];
+            handle.stdout.on('data', (chunk) => {
+                const lines = chunk.toString().split('\n');
+                for (const l of lines) {
+                    if (l.trim())
+                        receivedLines.push(l.trim());
+                }
+            });
+            handle.stdin.write('ping-50\n');
+            const start = Date.now();
+            while (!receivedLines.includes('REPLY:ping-50') && Date.now() - start < 3000) {
+                await new Promise((r) => setTimeout(r, 20));
+            }
+            expect(receivedLines).toContain('REPLY:ping-50');
+            // 停止 service 走标准流水线
+            await handle.stop(1000);
+            const events = domain.getStore().getJournalEvents(domain.domainId);
+            const startEvt = events.find((e) => e.type === 'SERVICE_STARTED' && e.payload?.serviceId === 'service-c50');
+            const readyEvt = events.find((e) => e.type === 'SERVICE_READY' && e.payload?.serviceId === 'service-c50');
+            const stopEvt = events.find((e) => e.type === 'SERVICE_STOPPED' && e.payload?.serviceId === 'service-c50');
+            expect(startEvt).toBeDefined();
+            expect(readyEvt).toBeDefined();
+            expect(stopEvt).toBeDefined();
+        });
+        it('契约 51: service on-failure 按退避重启且不超过上限；每次重启是新实例 op 并写 journal；超限 => failed', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            const runId = 'run-c51';
+            ensureTaskAndRun(domain, 'task-c51', runId);
+            const script = `
+        const readline = require('readline');
+        const rl = readline.createInterface({ input: process.stdin, terminal: false });
+        rl.once('line', () => process.exit(42));
+      `;
+            const handle = await supervisor.startService({
+                serviceId: 'service-c51',
+                runId,
+                command: {
+                    execPath: process.execPath,
+                    args: ['-e', script],
+                    cwd: tempDir,
+                },
+                readiness: 'spawned',
+                restart: { policy: 'on-failure', maxRestarts: 2, backoffMs: 50 },
+            });
+            await handle.ready;
+            expect(handle.currentInstanceOpId).toBe('service-c51#1');
+            // 退出 instance #1
+            handle.stdin.write('die-1\n');
+            const start1 = Date.now();
+            while (handle.currentInstanceOpId !== 'service-c51#2' && Date.now() - start1 < 3000) {
+                await new Promise((r) => setTimeout(r, 20));
+            }
+            expect(handle.currentInstanceOpId).toBe('service-c51#2');
+            // 退出 instance #2
+            handle.stdin.write('die-2\n');
+            const start2 = Date.now();
+            while (handle.currentInstanceOpId !== 'service-c51#3' && Date.now() - start2 < 3000) {
+                await new Promise((r) => setTimeout(r, 20));
+            }
+            expect(handle.currentInstanceOpId).toBe('service-c51#3');
+            // 退出 instance #3（达到上限）
+            handle.stdin.write('die-3\n');
+            const start3 = Date.now();
+            let events = domain.getStore().getJournalEvents(domain.domainId);
+            while (!events.some((e) => e.type === 'SERVICE_FAILED' && e.payload?.serviceId === 'service-c51') && Date.now() - start3 < 3000) {
+                await new Promise((r) => setTimeout(r, 20));
+                events = domain.getStore().getJournalEvents(domain.domainId);
+            }
+            events = domain.getStore().getJournalEvents(domain.domainId);
+            const restarts = events.filter((e) => e.type === 'SERVICE_RESTARTED' && e.payload?.serviceId === 'service-c51');
+            expect(restarts.length).toBe(2);
+            const failed = events.find((e) => e.type === 'SERVICE_FAILED' && e.payload?.serviceId === 'service-c51');
+            expect(failed).toBeDefined();
+            expect(failed?.payload?.maxRestartsExceeded).toBe(true);
+        });
+        it('契约 52: 宿主崩溃后 service 实例被核验并清场，恢复引擎不自动重启', async () => {
+            const { supervisor, domain, driver, tempDir } = ctx;
+            const runId = 'run-c52';
+            ensureTaskAndRun(domain, 'task-c52', runId);
+            const resource = 'res:c52-service';
+            const script = `
+        console.log('READY');
+        setInterval(() => {}, 1000);
+      `;
+            const handle = await supervisor.startService({
+                serviceId: 'service-c52',
+                runId,
+                command: { execPath: process.execPath, args: ['-e', script], cwd: tempDir },
+                requiredResources: [resource],
+                readiness: { stdoutLine: /^READY$/ },
+                restart: { policy: 'on-failure', maxRestarts: 3, backoffMs: 50 },
+            });
+            await handle.ready;
+            expect(domain.isResourceLocked(resource)).toBe(true);
+            const op = domain.getStore().getOperation('service-c52#1');
+            const childPid = op?.processIdentity?.pid;
+            expect(childPid).toBeDefined();
+            // 模拟宿主崩溃：关闭 domain，但不主动停止 service 实例
+            domain.close();
+            // 新宿主 acquire 并执行恢复
+            const restartedDomain = ExecutionDomain.acquire(tempDir, domain.domainId);
+            expect(restartedDomain.isResourceLocked(resource)).toBe(true);
+            const recoveryEngine = new RecoveryEngine(restartedDomain, driver);
+            const report = await recoveryEngine.recover();
+            expect(report.recoveredServices).toBeDefined();
+            const srvReport = report.recoveredServices.find((s) => s.serviceId === 'service-c52');
+            expect(srvReport).toBeDefined();
+            expect(srvReport?.resourcesReleased).toBe(true);
+            expect(srvReport?.instanceOpIds).toContain('service-c52#1');
+            // 资源租约已完全释放
+            expect(restartedDomain.isResourceLocked(resource)).toBe(false);
+            // 进程已停止
+            let isAlive = true;
+            try {
+                process.kill(childPid, 0);
+            }
+            catch (err) {
+                if (err.code === 'ESRCH')
+                    isAlive = false;
+            }
+            expect(isAlive).toBe(false);
+            // 不会自动重启新实例
+            await new Promise((r) => setTimeout(r, 150));
+            const allOps = restartedDomain.getStore().getOperationsByRun(runId);
+            expect(allOps.find((o) => o.id === 'service-c52#2')).toBeUndefined();
+            restartedDomain.close();
+        });
+        it('契约 28: 回滚后指纹核验：restored / partial / failed 如实区分', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            const repoDir = path.join(tempDir, 'repo-c28');
+            fs.mkdirSync(repoDir, { recursive: true });
+            await execFileAsync('git', ['init', '-b', 'main'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.name', 'Tester'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.email', 'tester@test.local'], { cwd: repoDir });
+            fs.writeFileSync(path.join(repoDir, 'main.ts'), 'version 1;\n');
+            await execFileAsync('git', ['add', '.'], { cwd: repoDir });
+            await execFileAsync('git', ['commit', '-m', 'v1'], { cwd: repoDir });
+            ensureTaskAndRun(domain, 'task-c28', 'run-c28');
+            // 捕获快照
+            const snapRes = await supervisor.captureSnapshot({
+                runId: 'run-c28',
+                opId: 'op-c28-snap',
+                roots: [repoDir],
+            });
+            expect(snapRes.status).toBe('succeeded');
+            const snapId = snapRes.snapshot.id;
+            // 修改工作区文件并增加新文件
+            fs.writeFileSync(path.join(repoDir, 'main.ts'), 'version 2 modified;\n');
+            fs.writeFileSync(path.join(repoDir, 'extra.txt'), 'extra untracked\n');
+            // 执行回滚
+            const rbRes = await supervisor.rollback({
+                runId: 'run-c28',
+                opId: 'op-c28-rollback-1',
+                snapshotId: snapId,
+            });
+            expect(rbRes.status).toBe('restored');
+            expect(fs.readFileSync(path.join(repoDir, 'main.ts'), 'utf8')).toBe('version 1;\n');
+            expect(fs.existsSync(path.join(repoDir, 'extra.txt'))).toBe(false);
+            expect(domain.isResourceLocked(`workspace:write:${path.resolve(repoDir)}`)).toBe(false);
+        });
+        it('契约 29: 无写入限制时回滚 coverage 不得为 complete，outOfScopeEffects = "possible"', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            const repoDir = path.join(tempDir, 'repo-c29');
+            fs.mkdirSync(repoDir, { recursive: true });
+            await execFileAsync('git', ['init', '-b', 'main'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.name', 'Tester'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.email', 'tester@test.local'], { cwd: repoDir });
+            fs.writeFileSync(path.join(repoDir, 'code.js'), 'let x = 1;\n');
+            await execFileAsync('git', ['add', '.'], { cwd: repoDir });
+            await execFileAsync('git', ['commit', '-m', 'init'], { cwd: repoDir });
+            ensureTaskAndRun(domain, 'task-c29', 'run-c29');
+            const snapRes = await supervisor.captureSnapshot({
+                runId: 'run-c29',
+                opId: 'op-c29-snap',
+                roots: [repoDir],
+            });
+            const snapId = snapRes.snapshot.id;
+            // 执行一个普通不受限的 process 操作
+            await supervisor.executeProcess({
+                runId: 'run-c29',
+                opId: 'op-c29-unconfined',
+                name: 'unconfined-cmd',
+                command: { execPath: process.execPath, args: ['-e', 'console.log(123)'], cwd: repoDir },
+                requiredResources: [],
+            });
+            // 回滚
+            const rbRes = await supervisor.rollback({
+                runId: 'run-c29',
+                opId: 'op-c29-rollback',
+                snapshotId: snapId,
+            });
+            // 契约 #29 严禁在无写入限制时声明 complete
+            expect(rbRes.coverage).not.toBe('complete');
+            expect(rbRes.coverage).toBe('declared_roots');
+            expect(rbRes.outOfScopeEffects).toBe('possible');
+        });
+        it('契约 30: 回滚与目标根目录上的活跃 / 未裁决操作互斥', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            const repoDir = path.join(tempDir, 'repo-c30');
+            fs.mkdirSync(repoDir, { recursive: true });
+            await execFileAsync('git', ['init', '-b', 'main'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.name', 'Tester'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.email', 'tester@test.local'], { cwd: repoDir });
+            fs.writeFileSync(path.join(repoDir, 'index.js'), '// initial\n');
+            await execFileAsync('git', ['add', '.'], { cwd: repoDir });
+            await execFileAsync('git', ['commit', '-m', 'init'], { cwd: repoDir });
+            ensureTaskAndRun(domain, 'task-c30', 'run-c30');
+            const snapRes = await supervisor.captureSnapshot({
+                runId: 'run-c30',
+                opId: 'op-c30-snap',
+                roots: [repoDir],
+            });
+            const snapId = snapRes.snapshot.id;
+            // 在目标根上持有写租约并启动长时间操作
+            const writeRes = `workspace:write:${path.resolve(repoDir)}`;
+            const activePromise = supervisor.executeProcess({
+                runId: 'run-c30',
+                opId: 'op-c30-holding',
+                name: 'holder',
+                command: { execPath: process.execPath, args: ['-e', 'setTimeout(() => {}, 2000)'], cwd: repoDir },
+                requiredResources: [writeRes],
+            });
+            // 等待进程启动获得租约
+            const normRes = normalizeResourceName(writeRes);
+            while (!domain.isResourceLocked(normRes)) {
+                await new Promise((r) => setTimeout(r, 10));
+            }
+            // 尝试在活跃操作持有目标目录时回滚，必须被拒绝并给出持有者诊断
+            await expect(supervisor.rollback({
+                runId: 'run-c30',
+                opId: 'op-c30-rollback-conflict',
+                snapshotId: snapId,
+            })).rejects.toThrow(ResourceConflictError);
+            await supervisor.cancelOperation('op-c30-holding');
+            await activePromise;
+        });
+        it('契约 31: 回滚中途崩溃：恢复按指纹判定 restored 或 indeterminate', async () => {
+            const { supervisor, domain, driver, tempDir } = ctx;
+            const repoDir = path.join(tempDir, 'repo-c31');
+            fs.mkdirSync(repoDir, { recursive: true });
+            await execFileAsync('git', ['init', '-b', 'main'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.name', 'Tester'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.email', 'tester@test.local'], { cwd: repoDir });
+            fs.writeFileSync(path.join(repoDir, 'tracked.txt'), 'clean v1\n');
+            await execFileAsync('git', ['add', '.'], { cwd: repoDir });
+            await execFileAsync('git', ['commit', '-m', 'clean v1'], { cwd: repoDir });
+            ensureTaskAndRun(domain, 'task-c31', 'run-c31');
+            const snapRes = await supervisor.captureSnapshot({
+                runId: 'run-c31',
+                opId: 'op-c31-snap',
+                roots: [repoDir],
+            });
+            const snapId = snapRes.snapshot.id;
+            // 场景 A: 模拟回滚中途宿主崩溃，但工作区指纹与快照一致
+            const writeRes = `workspace:write:${path.resolve(repoDir)}`;
+            domain.getStore().registerOperationIntent({
+                id: 'op-c31-crash-match',
+                runId: 'run-c31',
+                kind: 'rollback',
+                name: `rollback:${snapId}`,
+                inputFingerprint: 'fp-c31',
+                requiredResources: [writeRes],
+                mutationRoots: [path.resolve(repoDir)],
+                outputRef: snapId,
+                status: 'intent_registered',
+            }, domain.domainId);
+            domain.getStore().updateOperationStatus('op-c31-crash-match', 'active');
+            domain.allocateResources('op-c31-crash-match', [writeRes]);
+            const recoveryA = new RecoveryEngine(domain, driver);
+            const repA = await recoveryA.recover();
+            const recA = repA.recoveredOperations.find((o) => o.opId === 'op-c31-crash-match');
+            expect(recA?.resourcesReleased).toBe(true);
+            const opA = domain.getStore().getOperation('op-c31-crash-match');
+            expect(opA?.result?.status).toBe('restored');
+            expect(domain.isResourceLocked(writeRes)).toBe(false);
+            // 场景 B: 模拟回滚中途宿主崩溃，且工作区被修改导致指纹不匹配
+            ensureTaskAndRun(domain, 'task-c31', 'run-c31-b');
+            fs.writeFileSync(path.join(repoDir, 'tracked.txt'), 'corrupted mid-rollback\n');
+            domain.getStore().registerOperationIntent({
+                id: 'op-c31-crash-mismatch',
+                runId: 'run-c31-b',
+                kind: 'rollback',
+                name: `rollback:${snapId}`,
+                inputFingerprint: 'fp-c31-b',
+                requiredResources: [writeRes],
+                mutationRoots: [path.resolve(repoDir)],
+                outputRef: snapId,
+                status: 'intent_registered',
+            }, domain.domainId);
+            domain.getStore().updateOperationStatus('op-c31-crash-mismatch', 'active');
+            domain.allocateResources('op-c31-crash-mismatch', [writeRes]);
+            const repB = await recoveryA.recover();
+            const recB = repB.recoveredOperations.find((o) => o.opId === 'op-c31-crash-mismatch');
+            expect(recB?.resourcesReleased).toBe(false);
+            const opB = domain.getStore().getOperation('op-c31-crash-mismatch');
+            expect(opB?.result?.status).toBe('indeterminate');
+            expect(domain.isResourceLocked(writeRes)).toBe(true);
+            // 清理资源
+            domain.internalReleaseResources('op-c31-crash-mismatch', [writeRes]);
+        });
+        it('契约 32: git-shadow 快照不改动用户 index、HEAD 与分支，并如实声明 worktree_non_ignored', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            const repoDir = path.join(tempDir, 'repo-c32');
+            fs.mkdirSync(repoDir, { recursive: true });
+            await execFileAsync('git', ['init', '-b', 'main'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.name', 'Tester'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.email', 'tester@test.local'], { cwd: repoDir });
+            fs.writeFileSync(path.join(repoDir, 'base.txt'), 'base\n');
+            fs.writeFileSync(path.join(repoDir, '.gitignore'), '.env\n');
+            await execFileAsync('git', ['add', '.'], { cwd: repoDir });
+            await execFileAsync('git', ['commit', '-m', 'base commit'], { cwd: repoDir });
+            // 构造用户正在工作的工作区现场
+            fs.writeFileSync(path.join(repoDir, 'staged.txt'), 'user staged change\n');
+            await execFileAsync('git', ['add', 'staged.txt'], { cwd: repoDir });
+            fs.writeFileSync(path.join(repoDir, 'unstaged.txt'), 'user unstaged change\n');
+            fs.writeFileSync(path.join(repoDir, '.env'), 'SECRET=donttouch\n');
+            const statusBefore = (await execFileAsync('git', ['status', '--porcelain'], { cwd: repoDir })).stdout;
+            const stageBefore = (await execFileAsync('git', ['ls-files', '--stage'], { cwd: repoDir })).stdout;
+            const headBefore = (await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repoDir })).stdout;
+            const branchBefore = (await execFileAsync('git', ['branch'], { cwd: repoDir })).stdout;
+            ensureTaskAndRun(domain, 'task-c32', 'run-c32');
+            const snapRes = await supervisor.captureSnapshot({
+                runId: 'run-c32',
+                opId: 'op-c32',
+                roots: [repoDir],
+            });
+            expect(snapRes.status).toBe('succeeded');
+            expect(snapRes.snapshot?.coverage).toBe('worktree_non_ignored');
+            const statusAfter = (await execFileAsync('git', ['status', '--porcelain'], { cwd: repoDir })).stdout;
+            const stageAfter = (await execFileAsync('git', ['ls-files', '--stage'], { cwd: repoDir })).stdout;
+            const headAfter = (await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repoDir })).stdout;
+            const branchAfter = (await execFileAsync('git', ['branch'], { cwd: repoDir })).stdout;
+            expect(statusAfter).toBe(statusBefore);
+            expect(stageAfter).toBe(stageBefore);
+            expect(headAfter).toBe(headBefore);
+            expect(branchAfter).toBe(branchBefore);
+        });
+        it('契约 53: SnapshotRef.journalSeq 与捕获事件 seq 一致；可按 seq 查询不晚于它的最近快照', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            const repoDir = path.join(tempDir, 'repo-c53');
+            fs.mkdirSync(repoDir, { recursive: true });
+            await execFileAsync('git', ['init', '-b', 'main'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.name', 'Tester'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.email', 'tester@test.local'], { cwd: repoDir });
+            fs.writeFileSync(path.join(repoDir, 'step.txt'), 'step 0\n');
+            await execFileAsync('git', ['add', '.'], { cwd: repoDir });
+            await execFileAsync('git', ['commit', '-m', 'step 0'], { cwd: repoDir });
+            ensureTaskAndRun(domain, 'task-c53', 'run-c53');
+            // 捕获第 1 个快照
+            const snap1 = await supervisor.captureSnapshot({
+                runId: 'run-c53',
+                opId: 'snap-1',
+                roots: [repoDir],
+            });
+            const events1 = domain.getStore().getJournalEvents(domain.domainId);
+            const capEvent1 = events1.find((e) => e.type === 'SNAPSHOT_CAPTURED' && e.payload?.snapshotId === 'snap-1');
+            expect(capEvent1).toBeDefined();
+            expect(snap1.snapshot?.journalSeq).toBe(capEvent1?.seq);
+            fs.writeFileSync(path.join(repoDir, 'step.txt'), 'step 1\n');
+            // 捕获第 2 个快照
+            const snap2 = await supervisor.captureSnapshot({
+                runId: 'run-c53',
+                opId: 'snap-2',
+                roots: [repoDir],
+            });
+            const events2 = domain.getStore().getJournalEvents(domain.domainId);
+            const capEvent2 = events2.find((e) => e.type === 'SNAPSHOT_CAPTURED' && e.payload?.snapshotId === 'snap-2');
+            expect(snap2.snapshot?.journalSeq).toBe(capEvent2?.seq);
+            // 查询 seq 不晚于 capEvent1.seq 的快照 => 必须返回 snap-1
+            const foundSnap1 = domain.getStore().findSnapshotAtOrBefore(domain.domainId, capEvent1.seq);
+            expect(foundSnap1?.id).toBe('snap-1');
+            // 查询 seq 不晚于 capEvent2.seq 的快照 => 必须返回 snap-2
+            const foundSnap2 = domain.getStore().findSnapshotAtOrBefore(domain.domainId, capEvent2.seq);
+            expect(foundSnap2?.id).toBe('snap-2');
+        });
+        it('契约 54: materialize 生成的工作区独立；源工作区、用户 index、HEAD 与分支不变；dematerialize 后无残留 worktree', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            const repoDir = path.join(tempDir, 'repo-c54');
+            fs.mkdirSync(repoDir, { recursive: true });
+            await execFileAsync('git', ['init', '-b', 'main'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.name', 'Tester'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.email', 'tester@test.local'], { cwd: repoDir });
+            fs.writeFileSync(path.join(repoDir, 'entry.ts'), 'export const val = 42;\n');
+            await execFileAsync('git', ['add', '.'], { cwd: repoDir });
+            await execFileAsync('git', ['commit', '-m', 'entry commit'], { cwd: repoDir });
+            ensureTaskAndRun(domain, 'task-c54', 'run-c54');
+            const snapRes = await supervisor.captureSnapshot({
+                runId: 'run-c54',
+                opId: 'snap-c54',
+                roots: [repoDir],
+            });
+            const forkDir = path.join(tempDir, 'fork-c54');
+            const { worktreePath } = await supervisor.materialize('snap-c54', forkDir);
+            expect(worktreePath).toBe(forkDir);
+            expect(fs.existsSync(path.join(forkDir, 'entry.ts'))).toBe(true);
+            expect(domain.isResourceLocked(`workspace:write:${path.resolve(forkDir)}`)).toBe(true);
+            // dematerialize
+            await supervisor.dematerialize(forkDir);
+            expect(fs.existsSync(forkDir)).toBe(false);
+            expect(domain.isResourceLocked(`workspace:write:${path.resolve(forkDir)}`)).toBe(false);
+            const { stdout: wtList } = await execFileAsync('git', ['worktree', 'list'], { cwd: repoDir });
+            expect(wtList).not.toContain(forkDir);
+        });
+        it('契约 55: 准入校验：过期 / 撤销 / 旧 epoch / 越界资源 / 越界路径抛 CapabilityViolationError 并记 CAPABILITY_REJECTED；缺省推导生效并记 CAPABILITY_USED', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            ensureTaskAndRun(domain, 'task-c55', 'run-c55');
+            const allowedDir = path.join(tempDir, 'allowed');
+            const outsideDir = path.join(tempDir, 'outside');
+            fs.mkdirSync(allowedDir, { recursive: true });
+            fs.mkdirSync(outsideDir, { recursive: true });
+            // 1. 签发有效 capability
+            const cap = domain.issueCapability({
+                write: [allowedDir],
+                exclusive: ['res:allowed-1'],
+            }, 'tester', 60000);
+            // 2. 越界资源
+            await expect(supervisor.executeProcess({
+                runId: 'run-c55',
+                opId: 'op-c55-res-violation',
+                name: 'violating-proc',
+                command: { execPath: process.execPath, args: ['-e', 'process.exit(0)'], cwd: allowedDir },
+                requiredResources: ['res:unauthorized-res'],
+                capabilityId: cap.id,
+            })).rejects.toThrowError(CapabilityViolationError);
+            // 3. 越界路径 (cwd 在 allowedDir 之外)
+            await expect(supervisor.executeProcess({
+                runId: 'run-c55',
+                opId: 'op-c55-path-violation',
+                name: 'violating-path',
+                command: { execPath: process.execPath, args: ['-e', 'process.exit(0)'], cwd: outsideDir },
+                capabilityId: cap.id,
+            })).rejects.toThrowError(CapabilityViolationError);
+            // 4. 撤销 capability
+            domain.revokeCapability(cap.id, 'test_revocation');
+            await expect(supervisor.executeProcess({
+                runId: 'run-c55',
+                opId: 'op-c55-revoked',
+                name: 'revoked-proc',
+                command: { execPath: process.execPath, args: ['-e', 'process.exit(0)'], cwd: allowedDir },
+                capabilityId: cap.id,
+            })).rejects.toThrowError(CapabilityViolationError);
+            // 验证 CAPABILITY_REJECTED 事件已入 journal
+            const events = domain.getStore().getJournalEvents(domain.domainId);
+            const rejectedEvents = events.filter((e) => e.type === 'CAPABILITY_REJECTED');
+            expect(rejectedEvents.length).toBeGreaterThanOrEqual(3);
+            // 5. 缺省 capability 推导生效与 CAPABILITY_USED 记录
+            const validCap = domain.issueCapability({
+                write: [tempDir],
+                exclusive: ['res:default-1'],
+            }, 'tester', 60000);
+            const res = await supervisor.executeProcess({
+                runId: 'run-c55',
+                opId: 'op-c55-success',
+                name: 'valid-proc',
+                command: { execPath: process.execPath, args: ['-e', 'process.exit(0)'], cwd: tempDir },
+                requiredResources: ['res:default-1'],
+                capabilityId: validCap.id,
+            });
+            expect(res.status).toBe('succeeded');
+            expect(res.capabilityId).toBe(validCap.id);
+            const usedEvents = domain.getStore().getJournalEvents(domain.domainId).filter((e) => e.type === 'CAPABILITY_USED');
+            expect(usedEvents.some((e) => e.payload?.capabilityId === validCap.id)).toBe(true);
+        });
+        it('契约 56: 写入限制驱动：受限写外部路径失败；快照后全受限回滚声明 complete，混入不受限声明 declared_roots', async () => {
+            const { supervisor, domain, tempDir } = ctx;
+            const repoDir = path.join(tempDir, 'repo-c56');
+            fs.mkdirSync(repoDir, { recursive: true });
+            await execFileAsync('git', ['init', '-b', 'main'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.name', 'Tester'], { cwd: repoDir });
+            await execFileAsync('git', ['config', 'user.email', 'tester@test.local'], { cwd: repoDir });
+            fs.writeFileSync(path.join(repoDir, 'init.txt'), 'init\n');
+            await execFileAsync('git', ['add', '.'], { cwd: repoDir });
+            await execFileAsync('git', ['commit', '-m', 'init'], { cwd: repoDir });
+            ensureTaskAndRun(domain, 'task-c56', 'run-c56');
+            const mockDriver = {
+                name: 'mock-confinement',
+                wrap: (cmd) => cmd,
+            };
+            // 1. 签发受限 capability (针对 repoDir)
+            const confinedCap = domain.issueCapability({
+                write: [repoDir],
+                exclusive: [`workspace:write:${path.resolve(repoDir)}`],
+            }, 'tester', 60000);
+            // 捕获快照
+            const snapRes = await supervisor.captureSnapshot({
+                runId: 'run-c56',
+                opId: 'snap-c56',
+                capabilityId: confinedCap.id,
+            });
+            expect(snapRes.status).toBe('succeeded');
+            // 在受限下运行进程写文件
+            const p1 = await supervisor.executeProcess({
+                runId: 'run-c56',
+                opId: 'op-c56-confined',
+                name: 'write-in-repo',
+                command: {
+                    execPath: process.execPath,
+                    args: ['-e', `require('node:fs').writeFileSync(${JSON.stringify(path.join(repoDir, 'a.txt'))}, 'a');`],
+                    cwd: repoDir,
+                },
+                capabilityId: confinedCap.id,
+                confinementDriver: mockDriver,
+            });
+            expect(p1.status).toBe('succeeded');
+            expect(p1.confined).toBe(true);
+            // 全部 op 受限，回滚 coverage 必须为 complete
+            const rollback1 = await supervisor.rollback({
+                runId: 'run-c56',
+                opId: 'rb-c56-1',
+                snapshotId: 'snap-c56',
+                capabilityId: confinedCap.id,
+            });
+            expect(rollback1.coverage).toBe('complete');
+            expect(rollback1.outOfScopeEffects).toBe('none_possible');
+            // 2. 混入不受限操作
+            ensureTaskAndRun(domain, 'task-c56', 'run-c56-unconfined');
+            const snap2 = await supervisor.captureSnapshot({
+                runId: 'run-c56-unconfined',
+                opId: 'snap-c56-2',
+                roots: [repoDir],
+            });
+            const p2 = await supervisor.executeProcess({
+                runId: 'run-c56-unconfined',
+                opId: 'op-c56-unconfined',
+                name: 'write-unconfined',
+                command: {
+                    execPath: process.execPath,
+                    args: ['-e', `require('node:fs').writeFileSync(${JSON.stringify(path.join(repoDir, 'b.txt'))}, 'b');`],
+                    cwd: repoDir,
+                },
+                requiredResources: [`workspace:write:${path.resolve(repoDir)}`],
+            });
+            expect(p2.confined).toBeFalsy();
+            // 混入不受限操作，回滚 coverage 退化为 declared_roots
+            const rollback2 = await supervisor.rollback({
+                runId: 'run-c56-unconfined',
+                opId: 'rb-c56-2',
+                snapshotId: 'snap-c56-2',
+            });
+            expect(rollback2.coverage).toBe('declared_roots');
+            expect(rollback2.outOfScopeEffects).toBe('possible');
+        });
     });
 }
 //# sourceMappingURL=contract-suite.js.map