@zq-silk/yui 0.15.12 → 0.16.0

package/dist/integration/integrationQueueService.js

@@ -1,810 +0,0 @@
-import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
-import { workspaceProjectEntry } from "../worktree/managedWorkspace.js";
-import { createIntegrationAttempt, recordResolutionDecision, updateIntegrationAttempt } from "./integrationAttempt.js";
-import { createConvergedIntegrationQueueEntry, createIntegrationQueueEntry, markIntegrationQueueBlocked, markIntegrationQueueCommitted, markIntegrationQueueRequeued, markIntegrationQueueRunning, markIntegrationQueueSuperseded, recordIntegrationQueueAffectedPaths, recordIntegrationQueueAttempt } from "./integrationQueueEntry.js";
-import { GitIntegrationService } from "./gitIntegrationService.js";
-import { governingWorkItemCandidate } from "../workItem/workItem.js";
-/**
- * Producer WorkItem statuses that close the WorkItem lifecycle.  A ChangeSet
- * captured from a WorkItem that reached one of these without ever producing a
- * Candidate has no deliverable to integrate: landing it would break Task-final
- * provenance, which traces every queued ChangeSet back to its WorkItem's
- * Candidate.
- */
-const TERMINAL_PRODUCER_STATUSES = new Set([
-    "accepted",
-    "retired"
-]);
-/**
- * Only a ChangeSet whose producer WorkItem reached a deliverable may enter the
- * queue.  In-progress WorkItems are left to the capture path, which only runs
- * once a Candidate exists; the re-check inside the write transaction closes
- * the TOCTOU window between this read and the entry creation.
- */
-function assertEnqueueableProducer(store, taskId, changeSet) {
-    const workItem = store.getWorkItem(taskId, changeSet.workItemId);
-    if (workItem === null) {
-        throw new Error(`ChangeSet producer WorkItem not found: ${changeSet.workItemId}.`);
-    }
-    if (workItem.candidates.length === 0
-        && TERMINAL_PRODUCER_STATUSES.has(workItem.status)) {
-        throw new Error(`ChangeSet producer WorkItem has no terminal Candidate: ${workItem.id}/${workItem.status}.`);
-    }
-}
-/**
- * Synchronous Task-active fence usable inside a write transaction.  The Task
- * may retire between the pre-flight read and the commit point; a terminal Task
- * must not gain new queue entries or Integration Attempts.
- */
-function assertTaskActive(store, taskId) {
-    const task = store.getTask(taskId);
-    if (task === null) {
-        throw new Error(`Task not found: ${taskId}.`);
-    }
-    if (task.status !== "active") {
-        throw new Error(`Task is not active: ${task.id}/${task.status}.`);
-    }
-}
-/**
- * Synchronous current-Candidate fence usable inside a write transaction.
- * Rejects a running WorkItem (no current Candidate) and a ChangeSet whose
- * headCommit no longer matches the latest immutable Candidate snapshot.
- * Returns without error when the Candidate carries no head snapshot: the
- * async workspace fallback in assertCurrentCandidateHead covers that case
- * outside the transaction.
- */
-function assertCurrentCandidateInStore(store, taskId, changeSet) {
-    const workItem = store.getWorkItem(taskId, changeSet.workItemId);
-    if (workItem === null) {
-        throw new Error(`ChangeSet producer WorkItem not found: ${changeSet.workItemId}.`);
-    }
-    // A running WorkItem has no current Candidate: a new one is expected.
-    if (workItem.status === "open" && workItem.currentCandidateId === undefined) {
-        throw new Error(`ChangeSet ${changeSet.id} has no current Candidate: `
-            + `WorkItem ${workItem.id} is running.`);
-    }
-    const latestCandidate = governingWorkItemCandidate(workItem);
-    if (latestCandidate !== undefined) {
-        const snapshotHead = candidateHeadCommit(latestCandidate, changeSet.projectId);
-        if (snapshotHead !== undefined && snapshotHead !== changeSet.headCommit) {
-            throw new Error(`ChangeSet ${changeSet.id} was captured from a superseded Candidate: `
-                + `current Candidate head is ${snapshotHead}, ChangeSet head is ${changeSet.headCommit}.`);
-        }
-    }
-}
-/**
- * A ChangeSet captured from a since-superseded Candidate must not enter the
- * queue.  The fence binds to the latest immutable Candidate snapshot: a
- * running WorkItem has no current Candidate, and a ChangeSet whose headCommit
- * no longer matches the latest Candidate (or the workspace HEAD when the
- * Candidate carries no head snapshot) was captured from an earlier Candidate.
- * When the workspace exists but cannot be inspected, fail closed.
- */
-async function assertCurrentCandidateHead(store, taskId, changeSet, git) {
-    assertCurrentCandidateInStore(store, taskId, changeSet);
-    // Fall back to the managed workspace HEAD when the Candidate carries no
-    // head-commit snapshot.  Fail closed: a workspace that exists but cannot
-    // be inspected blocks enqueue.
-    const workspace = store.getManagedWorkspace({
-        type: "work-item",
-        taskId,
-        workItemId: changeSet.workItemId
-    });
-    if (workspace === null)
-        return;
-    const entry = workspace.entries.find((e) => e.projectId === changeSet.projectId);
-    if (entry === undefined)
-        return;
-    let currentHead;
-    try {
-        currentHead = (await git.inspect(entry.path)).baseCommit;
-    }
-    catch {
-        throw new Error(`ChangeSet ${changeSet.id} cannot be verified: `
-            + `workspace ${entry.path} exists but cannot be inspected.`);
-    }
-    if (currentHead !== changeSet.headCommit) {
-        throw new Error(`ChangeSet ${changeSet.id} was captured from a superseded Candidate: `
-            + `workspace HEAD is ${currentHead}, ChangeSet head is ${changeSet.headCommit}.`);
-    }
-}
-function candidateHeadCommit(candidate, projectId) {
-    const gitSnapshotHead = candidate.gitSnapshot?.projects
-        .find((p) => p.projectId === projectId)?.commit;
-    if (gitSnapshotHead !== undefined)
-        return gitSnapshotHead;
-    const taskMainHead = candidate.taskMainSnapshot?.projects
-        .find((p) => p.projectId === projectId)?.headCommit;
-    if (taskMainHead !== undefined)
-        return taskMainHead;
-    return undefined;
-}
-/**
- * Enqueue one ChangeSet.  Enqueue is idempotent per (Project, ChangeSet): an
- * existing non-superseded entry is returned instead of duplicated.  When the
- * ChangeSet is already represented on the target (an ancestor or a same-tree
- * commit) the entry converges directly to committed with its proof.
- */
-export async function enqueueIntegrationQueueEntry(input) {
-    const now = input.now ?? (() => new Date());
-    const git = input.git ?? new NodeGitWorkspace();
-    const task = input.store.getTask(input.taskId);
-    if (task === null)
-        throw new Error(`Task not found: ${input.taskId}.`);
-    if (task.status !== "active") {
-        throw new Error(`Task is not active: ${task.id}/${task.status}.`);
-    }
-    const changeSet = input.store.getChangeSet(task.id, input.changeSetId);
-    if (changeSet === null)
-        throw new Error(`ChangeSet not found: ${input.changeSetId}.`);
-    if (changeSet.projectId !== input.projectId) {
-        throw new Error(`ChangeSet belongs to another Project: ${changeSet.projectId}.`);
-    }
-    if (!task.projectBindings.some(({ projectId }) => projectId === input.projectId)) {
-        throw new Error(`Project does not belong to Task: ${input.projectId}.`);
-    }
-    // Producer fence: only a ChangeSet whose WorkItem reached a deliverable may
-    // enter the queue.  Re-checked inside the write transaction.
-    assertEnqueueableProducer(input.store, task.id, changeSet);
-    // Current-Candidate fence: a ChangeSet captured from a since-superseded
-    // Candidate must not enter the queue.  Runs before the duplicate fast path
-    // so a retry-window WorkItem cannot resurrect a stale ChangeSet that was
-    // enqueued before its Candidate was superseded.
-    await assertCurrentCandidateHead(input.store, task.id, changeSet, git);
-    // Fast path: a duplicate already visible returns without any git inspection.
-    // The authoritative re-check happens inside the write transaction so two
-    // concurrent enqueues cannot both create entries for the same ChangeSet.
-    const existing = findActiveQueueDuplicate(input.store, task.id, input.projectId, input.changeSetId);
-    if (existing !== undefined) {
-        // A conflicting idempotency retry must fail closed, even on the fast
-        // path: a caller that enqueues with a different explicit gate is either
-        // mistaken or trying to bypass the original gate.  Reject instead of
-        // silently discarding the requested checks.  A retry with no gate is a
-        // plain idempotent lookup and returns the existing entry.
-        const requestedChecks = input.checkCommands ?? [];
-        if (requestedChecks.length > 0
-            && (existing.checkCommands.length !== requestedChecks.length
-                || existing.checkCommands.some((cmd, i) => cmd !== requestedChecks[i]))) {
-            throw new Error(`ChangeSet ${input.changeSetId} is already queued as ${existing.id} `
-                + `with checkCommands [${existing.checkCommands.join(", ")}]; `
-                + `a conflicting retry with [${requestedChecks.join(", ")}] is not allowed.`);
-        }
-        // A conflicting explicit target must also fail closed: a caller that
-        // enqueues for a different branch is either mistaken or trying to land
-        // the same ChangeSet on two targets through one entry.  A retry with no
-        // explicit target is a plain idempotent lookup.
-        if (input.targetRef !== undefined) {
-            const requestedTarget = canonicalizeTargetRef(input.targetRef);
-            if (requestedTarget !== existing.targetRef) {
-                throw new Error(`ChangeSet ${input.changeSetId} is already queued as ${existing.id} `
-                    + `with targetRef ${existing.targetRef}; `
-                    + `a conflicting retry with targetRef ${requestedTarget} is not allowed.`);
-            }
-        }
-        return {
-            entry: existing,
-            outcome: existing.status === "committed" ? "already-committed" : "already-queued"
-        };
-    }
-    const project = input.store.getProject(input.projectId);
-    if (project === null)
-        throw new Error(`Project not found: ${input.projectId}.`);
-    const targetRef = input.targetRef
-        ?? changeSet.manifest.targetRef
-        ?? taskMainBranch(input.store, task.id, input.projectId);
-    if (targetRef === undefined) {
-        throw new Error(`Task main worktree is not ready; reconcile the Task first: ${task.id}.`);
-    }
-    const canonicalTargetRef = canonicalizeTargetRef(targetRef);
-    const repositoryPath = taskMainRepositoryPath(input.store, task.id, project.id);
-    const targetHead = (await git.inspect(repositoryPath, exactBranchRef(canonicalTargetRef))).baseCommit;
-    let equivalent = await findEquivalentCommit(git, repositoryPath, changeSet.headCommit, targetHead, changeSet.baseCommit);
-    if (equivalent === null) {
-        // The identical change may already have landed through another commit
-        // while the target also moved on with unrelated work: the whole-tree
-        // check misses it, but the touched paths already agree.
-        equivalent = await findContainedChangeSet(git, repositoryPath, changeSet, targetHead);
-    }
-    return input.store.transactionAsync(async (tx) => {
-        const duplicate = findActiveQueueDuplicate(tx, task.id, input.projectId, input.changeSetId);
-        if (duplicate !== undefined) {
-            // A conflicting idempotency retry must fail closed: a caller that
-            // enqueues with a different explicit gate is either mistaken or trying
-            // to bypass the original gate.  Reject instead of silently discarding
-            // the requested checks.  A retry with no gate is a plain idempotent
-            // lookup and returns the existing entry.
-            const requestedChecks = input.checkCommands ?? [];
-            if (requestedChecks.length > 0
-                && (duplicate.checkCommands.length !== requestedChecks.length
-                    || duplicate.checkCommands.some((cmd, i) => cmd !== requestedChecks[i]))) {
-                throw new Error(`ChangeSet ${input.changeSetId} is already queued as ${duplicate.id} `
-                    + `with checkCommands [${duplicate.checkCommands.join(", ")}]; `
-                    + `a conflicting retry with [${requestedChecks.join(", ")}] is not allowed.`);
-            }
-            // A conflicting explicit target must also fail closed.  A retry with
-            // no explicit target is a plain idempotent lookup.
-            if (input.targetRef !== undefined && canonicalTargetRef !== duplicate.targetRef) {
-                throw new Error(`ChangeSet ${input.changeSetId} is already queued as ${duplicate.id} `
-                    + `with targetRef ${duplicate.targetRef}; `
-                    + `a conflicting retry with targetRef ${canonicalTargetRef} is not allowed.`);
-            }
-            return {
-                entry: duplicate,
-                outcome: duplicate.status === "committed" ? "already-committed" : "already-queued"
-            };
-        }
-        // Re-verify the Task is still active inside the write transaction:
-        // the Task may have retired between the pre-flight read and this commit.
-        assertTaskActive(tx, task.id);
-        // Re-verify the producer inside the write transaction: the WorkItem may
-        // have retired (or been deleted) between the read above and this commit.
-        assertEnqueueableProducer(tx, task.id, changeSet);
-        // Re-verify the current-Candidate fence inside the write transaction:
-        // the WorkItem may have entered retry (status running) between the
-        // async target inspection and this commit.
-        assertCurrentCandidateInStore(tx, task.id, changeSet);
-        const id = tx.nextIntegrationQueueEntryId(task.id);
-        const requestedChecks = input.checkCommands ?? [];
-        // The async proof above observed the target before this write
-        // transaction.  A concurrent landing may have advanced it since; a
-        // stale containment proof cannot terminalize the entry against the
-        // old head, so re-read inside the transaction and invalidate the
-        // proof if it moved.
-        let effectiveTargetHead = targetHead;
-        if (equivalent !== null) {
-            effectiveTargetHead = (await git.inspect(repositoryPath, exactBranchRef(canonicalTargetRef))).baseCommit;
-            if (effectiveTargetHead !== targetHead) {
-                equivalent = null;
-            }
-            else {
-                // The inspect above is itself async: a concurrent landing can
-                // advance the target during the call, so the returned head may
-                // already be stale.  Verify with a second read; if it moved, the
-                // convergence proof is stale and the entry must queue.
-                const verifiedHead = (await git.inspect(repositoryPath, exactBranchRef(canonicalTargetRef))).baseCommit;
-                if (verifiedHead !== effectiveTargetHead) {
-                    equivalent = null;
-                    effectiveTargetHead = verifiedHead;
-                }
-            }
-        }
-        if (equivalent === null || requestedChecks.length > 0) {
-            const entry = createIntegrationQueueEntry({
-                id,
-                taskId: task.id,
-                projectId: input.projectId,
-                changeSetId: input.changeSetId,
-                targetRef: canonicalTargetRef,
-                checkCommands: requestedChecks
-            }, now());
-            tx.saveIntegrationQueueEntry(task.id, entry);
-            return { entry, outcome: "queued" };
-        }
-        // The ChangeSet is already represented on the target and no gate was
-        // requested, so applying it would be a no-op and the target does not move.
-        // Still record the one integration authority every acceptance and
-        // provenance consumer reads: a committed IntegrationAttempt against the
-        // exact observed target head, with the converged queue entry pointing at
-        // it.  No gate runs because there is nothing new to apply and none was
-        // requested; the entry's proof string says why.
-        //
-        // Each inspect above is async: a concurrent landing can advance the
-        // target after the last read returns but before this transaction
-        // commits.  A stale convergence proof would terminalize the entry
-        // against a head that no longer contains the candidate, so linearize
-        // with an atomic compare-and-swap on the target ref (the same
-        // `git update-ref` CAS that GitIntegrationService uses for actual
-        // landings).  The CAS succeeds only when the ref still points at the
-        // expected head; a concurrent advance between the last inspect and
-        // this call makes it fail, and the entry falls back to queued so the
-        // process path re-evaluates at the new head.
-        const attempt = updateIntegrationAttempt(createIntegrationAttempt({
-            id: tx.nextIntegrationAttemptId(task.id),
-            taskId: task.id,
-            projectId: input.projectId,
-            targetRef: canonicalTargetRef,
-            beforeCommit: effectiveTargetHead,
-            source: {
-                kind: "work-item",
-                workItemId: changeSet.workItemId,
-                startCommit: changeSet.baseCommit,
-                resultCommit: changeSet.headCommit,
-                strategy: "cherry-pick"
-            },
-            checkCommands: []
-        }, now()), {
-            status: "committed",
-            candidateCommit: effectiveTargetHead,
-            afterCommit: effectiveTargetHead,
-            summary: `WorkItem ${changeSet.workItemId} result was already represented; Task head was unchanged.`
-        }, now());
-        const convergedEntry = createConvergedIntegrationQueueEntry({
-            id,
-            taskId: task.id,
-            projectId: input.projectId,
-            changeSetId: input.changeSetId,
-            targetRef: canonicalTargetRef,
-            targetHead: effectiveTargetHead,
-            proof: equivalent === changeSet.headCommit
-                ? `ancestor-convergence:${equivalent}`
-                : `tree-convergence:${equivalent}`,
-            integrationAttemptId: attempt.id
-        }, now());
-        try {
-            await git.assertRefAt(repositoryPath, exactBranchRef(canonicalTargetRef), effectiveTargetHead);
-        }
-        catch {
-            const queuedEntry = createIntegrationQueueEntry({
-                id,
-                taskId: task.id,
-                projectId: input.projectId,
-                changeSetId: input.changeSetId,
-                targetRef: canonicalTargetRef,
-                checkCommands: requestedChecks
-            }, now());
-            tx.saveIntegrationQueueEntry(task.id, queuedEntry);
-            return { entry: queuedEntry, outcome: "queued" };
-        }
-        tx.saveIntegrationAttempt(task.id, attempt);
-        tx.saveIntegrationQueueEntry(task.id, convergedEntry);
-        return { entry: convergedEntry, outcome: "converged" };
-    });
-}
-function findActiveQueueDuplicate(store, taskId, projectId, changeSetId) {
-    return store.listIntegrationQueueEntries(taskId)
-        .find((entry) => entry.projectId === projectId
-        && entry.changeSetId === changeSetId
-        && entry.status !== "superseded");
-}
-/**
- * Process queued items in id order. Each item gets a fresh IntegrationAttempt
- * on the exact current target; conflicts and gate failures map the item to
- * `conflicted` without touching the others.  After every commit the remaining
- * items recompute overlap diagnostics.
- *
- * A lane (one Project/targetRef pair) integrates one item at a time: while an
- * item is `running` — claimed by this or another processor — no other item of
- * the lane is selected, and the claim re-checks the barrier inside its write
- * transaction so two store instances cannot run items of the same target
- * concurrently.  The barrier covers the whole lane regardless of id order, so
- * a requeued predecessor is serialized behind a successor that started first.
- */
-export async function processIntegrationQueue(store, home, taskId, options = {}) {
-    const now = options.now ?? (() => new Date());
-    const git = options.git ?? new NodeGitWorkspace();
-    const task = store.getTask(taskId);
-    if (task === null)
-        throw new Error(`Task not found: ${taskId}.`);
-    if (task.status !== "active") {
-        throw new Error(`Task is not active: ${task.id}/${task.status}.`);
-    }
-    const processed = [];
-    for (;;) {
-        if (options.limit !== undefined && processed.length >= options.limit)
-            break;
-        await reconcileTerminalAttempts(store, task.id, git, now);
-        // The store already returns entries in numeric id order; trust it instead
-        // of re-sorting with a lexicographic compare (which yields 1, 10, 2, ...).
-        // A running entry is the persistent head of its lane: its successors are
-        // skipped here so another processor's in-flight item is never claimed
-        // past.
-        const candidate = firstClaimableQueueEntry(store.listIntegrationQueueEntries(task.id), options.projectId);
-        if (candidate === undefined)
-            break;
-        const project = store.getProject(candidate.projectId);
-        if (project === null)
-            throw new Error(`Project not found: ${candidate.projectId}.`);
-        const repositoryPath = taskMainRepositoryPath(store, task.id, project.id);
-        const targetBefore = (await git.inspect(repositoryPath, exactBranchRef(candidate.targetRef))).baseCommit;
-        // CAS claim: re-read the entry inside the write transaction.  Another
-        // store instance may have taken it since selection; if the status changed,
-        // do not create an Attempt and re-select instead.  The running barrier is
-        // re-checked here as well: an earlier lane mate that started running
-        // between selection and claim serializes this entry behind it.
-        const claimed = store.transaction((tx) => {
-            const current = tx.getIntegrationQueueEntry(task.id, candidate.id);
-            if (current === null || current.status !== "queued") {
-                return { skipped: true };
-            }
-            if (laneBlockedByRunningEntry(tx.listIntegrationQueueEntries(task.id), current)) {
-                return { skipped: true };
-            }
-            // Task-active fence: the Task may have retired between the pre-flight
-            // read and this commit.  A terminal Task must not gain a new running
-            // Integration Attempt.  This throws (not caught by the Candidate-fence
-            // handler below) so the caller sees the rejection.
-            assertTaskActive(tx, task.id);
-            // Current-Candidate fence: a queued ChangeSet whose producer WorkItem
-            // entered retry (or whose latest Candidate no longer matches) must not
-            // advance the target.  Mark it conflicted so the Leader can supersede
-            // or re-enqueue a fresh ChangeSet.
-            const changeSet = tx.getChangeSet(task.id, current.changeSetId);
-            try {
-                if (changeSet === null) {
-                    throw new Error(`ChangeSet not found: ${current.changeSetId}.`);
-                }
-                assertCurrentCandidateInStore(tx, task.id, changeSet);
-            }
-            catch (error) {
-                const running = markIntegrationQueueRunning(current, targetBefore, now());
-                tx.saveIntegrationQueueEntry(task.id, running);
-                tx.saveIntegrationQueueEntry(task.id, markIntegrationQueueBlocked(running, error instanceof Error ? error.message : String(error), now()));
-                return { skipped: true };
-            }
-            if (changeSet === null) {
-                throw new Error(`ChangeSet not found after validation: ${current.changeSetId}.`);
-            }
-            const attempt = createIntegrationAttempt({
-                id: tx.nextIntegrationAttemptId(task.id),
-                taskId: task.id,
-                projectId: current.projectId,
-                targetRef: current.targetRef,
-                beforeCommit: targetBefore,
-                source: {
-                    kind: "work-item",
-                    workItemId: changeSet.workItemId,
-                    startCommit: changeSet.baseCommit,
-                    resultCommit: changeSet.headCommit,
-                    strategy: "cherry-pick"
-                },
-                checkCommands: current.checkCommands
-            }, now());
-            tx.saveIntegrationAttempt(task.id, attempt);
-            const entry = recordIntegrationQueueAttempt(markIntegrationQueueRunning(current, targetBefore, now()), attempt.id, now());
-            tx.saveIntegrationQueueEntry(task.id, entry);
-            return { skipped: false, entry, attempt };
-        });
-        if (claimed.skipped)
-            continue;
-        const result = await new GitIntegrationService(home, store, git, now, options.environment)
-            .integrate(task.id, claimed.attempt.id);
-        const settled = store.transaction((tx) => {
-            let entry = claimed.entry;
-            if (result.status === "committed") {
-                entry = markIntegrationQueueCommitted(entry, committedTargetAfter(result.attempt), now());
-            }
-            else if (result.status === "blocked" || result.status === "conflicted") {
-                entry = markIntegrationQueueBlocked(entry, result.attempt.conflict?.summary
-                    ?? result.attempt.summary ?? "Inspect the unfinished Integration.", now());
-            }
-            else {
-                entry = markIntegrationQueueBlocked(entry, gateFailureSummary(result.attempt), now());
-            }
-            tx.saveIntegrationQueueEntry(task.id, entry);
-            return entry;
-        });
-        if (result.status === "committed") {
-            await recomputeAffectedPaths(store, task.id, settled, taskMainRepositoryPath(store, task.id, settled.projectId), git, now);
-        }
-        processed.push({ entry: settled, attempt: result.attempt, result });
-    }
-    return processed;
-}
-/**
- * A queue lane serializes one target ref: entries for the same Project and
- * targetRef integrate one at a time in id order.  Entries of different lanes
- * (another Project or ref) do not share a target and may integrate alongside.
- */
-/**
- * Canonicalise a Git ref so that "master" and "refs/heads/master" share one
- * lane.  Only the `refs/heads/` prefix is stripped; other ref namespaces
- * (tags, remotes) are kept distinct.
- */
-function canonicalizeTargetRef(ref) {
-    return ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
-}
-/**
- * Resolve a canonical target ref to its exact Git ref for inspection.  A
- * short name or `refs/heads/*` resolves to the exact branch ref, so a
- * same-named tag cannot shadow the branch.  Other fully-qualified refs
- * keep their exact meaning.
- */
-function exactBranchRef(canonicalRef) {
-    return canonicalRef.startsWith("refs/") ? canonicalRef : `refs/heads/${canonicalRef}`;
-}
-function queueLaneKey(entry) {
-    return `${entry.projectId} ${canonicalizeTargetRef(entry.targetRef)}`;
-}
-/**
- * The first entry a processor may claim: the earliest queued entry
- * whose lane has no running entry anywhere in it.  A running entry serializes
- * its whole lane — predecessors and successors alike — so a requeued
- * predecessor cannot slip past a successor that is already running.
- */
-function firstClaimableQueueEntry(entries, projectId) {
-    const blockedLanes = new Set();
-    for (const entry of entries) {
-        if (projectId !== undefined && entry.projectId !== projectId)
-            continue;
-        if (entry.status === "running") {
-            blockedLanes.add(queueLaneKey(entry));
-        }
-    }
-    for (const entry of entries) {
-        if (projectId !== undefined && entry.projectId !== projectId)
-            continue;
-        if (entry.status === "queued"
-            && !blockedLanes.has(queueLaneKey(entry))) {
-            return entry;
-        }
-    }
-    return undefined;
-}
-/**
- * The claim-time re-check of the running barrier: the candidate stays
- * claimable only while no other entry of its lane is running.  The barrier
- * covers the whole lane regardless of id order, so a requeued predecessor is
- * serialized behind a successor that started running first.
- */
-function laneBlockedByRunningEntry(entries, candidate) {
-    const lane = queueLaneKey(candidate);
-    return entries.some((entry) => entry.id !== candidate.id
-        && entry.status === "running"
-        && queueLaneKey(entry) === lane);
-}
-/**
- * A conflicted entry whose manual-resolution Attempt committed converges.  The
- * settle happens in one transaction; the downstream affected-path recompute
- * follows with the same committed evidence, so waiting successors never keep
- * stale overlap evidence.
- */
-export async function reconcileIntegrationQueueEntry(store, taskId, entryId, git, now = () => new Date()) {
-    const entry = store.getIntegrationQueueEntry(taskId, entryId);
-    if (entry === null) {
-        throw new Error(`Integration queue entry not found: ${taskId}/${entryId}.`);
-    }
-    if (entry.status !== "conflicted") {
-        throw new Error(`Integration queue entry is not conflicted: ${entry.id}/${entry.status}.`);
-    }
-    const attempt = entry.integrationAttemptId === undefined
-        ? undefined
-        : store.getIntegrationAttempt(taskId, entry.integrationAttemptId);
-    if (attempt?.status !== "committed") {
-        throw new Error(`Integration Attempt has not committed: ${entry.integrationAttemptId ?? "-"}/${attempt?.status ?? "missing"}.`);
-    }
-    const committed = store.transaction((tx) => {
-        const settled = markIntegrationQueueCommitted(entry, committedTargetAfter(attempt), now());
-        tx.saveIntegrationQueueEntry(taskId, settled);
-        return settled;
-    });
-    await recomputeAffectedPaths(store, taskId, committed, taskMainRepositoryPath(store, taskId, committed.projectId), git, now);
-    return committed;
-}
-/**
- * A conflicted entry may carry a blocked IntegrationAttempt waiting for a
- * Task Agent decision. Requeue or supersede IS that decision — the blocked
- * attempt is abandoned — so resolve it as rejected (terminal `failed`)
- * rather than leaving it to block Task retirement.
- */
-function resolveBlockedAttempt(store, taskId, entry, decision, decidedBy, now) {
-    if (entry.integrationAttemptId === undefined)
-        return;
-    const attempt = store.getIntegrationAttempt(taskId, entry.integrationAttemptId);
-    if (attempt === null || (attempt.status !== "blocked" && attempt.status !== "conflicted"))
-        return;
-    const rejected = recordResolutionDecision(attempt, {
-        action: "reject",
-        rationale: `Integration Attempt rejected by queue ${decision}.`
-    }, decidedBy, now());
-    store.saveIntegrationAttempt(taskId, rejected);
-}
-/**
- * A linked Integration Attempt that is actively processing or already
- * committed cannot be discarded by requeue or supersede.  Only a blocked
- * Attempt (finalized by resolveBlockedAttempt) or a failed one is safe to
- * recover; a running, validating, or committed Attempt would leave the
- * queue entry contradicting the Attempt/target state.
- */
-function assertRecoverableAttempt(store, taskId, entry, action) {
-    if (entry.integrationAttemptId === undefined)
-        return;
-    const attempt = store.getIntegrationAttempt(taskId, entry.integrationAttemptId);
-    if (attempt === null)
-        return;
-    if (attempt.status !== "blocked" && attempt.status !== "conflicted" && attempt.status !== "failed") {
-        throw new Error(`Integration queue entry ${entry.id} is backed by ${attempt.status} `
-            + `Integration Attempt ${attempt.id}; reconcile the queue entry instead `
-            + `of ${action} it.`);
-    }
-}
-/** Retry a conflicted item (for example after a gate failure was fixed). */
-export function requeueIntegrationQueueEntry(store, taskId, entryId, decidedBy, now = () => new Date()) {
-    // The committed-Attempt guard, the blocked-Attempt finalization, and the
-    // queue write must be atomic: a concurrent manual-resolution continue can
-    // commit the Attempt between the guard and the write, leaving the queue
-    // entry requeued behind a committed target.
-    return store.transaction((tx) => {
-        assertTaskActive(tx, taskId);
-        const entry = tx.getIntegrationQueueEntry(taskId, entryId);
-        if (entry === null) {
-            throw new Error(`Integration queue entry not found: ${taskId}/${entryId}.`);
-        }
-        assertRecoverableAttempt(tx, taskId, entry, "requeue");
-        resolveBlockedAttempt(tx, taskId, entry, "requeue", decidedBy, now);
-        const waiting = markIntegrationQueueRequeued(entry, now());
-        tx.saveIntegrationQueueEntry(taskId, waiting);
-        return waiting;
-    });
-}
-export function supersedeIntegrationQueueEntry(store, taskId, entryId, reason, decidedBy, now = () => new Date()) {
-    return store.transaction((tx) => {
-        const entry = tx.getIntegrationQueueEntry(taskId, entryId);
-        if (entry === null) {
-            throw new Error(`Integration queue entry not found: ${taskId}/${entryId}.`);
-        }
-        assertRecoverableAttempt(tx, taskId, entry, "supersede");
-        resolveBlockedAttempt(tx, taskId, entry, "supersede", decidedBy, now);
-        const superseded = markIntegrationQueueSuperseded(entry, reason, now());
-        tx.saveIntegrationQueueEntry(taskId, superseded);
-        return superseded;
-    });
-}
-/**
- * Converge entries whose linked IntegrationAttempt already settled.  A
- * conflicted entry whose manual resolve committed, or a `running` entry
- * whose process crashed between the Attempt's terminal write and the queue
- * settle, both prove their outcome through the Attempt itself: converge
- * them idempotently — a committed Attempt to `committed`, replaying the
- * downstream affected/evidence updates a normal settle would, and a failed
- * or blocked Attempt to `conflicted` carrying the Attempt's own diagnosis —
- * so the next process pass sees a consistent queue and a wedged lane frees.
- */
-async function reconcileTerminalAttempts(store, taskId, git, now) {
-    for (const entry of store.listIntegrationQueueEntries(taskId)) {
-        if (entry.integrationAttemptId === undefined)
-            continue;
-        if (entry.status === "committed") {
-            // Crash window: the settle marked this entry committed but died before
-            // recomputing downstream affectedPaths.  Replay that update idempotently
-            // so waiting entries regain their overlap evidence.
-            await recomputeAffectedPaths(store, taskId, entry, taskMainRepositoryPath(store, taskId, entry.projectId), git, now);
-            continue;
-        }
-        if (entry.status !== "conflicted" && entry.status !== "running")
-            continue;
-        const attempt = store.getIntegrationAttempt(taskId, entry.integrationAttemptId);
-        if (attempt === null)
-            continue;
-        if (attempt.status === "committed") {
-            const committed = markIntegrationQueueCommitted(entry, committedTargetAfter(attempt), now());
-            store.saveIntegrationQueueEntry(taskId, committed);
-            await recomputeAffectedPaths(store, taskId, committed, taskMainRepositoryPath(store, taskId, committed.projectId), git, now);
-            continue;
-        }
-        // Crash window: the Attempt persisted a terminal failed/blocked outcome
-        // but the process died before settling the entry.  Only a `running`
-        // entry can be wedged by it — a `conflicted` entry already carries its
-        // diagnosis — so converge the stuck lane head to `conflicted` with the
-        // Attempt's own diagnosis, after which requeue or supersede can recover
-        // it.  An Attempt still running or validating is genuinely in flight.
-        if (entry.status !== "running")
-            continue;
-        if (attempt.status !== "failed" && attempt.status !== "blocked" && attempt.status !== "conflicted")
-            continue;
-        const diagnosis = attempt.status === "blocked" || attempt.status === "conflicted"
-            ? attempt.conflict?.summary ?? "Integration blocked without a conflict report."
-            : gateFailureSummary(attempt);
-        store.saveIntegrationQueueEntry(taskId, markIntegrationQueueBlocked(entry, diagnosis, now()));
-    }
-}
-async function recomputeAffectedPaths(store, taskId, committed, projectPath, git, now) {
-    const committedChangeSet = store.getChangeSet(taskId, committed.changeSetId);
-    if (committedChangeSet === null)
-        return;
-    const landed = new Set(committedChangeSet.changedPaths);
-    for (const entry of store.listIntegrationQueueEntries(taskId)) {
-        if (entry.projectId !== committed.projectId)
-            continue;
-        if (canonicalizeTargetRef(entry.targetRef) !== canonicalizeTargetRef(committed.targetRef))
-            continue;
-        if (entry.status !== "queued")
-            continue;
-        const changeSet = store.getChangeSet(taskId, entry.changeSetId);
-        if (changeSet === null)
-            continue;
-        // A committed entry whose targetAfter is already an ancestor of the
-        // waiting entry's baseCommit is part of that entry's base, not a
-        // post-enqueue target advance.  This prevents recovery replay from
-        // reviving evidence that was valid at enqueue time, and covers both
-        // the direct predecessor and transitive history cases.
-        if (committed.targetAfter !== undefined
-            && await git.isAncestor(projectPath, committed.targetAfter, changeSet.baseCommit))
-            continue;
-        const affected = changeSet.changedPaths.filter((path) => landed.has(path));
-        // Re-read inside the transaction: a concurrent processor may have claimed
-        // or conflicted this entry during the async isAncestor gap above.  Only
-        // persist the recompute when the entry is still waiting to be processed.
-        store.transaction((tx) => {
-            const current = tx.getIntegrationQueueEntry(taskId, entry.id);
-            if (current === null)
-                return;
-            if (current.status !== "queued")
-                return;
-            const updated = recordIntegrationQueueAffectedPaths(current, affected, now());
-            // A queued entry keeps its place and runs its checks against the exact
-            // current target at process time.  Disjoint changedPaths must never
-            // rebind its evidence to the new target head: a gate may read any file,
-            // so a non-empty target increment cannot be proven irrelevant from path
-            // metadata alone.
-            if ((updated.affectedPaths ?? []).join("\n")
-                !== (current.affectedPaths ?? []).join("\n")) {
-                tx.saveIntegrationQueueEntry(taskId, updated);
-            }
-        });
-    }
-}
-function committedTargetAfter(attempt) {
-    if (attempt.candidateCommit === undefined) {
-        throw new Error(`Committed Integration Attempt has no candidate commit: ${attempt.id}.`);
-    }
-    return attempt.candidateCommit;
-}
-function gateFailureSummary(attempt) {
-    const failed = (attempt.checks ?? []).find((check) => check.outcome === "failed");
-    return failed === undefined
-        ? attempt.summary ?? "Inspect the Integration target and preserved evidence."
-        : `gate failed: ${failed.name}${failed.details === undefined ? "" : `: ${failed.details}`}`;
-}
-async function findEquivalentCommit(git, repositoryPath, sourceCommit, historyHead, baseCommit) {
-    if (git.findCommitWithSameTreeInHistory === undefined) {
-        return (await git.isAncestor(repositoryPath, sourceCommit, historyHead))
-            ? sourceCommit
-            : null;
-    }
-    const found = await git.findCommitWithSameTreeInHistory({
-        repositoryPath,
-        sourceCommit,
-        historyHead
-    });
-    if (found === null)
-        return null;
-    // The exact source commit landing on the target is integration evidence
-    // regardless of the base relationship.  A different same-tree commit is
-    // only evidence when it is at or after the ChangeSet base: a same-tree
-    // commit older than the base is history the ChangeSet may be deliberately
-    // restoring, not proof that the restore landed.
-    if (found === sourceCommit)
-        return found;
-    return (await git.isAncestor(repositoryPath, baseCommit, found)) ? found : null;
-}
-/**
- * A ChangeSet whose head already agrees with the target on every path it
- * touched (deletions included) is fully represented there: an identical
- * parallel change landed through another commit.  Converge it directly,
- * since applying it would be a no-op and a second commit would only
- * duplicate the same work.
- */
-async function findContainedChangeSet(git, repositoryPath, changeSet, targetHead) {
-    if (git.treesAgreeOnPaths === undefined)
-        return null;
-    const paths = [...new Set([
-            ...changeSet.changedPaths,
-            ...changeSet.manifest.deletedPaths
-        ])];
-    if (paths.length === 0)
-        return null;
-    const agrees = await git.treesAgreeOnPaths({
-        repositoryPath,
-        leftCommit: changeSet.headCommit,
-        rightCommit: targetHead,
-        paths
-    });
-    return agrees ? targetHead : null;
-}
-function taskMainBranch(store, taskId, projectId) {
-    const mainWorkspace = store.getTaskWorkspace(taskId);
-    if (mainWorkspace === null)
-        return undefined;
-    return workspaceProjectEntry(mainWorkspace, projectId)?.branch;
-}
-function taskMainRepositoryPath(store, taskId, projectId) {
-    const mainWorkspace = store.getTaskWorkspace(taskId);
-    if (mainWorkspace === null || mainWorkspace.owner.type !== "task") {
-        throw new Error(`Task has no authoritative main workspace: ${taskId}.`);
-    }
-    const entry = workspaceProjectEntry(mainWorkspace, projectId);
-    if (entry === undefined) {
-        throw new Error(`Task main workspace has no Project: ${taskId}/${projectId}.`);
-    }
-    return entry.path;
-}