@xioflow/kernel 0.3.0 → 0.5.0

package/dist/testing/contract-suite.js

@@ -2,8 +2,26 @@ 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, OperationIdConflictError, RecoveryRequiredError, computeInputFingerprint, } 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';
+/** 进程是否已真正消失（容许 init / 持有者回收僵尸的短暂延迟）。 */
+async function waitUntilGone(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            process.kill(pid, 0);
+        }
+        catch (err) {
+            if (err.code === 'ESRCH')
+                return true;
+        }
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((r) => setTimeout(r, 25));
+    }
+}
 function ensureTaskAndRun(domain, taskId, runId) {
     const store = domain.getStore();
     if (!store.getTask(taskId)) {
@@ -369,7 +387,7 @@ export function defineContractTestSuite(consumerName, createContext) {
             expect(grandchildAliveAfter).toBe(false);
             await executePromise;
         });
-        it('契约 10: 逃逸后代诚实上报，驱动无法确认停止时如实标记 cannot_determine', async () => {
+        it('契约 10: 逃逸后代诚实上报：停止结论与事实一致，无法确认时如实标记 cannot_determine', async () => {
             const { supervisor, domain, tempDir } = ctx;
             ensureTaskAndRun(domain, 'task-c10', 'run-c10');
             const escapedPidFile = path.join(tempDir, 'escaped.pid');
@@ -421,9 +439,19 @@ export function defineContractTestSuite(consumerName, createContext) {
                 }
                 catch { }
                 expect(escapedAliveBefore).toBe(true);
-                // 调用停止流水线：NodePlatformDriver 真实后代树扫描探测到逃逸残留
+                // 等待采样轮询器（每 35ms 周期）至少完成一次后代树捕获
+                await new Promise((r) => setTimeout(r, 200));
+                // 调用停止流水线。结论必须与事实一致：
+                // - 能持有整棵树的驱动（如 Linux 子收割者）可以真的停掉逃逸者，此时逃逸者必须确已消失；
+                // - 做不到的驱动必须如实上报 cannot_determine + residualPids，绝不能声称 confirmed_stopped。
                 const cancelRes = await supervisor.cancelOperation('op-c10-escape', 1000);
-                // 真实上报 stopped: cannot_determine，且 residualPids 包含逃逸孤儿 PID
+                if (cancelRes.stopped === 'confirmed_stopped') {
+                    expect(await waitUntilGone(escapedPid, 2000)).toBe(true);
+                    const result = await executePromise;
+                    expect(result.status).toBe('cancelled');
+                    expect(domain.isResourceLocked('res:c10-lock')).toBe(false);
+                    return;
+                }
                 expect(cancelRes.stopped).toBe('cannot_determine');
                 expect(cancelRes.residualPids).toBeDefined();
                 expect(cancelRes.residualPids).toContain(escapedPid);
@@ -696,7 +724,7 @@ export function defineContractTestSuite(consumerName, createContext) {
             expect(throwing.stdout).toBe('captured-anyway');
             expect(throwing.streamCallbackError).toBe('consumer projection failed');
         });
-        it('契约 19: 超时 + 逃逸后代持有管道，操作在有界时间内返回 indeterminate，不挂到逃逸进程退出', async () => {
+        it('契约 19: 超时 + 逃逸后代持有管道，操作在有界时间内结清，不挂到逃逸进程退出', async () => {
             const { supervisor, domain, tempDir } = ctx;
             ensureTaskAndRun(domain, 'task-c19', 'run-c19');
             const subPidFile = path.join(tempDir, 'sub-c19.pid');
@@ -726,13 +754,26 @@ export function defineContractTestSuite(consumerName, createContext) {
             });
             const duration = Date.now() - startedAt;
             expect(duration).toBeLessThan(3500);
-            expect(result.status).toBe('indeterminate');
-            expect(domain.isResourceLocked('res:c19-bounded')).toBe(true);
-            // 清理逃逸孙进程
-            if (fs.existsSync(subPidFile)) {
+            const subPid = fs.existsSync(subPidFile) ? parseInt(fs.readFileSync(subPidFile, 'utf8'), 10) : 0;
+            expect(subPid).toBeGreaterThan(0);
+            try {
+                // executeProcess 的声明类型不含 indeterminate，运行时结果可能是它
+                if (result.status === 'indeterminate') {
+                    // 逃逸者未被确认停止：保留租约等待裁决
+                    expect(domain.isResourceLocked('res:c19-bounded')).toBe(true);
+                }
+                else {
+                    // 驱动确认停掉了整棵树：只有逃逸者确已消失才允许按超时失败结清并释放租约
+                    expect(result.status).toBe('failed');
+                    expect(result.terminationReason).toBe('timed_out');
+                    expect(await waitUntilGone(subPid, 2000)).toBe(true);
+                    expect(domain.isResourceLocked('res:c19-bounded')).toBe(false);
+                }
+            }
+            finally {
+                // 清理逃逸孙进程
                 try {
-                    const pid = parseInt(fs.readFileSync(subPidFile, 'utf8'), 10);
-                    process.kill(pid, 'SIGKILL');
+                    process.kill(subPid, 'SIGKILL');
                 }
                 catch { }
             }
@@ -802,6 +843,8 @@ export function defineContractTestSuite(consumerName, createContext) {
                 expect(domain.isResourceLocked('res:c21')).toBe(false);
                 const result = domain.getStore().getOperation(opId).result;
                 expect(result.status).toBe('failed');
+                // 退出事实未被观察到：结局未知，不能被当作「确实失败、可换 opId 重试」
+                expect(result.terminationReason).toBe('exit_unobserved');
                 expect(result.kind === 'process' ? result.stderr : '').toContain('reaped during recovery');
             }
             finally {
@@ -1163,6 +1206,570 @@ export function defineContractTestSuite(consumerName, createContext) {
             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