@xioflow/kernel 0.4.0 → 0.5.1

package/dist/supervisor/replay.d.ts

@@ -0,0 +1,14 @@
+import { ExecutionDomain } from '../domain.js';
+import { ProcessOperationResult } from '../types.js';
+import { ActiveOperationState, ExecuteProcessOptions } from './types.js';
+/**
+ * 在飞操作重放（ARCHITECTURE §3.7 / 契约 #46）：同指纹加入原执行并共享流投影，
+ * 不同指纹抛 OperationIdConflictError。abortSignal 只中止本次等待，不影响原操作。
+ */
+export declare function joinInFlight(domain: ExecutionDomain, inFlight: ActiveOperationState, options: ExecuteProcessOptions, inputFingerprint: string): Promise<ProcessOperationResult>;
+/**
+ * 已持久化操作重放（ARCHITECTURE §3.7 / 契约 #45, #47, #48, #49）。
+ * 返回 undefined 表示该 opId 从未登记，调用方应正常执行。
+ */
+export declare function replayRecorded(domain: ExecutionDomain, options: ExecuteProcessOptions, inputFingerprint: string): ProcessOperationResult | undefined;
+//# sourceMappingURL=replay.d.ts.map

package/dist/supervisor/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/supervisor/replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAA4B,sBAAsB,EAAyB,MAAM,aAAa,CAAC;AACtG,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEzE;;;GAGG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,qBAAqB,EAC9B,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,sBAAsB,CAAC,CAiDjC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,qBAAqB,EAC9B,gBAAgB,EAAE,MAAM,GACvB,sBAAsB,GAAG,SAAS,CA2BpC"}

package/dist/supervisor/replay.js

@@ -0,0 +1,70 @@
+import { OperationIdConflictError, RecoveryRequiredError } from '../types.js';
+/**
+ * 在飞操作重放（ARCHITECTURE §3.7 / 契约 #46）：同指纹加入原执行并共享流投影，
+ * 不同指纹抛 OperationIdConflictError。abortSignal 只中止本次等待，不影响原操作。
+ */
+export async function joinInFlight(domain, inFlight, options, inputFingerprint) {
+    if (inFlight.inputFingerprint !== inputFingerprint) {
+        throw new OperationIdConflictError(options.opId, inFlight.inputFingerprint, inputFingerprint, inFlight.phase, inFlight.runId);
+    }
+    domain.getStore().recordReplay(domain.domainId, options.opId, 'joined', options.runId);
+    const subscriber = options.onStreamChunk;
+    if (subscriber) {
+        inFlight.streamSubscribers.add(subscriber);
+    }
+    const unsubscribe = () => {
+        if (subscriber)
+            inFlight.streamSubscribers.delete(subscriber);
+    };
+    const signal = options.abortSignal;
+    if (!signal) {
+        const res = await inFlight.resultPromise;
+        unsubscribe();
+        return { ...res, replayed: true };
+    }
+    if (signal.aborted) {
+        unsubscribe();
+        throw signal.reason || new Error('Operation wait aborted');
+    }
+    return await new Promise((resolve, reject) => {
+        const onAbort = () => {
+            unsubscribe();
+            reject(signal.reason || new Error('Operation wait aborted'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        inFlight.resultPromise.then((res) => {
+            signal.removeEventListener('abort', onAbort);
+            unsubscribe();
+            resolve({ ...res, replayed: true });
+        }, (err) => {
+            signal.removeEventListener('abort', onAbort);
+            unsubscribe();
+            reject(err);
+        });
+    });
+}
+/**
+ * 已持久化操作重放（ARCHITECTURE §3.7 / 契约 #45, #47, #48, #49）。
+ * 返回 undefined 表示该 opId 从未登记，调用方应正常执行。
+ */
+export function replayRecorded(domain, options, inputFingerprint) {
+    const existingRecorded = domain.getStore().getOperation(options.opId);
+    if (!existingRecorded)
+        return undefined;
+    if (existingRecorded.inputFingerprint !== inputFingerprint) {
+        throw new OperationIdConflictError(options.opId, existingRecorded.inputFingerprint, inputFingerprint, existingRecorded.status, existingRecorded.runId);
+    }
+    // 未终结状态且不在内存中 → 必须先执行恢复（崩溃残留现场）
+    if (existingRecorded.status !== 'done') {
+        throw new RecoveryRequiredError(options.opId, existingRecorded.status, existingRecorded.runId);
+    }
+    // indeterminate：绝不重跑，原样返回，保留租约；已结清终态返回已持久化结果
+    const kind = existingRecorded.result?.status === 'indeterminate' ? 'indeterminate' : 'recorded';
+    domain.getStore().recordReplay(domain.domainId, options.opId, kind, options.runId);
+    return {
+        ...existingRecorded.result,
+        replayed: true,
+        runId: existingRecorded.runId,
+    };
+}
+//# sourceMappingURL=replay.js.map

package/dist/supervisor/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../src/supervisor/replay.ts"],"names":[],"mappings":"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"}

package/dist/supervisor/rollback.d.ts

@@ -0,0 +1,8 @@
+import { RollbackOperationResult } from '../types.js';
+import { SnapshotContext } from './snapshot-ops.js';
+import { RollbackOptions } from './types.js';
+/**
+ * 回滚协议 (ARCHITECTURE §3.5 / 契约 #28–#30, #56)
+ */
+export declare function rollback(ctx: SnapshotContext, options: RollbackOptions): Promise<RollbackOperationResult>;
+//# sourceMappingURL=rollback.d.ts.map

package/dist/supervisor/rollback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback.d.ts","sourceRoot":"","sources":["../../src/supervisor/rollback.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoC,uBAAuB,EAAe,MAAM,aAAa,CAAC;AAGrG,OAAO,EAAyC,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC3F,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA0E/G"}

package/dist/supervisor/rollback.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ResourceConflictError } from '../types.js';
+import { isPathContained } from '../capability/index.js';
+import { activateInternalOperation, sha256Json } from './snapshot-ops.js';
+/**
+ * 回滚协议 (ARCHITECTURE §3.5 / 契约 #28–#30, #56)
+ */
+export async function rollback(ctx, options) {
+    const { domain, snapshotDriver } = ctx;
+    const startTime = Date.now();
+    const snapshot = domain.getStore().getSnapshot(options.snapshotId);
+    if (!snapshot) {
+        throw new Error(`Snapshot not found: ${options.snapshotId}`);
+    }
+    let targetRoots = (options.roots || snapshot.roots).map((r) => path.resolve(r));
+    let capAdmission;
+    if (options.capabilityId) {
+        capAdmission = domain.checkCapabilityAdmission({
+            capabilityId: options.capabilityId,
+            mutationRoots: targetRoots,
+            runId: options.runId,
+            opId: options.opId,
+        });
+        targetRoots = capAdmission.effectiveMutationRoots;
+    }
+    assertRootsQuiescent(domain, targetRoots, options.opId);
+    const op = {
+        id: options.opId,
+        runId: options.runId,
+        kind: 'rollback',
+        name: `rollback:${options.snapshotId}`,
+        inputFingerprint: sha256Json({
+            kind: 'rollback',
+            snapshotId: options.snapshotId,
+            targetRoots,
+            capabilityId: options.capabilityId ?? null,
+        }),
+        requiredResources: targetRoots.map((r) => `workspace:write:${r}`),
+        mutationRoots: targetRoots,
+        capabilityId: options.capabilityId,
+        outputRef: options.snapshotId,
+        timeoutMs: options.timeoutMs,
+        status: 'intent_registered',
+    };
+    activateInternalOperation(domain, op, capAdmission);
+    try {
+        const { unrestoredPaths } = await snapshotDriver.restore(snapshot, { force: options.force });
+        const currentFp = await snapshotDriver.fingerprint(targetRoots, { against: snapshot });
+        const status = currentFp !== snapshot.treeFingerprint ? 'failed' : unrestoredPaths.length > 0 ? 'partial' : 'restored';
+        const { coverage, outOfScopeEffects } = rollbackCoverage(status, () => allEffectsConfinedToRoots(domain, snapshot, targetRoots, options.opId));
+        let result;
+        domain.getStore().transaction(() => {
+            result = {
+                kind: 'rollback',
+                status,
+                snapshotId: options.snapshotId,
+                unrestoredPaths: unrestoredPaths.length > 0 ? unrestoredPaths : undefined,
+                coverage,
+                outOfScopeEffects,
+                capabilityId: options.capabilityId,
+                durationMs: Date.now() - startTime,
+                completedAt: new Date().toISOString(),
+            };
+            domain.getStore().recordOperationResult(options.opId, result);
+            domain.getStore().updateOperationStatus(options.opId, 'done');
+        });
+        domain.internalReleaseResources(options.opId);
+        return result;
+    }
+    catch (err) {
+        domain.internalReleaseResources(options.opId);
+        throw err;
+    }
+}
+/** 同一根目录的两种写资源名（原路径与 realpath），和它们对应的目录。 */
+function rootAliases(root) {
+    let realRoot = root;
+    try {
+        realRoot = fs.realpathSync(root);
+    }
+    catch { }
+    return { root, realRoot, writeRes: `workspace:write:${root}`, writeResReal: `workspace:write:${realRoot}` };
+}
+/**
+ * 前置条件（契约 #30）：目标根目录上不存在 active / stopping / 未裁决 indeterminate 的操作。
+ * 依次检查内存租约、未结清操作、持久化租约（含 indeterminate 保留的租约）。
+ */
+function assertRootsQuiescent(domain, targetRoots, opId) {
+    const aliases = targetRoots.map(rootAliases);
+    for (const a of aliases) {
+        for (const res of [a.writeRes, a.writeResReal]) {
+            if (domain.isResourceLocked(res)) {
+                throw new ResourceConflictError(res, domain.getResourceOwner(res) || 'unknown', opId, 0);
+            }
+        }
+    }
+    for (const op of domain.getStore().getUnfinishedOperations(domain.domainId)) {
+        if (op.id === opId)
+            continue;
+        for (const a of aliases) {
+            const touchesRoot = op.requiredResources.includes(a.writeRes) ||
+                op.requiredResources.includes(a.writeResReal) ||
+                op.mutationRoots?.some((mr) => {
+                    const resolved = path.resolve(mr);
+                    return resolved === a.root || resolved === a.realRoot;
+                });
+            if (touchesRoot) {
+                throw new ResourceConflictError(a.writeRes, op.id, opId, 0);
+            }
+        }
+    }
+    for (const lease of domain.getStore().getPersistedResourceLeases(domain.domainId)) {
+        for (const a of aliases) {
+            if ((lease.resourceId === a.writeRes || lease.resourceId === a.writeResReal) && lease.operationId !== opId) {
+                throw new ResourceConflictError(lease.resourceId, lease.operationId, opId, 0);
+            }
+        }
+    }
+}
+/**
+ * 快照之后的每个已记录操作都在写入限制下运行、且写入范围落在回滚根内，才可声称 complete。
+ * 快照与回滚本身不产生根外副作用。
+ */
+function allEffectsConfinedToRoots(domain, snapshot, targetRoots, rollbackOpId) {
+    const store = domain.getStore();
+    // An operation still running has no result yet, so nothing proves it ran
+    // confined; it may be writing outside the roots right now (long-running
+    // services included).
+    // An indeterminate one may still be alive, whenever it was recorded.
+    const stillRunning = store.getAllOperations(domain.domainId).some((op) => op.id !== rollbackOpId && op.kind !== 'snapshot' && op.kind !== 'rollback' && (op.status !== 'done'
+        || (op.result?.status === 'indeterminate' && op.result.confined !== true)));
+    if (stillRunning)
+        return false;
+    const eventsSince = snapshot.journalSeq !== undefined ? store.getJournalEvents(domain.domainId, snapshot.journalSeq) : [];
+    const opResults = eventsSince.filter((e) => e.type === 'OPERATION_RESULT_RECORDED' && e.operationId !== rollbackOpId);
+    return opResults.every((e) => {
+        const res = e.payload?.result || e.payload;
+        const storedOp = store.getOperation(e.operationId);
+        if (storedOp?.kind === 'snapshot' || storedOp?.kind === 'rollback') {
+            return true;
+        }
+        if (res?.confined !== true) {
+            return false;
+        }
+        const opRoots = storedOp?.mutationRoots || [];
+        if (opRoots.length === 0)
+            return true;
+        return opRoots.every((opr) => targetRoots.some((sr) => isPathContained(sr, opr)));
+    });
+}
+function rollbackCoverage(status, allConfined) {
+    if (status !== 'restored') {
+        return { coverage: status === 'partial' ? 'declared_roots' : 'none', outOfScopeEffects: 'possible' };
+    }
+    if (allConfined()) {
+        return { coverage: 'complete', outOfScopeEffects: 'none_possible' };
+    }
+    return { coverage: 'declared_roots', outOfScopeEffects: 'possible' };
+}
+//# sourceMappingURL=rollback.js.map

package/dist/supervisor/rollback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback.js","sourceRoot":"","sources":["../../src/supervisor/rollback.ts"],"names":[],"mappings":"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"}

package/dist/supervisor/snapshot-ops.d.ts

@@ -0,0 +1,36 @@
+import { ExecutionDomain } from '../domain.js';
+import { Operation, SnapshotDriver, SnapshotOperationResult } from '../types.js';
+import { CapabilityAdmission } from './admission.js';
+import { CaptureSnapshotOptions } from './types.js';
+export interface SnapshotContext {
+    domain: ExecutionDomain;
+    snapshotDriver: SnapshotDriver;
+}
+export declare function sha256Json(value: unknown): string;
+/** 快照 / 回滚这类内核内部操作：登记意图并直接转 active，按需记录 capability 使用。 */
+export declare function activateInternalOperation(domain: ExecutionDomain, op: Operation, capAdmission: CapabilityAdmission | undefined): void;
+/**
+ * 快照捕获协议 (ARCHITECTURE §3.5 / 契约 #32, #53)
+ */
+export declare function captureSnapshot(ctx: SnapshotContext, options: CaptureSnapshotOptions): Promise<SnapshotOperationResult>;
+/**
+ * 分叉工作区 Materialize (ARCHITECTURE §3.5 / 契约 #54)
+ */
+export declare function materialize(ctx: SnapshotContext, snapshotId: string, newRoot: string): Promise<{
+    worktreePath: string;
+}>;
+/**
+ * 回收分叉工作区 Dematerialize (ARCHITECTURE §3.5 / 契约 #54)
+ */
+export declare function dematerialize(ctx: SnapshotContext, newRoot: string, options?: {
+    force?: boolean;
+}): Promise<void>;
+/**
+ * 回收快照：删除驱动侧的私有 ref 与 store 记录，并写 SNAPSHOT_PRUNED。
+ * 宿主按自己的保留策略调用（例如每轮只保留会话基线与当前轮检查点），否则快照 ref 会无限累积。
+ * 未知 id 视为已回收（幂等）；驱动删除失败直接抛出，store 记录保留，便于重试。
+ */
+export declare function pruneSnapshots(ctx: SnapshotContext, snapshotIds: string[], options?: {
+    runId?: string;
+}): Promise<string[]>;
+//# sourceMappingURL=snapshot-ops.d.ts.map

package/dist/supervisor/snapshot-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-ops.d.ts","sourceRoot":"","sources":["../../src/supervisor/snapshot-ops.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAyB,cAAc,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAExG,OAAO,EAAE,mBAAmB,EAAwB,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,cAAc,EAAE,cAAc,CAAC;CAChC;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEjD;AAED,0DAA0D;AAC1D,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,eAAe,EACvB,EAAE,EAAE,SAAS,EACb,YAAY,EAAE,mBAAmB,GAAG,SAAS,GAC5C,IAAI,CAcN;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CA0GlC;AA4BD;;GAEG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,eAAe,EACpB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CAqBnC;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5B,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,eAAe,EACpB,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3B,OAAO,CAAC,MAAM,EAAE,CAAC,CA0BnB"}

package/dist/supervisor/snapshot-ops.js

@@ -0,0 +1,243 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { ResourceConflictError } from '../types.js';
+import { GitShadowSnapshotDriver } from '../snapshot/git-shadow.js';
+import { recordCapabilityUsed } from './admission.js';
+export function sha256Json(value) {
+    return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+/** 快照 / 回滚这类内核内部操作：登记意图并直接转 active，按需记录 capability 使用。 */
+export function activateInternalOperation(domain, op, capAdmission) {
+    domain.registerOperationIntent(op);
+    domain.getStore().updateOperationStatus(op.id, 'active');
+    domain.getStore().recordEventAndTransitionState({
+        domainId: domain.domainId,
+        runId: op.runId,
+        operationId: op.id,
+        type: 'OPERATION_STATUS_TRANSITION',
+        payload: { status: 'active' },
+        timestamp: new Date().toISOString(),
+    });
+    if (op.capabilityId && capAdmission) {
+        recordCapabilityUsed(domain, { runId: op.runId, opId: op.id, capabilityId: op.capabilityId }, capAdmission);
+    }
+}
+/**
+ * 快照捕获协议 (ARCHITECTURE §3.5 / 契约 #32, #53)
+ */
+export async function captureSnapshot(ctx, options) {
+    const { domain, snapshotDriver } = ctx;
+    const startTime = Date.now();
+    let targetRoots = options.roots;
+    let capAdmission;
+    if (options.capabilityId) {
+        capAdmission = domain.checkCapabilityAdmission({
+            capabilityId: options.capabilityId,
+            mutationRoots: targetRoots,
+            runId: options.runId,
+            opId: options.opId,
+        });
+        if (!targetRoots || targetRoots.length === 0) {
+            targetRoots = capAdmission.effectiveMutationRoots;
+        }
+    }
+    if (!targetRoots || targetRoots.length === 0) {
+        throw new Error('captureSnapshot requires at least one root directory');
+    }
+    const realRoots = targetRoots.map((r) => path.resolve(r));
+    const requiredResources = realRoots.map((r) => `workspace:write:${r}`);
+    if (snapshotDriver instanceof GitShadowSnapshotDriver) {
+        try {
+            const { commonDir } = await snapshotDriver.assertGitRepo(realRoots[0]);
+            requiredResources.push(`git:objects:${commonDir}`);
+        }
+        catch { }
+    }
+    const op = {
+        id: options.opId,
+        runId: options.runId,
+        kind: 'snapshot',
+        name: `snapshot:${realRoots[0]}`,
+        inputFingerprint: sha256Json({
+            kind: 'snapshot',
+            roots: realRoots,
+            includeIgnored: !!options.includeIgnored,
+            maxTreeSizeBytes: options.maxTreeSizeBytes,
+            capabilityId: options.capabilityId ?? null,
+        }),
+        requiredResources,
+        mutationRoots: realRoots,
+        capabilityId: options.capabilityId,
+        timeoutMs: options.timeoutMs,
+        status: 'intent_registered',
+    };
+    activateInternalOperation(domain, op, capAdmission);
+    try {
+        const snapRef = await snapshotDriver.capture(realRoots, {
+            id: options.opId,
+            domainId: domain.domainId,
+            opId: options.opId,
+            includeIgnored: options.includeIgnored,
+            maxTreeSizeBytes: options.maxTreeSizeBytes,
+        });
+        const store = domain.getStore();
+        let result;
+        store.transaction(() => {
+            const seq = store.recordEventAndTransitionState({
+                domainId: domain.domainId,
+                runId: options.runId,
+                operationId: options.opId,
+                type: 'SNAPSHOT_CAPTURED',
+                payload: {
+                    snapshotId: snapRef.id,
+                    roots: snapRef.roots,
+                    treeFingerprint: snapRef.treeFingerprint,
+                    commitHash: snapRef.commitHash,
+                },
+                timestamp: new Date().toISOString(),
+            });
+            snapRef.journalSeq = seq;
+            store.recordSnapshot(snapRef);
+            result = {
+                kind: 'snapshot',
+                status: 'succeeded',
+                snapshot: snapRef,
+                capabilityId: options.capabilityId,
+                durationMs: Date.now() - startTime,
+                completedAt: new Date().toISOString(),
+            };
+            store.recordOperationResult(options.opId, result);
+            store.updateOperationStatus(options.opId, 'done');
+            store.recordEventAndTransitionState({
+                domainId: domain.domainId,
+                runId: options.runId,
+                operationId: options.opId,
+                type: 'OPERATION_RESULT_RECORDED',
+                payload: { status: 'succeeded', snapshotId: snapRef.id },
+                timestamp: new Date().toISOString(),
+            });
+        });
+        domain.internalReleaseResources(options.opId);
+        return result;
+    }
+    catch (err) {
+        throw recordFailedSnapshot(domain, options.opId, err, startTime);
+    }
+}
+/** 记录失败快照并释放租约；返回调用方应抛出的错误（失败事实没能落盘时要让调用方知道）。 */
+function recordFailedSnapshot(domain, opId, err, startTime) {
+    const failResult = {
+        kind: 'snapshot',
+        status: 'failed',
+        errorMessage: err.message,
+        durationMs: Date.now() - startTime,
+        completedAt: new Date().toISOString(),
+    };
+    let recordError;
+    try {
+        domain.getStore().recordOperationResult(opId, failResult);
+        domain.getStore().updateOperationStatus(opId, 'done');
+    }
+    catch (recErr) {
+        recordError = recErr;
+    }
+    domain.internalReleaseResources(opId);
+    if (recordError === undefined) {
+        return err;
+    }
+    const recMsg = recordError instanceof Error ? recordError.message : String(recordError);
+    return new Error(`${err.message} (additionally, recording the failed snapshot result failed: ${recMsg})`, {
+        cause: err,
+    });
+}
+/**
+ * 分叉工作区 Materialize (ARCHITECTURE §3.5 / 契约 #54)
+ */
+export async function materialize(ctx, snapshotId, newRoot) {
+    const { domain, snapshotDriver } = ctx;
+    const absNewRoot = path.resolve(newRoot);
+    const writeRes = `workspace:write:${absNewRoot}`;
+    if (domain.isResourceLocked(writeRes)) {
+        throw new ResourceConflictError(writeRes, domain.getResourceOwner(writeRes) || 'unknown', 'materialize');
+    }
+    const opId = `mat-${snapshotId}-${Date.now()}`;
+    domain.allocateResources(opId, [writeRes]);
+    try {
+        if (!snapshotDriver.materialize) {
+            throw new Error(`Snapshot driver ${snapshotDriver.name} does not support materialize`);
+        }
+        const snapshot = domain.getStore().getSnapshot(snapshotId);
+        const repoRoot = snapshot?.roots[0];
+        return await snapshotDriver.materialize(snapshotId, absNewRoot, { repoRoot });
+    }
+    catch (err) {
+        domain.internalReleaseResources(opId);
+        throw err;
+    }
+}
+/**
+ * 回收分叉工作区 Dematerialize (ARCHITECTURE §3.5 / 契约 #54)
+ */
+export async function dematerialize(ctx, newRoot, options) {
+    const { domain, snapshotDriver } = ctx;
+    const absNewRoot = path.resolve(newRoot);
+    let realNewRoot = absNewRoot;
+    try {
+        realNewRoot = fs.realpathSync(absNewRoot);
+    }
+    catch { }
+    if (!snapshotDriver.dematerialize) {
+        throw new Error(`Snapshot driver ${snapshotDriver.name} does not support dematerialize`);
+    }
+    await snapshotDriver.dematerialize(absNewRoot, options);
+    const writeRes = `workspace:write:${absNewRoot}`;
+    const writeResReal = `workspace:write:${realNewRoot}`;
+    const owner1 = domain.getResourceOwner(writeRes);
+    const owner2 = domain.getResourceOwner(writeResReal);
+    if (owner1) {
+        domain.internalReleaseResources(owner1, [writeRes]);
+    }
+    if (owner2 && owner2 !== owner1) {
+        domain.internalReleaseResources(owner2, [writeResReal]);
+    }
+    const leases = domain.getStore().getPersistedResourceLeases(domain.domainId);
+    for (const lease of leases) {
+        if (lease.resourceId === writeRes || lease.resourceId === writeResReal) {
+            domain.internalReleaseResources(lease.operationId, [lease.resourceId]);
+        }
+    }
+}
+/**
+ * 回收快照：删除驱动侧的私有 ref 与 store 记录，并写 SNAPSHOT_PRUNED。
+ * 宿主按自己的保留策略调用（例如每轮只保留会话基线与当前轮检查点），否则快照 ref 会无限累积。
+ * 未知 id 视为已回收（幂等）；驱动删除失败直接抛出，store 记录保留，便于重试。
+ */
+export async function pruneSnapshots(ctx, snapshotIds, options) {
+    const { domain, snapshotDriver } = ctx;
+    const store = domain.getStore();
+    const pruned = [];
+    for (const id of snapshotIds) {
+        const snapshot = store.getSnapshot(id);
+        if (!snapshot)
+            continue;
+        store.verifyEpochFencing(domain.domainId);
+        const repoRoot = snapshotDriver instanceof GitShadowSnapshotDriver
+            ? (await snapshotDriver.assertGitRepo(snapshot.roots[0])).repoRoot
+            : undefined;
+        await snapshotDriver.prune([id], { repoRoot });
+        store.transaction(() => {
+            store.deleteSnapshot(id);
+            store.recordEventAndTransitionState({
+                domainId: domain.domainId,
+                runId: options?.runId,
+                type: 'SNAPSHOT_PRUNED',
+                payload: { snapshotId: id, roots: snapshot.roots },
+                timestamp: new Date().toISOString(),
+            });
+        });
+        pruned.push(id);
+    }
+    return pruned;
+}
+//# sourceMappingURL=snapshot-ops.js.map

package/dist/supervisor/snapshot-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-ops.js","sourceRoot":"","sources":["../../src/supervisor/snapshot-ops.ts"],"names":[],"mappings":"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"}