@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.18

package/lib/types/commit-recovery.js

@@ -1,120 +1,97 @@
-/** Startup replay for non-terminal commit journals. */
+/** Startup replay for non-terminal commit journals: report only, never write skills. */
 import { join } from 'node:path';
-import { recoveryFor } from "./domain/commit-journal.js";
 import { writeJournal } from "./domain/commit-journal-store.js";
-import { readCommitSnapshot, skillBodyPath, skillFilePath } from "./commit-snapshot.js";
+import { snapshotPath } from "./commit-snapshot.js";
 import { readCommitReceipt } from "./commit-receipt.js";
-export async function recoverCommitJournals(io, home, now, skillRoot, restoreSource, isActive) {
+import { readUnitEvidence } from '@lmzhen/dsh-evolution-core';
+export async function recoverCommitJournals(io, home, now, isActive) {
     const dir = join(home, 'merge', 'journals');
-    if (!(await io.exists(dir)))
-        return [];
-    const files = (await io.list(dir)).filter(name => name.endsWith('.json'));
     const reports = [];
-    for (const file of files) {
-        let journal;
-        try {
-            journal = JSON.parse(await io.readText(join(dir, file)) ?? '');
-        }
-        catch {
-            continue;
-        }
-        if (isActive?.(journal.runId) === true) {
-            reports.push({ runId: journal.runId, phase: journal.phase, action: 'skipped-active-run', ok: true });
-            continue;
-        }
-        const recovery = recoveryFor(journal);
-        if (recovery === 'none')
-            continue;
-        if (recovery === 'refuse') {
-            reports.push({ runId: journal.runId, phase: journal.phase, action: 'unknown-phase-refused', ok: false });
-            continue;
-        }
-        let receipt = null;
+    let files = [];
+    if (await io.exists(dir)) {
         try {
-            receipt = await readCommitReceipt(io, home, journal.runId, journal.target);
+            files = (await io.list(dir)).filter(name => name.endsWith('.json'));
         }
         catch {
-            reports.push({ runId: journal.runId, phase: journal.phase, action: 'receipt-read-failed', ok: false });
-            continue;
+            reports.push({ runId: '(list)', phase: 'unknown', action: 'journal-list-failed', ok: false, journalPath: dir });
         }
-        if (receipt !== null) {
-            await writeJournal(io, home, { ...journal, phase: 'committed', unitId: receipt.unitId, updatedAt: new Date(now).toISOString() });
-            reports.push({ runId: journal.runId, phase: journal.phase, action: 'receipt-committed', ok: true });
-            continue;
-        }
-        let snapshot;
+    }
+    for (const file of files) {
+        const path = join(dir, file);
         try {
-            snapshot = await readCommitSnapshot(io, home, journal.runId);
+            let journal;
+            try {
+                journal = JSON.parse(await io.readText(path) ?? '');
+            }
+            catch {
+                reports.push({ runId: file.replace(/\.json$/, ''), phase: 'unknown', action: 'journal-unreadable', ok: false, journalPath: path });
+                continue;
+            }
+            if (isActive?.(journal.runId) === true) {
+                reports.push({ runId: journal.runId, phase: journal.phase, action: 'skipped-active-run', ok: true, target: journal.target, sources: journal.sources, journalPath: path });
+                continue;
+            }
+            let receipt = null;
+            try {
+                receipt = await readCommitReceipt(io, home, journal.runId, journal.target);
+            }
+            catch {
+                reports.push({ runId: journal.runId, phase: journal.phase, action: 'receipt-read-failed', ok: false, target: journal.target, sources: journal.sources, journalPath: path });
+                continue;
+            }
+            if (receipt !== null) {
+                await writeJournal(io, home, { ...journal, phase: 'committed', unitId: receipt.unitId, updatedAt: new Date(now).toISOString() });
+                reports.push({ runId: journal.runId, phase: journal.phase, action: 'receipt-committed', ok: true, target: journal.target, sources: journal.sources, journalPath: path, unitId: receipt.unitId });
+                continue;
+            }
+            if (journal.phase === 'committed') {
+                reports.push({ runId: journal.runId, phase: journal.phase, action: 'receipt-missing', ok: false, target: journal.target, sources: journal.sources, journalPath: path });
+                continue;
+            }
+            if (journal.phase === 'failed' || journal.phase === 'rolled-back')
+                continue;
+            reports.push({
+                runId: journal.runId, phase: journal.phase, action: 'manual-required', ok: false,
+                target: journal.target, sources: journal.sources, journalPath: path, snapshotPath: snapshotPath(home, journal.runId),
+            });
         }
         catch (error) {
-            reports.push({ runId: journal.runId, phase: journal.phase, action: 'snapshot-read-failed: ' + (error instanceof Error ? error.message : String(error)), ok: false });
-            continue;
-        }
-        let action = 'report-only';
-        let ok = true;
-        if (recovery === 'retry-commit') {
-            action = 'no-host-write';
+            reports.push({ runId: file.replace(/\.json$/, ''), phase: 'unknown', action: 'recovery-error: ' + (error instanceof Error ? error.message : String(error)), ok: false, journalPath: path });
         }
-        else if (snapshot === null) {
-            action = 'snapshot-missing';
-            ok = false;
+    }
+    const unitDir = join(home, 'merge', 'unit-journals');
+    if (await io.exists(unitDir)) {
+        let unitFiles = [];
+        try {
+            unitFiles = (await io.list(unitDir)).filter(name => name.endsWith('.json'));
         }
-        else {
+        catch { /* no unit journals */ }
+        for (const file of unitFiles) {
+            const path = join(unitDir, file);
             try {
-                if (recovery === 'rollback-sources') {
-                    let restoredArchived = restoreSource !== undefined;
-                    if (restoreSource !== undefined) {
-                        for (const source of snapshot.sourceBodies) {
-                            if (!(await restoreSource(source.name)))
-                                restoredArchived = false;
-                        }
-                    }
-                    if (!restoredArchived) {
-                        for (const source of snapshot.sourceBodies)
-                            await io.writeText(skillBodyPath(skillRoot, source.name), source.body);
-                    }
-                }
-                if (snapshot.create && snapshot.targetBody === null) {
-                    try {
-                        await io.remove(skillBodyPath(skillRoot, snapshot.target));
-                    }
-                    catch { /* already gone */ }
-                    try {
-                        const dir = join(skillRoot, snapshot.target);
-                        if ((await io.list(dir)).length === 0)
-                            await io.remove(dir);
-                    }
-                    catch { /* absent or non-empty */ }
+                const journal = JSON.parse(await io.readText(path) ?? '');
+                const evidence = await readUnitEvidence(io, home, journal.unitId);
+                if (evidence !== null) {
+                    reports.push({ runId: journal.runId, phase: 'committed', action: 'unit-committed', ok: true, target: journal.target, sources: journal.sources, journalPath: path, unitId: journal.unitId });
+                    continue;
                 }
-                else if (snapshot.targetBody !== null) {
-                    await io.writeText(skillBodyPath(skillRoot, snapshot.target), snapshot.targetBody);
+                if (journal.phase === 'committed') {
+                    reports.push({ runId: journal.runId, phase: 'committed', action: 'unit-evidence-missing', ok: false, target: journal.target, sources: journal.sources, journalPath: path, unitId: journal.unitId });
+                    continue;
                 }
-                const oldPaths = new Set((snapshot.targetSupport ?? []).map(file => file.path));
-                for (const file of snapshot.targetSupport ?? []) {
-                    await io.writeText(skillFilePath(skillRoot, snapshot.target, file.path), file.content);
-                }
-                for (const file of snapshot.targetSupportAfter ?? []) {
-                    if (!oldPaths.has(file.path)) {
-                        try {
-                            await io.remove(skillFilePath(skillRoot, snapshot.target, file.path));
-                        }
-                        catch { /* already gone */ }
-                    }
-                }
-                for (const file of snapshot.sourceSupport ?? [])
-                    await io.writeText(skillFilePath(skillRoot, file.name, file.path), file.content);
-                action = recovery === 'rollback-sources' ? 'restored-sources-and-target' : 'restored-target';
+                if (journal.phase === 'failed' || journal.phase === 'rolled-back')
+                    continue;
+                reports.push({ runId: journal.runId, phase: journal.phase, action: 'unit-manual-required', ok: false, target: journal.target, sources: journal.sources, journalPath: path, unitId: journal.unitId });
             }
-            catch (error) {
-                action = 'restore-failed: ' + (error instanceof Error ? error.message : String(error));
-                ok = false;
+            catch {
+                reports.push({ runId: '(unit)', phase: 'unknown', action: 'unit-journal-unreadable', ok: false, journalPath: path });
             }
         }
-        if (ok)
-            await writeJournal(io, home, { ...journal, phase: 'rolled-back', updatedAt: new Date(now).toISOString() });
-        reports.push({ runId: journal.runId, phase: journal.phase, action, ok });
     }
-    await io.writeText(join(home, 'merge', 'recovery.json'), JSON.stringify(reports, null, 2));
+    try {
+        await io.writeText(join(home, 'merge', 'recovery.json'), JSON.stringify(reports, null, 2));
+    }
+    catch { /* report file is best-effort; reports are still returned */ }
     return reports;
 }
 //# sourceMappingURL=commit-recovery.js.map

package/lib/types/contracts.d.ts

@@ -4,7 +4,7 @@
  * The data layer keeps four states; the user face collapses verify/fuse into one retry
  * queue and keeps the stage as a chip. The API queue must never expose the raw state.
  */
-export declare const MERGE_STATE_VERSION = 2;
+export declare const MERGE_STATE_VERSION = 3;
 export type MergePairState = 'verify' | 'pending' | 'approved' | 'fuse' | 'skipped';
 export type MergeQueue = 'verify' | 'pending' | 'fuse' | 'skipped';
 export type MergeStage = 'verify' | 'decide' | 'author' | 'commit';

package/lib/types/contracts.js

@@ -4,7 +4,7 @@
  * The data layer keeps four states; the user face collapses verify/fuse into one retry
  * queue and keeps the stage as a chip. The API queue must never expose the raw state.
  */
-export const MERGE_STATE_VERSION = 2;
+export const MERGE_STATE_VERSION = 3;
 export const MERGE_PAIR_STATES = ['verify', 'pending', 'approved', 'fuse', 'skipped'];
 export const MERGE_QUEUES = ['verify', 'pending', 'fuse', 'skipped'];
 /** User-facing queue of one data state. verify/fuse share retry, not two tabs. */

package/lib/types/coordinator.d.ts

@@ -2,7 +2,7 @@
  * Pure merge transition table. No io, no run shell, no subagents.
  *
  * Every transition returns the whole next row (or a drop), so the caller can persist it
- * through mutateMergeState in one transaction. Invalid transitions are refused by name;
+ * through one state transaction. Invalid transitions are refused by name;
  * a caller never "repairs" a row by guessing which state the operator meant.
  */
 import { type MergeDecision, type MergeFailure, type MergeRow } from './contracts.ts';
@@ -72,5 +72,6 @@ export type TransitionResult = {
     readonly code: 'invalid-transition';
     readonly message: string;
 };
-export declare function transition(current: MergeRow | undefined, event: MergeEvent): TransitionResult;
+/** Legacy v2 projection only; runtime writes must use transitionV3/RowTx. */
+export declare function transitionLegacyForProjection(current: MergeRow | undefined, event: MergeEvent): TransitionResult;
 //# sourceMappingURL=coordinator.d.ts.map

package/lib/types/coordinator.js

@@ -2,7 +2,7 @@
  * Pure merge transition table. No io, no run shell, no subagents.
  *
  * Every transition returns the whole next row (or a drop), so the caller can persist it
- * through mutateMergeState in one transaction. Invalid transitions are refused by name;
+ * through one state transaction. Invalid transitions are refused by name;
  * a caller never "repairs" a row by guessing which state the operator meant.
  */
 import { pairKey, queueOf, rowIdOf, } from "./contracts.js";
@@ -49,7 +49,8 @@ function next(row, at, state, patch = {}) {
         },
     };
 }
-export function transition(current, event) {
+/** Legacy v2 projection only; runtime writes must use transitionV3/RowTx. */
+export function transitionLegacyForProjection(current, event) {
     if (event.type === 'candidate') {
         if (current !== undefined)
             return { ok: true, row: current };
@@ -106,7 +107,7 @@ export function transition(current, event) {
                 : invalid(event, current.state);
         case 'approve':
             return current.state === 'pending'
-                ? next(current, event.at, 'approved', { ...(event.runId === undefined ? {} : { runId: event.runId }) })
+                ? next(current, event.at, 'approved', (event.runId === undefined ? {} : { runId: event.runId }))
                 : invalid(event, current.state);
         case 'reject':
             return current.state === 'pending' ? next(current, event.at, 'skipped', { origin: 'human' }) : invalid(event, current.state);

package/lib/types/decision.js

@@ -1,5 +1,5 @@
 function extractJson(text) {
-    const fenced = /\`\`\`(?:json)?\s*([\s\S]*?)\`\`\`/i.exec(text);
+    const fenced = /`\``(?:json)?\s*([\s\S]*?)`\``/i.exec(text);
     const body = fenced?.[1] ?? text;
     const start = body.indexOf('{');
     if (start < 0)

package/lib/types/doctor.d.ts

@@ -6,5 +6,12 @@ export interface MergeDoctorRow {
     readonly status: 'ok' | 'warn' | 'unknown';
     readonly detail: string;
 }
+/** Global doctor host section: a missing merge mount must fail with E-325, not render empty. */
+export declare function mergeDoctorAvailability(mounted: boolean): {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: 'E-325';
+};
 export declare function mergeDoctor(io: EvolutionIoLike, home: string, configuredRoot?: string): Promise<readonly MergeDoctorRow[]>;
 //# sourceMappingURL=doctor.d.ts.map

package/lib/types/doctor.js

@@ -4,11 +4,19 @@
  * operator can act on. This module never repairs or writes.
  */
 import { join } from 'node:path';
-import { probeList } from '@lmzhen/dsh-evolution-core';
+import { probeList, readTreeLock, runsFile } from '@lmzhen/dsh-evolution-core';
+import { v2BackupPath } from "./domain/state-v3.js";
 import { loadMergeState } from "./state.js";
 import { countRows } from "./status.js";
 import { stagingRoot } from "./staging.js";
+import { validateArtifacts } from "./domain/consistency.js";
+import { readJournal } from "./domain/commit-journal-store.js";
+import { loadStateSchema } from "./state.js";
 export const MERGE_DOCTOR_SCHEMA_VERSION = 3;
+/** Global doctor host section: a missing merge mount must fail with E-325, not render empty. */
+export function mergeDoctorAvailability(mounted) {
+    return mounted ? { ok: true } : { ok: false, code: 'E-325' };
+}
 export async function mergeDoctor(io, home, configuredRoot) {
     const rows = [];
     const loaded = await loadMergeState(io, home);
@@ -19,9 +27,83 @@ export async function mergeDoctor(io, home, configuredRoot) {
         status: loaded.note === undefined ? 'ok' : 'warn',
         detail: loaded.note ?? 'pairs ' + String(loaded.state.rows.length) + '；verify ' + String(counts.verify) + ' / pending ' + String(counts.pending) + ' / fuse ' + String(counts.fuse) + ' / skipped ' + String(counts.skipped),
     });
-    const modelRoot = configuredRoot !== undefined && configuredRoot !== '' ? configuredRoot : process.env.SKILL_MERGE_MODELS_ROOT;
-    if (modelRoot === undefined || modelRoot === '') {
-        rows.push({ key: 'models', label: '合并模型', status: 'warn', detail: '未设置 SKILL_MERGE_MODELS_ROOT；合并扫描会 fail loud' });
+    const recoveryRuns = new Set();
+    try {
+        const raw = await io.readText(join(home, 'merge', 'recovery.json'));
+        if (raw !== null)
+            for (const report of JSON.parse(raw))
+                if (report.ok === true && report.runId !== undefined)
+                    recoveryRuns.add(report.runId);
+    }
+    catch { }
+    const receiptRuns = new Set();
+    const receiptDir = await probeList(io, join(home, 'merge', 'receipts'));
+    if (receiptDir.kind === 'present')
+        for (const name of receiptDir.value)
+            receiptRuns.add(name);
+    const invalid = [];
+    for (const row of loaded.state.rows) {
+        const run = row.state === 'pending' && row.runId !== undefined ? 'awaiting-approval' : row.runId === undefined ? 'none' : 'running';
+        const staging = row.stagingRef !== undefined ? 'kept' : row.state === 'fuse' ? 'missing' : 'none';
+        const phase = row.runId === undefined ? undefined : (await readJournal(io, home, row.runId))?.phase;
+        const journal = phase === undefined || phase === null ? 'none'
+            : phase === 'committed' ? 'committed'
+                : phase === 'prepared' ? 'prepared'
+                    : phase === 'rolled-back' ? 'rolled-back'
+                        : phase === 'failed' ? 'failed'
+                            : 'committing';
+        const evidence = row.runId !== undefined && receiptRuns.has(row.runId) ? 'receipt' : 'none';
+        const recovery = row.runId !== undefined && recoveryRuns.has(row.runId);
+        if (!validateArtifacts({ row: row.state, run, staging, journal, evidence, activeRuns: run === 'running' || run === 'awaiting-approval' ? 1 : 0, recovery }).ok)
+            invalid.push(row);
+    }
+    const schema = await loadStateSchema(io, home);
+    rows.push({ key: 'merge-state-v3', label: 'state schema', status: schema === 3 ? 'ok' : schema === 2 ? 'warn' : 'unknown', detail: schema === 3 ? 'schemaVersion 3' : schema === 2 ? 'schemaVersion 2；等待 v3 迁移' : 'schemaVersion 未知/不可读' });
+    let quarantineCount = 0;
+    try {
+        const qraw = await io.readText(join(home, 'merge', 'merge-state.quarantine.json'));
+        if (qraw !== null) {
+            const parsed = JSON.parse(qraw);
+            quarantineCount = Array.isArray(parsed) ? parsed.length : 0;
+        }
+    }
+    catch {
+        quarantineCount = -1;
+    }
+    rows.push({ key: 'quarantine', label: 'quarantine', status: quarantineCount < 0 ? 'unknown' : quarantineCount === 0 ? 'ok' : 'warn', detail: quarantineCount < 0 ? 'quarantine 不可读' : quarantineCount + ' 行待人工检查' });
+    const holder = await readTreeLock(io, home).catch(() => null);
+    rows.push({ key: 'tree-lock', label: 'tree lock', status: holder == null ? 'ok' : 'warn', detail: holder == null ? 'free' : 'holder pid=' + String(holder.pid) + ' epoch=' + String(holder.epoch) + ' token=' + holder.token.slice(0, 8) });
+    rows.push({ key: 'backup', label: 'v2 backup', status: await io.exists(v2BackupPath(home)) ? 'ok' : 'unknown', detail: await io.exists(v2BackupPath(home)) ? 'merge-state.v2.bak.json' : 'no v2 backup (not migrated or already cleaned)' });
+    const claims = await probeList(io, join(home, 'merge', 'claims'));
+    rows.push({ key: 'target-claim', label: 'target claim', status: claims.kind === 'unknown' ? 'unknown' : 'ok', detail: claims.kind === 'unknown' ? 'claims unreadable' : claims.kind === 'absent' ? 'no claims' : String(claims.value.length) + ' claim files' });
+    let orphanRuns = 0;
+    let runCount = 0;
+    try {
+        const raw = await io.readText(runsFile(home));
+        if (raw !== null) {
+            const parsed = JSON.parse(raw);
+            runCount = parsed.runs?.length ?? 0;
+            for (const run of parsed.runs ?? []) {
+                if (run.state !== 'running' || typeof run.pid !== 'number')
+                    continue;
+                try {
+                    process.kill(run.pid, 0);
+                }
+                catch {
+                    orphanRuns += 1;
+                }
+            }
+        }
+    }
+    catch {
+        orphanRuns = -1;
+    }
+    rows.push({ key: 'runs', label: 'run owner', status: orphanRuns < 0 ? 'unknown' : orphanRuns === 0 ? 'ok' : 'warn', detail: orphanRuns < 0 ? 'runs.json unreadable' : String(runCount) + ' runs; ' + String(orphanRuns) + ' dead-owner running' });
+    rows.push({ key: 'install', label: 'install form', status: io.exists === undefined ? 'unknown' : 'ok', detail: 'merge plugin loaded' });
+    rows.push({ key: 'consistency', label: '一致性', status: invalid.length === 0 ? 'ok' : 'warn', detail: invalid.length === 0 ? '无非法组合' : String(invalid.length) + ' 行需人工检查: ' + invalid.map(row => row.id).join(', ') });
+    const modelRoot = configuredRoot?.trim() ?? '';
+    if (modelRoot === '') {
+        rows.push({ key: 'models', label: '合并模型', status: 'warn', detail: '未配置 mergeModelsRoot；合并扫描会 fail loud' });
     }
     else {
         const int8 = join(modelRoot, 'potion-multilingual-128M-int8');
@@ -45,6 +127,24 @@ export async function mergeDoctor(io, home, configuredRoot) {
         status: 'ok',
         detail: stagingRoot(home, '<runId>'),
     });
+    try {
+        const raw = await io.readText(join(home, 'merge', 'recovery.json'));
+        if (raw !== null) {
+            const reports = JSON.parse(raw);
+            const failed = reports.filter(report => report.ok !== true);
+            rows.push({
+                key: 'recovery',
+                label: '提交恢复',
+                status: failed.length === 0 ? 'ok' : 'warn',
+                detail: failed.length === 0
+                    ? String(reports.length) + ' 条恢复报告，无待处理'
+                    : String(failed.length) + ' 条待处理：' + failed.map(report => (report.runId ?? '?') + '=' + (report.action ?? '?')).join(', '),
+            });
+        }
+    }
+    catch {
+        rows.push({ key: 'recovery', label: '提交恢复', status: 'unknown', detail: '无法读取 merge/recovery.json' });
+    }
     return rows;
 }
 //# sourceMappingURL=doctor.js.map

package/lib/types/domain/claim.d.ts

@@ -3,8 +3,11 @@ export interface Claim {
     readonly id: string;
     readonly token: string;
     readonly expiresAt: number;
+    readonly pid?: number;
+    /** Process start time; detects pid reuse when the same pid hosts a newer process. */
+    readonly startedAt?: number;
 }
-export declare function acquireClaim(current: Claim | undefined, now: number, leaseMs: number, token: string): Claim | undefined;
+export declare function acquireClaim(current: Claim | undefined, now: number, leaseMs: number, token: string, pid?: number, startedAt?: number): Claim | undefined;
 export declare function releaseClaim(current: Claim | undefined, token: string): Claim | undefined;
 export declare function isClaimExpired(current: Claim | undefined, now: number): boolean;
 //# sourceMappingURL=claim.d.ts.map

package/lib/types/domain/claim.js

@@ -1,7 +1,7 @@
-export function acquireClaim(current, now, leaseMs, token) {
+export function acquireClaim(current, now, leaseMs, token, pid, startedAt) {
     if (current !== undefined && current.expiresAt > now)
         return undefined;
-    return { id: 'claim', token, expiresAt: now + Math.max(1, leaseMs) };
+    return { id: 'claim', token, expiresAt: now + Math.max(1, leaseMs), ...(pid === undefined ? {} : { pid }), ...(startedAt === undefined ? {} : { startedAt }) };
 }
 export function releaseClaim(current, token) {
     return current?.token === token ? undefined : current;

package/lib/types/domain/commit-journal-store.js

@@ -5,7 +5,11 @@ export function journalPath(home, runId) {
 }
 export async function writeJournal(io, home, journal) {
     const path = journalPath(home, journal.runId);
-    await io.writeText(path, JSON.stringify(journal, null, 2));
+    const content = JSON.stringify(journal, null, 2);
+    if (io.transact !== undefined)
+        await io.transact(path, () => content);
+    else
+        await io.writeText(path, content);
     return path;
 }
 export async function readJournal(io, home, runId) {

package/lib/types/domain/commit-journal.js

@@ -1,5 +1,5 @@
 const NEXT = {
-    prepared: ['target-written', 'failed'],
+    prepared: ['committed', 'target-written', 'failed'],
     'target-written': ['sources-archived', 'rolled-back', 'failed'],
     'sources-archived': ['committed', 'rolled-back', 'failed'],
     committed: [],

package/lib/types/domain/consistency.d.ts

@@ -0,0 +1,22 @@
+/** RG0 cross-artifact consistency. Pure; no IO. */
+export type RowState = 'verify' | 'pending' | 'approved' | 'fuse' | 'skipped' | 'merged';
+export type RunState = 'none' | 'awaiting-approval' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'orphan';
+export type StagingState = 'none' | 'cleaned' | 'kept' | 'missing';
+export type JournalState = 'none' | 'committing' | 'prepared' | 'committed' | 'rolled-back' | 'failed';
+export type EvidenceState = 'none' | 'receipt';
+export interface ArtifactState {
+    readonly row: RowState;
+    readonly run: RunState;
+    readonly staging: StagingState;
+    readonly journal: JournalState;
+    readonly evidence: EvidenceState;
+    readonly activeRuns: number;
+    readonly hasOwner?: boolean;
+    readonly recovery?: boolean;
+}
+export interface ConsistencyResult {
+    readonly ok: boolean;
+    readonly reason?: string;
+}
+export declare function validateArtifacts(state: ArtifactState): ConsistencyResult;
+//# sourceMappingURL=consistency.d.ts.map

package/lib/types/domain/consistency.js

@@ -0,0 +1,50 @@
+const ALLOWED = [
+    { row: 'verify', run: 'none', staging: 'none', journal: 'none', evidence: 'none', activeRuns: 0 },
+    { row: 'verify', run: 'running', staging: 'none', journal: 'none', evidence: 'none', activeRuns: 1 },
+    { row: 'verify', run: 'failed', staging: 'none', journal: 'none', evidence: 'none', activeRuns: 0 },
+    { row: 'pending', run: 'none', staging: 'none', journal: 'none', evidence: 'none', activeRuns: 0 },
+    { row: 'pending', run: 'awaiting-approval', staging: 'none', journal: 'none', evidence: 'none', activeRuns: 1 },
+    { row: 'approved', run: 'none', staging: 'none', journal: 'none', evidence: 'none', activeRuns: 0 },
+    { row: 'approved', run: 'running', staging: 'none', journal: 'none', evidence: 'none', activeRuns: 1 },
+    { row: 'fuse', run: 'none', staging: 'kept', journal: 'none', evidence: 'none', activeRuns: 0 },
+    { row: 'fuse', run: 'running', staging: 'kept', journal: 'none', evidence: 'none', activeRuns: 1 },
+    { row: 'fuse', run: 'failed', staging: 'kept', journal: 'none', evidence: 'none', activeRuns: 0 },
+    { row: 'fuse', run: 'orphan', staging: 'kept', journal: 'none', evidence: 'none', activeRuns: 0 },
+    { row: 'fuse', run: 'none', staging: 'none', journal: 'none', evidence: 'none', activeRuns: 0, recovery: true },
+    { row: 'fuse', run: 'failed', staging: 'none', journal: 'none', evidence: 'none', activeRuns: 0, recovery: true },
+    { row: 'fuse', run: 'orphan', staging: 'none', journal: 'none', evidence: 'none', activeRuns: 0, recovery: true },
+    { row: 'fuse', run: 'running', staging: 'none', journal: 'none', evidence: 'none', activeRuns: 1, recovery: true },
+    { row: 'fuse', run: 'none', staging: 'missing', journal: 'none', evidence: 'none', activeRuns: 0, recovery: true },
+    { row: 'fuse', run: 'failed', staging: 'missing', journal: 'none', evidence: 'none', activeRuns: 0, recovery: true },
+    { row: 'fuse', run: 'orphan', staging: 'missing', journal: 'none', evidence: 'none', activeRuns: 0, recovery: true },
+    { row: 'fuse', run: 'running', staging: 'missing', journal: 'none', evidence: 'none', activeRuns: 1, recovery: true },
+    { row: 'fuse', run: 'running', staging: 'kept', journal: 'committing', evidence: 'none', activeRuns: 1 },
+    { row: 'skipped', run: 'none', staging: 'none', journal: 'none', evidence: 'none', activeRuns: 0 },
+    { row: 'merged', run: 'succeeded', staging: 'cleaned', journal: 'committed', evidence: 'receipt', activeRuns: 0 },
+    { row: 'merged', run: 'succeeded', staging: 'kept', journal: 'committed', evidence: 'receipt', activeRuns: 0 },
+];
+function same(a, b) {
+    return a.row === b.row && a.run === b.run && a.staging === b.staging && a.journal === b.journal
+        && a.evidence === b.evidence && a.activeRuns === b.activeRuns
+        && (b.recovery ?? false) === (a.recovery ?? false);
+}
+export function validateArtifacts(state) {
+    if (state.activeRuns > 1)
+        return { ok: false, reason: 'multiple-active-runs' };
+    if (state.activeRuns > 0 && state.hasOwner === false)
+        return { ok: false, reason: 'active-run-no-owner' };
+    if (ALLOWED.some(item => same(state, item)))
+        return { ok: true };
+    if (state.row === 'pending' && state.staging !== 'none')
+        return { ok: false, reason: 'pending-staging' };
+    if (state.row === 'skipped' && state.run === 'running')
+        return { ok: false, reason: 'skipped-running' };
+    if (state.row === 'fuse' && state.staging === 'missing' && state.recovery !== true)
+        return { ok: false, reason: 'fuse-lost-staging' };
+    if (state.journal === 'committed' && state.evidence !== 'receipt')
+        return { ok: false, reason: 'committed-no-evidence' };
+    if (state.row === 'merged' && state.journal === 'rolled-back')
+        return { ok: false, reason: 'committed-rollback' };
+    return { ok: false, reason: 'not-allowed' };
+}
+//# sourceMappingURL=consistency.js.map

package/lib/types/domain/ledger.js

@@ -1,5 +1,7 @@
 /** Pure v2 ledger normalization/projection. No IO. */
 import { migrateV1Row } from "./migrate-v1.js";
+import { isV3Row } from "./row-v3.js";
+import { v3ToLegacy } from "./row-v3-bridge.js";
 import { queueOf } from "./state.js";
 function isRow(value) {
     const row = value;
@@ -17,11 +19,18 @@ export function parseLedger(raw) {
         return { ok: false, ledger: { schemaVersion: 2, rows: [] }, note: 'invalid json' };
     }
     const body = parsed;
-    if (typeof body.schemaVersion === 'number' && body.schemaVersion > 2) {
+    if (typeof body.schemaVersion === 'number' && body.schemaVersion > 3) {
         return { ok: false, ledger: { schemaVersion: 2, rows: [] }, note: 'merge-state-forward-only' };
     }
     if (!Array.isArray(body.rows))
         return { ok: false, ledger: { schemaVersion: 2, rows: [] }, note: 'rows missing' };
+    if (body.schemaVersion === 3) {
+        if (!body.rows.every(isV3Row)) {
+            const v3Like = body.rows.some(row => row !== null && typeof row === 'object' && 'pairKey' in row && 'version' in row);
+            return { ok: false, ledger: { schemaVersion: 2, rows: [] }, note: v3Like ? 'merge-state-needs-repair' : 'merge-state-forward-only' };
+        }
+        return { ok: true, ledger: { schemaVersion: 2, rows: body.rows.map(v3ToLegacy) } };
+    }
     const rows = [];
     let skipped = 0;
     for (const value of body.rows) {

package/lib/types/domain/migrate-v3.d.ts

@@ -0,0 +1,20 @@
+import type { V3Row } from './row-v3.ts';
+export interface V3State {
+    readonly schemaVersion: 3;
+    readonly rows: readonly V3Row[];
+}
+export interface QuarantinedRow {
+    readonly reason: string;
+    readonly raw: unknown;
+}
+export type V3Migration = {
+    readonly ok: true;
+    readonly state: V3State;
+    readonly quarantine: readonly QuarantinedRow[];
+} | {
+    readonly ok: false;
+    readonly code: 'state-migration-blocked';
+    readonly message: string;
+};
+export declare function migrateV2ToV3(raw: unknown): V3Migration;
+//# sourceMappingURL=migrate-v3.d.ts.map