newmark-agent 0.6.2 → 0.6.4

package/dist/core/continuation/store.js

@@ -0,0 +1,1077 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardedContinuationStore = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+const contracts_1 = require("./contracts");
+/**
+ * Single-writer continuation ledger for one workspace.
+ *
+ * The spec's reference uses SQLite. This implementation keeps the same
+ * boundaries with a lock-file + atomic-replace JSON ledger because the project
+ * does not ship a native SQLite module and an Electron native dependency would
+ * change the packaging/signing contract. All continuation writes must go
+ * through this class; callers never mutate the ledger directly.
+ */
+class GuardedContinuationStore {
+    workspacePath;
+    workspaceId;
+    ledgerPath;
+    lockPath;
+    leaseMs;
+    eventRetention;
+    fingerprint = '';
+    cached = null;
+    constructor(workspacePath, workspaceId, options = {}) {
+        this.workspacePath = workspacePath;
+        this.workspaceId = workspaceId;
+        this.ledgerPath = path.join(path.resolve(workspacePath), 'conversations', 'continuation-ledger.json');
+        this.lockPath = `${this.ledgerPath}.lock`;
+        this.leaseMs = Math.max(5_000, Math.floor(options.leaseMs || 60_000));
+        this.eventRetention = Math.max(200, Math.floor(options.eventRetention || 5_000));
+    }
+    get filePath() {
+        return this.ledgerPath;
+    }
+    ensureRoot(rootId, defaultBranchId) {
+        this.mutate(ledger => {
+            if (!ledger.roots[rootId]) {
+                ledger.roots[rootId] = {
+                    rootId,
+                    workspaceId: this.workspaceId,
+                    defaultBranchId,
+                    createdAt: new Date().toISOString(),
+                };
+            }
+            this.ensureBranchRecord(ledger, { rootId, branchId: defaultBranchId, parentAnchorBuildId: null });
+        });
+    }
+    ensureBranch(input) {
+        return this.mutate(ledger => this.ensureBranchRecord(ledger, input));
+    }
+    getReceipt(actorId, commandId) {
+        return this.readLedger().commands[(0, contracts_1.commandKey)(actorId, commandId)];
+    }
+    enqueueBuild(command) {
+        if (!command.target?.workspaceId || !command.target.expectedRootId || !command.target.branchId) {
+            throw new contracts_1.ContinuationError('TARGET_REQUIRED', 'workspaceId, expectedRootId and branchId are required');
+        }
+        if (command.target.workspaceId !== this.workspaceId) {
+            throw new contracts_1.ContinuationError('ROUTE_MISMATCH', `Command workspace ${command.target.workspaceId} does not match ledger workspace ${this.workspaceId}`);
+        }
+        const hash = (0, contracts_1.requestHash)(command);
+        return this.mutate(ledger => {
+            const key = (0, contracts_1.commandKey)(command.actorId, command.commandId);
+            const existing = ledger.commands[key];
+            if (existing) {
+                if (existing.requestHash !== hash) {
+                    throw new contracts_1.ContinuationError('IDEMPOTENCY_KEY_REUSE', `Command ${command.commandId} was already used with a different request`, { commandId: command.commandId });
+                }
+                return { ...existing, duplicate: true };
+            }
+            const branch = this.requireBranch(ledger, {
+                workspaceId: command.target.workspaceId,
+                rootId: command.target.expectedRootId,
+                branchId: command.target.branchId,
+            });
+            if (branch.queueRevision !== command.expectedQueueRevision) {
+                throw new contracts_1.ContinuationError('QUEUE_REVISION_CONFLICT', `Queue revision ${command.expectedQueueRevision} is stale; authoritative revision is ${branch.queueRevision}`, {
+                    expected: command.expectedQueueRevision,
+                    actual: branch.queueRevision,
+                });
+            }
+            if ((branch.tailBuildId || null) !== (command.expectedTailBuildId || null)) {
+                throw new contracts_1.ContinuationError('QUEUE_REVISION_CONFLICT', `Expected tail ${command.expectedTailBuildId || 'null'} does not match authoritative tail ${branch.tailBuildId || 'null'}`, {
+                    expected: command.expectedTailBuildId,
+                    actual: branch.tailBuildId,
+                });
+            }
+            const parentBuildId = branch.tailBuildId;
+            const parent = parentBuildId ? ledger.builds[parentBuildId] : null;
+            if (parentBuildId && (!parent || parent.branchId !== branch.branchId)) {
+                throw new contracts_1.ContinuationError('ROUTE_MISMATCH', `Branch tail ${parentBuildId} is not owned by branch ${branch.branchId}`);
+            }
+            const buildId = `build-${(0, crypto_1.randomUUID)()}`;
+            const queueSequence = ledger.nextQueueSequence++;
+            const now = new Date().toISOString();
+            const build = {
+                buildId,
+                workspaceId: this.workspaceId,
+                rootId: branch.rootId,
+                branchId: branch.branchId,
+                parentBuildId,
+                inputHash: (0, contracts_1.buildInputHash)(command.input),
+                input: cloneInput(command.input),
+                recipeSnapshotId: command.recipeSnapshotId,
+                status: 'QUEUED',
+                queueSequence,
+                createdAt: now,
+                updatedAt: now,
+            };
+            ledger.builds[buildId] = build;
+            branch.tailBuildId = buildId;
+            branch.queueRevision += 1;
+            branch.lifecycleRevision += 1;
+            branch.updatedAt = now;
+            const receipt = {
+                schemaVersion: 1,
+                commandId: command.commandId,
+                requestHash: hash,
+                workspaceId: this.workspaceId,
+                rootId: branch.rootId,
+                branchId: branch.branchId,
+                buildId,
+                parentBuildId,
+                queueSequence,
+                queueRevision: branch.queueRevision,
+                lifecycleRevision: branch.lifecycleRevision,
+                acceptedAt: now,
+            };
+            ledger.commands[key] = receipt;
+            this.appendEvent(ledger, {
+                type: 'BuildAccepted',
+                workspaceId: this.workspaceId,
+                rootId: branch.rootId,
+                branchId: branch.branchId,
+                buildId,
+                attemptId: null,
+                fence: null,
+                payload: { parentBuildId, queueSequence, inputHash: build.inputHash },
+            });
+            return receipt;
+        });
+    }
+    claimBuild(input) {
+        return this.mutate(ledger => {
+            const branch = this.requireBranch(ledger, input);
+            if (branch.paused)
+                throw new contracts_1.ContinuationError('BRANCH_PAUSED', `Branch ${branch.branchId} is paused`);
+            const now = input.now ?? Date.now();
+            const guard = this.ensureGuard(ledger, branch.branchId);
+            if (guard.activeBuildId && guard.leaseUntil > now) {
+                return null;
+            }
+            if (guard.activeBuildId)
+                this.releaseExpiredGuard(ledger, branch, guard, now);
+            const candidate = Object.values(ledger.builds)
+                .filter(build => build.branchId === branch.branchId && build.status === 'QUEUED')
+                .sort((a, b) => a.queueSequence - b.queueSequence)
+                .find(build => {
+                if ((branch.headBuildId || null) !== (build.parentBuildId || null))
+                    return false;
+                const parent = build.parentBuildId ? ledger.builds[build.parentBuildId] : null;
+                return !parent || parent.status === 'SUCCEEDED';
+            });
+            if (!candidate)
+                return null;
+            const attemptId = `attempt-${(0, crypto_1.randomUUID)()}`;
+            const fence = guard.fence + 1;
+            const leaseUntil = now + this.leaseMs;
+            const attempt = {
+                attemptId,
+                buildId: candidate.buildId,
+                branchId: branch.branchId,
+                fence,
+                status: 'RUNNING',
+                leaseUntil,
+                workerCapability: String(input.workerCapability || 'unknown'),
+                startedAt: new Date(now).toISOString(),
+            };
+            ledger.attempts[attemptId] = attempt;
+            ledger.guards[branch.branchId] = {
+                branchId: branch.branchId,
+                activeBuildId: candidate.buildId,
+                activeAttemptId: attemptId,
+                fence,
+                leaseUntil,
+                workerCapability: attempt.workerCapability,
+            };
+            candidate.status = 'RUNNING';
+            candidate.updatedAt = attempt.startedAt;
+            candidate.waitingReason = undefined;
+            branch.lifecycleRevision += 1;
+            branch.updatedAt = attempt.startedAt;
+            this.appendEvent(ledger, {
+                type: 'AttemptStarted',
+                workspaceId: this.workspaceId,
+                rootId: branch.rootId,
+                branchId: branch.branchId,
+                buildId: candidate.buildId,
+                attemptId,
+                fence,
+                payload: { parentBuildId: candidate.parentBuildId, workerCapability: attempt.workerCapability },
+            });
+            return {
+                workspaceId: this.workspaceId,
+                rootId: branch.rootId,
+                branchId: branch.branchId,
+                buildId: candidate.buildId,
+                attemptId,
+                fence,
+                parentBuildId: candidate.parentBuildId,
+                baseContextSnapshotId: candidate.recipeSnapshotId,
+                environmentSnapshotId: candidate.recipeSnapshotId,
+                workerCapability: attempt.workerCapability,
+            };
+        });
+    }
+    updateQueuedBuild(input) {
+        return this.mutate(ledger => {
+            const build = ledger.builds[input.buildId];
+            if (!build)
+                throw new contracts_1.ContinuationError('UNKNOWN_BUILD', `Build ${input.buildId} does not exist`);
+            if (build.workspaceId !== this.workspaceId || (input.rootId && build.rootId !== input.rootId)) {
+                throw new contracts_1.ContinuationError('ROUTE_MISMATCH', `Build ${input.buildId} does not belong to workspace/root ${this.workspaceId}/${input.rootId}`);
+            }
+            const branch = ledger.branches[build.branchId];
+            if (!branch)
+                throw new contracts_1.ContinuationError('UNKNOWN_BRANCH', `Build ${input.buildId} references missing branch ${build.branchId}`);
+            if (build.status !== 'QUEUED')
+                throw new contracts_1.ContinuationError('BUILD_NOT_READY', `Build ${build.buildId} is ${build.status}; only QUEUED builds can be edited`);
+            build.input = cloneInput(input.input);
+            build.inputHash = (0, contracts_1.buildInputHash)(build.input);
+            build.updatedAt = new Date().toISOString();
+            branch.queueRevision += 1;
+            branch.lifecycleRevision += 1;
+            branch.updatedAt = build.updatedAt;
+            return { ...build, input: cloneInput(build.input) };
+        });
+    }
+    /**
+     * dev-0.6.4 hotfix: 当某个被受理的 Build 失败/取消后，它的后继会永远无法被
+     * claim（`claimBuild` 只认「父 = 已提交 frontier」），整条队列就此卡死，新提交
+     * 也只是接在失败链后面。
+     *
+     * 这里提供一条**显式**修复通道：把被阻断的排队 Build 重新挂到当前已提交的
+     * frontier 上，保持原有队列顺序，并为每一次改挂写入 `BuildQueueRepaired`
+     * 审计事件（记录旧 parent / 新 parent / 原因）。它不是静默 rebase：调用方是
+     * 用户的显式动作（恢复队列）或一次新的入队命令。
+     */
+    repairBlockedQueue(input) {
+        return this.mutate(ledger => {
+            const branch = this.requireBranch(ledger, input);
+            const frontier = branch.headBuildId || null;
+            const queued = Object.values(ledger.builds)
+                .filter(build => build.branchId === branch.branchId && build.status === 'QUEUED')
+                .sort((a, b) => a.queueSequence - b.queueSequence);
+            const repaired = [];
+            let chainParent = frontier;
+            let mutated = false;
+            for (const build of queued) {
+                if ((build.parentBuildId || null) !== (chainParent || null)) {
+                    const previousParentBuildId = build.parentBuildId;
+                    build.parentBuildId = chainParent;
+                    build.waitingReason = undefined;
+                    build.updatedAt = new Date().toISOString();
+                    repaired.push(build.buildId);
+                    mutated = true;
+                    this.appendEvent(ledger, {
+                        type: 'BuildQueueRepaired',
+                        workspaceId: this.workspaceId,
+                        rootId: branch.rootId,
+                        branchId: branch.branchId,
+                        buildId: build.buildId,
+                        attemptId: null,
+                        fence: null,
+                        payload: {
+                            previousParentBuildId,
+                            newParentBuildId: chainParent,
+                            reason: String(input.reason || 'committed-frontier-repair'),
+                        },
+                    });
+                }
+                chainParent = build.buildId;
+            }
+            if (mutated) {
+                branch.queueRevision += 1;
+                branch.lifecycleRevision += 1;
+                branch.updatedAt = new Date().toISOString();
+            }
+            return { repaired, frontier };
+        });
+    }
+    /**
+     * dev-0.6.4 hotfix: 读取视角的受阻推导。
+     *
+     * 一个 QUEUED Build 只有在它的父正好是「已提交 frontier」或队列里位于它之前
+     * 的可执行 Build 时才可能被 claim（见 `claimBuild`）。这里按队列顺序推导哪些行
+     * 目前不可执行：父不是链上前驱、或父已 FAILED/CANCELLED 的行即为受阻，且受阻点
+     * 之后的所有行同样受阻。
+     */
+    blockedQueuedBuildIds(ledger, branch) {
+        const blocked = new Set();
+        const queued = Object.values(ledger.builds)
+            .filter(build => build.branchId === branch.branchId && build.status === 'QUEUED')
+            .sort((a, b) => a.queueSequence - b.queueSequence);
+        let chainParent = branch.headBuildId || null;
+        for (const build of queued) {
+            const parent = build.parentBuildId ? ledger.builds[build.parentBuildId] : null;
+            // 链上的前驱（frontier 或队列里位于它之前的行）在执行时已经提交，因此只有
+            // 「父不是链上前驱」或「父已 FAILED/CANCELLED」的行才是真正受阻的。
+            const parentIsChainPredecessor = (build.parentBuildId || null) === (chainParent || null);
+            const parentFailed = !!parent && (parent.status === 'FAILED' || parent.status === 'CANCELLED');
+            if (!parentIsChainPredecessor || parentFailed) {
+                blocked.add(build.buildId);
+                continue;
+            }
+            chainParent = build.buildId;
+        }
+        return blocked;
+    }
+    deleteQueuedBuild(input) {
+        this.mutate(ledger => {
+            const build = ledger.builds[input.buildId];
+            if (!build)
+                throw new contracts_1.ContinuationError('UNKNOWN_BUILD', `Build ${input.buildId} does not exist`);
+            if (build.workspaceId !== this.workspaceId || (input.rootId && build.rootId !== input.rootId)) {
+                throw new contracts_1.ContinuationError('ROUTE_MISMATCH', `Build ${input.buildId} does not belong to workspace/root ${this.workspaceId}/${input.rootId}`);
+            }
+            const branch = ledger.branches[build.branchId];
+            if (!branch)
+                throw new contracts_1.ContinuationError('UNKNOWN_BRANCH', `Build ${input.buildId} references missing branch ${build.branchId}`);
+            if (build.status !== 'QUEUED')
+                throw new contracts_1.ContinuationError('BUILD_NOT_READY', `Build ${build.buildId} is ${build.status}; only QUEUED builds can be deleted`);
+            if (Object.values(ledger.builds).some(item => item.parentBuildId === build.buildId)) {
+                throw new contracts_1.ContinuationError('ANCHOR_NOT_COMMITTED', `Build ${build.buildId} still has queued successors; delete them from the tail first`);
+            }
+            if (branch.tailBuildId === build.buildId)
+                branch.tailBuildId = build.parentBuildId;
+            delete ledger.builds[build.buildId];
+            branch.queueRevision += 1;
+            branch.lifecycleRevision += 1;
+            branch.updatedAt = new Date().toISOString();
+        });
+    }
+    reorderQueuedBuilds(input) {
+        return this.mutate(ledger => {
+            const branch = this.requireBranch(ledger, input);
+            const queued = Object.values(ledger.builds)
+                .filter(build => build.branchId === branch.branchId && build.status === 'QUEUED')
+                .sort((a, b) => a.queueSequence - b.queueSequence);
+            // continuation-v1 fixes parentBuildId at admission. Reordering admitted
+            // builds would silently change the context chain, so it is rejected.
+            // Changing the order requires explicit cancel + new commands.
+            throw new contracts_1.ContinuationError('ANCHOR_NOT_COMMITTED', `Branch ${branch.branchId} has ${queued.length} admitted queued build(s); reordering would change their fixed parents. Cancel the suffix and submit it as new commands.`, { branchId: branch.branchId, queuedBuildIds: queued.map(build => build.buildId) });
+        });
+    }
+    heartbeat(scope, now = Date.now()) {
+        return this.mutate(ledger => {
+            const guard = ledger.guards[scope.branchId];
+            const attempt = ledger.attempts[scope.attemptId];
+            if (!guard || !attempt
+                || guard.activeBuildId !== scope.buildId
+                || guard.activeAttemptId !== scope.attemptId
+                || guard.fence !== scope.fence
+                || attempt.fence !== scope.fence
+                || attempt.status !== 'RUNNING'
+                || guard.leaseUntil <= now) {
+                this.appendEvent(ledger, {
+                    type: 'StaleWriteRejected',
+                    workspaceId: this.workspaceId,
+                    rootId: ledger.builds[scope.buildId]?.rootId || '',
+                    branchId: scope.branchId,
+                    buildId: scope.buildId,
+                    attemptId: scope.attemptId,
+                    fence: scope.fence,
+                    payload: { operation: 'heartbeat' },
+                });
+                return false;
+            }
+            const leaseUntil = now + this.leaseMs;
+            attempt.leaseUntil = leaseUntil;
+            guard.leaseUntil = leaseUntil;
+            this.appendEvent(ledger, {
+                type: 'AttemptHeartbeat',
+                workspaceId: this.workspaceId,
+                rootId: ledger.builds[scope.buildId]?.rootId || '',
+                branchId: scope.branchId,
+                buildId: scope.buildId,
+                attemptId: scope.attemptId,
+                fence: scope.fence,
+                payload: { leaseUntil },
+            });
+            return true;
+        });
+    }
+    commitFinal(input) {
+        return this.mutate(ledger => {
+            const { scope } = input;
+            const branch = this.requireBranch(ledger, scope);
+            const build = ledger.builds[scope.buildId];
+            const attempt = ledger.attempts[scope.attemptId];
+            const guard = ledger.guards[scope.branchId];
+            const now = input.now ?? Date.now();
+            if (!build || build.branchId !== scope.branchId || build.rootId !== scope.rootId) {
+                throw new contracts_1.ContinuationError('UNKNOWN_BUILD', `Build ${scope.buildId} does not belong to branch ${scope.branchId}`);
+            }
+            if (ledger.finals[build.buildId]) {
+                throw new contracts_1.ContinuationError('FINAL_ALREADY_COMMITTED', `Build ${build.buildId} already has an immutable final`, { final: ledger.finals[build.buildId] });
+            }
+            if (!attempt || !guard
+                || guard.activeBuildId !== scope.buildId
+                || guard.activeAttemptId !== scope.attemptId
+                || guard.fence !== scope.fence
+                || attempt.fence !== scope.fence
+                || attempt.status !== 'RUNNING'
+                || guard.leaseUntil <= now) {
+                this.appendEvent(ledger, {
+                    type: 'StaleWriteRejected',
+                    workspaceId: this.workspaceId,
+                    rootId: branch.rootId,
+                    branchId: branch.branchId,
+                    buildId: build.buildId,
+                    attemptId: scope.attemptId,
+                    fence: scope.fence,
+                    payload: { operation: 'commit_final' },
+                });
+                throw new contracts_1.ContinuationError('STALE_EXECUTION', `Attempt ${scope.attemptId} no longer owns branch ${branch.branchId}`);
+            }
+            if ((branch.headBuildId || null) !== (build.parentBuildId || null)) {
+                throw new contracts_1.ContinuationError('ANCHOR_NOT_COMMITTED', `Build ${build.buildId} parent ${build.parentBuildId || 'null'} is not the current head ${branch.headBuildId || 'null'}`);
+            }
+            const final = {
+                finalId: `final-${(0, crypto_1.randomUUID)()}`,
+                buildId: build.buildId,
+                branchId: branch.branchId,
+                finalHash: String(input.finalHash || (0, crypto_1.createHash)('sha256').update(String(input.text || '')).digest('hex').slice(0, 24)),
+                stateSnapshotId: String(input.stateSnapshotId || build.recipeSnapshotId),
+                text: String(input.text || ''),
+                committedAt: new Date(now).toISOString(),
+            };
+            ledger.finals[build.buildId] = final;
+            build.status = 'SUCCEEDED';
+            build.finalId = final.finalId;
+            build.updatedAt = final.committedAt;
+            attempt.status = 'COMPLETED';
+            attempt.endedAt = final.committedAt;
+            branch.headBuildId = build.buildId;
+            branch.lifecycleRevision += 1;
+            branch.updatedAt = final.committedAt;
+            this.releaseGuard(ledger, branch.branchId, attempt.fence);
+            this.appendEvent(ledger, {
+                type: 'BuildCommitted',
+                workspaceId: this.workspaceId,
+                rootId: branch.rootId,
+                branchId: branch.branchId,
+                buildId: build.buildId,
+                attemptId: attempt.attemptId,
+                fence: attempt.fence,
+                payload: { finalId: final.finalId, finalHash: final.finalHash, headBuildId: branch.headBuildId },
+            });
+            return final;
+        });
+    }
+    /**
+     * Trusted external-owner completion.
+     *
+     * A Flow is a kernel-owned external run, not a leased model worker. It still
+     * has to be a durable build so queued Goal/Next successors have a committed
+     * parent. This path validates the parent/head relation transactionally but
+     * does not require a BranchGuard attempt; the kernel owns the Flow lifetime.
+     * If the build is not the next ready build, it stays QUEUED and the caller
+     * must retry after the predecessor commits.
+     */
+    commitExternalBuild(input) {
+        return this.mutate(ledger => {
+            const branch = this.requireBranch(ledger, input);
+            const build = ledger.builds[input.buildId];
+            if (!build || build.branchId !== branch.branchId)
+                throw new contracts_1.ContinuationError('UNKNOWN_BUILD', `Build ${input.buildId} is not in branch ${branch.branchId}`);
+            if (build.status === 'SUCCEEDED')
+                return true;
+            if (build.status !== 'QUEUED')
+                throw new contracts_1.ContinuationError('BUILD_NOT_READY', `External build ${build.buildId} is ${build.status}`);
+            if ((branch.headBuildId || null) !== (build.parentBuildId || null))
+                return false;
+            const now = input.now ?? Date.now();
+            const committedAt = new Date(now).toISOString();
+            const final = {
+                finalId: `final-${(0, crypto_1.randomUUID)()}`,
+                buildId: build.buildId,
+                branchId: branch.branchId,
+                finalHash: (0, crypto_1.createHash)('sha256').update(String(input.text || '')).digest('hex').slice(0, 24),
+                stateSnapshotId: build.recipeSnapshotId,
+                text: String(input.text || ''),
+                committedAt,
+            };
+            ledger.finals[build.buildId] = final;
+            build.status = 'SUCCEEDED';
+            build.finalId = final.finalId;
+            build.updatedAt = committedAt;
+            branch.headBuildId = build.buildId;
+            branch.lifecycleRevision += 1;
+            branch.updatedAt = committedAt;
+            this.appendEvent(ledger, {
+                type: 'BuildCommitted',
+                workspaceId: this.workspaceId,
+                rootId: branch.rootId,
+                branchId: branch.branchId,
+                buildId: build.buildId,
+                attemptId: null,
+                fence: null,
+                payload: { finalId: final.finalId, finalHash: final.finalHash, externalOwner: true, headBuildId: branch.headBuildId },
+            });
+            return true;
+        });
+    }
+    /**
+     * Claim a new attempt for an existing external Flow build (suspend/resume).
+     * The build identity and fixed parent are preserved; only the attempt/fence
+     * advance. This is the external-owner equivalent of retryBuild.
+     */
+    claimExternalBuild(input) {
+        return this.mutate(ledger => {
+            const branch = this.requireBranch(ledger, input);
+            const build = ledger.builds[input.buildId];
+            if (!build || build.branchId !== branch.branchId)
+                throw new contracts_1.ContinuationError('UNKNOWN_BUILD', `Build ${input.buildId} is not in branch ${branch.branchId}`);
+            if (build.status === 'SUCCEEDED')
+                throw new contracts_1.ContinuationError('FINAL_ALREADY_COMMITTED', `Build ${build.buildId} already committed`);
+            if (build.status !== 'QUEUED')
+                throw new contracts_1.ContinuationError('BUILD_NOT_READY', `External build ${build.buildId} is ${build.status}`);
+            if ((branch.headBuildId || null) !== (build.parentBuildId || null)) {
+                throw new contracts_1.ContinuationError('ANCHOR_NOT_COMMITTED', `External build ${build.buildId} parent is not the current head`);
+            }
+            const now = input.now ?? Date.now();
+            const guard = this.ensureGuard(ledger, branch.branchId);
+            const attemptId = `attempt-${(0, crypto_1.randomUUID)()}`;
+            const fence = guard.fence + 1;
+            const leaseUntil = now + this.leaseMs;
+            const attempt = {
+                attemptId,
+                buildId: build.buildId,
+                branchId: branch.branchId,
+                fence,
+                status: 'RUNNING',
+                leaseUntil,
+                workerCapability: String(input.workerCapability || 'flow-external'),
+                startedAt: new Date(now).toISOString(),
+            };
+            ledger.attempts[attemptId] = attempt;
+            ledger.guards[branch.branchId] = {
+                branchId: branch.branchId,
+                activeBuildId: build.buildId,
+                activeAttemptId: attemptId,
+                fence,
+                leaseUntil,
+                workerCapability: attempt.workerCapability,
+            };
+            build.status = 'RUNNING';
+            build.updatedAt = attempt.startedAt;
+            branch.lifecycleRevision += 1;
+            this.appendEvent(ledger, {
+                type: 'AttemptStarted',
+                workspaceId: this.workspaceId,
+                rootId: branch.rootId,
+                branchId: branch.branchId,
+                buildId: build.buildId,
+                attemptId,
+                fence,
+                payload: { externalOwner: true, workerCapability: attempt.workerCapability },
+            });
+            return {
+                workspaceId: this.workspaceId,
+                rootId: branch.rootId,
+                branchId: branch.branchId,
+                buildId: build.buildId,
+                attemptId,
+                fence,
+                parentBuildId: build.parentBuildId,
+                baseContextSnapshotId: build.recipeSnapshotId,
+                environmentSnapshotId: build.recipeSnapshotId,
+                workerCapability: attempt.workerCapability,
+            };
+        });
+    }
+    failBuild(input) {
+        this.terminateAttempt(input.scope, 'FAILED', input.reason, input.now);
+    }
+    cancelBuild(input) {
+        this.mutate(ledger => {
+            const branch = this.requireBranch(ledger, input);
+            const build = ledger.builds[input.buildId];
+            if (!build || build.branchId !== branch.branchId)
+                throw new contracts_1.ContinuationError('UNKNOWN_BUILD', `Build ${input.buildId} is not in branch ${branch.branchId}`);
+            if (build.status === 'SUCCEEDED')
+                throw new contracts_1.ContinuationError('FINAL_ALREADY_COMMITTED', `Build ${input.buildId} already committed`);
+            const guard = this.ensureGuard(ledger, branch.branchId);
+            if (guard.activeBuildId === build.buildId) {
+                const attempt = guard.activeAttemptId ? ledger.attempts[guard.activeAttemptId] : undefined;
+                if (attempt) {
+                    attempt.status = 'CANCELLED';
+                    attempt.endedAt = new Date(input.now ?? Date.now()).toISOString();
+                }
+                this.releaseGuard(ledger, branch.branchId, guard.fence);
+            }
+            build.status = 'CANCELLED';
+            build.updatedAt = new Date(input.now ?? Date.now()).toISOString();
+            branch.lifecycleRevision += 1;
+            this.markDependentsBlocked(ledger, branch, build.buildId);
+            this.appendEvent(ledger, {
+                type: 'BuildCancelled',
+                workspaceId: this.workspaceId,
+                rootId: branch.rootId,
+                branchId: branch.branchId,
+                buildId: build.buildId,
+                attemptId: null,
+                fence: null,
+            });
+        });
+    }
+    retryBuild(input) {
+        return this.mutate(ledger => {
+            const branch = this.requireBranch(ledger, input);
+            const build = ledger.builds[input.buildId];
+            if (!build || build.branchId !== branch.branchId)
+                throw new contracts_1.ContinuationError('UNKNOWN_BUILD', `Build ${input.buildId} is not in branch ${branch.branchId}`);
+            if (build.status !== 'FAILED' && build.status !== 'CANCELLED') {
+                throw new contracts_1.ContinuationError('BUILD_NOT_READY', `Build ${build.buildId} is ${build.status}; only FAILED/CANCELLED builds can be retried`);
+            }
+            if (this.hasCommittedDescendant(ledger, build.buildId)) {
+                throw new contracts_1.ContinuationError('ANCHOR_NOT_COMMITTED', `Build ${build.buildId} already has a committed descendant`);
+            }
+            build.status = 'QUEUED';
+            build.updatedAt = new Date().toISOString();
+            branch.lifecycleRevision += 1;
+            return { ...build, input: cloneInput(build.input) };
+        });
+    }
+    /**
+     * Idempotent failure recovery for an input that was never accepted.
+     *
+     * Stop/archive may release the branch guard before the runtime reports the
+     * failure. In that case the build is still the same durable row and must be
+     * returned to QUEUED for an explicit resume instead of being stranded in
+     * RUNNING (or permanently FAILED). A committed build is never requeued.
+     */
+    requeueBuild(input) {
+        return this.mutate(ledger => {
+            const branch = this.requireBranch(ledger, input);
+            const build = ledger.builds[input.buildId];
+            if (!build || build.branchId !== branch.branchId)
+                throw new contracts_1.ContinuationError('UNKNOWN_BUILD', `Build ${input.buildId} is not in branch ${branch.branchId}`);
+            if (build.status === 'SUCCEEDED')
+                throw new contracts_1.ContinuationError('FINAL_ALREADY_COMMITTED', `Build ${build.buildId} already committed and cannot be requeued`);
+            const guard = this.ensureGuard(ledger, branch.branchId);
+            if (guard.activeBuildId === build.buildId) {
+                const attempt = guard.activeAttemptId ? ledger.attempts[guard.activeAttemptId] : undefined;
+                if (attempt && attempt.status === 'RUNNING') {
+                    attempt.status = 'EXPIRED';
+                    attempt.endedAt = new Date().toISOString();
+                }
+                this.releaseGuard(ledger, branch.branchId, guard.fence);
+            }
+            build.status = 'QUEUED';
+            build.waitingReason = undefined;
+            build.updatedAt = new Date().toISOString();
+            branch.lifecycleRevision += 1;
+            branch.updatedAt = build.updatedAt;
+            return { ...build, input: cloneInput(build.input) };
+        });
+    }
+    forkBranch(input) {
+        const hash = (0, crypto_1.createHash)('sha256').update(JSON.stringify(input)).digest('hex');
+        return this.mutate(ledger => {
+            const key = (0, contracts_1.commandKey)(input.actorId, input.commandId);
+            const existing = ledger.commands[key];
+            if (existing) {
+                if (existing.requestHash !== hash)
+                    throw new contracts_1.ContinuationError('IDEMPOTENCY_KEY_REUSE', `Command ${input.commandId} was already used with a different fork request`);
+                return { ...ledger.branches[existing.branchId] };
+            }
+            const source = this.requireBranch(ledger, { workspaceId: input.workspaceId, rootId: '', branchId: input.sourceBranchId });
+            const anchor = ledger.builds[input.anchorBuildId];
+            if (!anchor || anchor.branchId !== source.branchId || anchor.status !== 'SUCCEEDED') {
+                throw new contracts_1.ContinuationError('ANCHOR_NOT_COMMITTED', `Anchor ${input.anchorBuildId} is not a committed build of source branch ${source.branchId}`);
+            }
+            if (!this.isAncestorOfHead(ledger, source, anchor.buildId)) {
+                throw new contracts_1.ContinuationError('ANCHOR_NOT_IN_LINEAGE', `Anchor ${anchor.buildId} is not on the source branch lineage`);
+            }
+            const branch = this.ensureBranchRecord(ledger, {
+                rootId: source.rootId,
+                branchId: input.newBranchId,
+                parentAnchorBuildId: anchor.buildId,
+            });
+            branch.headBuildId = anchor.buildId;
+            branch.tailBuildId = anchor.buildId;
+            branch.queueRevision = 0;
+            branch.lifecycleRevision += 1;
+            const receipt = {
+                schemaVersion: 1,
+                commandId: input.commandId,
+                requestHash: hash,
+                workspaceId: this.workspaceId,
+                rootId: source.rootId,
+                branchId: branch.branchId,
+                buildId: anchor.buildId,
+                parentBuildId: anchor.buildId,
+                queueSequence: 0,
+                queueRevision: branch.queueRevision,
+                lifecycleRevision: branch.lifecycleRevision,
+                acceptedAt: new Date().toISOString(),
+            };
+            ledger.commands[key] = receipt;
+            this.appendEvent(ledger, {
+                type: 'BranchForked',
+                workspaceId: this.workspaceId,
+                rootId: source.rootId,
+                branchId: branch.branchId,
+                buildId: anchor.buildId,
+                attemptId: null,
+                fence: null,
+                payload: { sourceBranchId: source.branchId, anchorBuildId: anchor.buildId },
+            });
+            return { ...branch };
+        });
+    }
+    setPaused(input) {
+        return this.mutate(ledger => {
+            const branch = this.requireBranch(ledger, input);
+            branch.paused = input.paused === true;
+            branch.lifecycleRevision += 1;
+            branch.updatedAt = new Date().toISOString();
+            this.appendEvent(ledger, {
+                type: branch.paused ? 'BranchPaused' : 'BranchResumed',
+                workspaceId: this.workspaceId,
+                rootId: branch.rootId,
+                branchId: branch.branchId,
+                buildId: null,
+                attemptId: null,
+                fence: null,
+            });
+            return branch.paused;
+        });
+    }
+    snapshot(input) {
+        const ledger = this.readLedger();
+        const branch = this.requireBranch(ledger, input);
+        return this.snapshotUnlocked(ledger, branch);
+    }
+    snapshotUnlocked(ledger, branch) {
+        const guard = ledger.guards[branch.branchId] || (0, contracts_1.defaultGuard)(branch.branchId);
+        // dev-0.6.4 hotfix: 受阻状态由父链推导，而不是只在失败瞬间给直系后继打标记。
+        // 这样“失败之后才入队”的行同样会显示为受阻，界面才能给出显式修复入口。
+        const blockedBuildIds = this.blockedQueuedBuildIds(ledger, branch);
+        const builds = Object.values(ledger.builds)
+            .filter(build => build.branchId === branch.branchId)
+            .sort((a, b) => a.queueSequence - b.queueSequence)
+            .map(build => ({
+            ...build,
+            input: cloneInput(build.input),
+            waitingReason: build.waitingReason || (blockedBuildIds.has(build.buildId) ? 'DEPENDENCY_FAILED' : undefined),
+        }));
+        return {
+            workspaceId: this.workspaceId,
+            rootId: branch.rootId,
+            branchId: branch.branchId,
+            headBuildId: branch.headBuildId,
+            tailBuildId: branch.tailBuildId,
+            queueRevision: branch.queueRevision,
+            lifecycleRevision: branch.lifecycleRevision,
+            paused: branch.paused,
+            activeBuildId: guard.activeBuildId,
+            guard: { ...guard },
+            builds,
+        };
+    }
+    events(afterCursor = 0, limit = 500) {
+        return this.readLedger().events
+            .filter(event => event.cursor > afterCursor)
+            .slice(0, Math.max(1, Math.min(5_000, limit)))
+            .map(event => ({ ...event, payload: event.payload ? { ...event.payload } : undefined }));
+    }
+    recoverExpiredLeases(now = Date.now()) {
+        return this.mutate(ledger => {
+            let recovered = 0;
+            for (const guard of Object.values(ledger.guards)) {
+                if (!guard.activeBuildId || guard.leaseUntil > now)
+                    continue;
+                const attempt = guard.activeAttemptId ? ledger.attempts[guard.activeAttemptId] : undefined;
+                const build = ledger.builds[guard.activeBuildId];
+                if (attempt && attempt.status === 'RUNNING') {
+                    attempt.status = 'EXPIRED';
+                    attempt.endedAt = new Date(now).toISOString();
+                }
+                if (build && build.status === 'RUNNING') {
+                    build.status = 'QUEUED';
+                    build.updatedAt = new Date(now).toISOString();
+                }
+                this.releaseGuard(ledger, guard.branchId, guard.fence);
+                recovered += 1;
+            }
+            return recovered;
+        });
+    }
+    terminateAttempt(scope, status, reason, now = Date.now()) {
+        this.mutate(ledger => {
+            const branch = this.requireBranch(ledger, scope);
+            const build = ledger.builds[scope.buildId];
+            const attempt = ledger.attempts[scope.attemptId];
+            const guard = ledger.guards[scope.branchId];
+            if (!build || !attempt || !guard
+                || guard.activeAttemptId !== scope.attemptId
+                || guard.fence !== scope.fence
+                || attempt.fence !== scope.fence) {
+                throw new contracts_1.ContinuationError('STALE_EXECUTION', `Attempt ${scope.attemptId} cannot terminate branch ${scope.branchId}`);
+            }
+            build.status = status;
+            build.updatedAt = new Date(now).toISOString();
+            attempt.status = status === 'FAILED' ? 'FAILED' : 'CANCELLED';
+            attempt.endedAt = build.updatedAt;
+            branch.lifecycleRevision += 1;
+            this.releaseGuard(ledger, branch.branchId, attempt.fence);
+            this.markDependentsBlocked(ledger, branch, build.buildId);
+            this.appendEvent(ledger, {
+                type: status === 'FAILED' ? 'BuildFailed' : 'BuildCancelled',
+                workspaceId: this.workspaceId,
+                rootId: branch.rootId,
+                branchId: branch.branchId,
+                buildId: build.buildId,
+                attemptId: attempt.attemptId,
+                fence: attempt.fence,
+                payload: { reason: String(reason || '') },
+            });
+        });
+    }
+    releaseExpiredGuard(ledger, branch, guard, now) {
+        const attempt = guard.activeAttemptId ? ledger.attempts[guard.activeAttemptId] : undefined;
+        const build = guard.activeBuildId ? ledger.builds[guard.activeBuildId] : undefined;
+        if (attempt && attempt.status === 'RUNNING') {
+            attempt.status = 'EXPIRED';
+            attempt.endedAt = new Date(now).toISOString();
+        }
+        if (build && build.status === 'RUNNING') {
+            build.status = 'QUEUED';
+            build.updatedAt = new Date(now).toISOString();
+        }
+        this.releaseGuard(ledger, branch.branchId, guard.fence);
+    }
+    markDependentsBlocked(ledger, branch, failedBuildId) {
+        for (const build of Object.values(ledger.builds)) {
+            if (build.branchId !== branch.branchId || build.status !== 'QUEUED')
+                continue;
+            if (build.parentBuildId === failedBuildId)
+                build.waitingReason = 'DEPENDENCY_FAILED';
+        }
+    }
+    hasCommittedDescendant(ledger, buildId) {
+        return Object.values(ledger.builds).some(build => build.parentBuildId === buildId && build.status === 'SUCCEEDED');
+    }
+    isAncestorOfHead(ledger, branch, anchorBuildId) {
+        let cursor = branch.headBuildId;
+        const seen = new Set();
+        while (cursor) {
+            if (seen.has(cursor))
+                return false;
+            seen.add(cursor);
+            if (cursor === anchorBuildId)
+                return true;
+            cursor = ledger.builds[cursor]?.parentBuildId || null;
+        }
+        return false;
+    }
+    ensureBranchRecord(ledger, input) {
+        const existing = ledger.branches[input.branchId];
+        if (existing)
+            return existing;
+        const now = new Date().toISOString();
+        const branch = {
+            branchId: input.branchId,
+            workspaceId: this.workspaceId,
+            rootId: input.rootId,
+            parentAnchorBuildId: input.parentAnchorBuildId,
+            headBuildId: input.parentAnchorBuildId,
+            tailBuildId: input.parentAnchorBuildId,
+            queueRevision: 0,
+            lifecycleRevision: 0,
+            paused: false,
+            createdAt: now,
+            updatedAt: now,
+        };
+        ledger.branches[branch.branchId] = branch;
+        ledger.guards[branch.branchId] = (0, contracts_1.defaultGuard)(branch.branchId);
+        if (!ledger.roots[branch.rootId]) {
+            ledger.roots[branch.rootId] = { rootId: branch.rootId, workspaceId: this.workspaceId, defaultBranchId: branch.branchId, createdAt: now };
+        }
+        return branch;
+    }
+    requireBranch(ledger, target) {
+        const branch = ledger.branches[target.branchId];
+        if (!branch)
+            throw new contracts_1.ContinuationError('UNKNOWN_BRANCH', `Branch ${target.branchId} does not exist`);
+        if (branch.workspaceId !== this.workspaceId) {
+            throw new contracts_1.ContinuationError('ROUTE_MISMATCH', `Branch ${target.branchId} belongs to workspace ${branch.workspaceId}`);
+        }
+        if (target.rootId && branch.rootId !== target.rootId) {
+            throw new contracts_1.ContinuationError('ROUTE_MISMATCH', `Branch ${target.branchId} belongs to root ${branch.rootId}, not ${target.rootId}`);
+        }
+        return branch;
+    }
+    ensureGuard(ledger, branchId) {
+        if (!ledger.guards[branchId])
+            ledger.guards[branchId] = (0, contracts_1.defaultGuard)(branchId);
+        return ledger.guards[branchId];
+    }
+    /**
+     * Release the active attempt without ever moving the branch fence backward.
+     * A recovered/completed attempt's fence stays as the monotonic high-water
+     * mark; the next claim increments it again.
+     */
+    releaseGuard(ledger, branchId, fence) {
+        ledger.guards[branchId] = {
+            ...(0, contracts_1.defaultGuard)(branchId),
+            fence: Math.max(0, Math.floor(Number(fence) || 0)),
+        };
+    }
+    appendEvent(ledger, input) {
+        const event = {
+            ...input,
+            eventId: `event-${(0, crypto_1.randomUUID)()}`,
+            cursor: ledger.nextEventCursor++,
+            at: input.at || new Date().toISOString(),
+        };
+        ledger.events.push(event);
+        if (ledger.events.length > this.eventRetention)
+            ledger.events = ledger.events.slice(-this.eventRetention);
+        return event;
+    }
+    mutate(apply) {
+        fs.mkdirSync(path.dirname(this.ledgerPath), { recursive: true });
+        const lockHandle = this.acquireLock();
+        try {
+            this.invalidateCache();
+            const ledger = this.readLedgerUnlocked();
+            const result = apply(ledger);
+            this.writeLedgerUnlocked(ledger);
+            return result;
+        }
+        finally {
+            try {
+                fs.closeSync(lockHandle);
+            }
+            catch { /* lock already released */ }
+            try {
+                fs.unlinkSync(this.lockPath);
+            }
+            catch { /* another process may have removed it */ }
+        }
+    }
+    acquireLock() {
+        for (let attempt = 0; attempt < 400; attempt += 1) {
+            try {
+                return fs.openSync(this.lockPath, 'wx');
+            }
+            catch (error) {
+                const code = error && typeof error === 'object' && 'code' in error ? String(error.code || '') : '';
+                if (!['EEXIST', 'EPERM', 'EACCES', 'EBUSY'].includes(code))
+                    throw error;
+                if (code === 'EEXIST') {
+                    try {
+                        if (Date.now() - fs.statSync(this.lockPath).mtimeMs > 30_000)
+                            fs.unlinkSync(this.lockPath);
+                    }
+                    catch { /* lock may have been released */ }
+                }
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5 + attempt);
+            }
+        }
+        throw new contracts_1.ContinuationError('EFFECT_UNCERTAIN', `Timed out acquiring continuation ledger lock: ${this.lockPath}`);
+    }
+    readLedger() {
+        this.ensureLedgerExists();
+        const stat = fs.statSync(this.ledgerPath, { bigint: true });
+        const fingerprint = `${stat.mtimeNs}:${stat.ctimeNs}:${stat.size}`;
+        if (this.cached && this.fingerprint === fingerprint)
+            return this.cached;
+        const ledger = this.readLedgerUnlocked();
+        this.cached = ledger;
+        this.fingerprint = fingerprint;
+        return ledger;
+    }
+    readLedgerUnlocked() {
+        this.ensureLedgerExists();
+        try {
+            const raw = fs.readFileSync(this.ledgerPath, 'utf-8').replace(/^\uFEFF/, '');
+            const parsed = JSON.parse(raw);
+            if (!parsed || parsed.version !== 1 || !parsed.branches || !parsed.builds) {
+                throw new contracts_1.ContinuationError('EFFECT_UNCERTAIN', `Continuation ledger ${this.ledgerPath} has an unsupported shape`);
+            }
+            parsed.attempts = parsed.attempts || {};
+            parsed.guards = parsed.guards || {};
+            parsed.commands = parsed.commands || {};
+            parsed.finals = parsed.finals || {};
+            parsed.events = Array.isArray(parsed.events) ? parsed.events : [];
+            parsed.nextEventCursor = Math.max(1, Number(parsed.nextEventCursor) || (parsed.events.at(-1)?.cursor || 0) + 1);
+            parsed.nextQueueSequence = Math.max(1, Number(parsed.nextQueueSequence) || (Object.values(parsed.builds).reduce((max, build) => Math.max(max, build.queueSequence || 0), 0) + 1));
+            return parsed;
+        }
+        catch (error) {
+            if (error instanceof contracts_1.ContinuationError)
+                throw error;
+            throw new contracts_1.ContinuationError('EFFECT_UNCERTAIN', `Continuation ledger ${this.ledgerPath} is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    writeLedgerUnlocked(ledger) {
+        const temp = `${this.ledgerPath}.${process.pid}.${(0, crypto_1.randomUUID)()}.tmp`;
+        fs.writeFileSync(temp, `${JSON.stringify(ledger, null, 2)}\n`, 'utf-8');
+        fs.renameSync(temp, this.ledgerPath);
+        this.invalidateCache();
+    }
+    ensureLedgerExists() {
+        if (fs.existsSync(this.ledgerPath))
+            return;
+        fs.mkdirSync(path.dirname(this.ledgerPath), { recursive: true });
+        const ledger = (0, contracts_1.emptyLedger)(this.workspaceId);
+        const temp = `${this.ledgerPath}.${process.pid}.${(0, crypto_1.randomUUID)()}.tmp`;
+        fs.writeFileSync(temp, `${JSON.stringify(ledger, null, 2)}\n`, 'utf-8');
+        fs.renameSync(temp, this.ledgerPath);
+    }
+    invalidateCache() {
+        this.cached = null;
+        this.fingerprint = '';
+    }
+}
+exports.GuardedContinuationStore = GuardedContinuationStore;
+function cloneInput(input) {
+    return {
+        ...input,
+        images: input.images?.map(image => ({ ...image })),
+        attachments: input.attachments?.map(attachment => ({ ...attachment })),
+        branchPath: input.branchPath?.slice(),
+    };
+}
+//# sourceMappingURL=store.js.map