@lmzhen/dsh-evolution-merge 0.30.18 → 0.30.19

package/lib/types/recovery-coordinator.js

@@ -0,0 +1,84 @@
+/** Batch 2c unit-journal recovery coordinator. UnitTransaction remains the only skill writer. */
+import { join } from 'node:path';
+import { probeList, readUnitEvidence } from '@lmzhen/dsh-evolution-core';
+import { evidenceSha256 } from "./domain/evidence-hash.js";
+import { projectRecoveredUnit } from "./recovery-projection.js";
+const branchOf = (phase) => {
+    if (phase === 'prepared' || phase === 'target-pending')
+        return 'A';
+    if (phase === 'target-written' || phase === 'support-pending' || phase === 'source-archiving')
+        return 'B';
+    if (phase === 'sources-archived' || phase === 'unit-written')
+        return 'C';
+    if (phase === 'committed')
+        return 'D';
+    return 'A';
+};
+export async function recoverCommitUnits(options) {
+    const dir = join(options.home, 'merge', 'unit-journals');
+    const listed = await probeList(options.io, dir);
+    if (listed.kind !== 'present')
+        return [];
+    const files = listed.value.filter(name => name.endsWith('.json'));
+    const reports = [];
+    for (const file of files.sort()) {
+        let journal = null;
+        try {
+            journal = JSON.parse(await options.io.readText(join(dir, file)) ?? '');
+        }
+        catch {
+            journal = null;
+        }
+        if (journal === null || typeof journal.unitId !== 'string')
+            continue;
+        if (options.isActive?.(journal.runId) === true) {
+            reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch: branchOf(journal.phase), action: 'none', ok: true, code: 'skipped-active-run' });
+            continue;
+        }
+        const evidence = await readUnitEvidence(options.io, options.home, journal.unitId);
+        const branch = branchOf(journal.phase);
+        if (journal.phase === 'committed' || evidence !== null || journal.phase === 'unit-written' || journal.phase === 'sources-archived') {
+            const result = await options.unit.finalize(journal.unitId);
+            if (result.ok) {
+                let projection;
+                try {
+                    projection = await projectRecoveredUnit({ io: options.io, home: options.home, runId: journal.runId, unitId: journal.unitId, evidence: result.evidence, now: options.now, ...(options.runs === undefined ? {} : { runs: options.runs }), ...(options.onProjectionPhase === undefined ? {} : { onPhase: options.onProjectionPhase }) });
+                }
+                catch (error) {
+                    projection = { ok: false, action: 'projection-threw', message: error instanceof Error ? error.message : String(error) };
+                }
+                if (!projection.ok)
+                    reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'blocked', ok: false, code: 'projection-failed', message: projection.message });
+                else
+                    reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'finalize', ok: true, evidenceSha256: evidenceSha256(result.evidence) });
+                continue;
+            }
+            reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'finalize', ok: false, code: result.code, message: result.message });
+            continue;
+        }
+        if (branch === 'A') {
+            const result = await options.unit.rollback({ unitId: journal.unitId, reason: 'startup recovery branch A' });
+            reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'rollback', ok: result.ok, ...(result.ok ? {} : { code: result.code, message: result.message }) });
+            continue;
+        }
+        if (branch === 'B') {
+            const result = await options.unit.rollForward(journal.unitId);
+            if (result.ok) {
+                let projection;
+                try {
+                    projection = await projectRecoveredUnit({ io: options.io, home: options.home, runId: journal.runId, unitId: journal.unitId, evidence: result.evidence, now: options.now, ...(options.runs === undefined ? {} : { runs: options.runs }), ...(options.onProjectionPhase === undefined ? {} : { onPhase: options.onProjectionPhase }) });
+                }
+                catch (error) {
+                    projection = { ok: false, action: 'projection-threw', message: error instanceof Error ? error.message : String(error) };
+                }
+                reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: projection.ok ? 'rollForward' : 'blocked', ok: projection.ok, ...(projection.ok ? { evidenceSha256: evidenceSha256(result.evidence) } : { code: 'projection-failed', message: projection.message }) });
+            }
+            else
+                reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'rollForward', ok: false, code: result.code, message: result.message });
+            continue;
+        }
+        reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch, action: 'blocked', ok: false, code: 'unit-recovery-blocked' });
+    }
+    return reports;
+}
+//# sourceMappingURL=recovery-coordinator.js.map

package/lib/types/recovery-projection.d.ts

@@ -0,0 +1,31 @@
+/** Post-recovery projection: evidence -> report -> row remove -> stage drop -> settle/meta. */
+import type { EvolutionIoLike, UnitEvidenceRecord } from '@lmzhen/dsh-evolution-core';
+export interface ProjectionResult {
+    readonly ok: boolean;
+    readonly action: string;
+    readonly message?: string;
+    readonly reportPath?: string;
+}
+export declare function projectRecoveredUnit(options: {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly runId: string;
+    readonly unitId: string;
+    readonly evidence: UnitEvidenceRecord;
+    readonly now: () => number;
+    readonly runs?: {
+        settle(id: string, outcome: {
+            state: 'succeeded' | 'failed' | 'cancelled';
+            resultRef?: string;
+            failure?: string;
+        }): Promise<void>;
+        /** Controlled orphan upgrade: lets a committed unit turn failed(orphan) back into succeeded. */
+        settleRecovered?(id: string, outcome: {
+            state: 'succeeded' | 'failed' | 'cancelled';
+            resultRef?: string;
+            failure?: string;
+        }): Promise<boolean>;
+    };
+    readonly onPhase?: (phase: string) => void | Promise<void>;
+}): Promise<ProjectionResult>;
+//# sourceMappingURL=recovery-projection.d.ts.map

package/lib/types/recovery-projection.js

@@ -0,0 +1,96 @@
+import { readCommitReceipts, writeCommitReceipt } from "./commit-receipt.js";
+import { mergeReportPath, readMergeReport, writeMergeReport } from "./report.js";
+import { pairLedger, readPairLedgerV4 } from "./domain/pair-ledger.js";
+import { readAllStages, readStageTree, writeStageIndex } from "./domain/stage-aggregate.js";
+import { dropStage } from "./domain/stage-aggregate.js";
+import { recordPair } from "./domain/pair-index-store.js";
+import { readRunMeta, writeRunMeta } from "./domain/run-coordinator.js";
+import { evidenceSha256 } from "./domain/evidence-hash.js";
+export async function projectRecoveredUnit(options) {
+    const evidenceSha = evidenceSha256(options.evidence);
+    const ledger = await readPairLedgerV4(options.io, options.home).catch(() => null);
+    const row = ledger?.rows.find(item => item.runId === options.runId && (item.state === 'fuse' || item.state === 'approved'));
+    const rowTarget = row !== undefined && 'target' in row && typeof row.target === 'string' ? row.target : undefined;
+    const rowDecisionTarget = row !== undefined && 'decision' in row ? row.decision.target : undefined;
+    const target = rowTarget ?? rowDecisionTarget ?? options.evidence.sources[0]?.absorbedInto ?? options.evidence.target.after;
+    const pairKey = row?.pairKey ?? target + '\u0000' + (options.evidence.sources[0]?.name ?? '');
+    const expectedPairKey = pairKey;
+    const stageEntry = (await readAllStages(options.io, options.home)).find(item => item.rowId === row?.id || item.pairKey === expectedPairKey);
+    const stageRowId = row?.id ?? stageEntry?.rowId;
+    if (row?.state === 'approved' && stageEntry?.state === 'reserved') {
+        const tree = await readStageTree(options.io, options.home, stageEntry.ref);
+        if (tree.kind !== 'present') {
+            await writeStageIndex(options.io, options.home, { ...stageEntry, state: 'lost' });
+            return { ok: false, action: 'stage-lost', message: 'approved+reserved has no stage tree' };
+        }
+    }
+    const receipts = await readCommitReceipts(options.io, options.home);
+    const receipt = receipts.find(item => item.unitId === options.unitId);
+    const evidencePlan = options.evidence.validationPlan;
+    const validationPlan = receipt?.validationPlan ?? evidencePlan;
+    if (receipt === undefined) {
+        await options.onPhase?.('merge-receipt');
+        await writeCommitReceipt(options.io, options.home, {
+            runId: options.runId, unitId: options.unitId, evidenceSha256: evidenceSha,
+            target, create: options.evidence.target.created,
+            sources: options.evidence.sources.map(source => source.name),
+            archived: options.evidence.sources.filter(source => source.archived).map(source => source.name),
+            pairKey, at: options.now(),
+            ...(validationPlan === undefined ? {} : { validationPlan }),
+        });
+    }
+    const at = options.now();
+    let reportPath;
+    const existing = await readMergeReport(options.io, options.home, options.runId);
+    if (existing.kind === 'present') {
+        reportPath = mergeReportPath(options.home, options.runId);
+        if (validationPlan !== undefined && existing.value.pairs.every(pair => pair.validationPlan === undefined)) {
+            await writeMergeReport(options.io, options.home, { ...existing.value, pairs: existing.value.pairs.map(pair => ({ ...pair, validationPlan })) });
+        }
+    }
+    else {
+        const report = {
+            schemaVersion: 2, runId: options.runId, kind: 'merge', command: 'approve', startedAt: at, endedAt: at,
+            stopReason: 'completed', approval: { platformWrite: false, mergeApproval: true },
+            scope: { candidatePairs: 1, queueBefore: { verify: 0, pending: 0, fuse: 0, skipped: 0 } },
+            pairs: [{ id: row?.id ?? options.unitId, pairKey, a: row?.a ?? target, b: row?.b ?? options.evidence.sources[0]?.name ?? '', queue: 'fuse', outcome: 'merged', archived: options.evidence.sources.filter(source => source.archived).map(source => source.name), unitId: options.unitId, ...(validationPlan === undefined ? {} : { validationPlan }) }],
+            totals: { merged: 1, kept: 0, pending: 0, failed: 0 }, notes: ['recovered from unit journal'],
+        };
+        await options.onPhase?.('report');
+        try {
+            reportPath = await writeMergeReport(options.io, options.home, report);
+        }
+        catch (error) {
+            return { ok: false, action: 'report-write-failed', message: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    if (row !== undefined) {
+        await options.onPhase?.('row-remove');
+        const removed = await pairLedger(options.io, options.home).transact(tx => {
+            const current = tx.rows().find(item => item.id === row.id);
+            return current === undefined ? true : tx.remove(row.id, 'committed', { unitId: options.unitId, evidenceSha256: evidenceSha }, current.version).ok;
+        });
+        if (!removed)
+            return { ok: false, action: 'row-remove-failed' };
+        await options.onPhase?.('stage-drop');
+        await dropStage(options.io, options.home, row.id);
+    }
+    else if (stageRowId !== undefined) {
+        await options.onPhase?.('stage-drop');
+        await dropStage(options.io, options.home, stageRowId);
+    }
+    await options.onPhase?.('pair-index');
+    await recordPair(options.io, options.home, { pairKey, runId: options.runId, result: 'merged', target });
+    await options.onPhase?.('run-meta');
+    const meta = await readRunMeta(options.io, options.home, options.runId);
+    await writeRunMeta(options.io, options.home, { version: 1, runId: options.runId, phase: 'settled', reportRef: reportPath, pairCount: 1, ...(meta?.parentRunId === undefined ? {} : { parentRunId: meta.parentRunId }), createdAt: meta?.createdAt ?? new Date(at).toISOString(), updatedAt: new Date(at).toISOString() });
+    await options.onPhase?.('settle');
+    if (options.runs !== undefined) {
+        const outcome = { state: 'succeeded', resultRef: reportPath };
+        const upgraded = options.runs.settleRecovered === undefined ? false : await options.runs.settleRecovered(options.runId, outcome);
+        if (!upgraded)
+            await options.runs.settle(options.runId, outcome);
+    }
+    return { ok: true, action: 'projected', reportPath };
+}
+//# sourceMappingURL=recovery-projection.js.map

package/lib/types/resume-command.d.ts

@@ -2,7 +2,7 @@
  * resume command: verify rows re-enter round1; fuse rows re-enter round2 with the persisted
  * decision. pending/skipped rows are not resumable.
  */
-import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 import { type MergeRegistryPort, type WithMergeRunResult } from './run-shell.ts';
 import type { ScanPorts, ScanRound2Outcome } from './scan-run.ts';
 import type { MergeDecision, MergeRow } from './contracts.ts';
@@ -17,11 +17,15 @@ export interface RunResumeCommandOptions {
     readonly round2WithRun?: (row: MergeRow, decision: MergeDecision, signal: AbortSignal, runId: string) => Promise<ScanRound2Outcome>;
     readonly rowId: string;
     readonly platformWrite: boolean;
+    readonly approval: boolean;
+    readonly parentRunId?: string;
     readonly detached?: boolean;
     readonly pairTimeoutMinutes?: number;
     readonly timeoutMinutes?: number;
     readonly now: () => number;
     readonly isOwnerActive?: (runId: string) => boolean | Promise<boolean>;
+    /** The invocation carried no agent at all (E-305), as opposed to an agent with no parent run. */
+    readonly agentless?: boolean;
 }
 export declare function runResumeCommand(options: RunResumeCommandOptions): Promise<WithMergeRunResult>;
 //# sourceMappingURL=resume-command.d.ts.map

package/lib/types/resume-command.js

@@ -1,28 +1,38 @@
+/**
+ * resume command: verify rows re-enter round1; fuse rows re-enter round2 with the persisted
+ * decision. pending/skipped rows are not resumable.
+ */
+import { errorText } from '@lmzhen/dsh-evolution-core';
 import { loadMergeState } from "./state.js";
 import { runScanCommand } from "./scan-command.js";
 import { withMergeRun } from "./run-shell.js";
 import { recordRound2Outcome } from "./round2-outcome.js";
+import { pairLedger } from "./domain/pair-ledger.js";
+import { presentStage } from "./domain/stage-aggregate.js";
+import { v4ToLegacy } from "./domain/row-v4.js";
+import { failure } from "./domain/errors.js";
 export async function runResumeCommand(options) {
     const loaded = await loadMergeState(options.io, options.home);
-    const row = loaded.state.rows.find(item => item.id === options.rowId);
+    let row = loaded.state.rows.find(item => item.id === options.rowId);
     if (row === undefined)
-        return { ok: false, message: 'merge row not found: ' + options.rowId };
-    if (row.state === 'verify') {
+        return failure('resume', 'row-not-found', '找不到可恢复行 ' + options.rowId, '运行 /evolution merge candidates 查看可恢复行');
+    const selected = row;
+    if (selected.state === 'verify') {
         if (row.runId !== undefined && (await options.isOwnerActive?.(row.runId)) === true) {
-            return { ok: false, message: 'merge run still owns this verify row: ' + row.runId };
+            return failure('resume', 'run-owns-row', '该 verify 行仍由运行中的 run 持有：' + row.runId, '等待该 run 结束，或运行 /evolution merge cancel ' + row.runId, row.runId);
         }
         return await runScanCommand({
             io: options.io, home: options.home, registry: options.registry,
-            approval: true, platformWrite: options.platformWrite, now: options.now,
+            approval: options.approval, platformWrite: options.platformWrite, now: options.now,
             ...(options.detached === true ? { detached: true } : {}),
             ...(options.makePorts === undefined
-                ? { ports: { ...options.ports, screening: () => Promise.resolve([{ a: row.a, b: row.b }]) } }
+                ? { ports: { ...options.ports, screening: () => Promise.resolve([{ a: selected.a, b: selected.b }]) } }
                 : {
                     makePorts: (runId) => {
                         const makePorts = options.makePorts;
                         if (makePorts === undefined)
                             throw new Error('resume makePorts disappeared');
-                        return { ...makePorts(runId), screening: () => Promise.resolve([{ a: row.a, b: row.b }]) };
+                        return { ...makePorts(runId), screening: () => Promise.resolve([{ a: selected.a, b: selected.b }]) };
                     },
                 }),
             ...(options.timeoutMinutes === undefined ? {} : { timeoutMinutes: options.timeoutMinutes }),
@@ -30,16 +40,38 @@ export async function runResumeCommand(options) {
         });
     }
     if (row.state !== 'fuse' && row.state !== 'approved')
-        return { ok: false, message: 'row is not resumable from state ' + row.state };
+        return failure('resume', 'row-not-resumable', '该行状态是 ' + row.state + '，不可恢复', '只有 approved/fuse 行可恢复；运行 /evolution merge status 查看队列', row.runId);
     if (row.runId !== undefined && (await options.isOwnerActive?.(row.runId)) === true) {
-        return { ok: false, message: 'merge run still owns this fuse row: ' + row.runId };
+        return failure('resume', 'run-owns-row', '该 fuse 行仍由运行中的 run 持有：' + row.runId, '等待该 run 结束，或运行 /evolution merge cancel ' + row.runId, row.runId);
     }
-    const decision = row.decision;
+    if (options.agentless === true)
+        return failure('resume', 'e-305', errorText('e-305-this-invocation-carries-no', { a1: 'resume' }), '在 GUI 或 CLI 的会话里运行 /evolution merge resume --retry ' + row.id);
+    const parentRunId = options.parentRunId ?? row.runId;
+    if (parentRunId === undefined)
+        return failure('resume', 'merge-parent-required', '缺 parent run id（E-305 提示：该行可能由无会话调用创建，或父 run 已丢失）', '在 agent 会话中执行 /evolution merge resume --retry ' + row.id, row.runId);
+    const decision = selected.decision;
     if (decision === undefined)
-        return { ok: false, message: 'fuse row has no decision' };
+        return failure('resume', 'row-invalid', '该 fuse 行没有持久化决策', '重新 pair 该技能对后再次恢复', row.runId);
+    if (selected.state === 'approved' && options.ports.stage !== undefined) {
+        const staged = await options.ports.stage(selected, decision);
+        if (!staged.ok)
+            return failure('resume', 'stage-failed', staged.message, '检查暂存目录后重试；不影响已记录的决策', selected.runId);
+        const fused = await pairLedger(options.io, options.home).transact(tx => {
+            const current = tx.rows().find(item => item.id === selected.id);
+            if (current === undefined)
+                return null;
+            const moved = tx.transition(selected.id, { type: 'staged' }, current.version);
+            return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
+        });
+        if (fused === null)
+            return failure('resume', 'row-changed', '行在暂存完成前被并发修改：' + selected.id, '运行 /evolution merge status ' + selected.id + ' 后重试', selected.runId);
+        await presentStage(options.io, options.home, staged.entry);
+        row = fused;
+    }
     const result = await withMergeRun({
         io: options.io, home: options.home, registry: options.registry,
-        command: 'resume', approval: { platformWrite: options.platformWrite, mergeApproval: true }, now: options.now,
+        command: 'resume', approval: { platformWrite: options.platformWrite, mergeApproval: options.approval }, pairKey: row.pairKey,
+        parentRunId, now: options.now,
         ...(options.detached === true ? { detached: true } : {}),
         async body(ctx) {
             await ctx.stage('author', { done: 0, total: 1 });
@@ -52,13 +84,14 @@ export async function runResumeCommand(options) {
             catch (error) {
                 outcome = { kind: 'failed', failure: { stage: 'author', code: 'merge-failed', message: error instanceof Error ? error.message : String(error), retryable: true, retryFrom: 'agent2' } };
             }
-            const record = await recordRound2Outcome(options.io, options.home, options.now, row, outcome);
+            const record = await recordRound2Outcome(options.io, options.home, options.now, row, outcome, true);
             return {
                 stopReason: record.merged ? 'completed' : 'failed',
                 scope: { candidatePairs: 1, queueBefore: { verify: 0, pending: 0, fuse: 1, skipped: 0 } },
                 pairs: [record.pair],
                 totals: record.merged ? { merged: 1, kept: 0, pending: 0, failed: 0 } : { merged: 0, kept: 0, pending: 0, failed: 1 },
                 notes: [],
+                ...(record.finalize === undefined ? {} : { finalize: record.finalize }),
             };
         },
     });

package/lib/types/revision.d.ts

@@ -1,6 +1,23 @@
 import type { SkillCard } from './skill-card.ts';
+import type { RevisionRef } from './contracts.ts';
 /** Stable source revision for a pair: names sorted, body+support hashed in that order. */
 export declare function sourceRevisionOf(cards: readonly SkillCard[], a: string, b: string): string | undefined;
 /** Revision of the merge target; undefined when the target is not a live card. */
 export declare function targetRevisionOf(cards: readonly SkillCard[], target: string): string | undefined;
+export declare function targetRevisionRefOf(cards: readonly SkillCard[], target: string): RevisionRef;
+/** Per-skill anchors for a set of names; absent names stay `kind: 'absent'` so a
+ *  later commit can tell "was not there" from "was not checked". */
+export declare function sourceRevisionRefsOf(cards: readonly SkillCard[], names: readonly string[]): Readonly<Record<string, RevisionRef>>;
+export declare function sourceRevisionRefOf(cards: readonly SkillCard[], a: string, b: string): RevisionRef;
+/** Record the round-1 anchors a later commit re-checks (target/source/support). */
+export declare function withDecisionRevisions<T extends {
+    readonly target: string;
+}>(decision: T, cards: readonly SkillCard[], a: string, b: string): T & {
+    readonly targetRevisionRef: RevisionRef;
+    readonly sourceRevisionRef: RevisionRef;
+    readonly sourceRevisions: Readonly<Record<string, RevisionRef>>;
+    readonly supportDigest: string;
+};
+export declare function supportDigestOf(cards: readonly SkillCard[], names: readonly string[]): string;
+export declare function revisionMismatch(expected: RevisionRef | undefined, current: RevisionRef): 'target-taken' | 'source-changed' | null;
 //# sourceMappingURL=revision.d.ts.map

package/lib/types/revision.js

@@ -1,7 +1,6 @@
-import { contentHash } from '@lmzhen/dsh-evolution-core';
+import { contentHash, revisionFingerprint, revisionSupportDigest } from '@lmzhen/dsh-evolution-core';
 function fingerprint(card) {
-    const files = [...(card.files ?? [])].sort((left, right) => left.path.localeCompare(right.path));
-    return card.name + '\u0000' + card.body + '\u0000' + files.map(file => file.path + '\u0000' + file.content).join('\u0000');
+    return revisionFingerprint(card.name, card.body, card.files ?? []);
 }
 /** Stable source revision for a pair: names sorted, body+support hashed in that order. */
 export function sourceRevisionOf(cards, a, b) {
@@ -18,4 +17,41 @@ export function targetRevisionOf(cards, target) {
     const card = cards.find(item => item.name === target);
     return card === undefined ? undefined : contentHash(fingerprint(card));
 }
+export function targetRevisionRefOf(cards, target) {
+    const revision = targetRevisionOf(cards, target);
+    return revision === undefined ? { kind: 'absent' } : { kind: 'present', sha256: revision };
+}
+/** Per-skill anchors for a set of names; absent names stay `kind: 'absent'` so a
+ *  later commit can tell "was not there" from "was not checked". */
+export function sourceRevisionRefsOf(cards, names) {
+    const byName = new Map(cards.map(card => [card.name, card]));
+    const out = {};
+    for (const name of [...new Set(names)].sort()) {
+        const card = byName.get(name);
+        out[name] = card === undefined ? { kind: 'absent' } : { kind: 'present', sha256: contentHash(fingerprint(card)) };
+    }
+    return out;
+}
+export function sourceRevisionRefOf(cards, a, b) {
+    const revision = sourceRevisionOf(cards, a, b);
+    return revision === undefined ? { kind: 'absent' } : { kind: 'present', sha256: revision };
+}
+/** Record the round-1 anchors a later commit re-checks (target/source/support). */
+export function withDecisionRevisions(decision, cards, a, b) {
+    return { ...decision, targetRevisionRef: targetRevisionRefOf(cards, decision.target), sourceRevisionRef: sourceRevisionRefOf(cards, a, b), sourceRevisions: sourceRevisionRefsOf(cards, [a, b]), supportDigest: supportDigestOf(cards, [decision.target, a, b]) };
+}
+export function supportDigestOf(cards, names) {
+    const byName = new Map(cards.map(card => [card.name, card]));
+    const involved = [...new Set(names)].map(name => byName.get(name)).filter((card) => card !== undefined);
+    return revisionSupportDigest(involved.map(fingerprint));
+}
+export function revisionMismatch(expected, current) {
+    if (expected === undefined)
+        return null;
+    if (expected.kind !== current.kind)
+        return 'target-taken';
+    if (expected.kind === 'absent')
+        return null;
+    return current.kind === 'present' && expected.sha256 === current.sha256 ? null : 'target-taken';
+}
 //# sourceMappingURL=revision.js.map

package/lib/types/round2-outcome.d.ts

@@ -8,6 +8,7 @@ import type { ScanRound2Outcome } from './scan-run.ts';
 export interface Round2Record {
     readonly pair: MergeReportPair;
     readonly merged: boolean;
+    readonly finalize?: () => Promise<void>;
 }
-export declare function recordRound2Outcome(io: EvolutionIoLike, home: string, now: () => number, row: MergeRow, outcome: ScanRound2Outcome): Promise<Round2Record>;
+export declare function recordRound2Outcome(io: EvolutionIoLike, home: string, now: () => number, row: MergeRow, outcome: ScanRound2Outcome, deferProjection?: boolean): Promise<Round2Record>;
 //# sourceMappingURL=round2-outcome.d.ts.map

package/lib/types/round2-outcome.js

@@ -1,14 +1,21 @@
-import { v3ToLegacy } from "./domain/row-v3-bridge.js";
-import { dropRowV3, transactRows } from "./state.js";
-import { recordPair } from "./domain/pair-index-store.js";
-export async function recordRound2Outcome(io, home, now, row, outcome) {
+import { v4ToLegacy } from "./domain/row-v4.js";
+import { pairLedger } from "./domain/pair-ledger.js";
+import { dropStage } from "./domain/stage-aggregate.js";
+import { casExpiredHook } from "./domain/failure-route.js";
+import { recordPair } from "./domain/run-coordinator.js";
+export async function recordRound2Outcome(io, home, now, row, outcome, deferProjection = false) {
     void now;
     if (outcome.kind === 'merged') {
-        {
-            const dropped = await dropRowV3(io, home, row.id, 'committed', outcome.unitId ?? 'unknown');
-            if (!dropped)
-                return { merged: false, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, outcome: 'failed', archived: [], failure: { stage: 'commit', code: 'row-changed', message: 'row changed before commit record', retryable: true, retryFrom: 'agent2' } } };
-            const target = outcome.target?.actual ?? outcome.target?.requested ?? row.decision?.target;
+        const unitRef = { unitId: outcome.unitId ?? 'unknown', evidenceSha256: outcome.evidenceSha256 ?? 'unknown' };
+        const target = outcome.target?.actual ?? outcome.target?.requested ?? row.decision?.target;
+        const finalize = async () => {
+            const removed = await pairLedger(io, home).transact(tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                return current === undefined ? { ok: false, code: 'row-not-found', message: 'row not found' } : tx.remove(row.id, 'committed', unitRef, current.version);
+            });
+            if (!removed.ok)
+                throw new Error('row changed before commit record: ' + row.id);
+            await dropStage(io, home, row.id);
             await recordPair(io, home, {
                 pairKey: row.pairKey,
                 runId: row.runId ?? 'merge',
@@ -16,6 +23,11 @@ export async function recordRound2Outcome(io, home, now, row, outcome) {
                 ...(target === undefined ? {} : { target }),
                 ...(outcome.unitId === undefined ? {} : { reportRef: outcome.unitId }),
             });
+        };
+        if (deferProjection)
+            return { merged: true, finalize, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, ...(row.decision === undefined ? {} : { decision: row.decision }), outcome: 'merged', archived: outcome.archived ?? [], ...(outcome.unitId === undefined ? {} : { unitId: outcome.unitId }), ...(outcome.target === undefined ? {} : { target: outcome.target }) } };
+        {
+            await finalize();
         }
         return {
             merged: true,
@@ -25,16 +37,52 @@ export async function recordRound2Outcome(io, home, now, row, outcome) {
                 outcome: 'merged', archived: outcome.archived ?? [],
                 ...(outcome.unitId === undefined ? {} : { unitId: outcome.unitId }),
                 ...(outcome.target === undefined ? {} : { target: outcome.target }),
+                ...(outcome.validationPlan === undefined ? {} : { validationPlan: outcome.validationPlan }),
             },
         };
     }
     const failure = outcome.failure ?? { stage: 'author', code: 'merge-failed', message: 'round2 failed', retryable: true, retryFrom: 'agent2' };
-    const projected = await transactRows(io, home, tx => {
+    if (failure.code === 'merge-over-limit' || failure.code === 'limit' || failure.code === 'merge-validation') {
+        const reason = failure.code === 'merge-validation' ? 'validation-failed' : 'merge-over-limit';
+        const skipped = await pairLedger(io, home).transact(tx => {
+            const current = tx.rows().find(item => item.id === row.id);
+            return current === undefined ? false : tx.transition(row.id, { type: 'skipped', reason, origin: 'system', skipSource: 'system' }, current.version).ok;
+        });
+        if (skipped)
+            await dropStage(io, home, row.id);
+        return { merged: false, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, ...(row.decision === undefined ? {} : { decision: row.decision }), outcome: 'failed', archived: [], failure } };
+    }
+    const cas = casExpiredHook(failure.code);
+    if (cas !== null) {
+        await pairLedger(io, home).transact(tx => {
+            const current = tx.rows().find(item => item.id === row.id);
+            if (current === undefined)
+                return false;
+            const moved = tx.transition(row.id, { type: 'skipped', reason: cas.reason, origin: 'system', skipSource: 'system' }, current.version);
+            return moved.ok;
+        });
+        await dropStage(io, home, row.id);
+        return { merged: false, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, ...(row.decision === undefined ? {} : { decision: row.decision }), outcome: 'failed', archived: [], failure: { ...failure, code: cas.reason, retryable: false, retryFrom: 'none' } } };
+    }
+    if (failure.code === 'commit-failed' || failure.code === 'validation-failed') {
+        await pairLedger(io, home).transact(tx => {
+            const current = tx.rows().find(item => item.id === row.id);
+            return current === undefined ? false : tx.remove(row.id, 'superseded', undefined, current.version).ok;
+        });
+    }
+    if (failure.code === 'source-gone') {
+        await pairLedger(io, home).transact(tx => {
+            const current = tx.rows().find(item => item.id === row.id);
+            return current === undefined ? false : tx.remove(row.id, 'superseded', undefined, current.version).ok;
+        });
+        return { merged: false, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, outcome: 'failed', archived: [], failure } };
+    }
+    const projected = await pairLedger(io, home).transact(tx => {
         const current = tx.rows().find(item => item.id === row.id);
         if (current === undefined)
             return null;
         const moved = tx.transition(row.id, { type: 'failed', failure }, current.version);
-        return moved.ok && moved.row !== null ? v3ToLegacy(moved.row) : null;
+        return moved.ok && moved.row !== null ? v4ToLegacy(moved.row) : null;
     });
     if (projected === null)
         return { merged: false, pair: { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, queue: row.queue, outcome: 'failed', archived: [], failure: { ...failure, code: 'row-changed', message: 'row changed before failure record' } } };

package/lib/types/run-shell.d.ts

@@ -7,12 +7,12 @@
  */
 import type { EvolutionIoLike, RunHandle, RunKind, RunStage } from '@lmzhen/dsh-evolution-core';
 import type { MergeReport, MergeReportPair, MergeRunCommand } from './contracts.ts';
+import type { MergeError } from './domain/errors.ts';
 export interface MergeRegistryPort {
     begin(kind: RunKind, seed?: {
         command?: MergeRunCommand;
         total?: number;
         parentRunId?: string;
-        mergeStatus?: 'running' | 'succeeded' | 'failed' | 'cancelled' | 'awaiting-approval' | 'undone' | 'superseded' | 'interrupted' | 'orphan';
     }): Promise<Pick<RunHandle, 'id' | 'signal' | 'startedAt'>>;
     stage(id: string, stage: RunStage, progress?: {
         done: number;
@@ -22,7 +22,6 @@ export interface MergeRegistryPort {
         state: 'succeeded' | 'failed' | 'cancelled';
         resultRef?: string;
         failure?: string;
-        mergeStatus?: 'running' | 'succeeded' | 'failed' | 'cancelled' | 'awaiting-approval' | 'undone' | 'superseded' | 'interrupted' | 'orphan';
     }): Promise<void>;
 }
 export interface MergeRunBodyContext {
@@ -41,6 +40,15 @@ export interface MergeRunReportDraft {
     readonly totals: MergeReport['totals'];
     readonly notes: readonly string[];
     readonly remaining?: MergeReport['remaining'];
+    readonly reportOnly?: MergeReport['reportOnly'];
+    readonly validationFailures?: MergeReport['validationFailures'];
+    readonly archived?: MergeReport['archived'];
+    readonly commit?: MergeReport['commit'];
+    readonly usage?: MergeReport['usage'];
+    readonly timing?: MergeReport['timing'];
+    readonly criteria?: MergeReport['criteria'];
+    /** Runs after the report is durable and before core settle (row/stage projection). */
+    readonly finalize?: () => Promise<void>;
 }
 export interface WithMergeRunOptions {
     readonly io: EvolutionIoLike;
@@ -50,7 +58,11 @@ export interface WithMergeRunOptions {
     readonly approval: MergeReport['approval'];
     readonly now: () => number;
     readonly total?: number;
+    readonly pairKey?: string;
+    readonly pairCount?: number;
+    readonly parentRunId?: string;
     readonly detached?: boolean;
+    readonly timeoutMinutes?: number;
     readonly body: (ctx: MergeRunBodyContext) => Promise<MergeRunReportDraft>;
 }
 export type WithMergeRunResult = {
@@ -67,6 +79,8 @@ export type WithMergeRunResult = {
     readonly runId?: string;
     readonly message: string;
     readonly reportPath?: string;
+    readonly error?: MergeError;
 };
+export declare function retryMergeReport(io: EvolutionIoLike, home: string, report: MergeReport): Promise<string>;
 export declare function withMergeRun(options: WithMergeRunOptions): Promise<WithMergeRunResult>;
 //# sourceMappingURL=run-shell.d.ts.map