@lmzhen/dsh-evolution-merge 0.30.18 → 0.30.19

package/lib/types/domain/reconcile.js

@@ -0,0 +1,178 @@
+import { readTextOrNull } from "./read-probe.js";
+/**
+ * Explicit merge reconciliation: the ONE writer of row-state convergence.
+ *
+ * Reconcile owns the durable corrections that used to be scattered across startup
+ * (skipped TTL expiry, approved+reserved continuation) and reports them in
+ * `<home>/merge/reconcile.json`. Snapshots and all four GET routes stay read-only:
+ * they may DERIVE a fact (an expired stage, a source that disappeared) but never
+ * persist it; only this module and the command lifecycle write rows.
+ */
+import { join } from 'node:path';
+import { transactIo } from '@lmzhen/dsh-evolution-core';
+import { readV4Readiness } from "./schema4.js";
+import { pairLedger } from "./pair-ledger.js";
+import { planSkippedExpiry } from "./skipped-expiry.js";
+import { presentStage, readAllStages, readStageTree, writeStageIndex } from "./stage-aggregate.js";
+import { pendingExpiry } from "./live-facts.js";
+export const RECONCILE_REPORT_VERSION = 1;
+export function reconcileReportPath(home) {
+    return join(home, 'merge', 'reconcile.json');
+}
+/** Read the last reconcile report; a malformed report is absent, never a throw. */
+export async function readReconcileReport(io, home) {
+    const raw = await readTextOrNull(io, reconcileReportPath(home));
+    if (raw === null)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== RECONCILE_REPORT_VERSION || (parsed.state !== 'ok' && parsed.state !== 'blocked'))
+            return null;
+        if (typeof parsed.at !== 'number' || !Array.isArray(parsed.actions))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function blockedReport(now, code, message) {
+    return { version: RECONCILE_REPORT_VERSION, at: now, state: 'blocked', code, message, actions: [], notes: ['reconcile wrote nothing: the merge state is not readable'] };
+}
+/** One stage's tree can still serve the round-2 author. */
+async function stageUsable(io, home, entry, now) {
+    if (entry.state !== 'reserved' && entry.state !== 'present')
+        return false;
+    if (entry.expiresAt <= now)
+        return false;
+    return (await readStageTree(io, home, entry.ref).catch(() => ({ kind: 'absent' }))).kind === 'present';
+}
+/**
+ * Converge the row layer once, atomically, then persist the report.
+ * A blocked state writes no rows and no report; every other run is idempotent.
+ */
+export async function reconcileMergeState(options) {
+    const now = options.now();
+    const ttlDays = options.ttlDays ?? 0;
+    const ready = await readV4Readiness(options.io, options.home);
+    if (!ready.ok)
+        return blockedReport(now, ready.code, ready.message);
+    const stages = await readAllStages(options.io, options.home);
+    const byRow = new Map(stages.map(entry => [entry.rowId, entry]));
+    const usable = new Map();
+    const expiredStages = [];
+    for (const entry of stages) {
+        if (entry.state !== 'reserved' && entry.state !== 'present')
+            continue;
+        if (entry.expiresAt <= now) {
+            expiredStages.push(entry);
+            continue;
+        }
+        usable.set(entry.rowId, await stageUsable(options.io, options.home, entry, now));
+    }
+    const actions = [];
+    const promote = [];
+    await pairLedger(options.io, options.home).transact(tx => {
+        for (const row of [...tx.rows()]) {
+            if (row.state === 'skipped' && ttlDays > 0 && planSkippedExpiry([row], ttlDays, now).length === 1) {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current !== undefined && tx.transition(row.id, { type: 'mark-skipped-expired', at: now }, current.version).ok) {
+                    actions.push({ kind: 'skipped-expired', rowId: row.id, from: 'skipped', to: 'skipped', code: 'skipped-ttl' });
+                }
+                continue;
+            }
+            if (row.state === 'pending' && row.expired === undefined && options.live !== undefined) {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined || current.state !== 'pending' || current.expired !== undefined)
+                    continue;
+                const kind = pendingExpiry(current, options.live);
+                if (kind === null)
+                    continue;
+                if (kind === 'source-gone') {
+                    const removed = tx.remove(row.id, 'superseded', undefined, current.version);
+                    if (removed.ok)
+                        actions.push({ kind: 'source-gone', rowId: row.id, from: 'pending', to: 'removed', code: 'source-gone', detail: [row.a, row.b].filter(name => !options.live?.managed(name)).join(', ') });
+                    continue;
+                }
+                const moved = tx.transition(row.id, { type: 'expired', kind }, current.version);
+                if (moved.ok)
+                    actions.push({ kind: 'pending-expired', rowId: row.id, from: 'pending', to: 'pending', code: kind });
+                continue;
+            }
+            if (row.state !== 'approved')
+                continue;
+            const current = tx.rows().find(item => item.id === row.id);
+            if (current === undefined || current.state !== 'approved')
+                continue;
+            const entry = byRow.get(row.id);
+            if (usable.get(row.id) === true) {
+                const moved = tx.transition(row.id, { type: 'staged' }, current.version);
+                if (moved.ok) {
+                    actions.push({ kind: 'approved-fused', rowId: row.id, from: 'approved', to: 'fuse', code: 'stage-present' });
+                    if (entry !== undefined && entry.state === 'reserved')
+                        promote.push(entry);
+                }
+                continue;
+            }
+            const failure = { stage: 'author', code: 'stage-lost', message: 'stage tree is missing, expired, or lost before round2', retryable: true, retryFrom: 'agent2' };
+            const moved = tx.transition(row.id, { type: 'failed', failure }, current.version);
+            if (moved.ok)
+                actions.push({ kind: 'approved-fused', rowId: row.id, from: 'approved', to: 'fuse', code: 'stage-lost' });
+        }
+        if (options.managed !== undefined) {
+            for (const row of [...tx.rows()]) {
+                if (row.state === 'skipped')
+                    continue;
+                if (options.managed.has(row.a) && options.managed.has(row.b))
+                    continue;
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined)
+                    continue;
+                const removed = tx.remove(row.id, 'superseded', undefined, current.version);
+                if (removed.ok)
+                    actions.push({ kind: 'source-gone', rowId: row.id, from: current.state, to: 'removed', code: 'source-gone', detail: [row.a, row.b].filter(name => !options.managed?.has(name)).join(', ') });
+            }
+        }
+        return actions.length;
+    });
+    for (const entry of promote) {
+        try {
+            await presentStage(options.io, options.home, entry);
+        }
+        catch { /* the stage index stays reserved; the report still names the row */ }
+    }
+    // NFR-06: the index (the record the read face and the resume path consult) must agree
+    // with the read-side derivation that an expired stage is no longer present.
+    for (const entry of expiredStages) {
+        try {
+            await writeStageIndex(options.io, options.home, { ...entry, state: 'expired' });
+        }
+        catch { /* report keeps the read-side verdict */ }
+    }
+    const notes = [];
+    if (expiredStages.length > 0)
+        notes.push(String(expiredStages.length) + ' expired stage(s) marked in the index');
+    if (options.managed === undefined)
+        notes.push('source-gone convergence skipped: no live library was supplied');
+    if (ttlDays <= 0)
+        notes.push('skipped TTL disabled (mergeSkippedTtlDays=0)');
+    const report = { version: RECONCILE_REPORT_VERSION, at: now, state: 'ok', actions, notes };
+    await transactIo(options.io, reconcileReportPath(options.home), () => JSON.stringify(report, null, 2) + '\n');
+    return report;
+}
+/** One-line text face for the CLI/doctor consumers. */
+export function formatReconcileReport(report) {
+    if (report.state === 'blocked')
+        return 'merge reconcile: blocked ' + (report.code ?? 'merge-state-blocked') + ' — ' + (report.message ?? 'state is not readable');
+    const counts = new Map();
+    for (const action of report.actions)
+        counts.set(action.kind, (counts.get(action.kind) ?? 0) + 1);
+    const summary = counts.size === 0 ? 'no actions' : [...counts].map(([kind, count]) => kind + ' ' + String(count)).join(', ');
+    const lines = ['merge reconcile: ' + summary + ' (at ' + new Date(report.at).toISOString() + ')'];
+    for (const action of report.actions)
+        lines.push('- ' + action.rowId + ': ' + action.from + ' → ' + action.to + ' [' + action.code + ']' + (action.detail === undefined ? '' : ' ' + action.detail));
+    for (const note of report.notes)
+        lines.push('note: ' + note);
+    return lines.join('\n');
+}
+//# sourceMappingURL=reconcile.js.map

package/lib/types/domain/resolve-pair.d.ts

@@ -1,11 +1,4 @@
-/** Pure pairKey lookup over run records. No IO. */
+/** Pure pair-index lookup. No run-record merge fields. */
 import type { PairIndexEntryV2 } from './indexes.ts';
-import type { PairRecord } from './run-record.ts';
-export interface PairRunLike {
-    readonly id: string;
-    readonly pairKey?: string;
-    readonly pairs: readonly PairRecord[];
-    readonly resultRef?: string;
-}
-export declare function findPairRun(runs: readonly PairRunLike[], pairKey: string): PairIndexEntryV2 | undefined;
+export declare function findPairRun(pairs: readonly PairIndexEntryV2[], pairKey: string): PairIndexEntryV2 | undefined;
 //# sourceMappingURL=resolve-pair.d.ts.map

package/lib/types/domain/resolve-pair.js

@@ -1,17 +1,4 @@
-export function findPairRun(runs, pairKey) {
-    for (const run of runs) {
-        if (run.pairKey === pairKey) {
-            return { pairKey, runId: run.id, result: 'merged', ...(run.resultRef === undefined ? {} : { reportRef: run.resultRef }) };
-        }
-        const pair = run.pairs.find(item => item.pairKey === pairKey);
-        if (pair !== undefined) {
-            return {
-                pairKey, runId: run.id, result: pair.result === 'undone' ? 'undone' : pair.result === 'kept' ? 'kept' : pair.result === 'failed' ? 'failed' : pair.result === 'cancelled' ? 'cancelled' : 'merged',
-                ...(pair.target?.actual === undefined ? {} : { target: pair.target.actual }),
-                ...(run.resultRef === undefined ? {} : { reportRef: run.resultRef }),
-            };
-        }
-    }
-    return undefined;
+export function findPairRun(pairs, pairKey) {
+    return pairs.find(entry => entry.pairKey === pairKey);
 }
 //# sourceMappingURL=resolve-pair.js.map

package/lib/types/domain/row-v4.d.ts

@@ -0,0 +1,148 @@
+/** Batch 1b-2a additive schema4 row types and pure write helpers. */
+import type { MergeDecision, MergeFailure, MergeRow } from '../contracts.ts';
+import type { V3Row } from './row-v3.ts';
+export type RowOriginV4 = 'agent' | 'human' | 'system';
+export type VerifySubStateV4 = 'candidate' | 'screened' | 'unverified';
+export interface RowBaseV4 {
+    readonly id: string;
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly version: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly origin: RowOriginV4;
+    readonly failure?: MergeFailure;
+    readonly runId?: string;
+}
+export interface VerifyRowV4 extends RowBaseV4 {
+    readonly state: 'verify';
+    readonly verifySubState: VerifySubStateV4;
+    readonly sourceRevision?: string;
+    readonly attempts: number;
+}
+export interface PendingRowV4 extends RowBaseV4 {
+    readonly state: 'pending';
+    readonly target: string;
+    readonly decision: MergeDecision;
+    readonly targetRevision?: string;
+    readonly sourceRevision?: string;
+    readonly promptVersion?: string;
+    readonly promptHash?: string;
+    readonly expired?: 'target-taken' | 'source-changed';
+    readonly expiredAt?: number;
+    readonly attempts: number;
+}
+export interface ApprovedRowV4 extends RowBaseV4 {
+    readonly state: 'approved';
+    readonly target: string;
+    readonly decision: MergeDecision;
+    readonly sourceRevision?: string;
+    readonly targetRevision?: string;
+    readonly runId?: string;
+    readonly attempts: number;
+}
+export interface FuseRowV4 extends RowBaseV4 {
+    readonly state: 'fuse';
+    readonly target: string;
+    readonly decision: MergeDecision;
+    readonly sourceRevision?: string;
+    readonly targetRevision?: string;
+    readonly runId?: string;
+    readonly attempts: number;
+}
+export interface SkippedRowV4 extends RowBaseV4 {
+    readonly state: 'skipped';
+    readonly reason: string;
+    readonly skipSource?: string;
+    readonly expiredAt?: number;
+    readonly attempts: number;
+}
+export type V4Row = VerifyRowV4 | PendingRowV4 | ApprovedRowV4 | FuseRowV4 | SkippedRowV4;
+export type V4Event = {
+    readonly type: 'verify-passed';
+    readonly decision: MergeDecision;
+    readonly target: string;
+    readonly sourceRevision?: string;
+    readonly promptVersion?: string;
+    readonly promptHash?: string;
+} | {
+    readonly type: 'approved';
+    readonly runId: string;
+} | {
+    readonly type: 'auto-approved';
+    readonly decision: MergeDecision;
+    readonly target: string;
+    readonly runId?: string;
+} | {
+    readonly type: 'staged';
+} | {
+    readonly type: 'committed';
+    readonly unitId: CommitUnitRef;
+} | {
+    readonly type: 'skipped';
+    readonly reason: string;
+    readonly origin?: RowOriginV4;
+    readonly skipSource?: string;
+} | {
+    readonly type: 'mark-skipped-expired';
+    readonly at: number;
+} | {
+    readonly type: 'expired';
+    readonly kind: 'target-taken' | 'source-changed';
+} | {
+    readonly type: 'failed';
+    readonly failure: MergeFailure;
+} | {
+    readonly type: 'restored';
+} | {
+    readonly type: 'superseded';
+};
+export interface CommitUnitRef {
+    readonly unitId: string;
+    readonly evidenceSha256: string;
+}
+export type V4Transition = {
+    readonly ok: true;
+    readonly row: V4Row | null;
+    readonly version: number;
+} | {
+    readonly ok: false;
+    readonly code: 'version-conflict' | 'illegal-transition';
+    readonly message: string;
+};
+export type V4Terminal = 'committed' | 'superseded' | 'restored';
+export type V4Write = {
+    readonly kind: 'createVerify';
+    readonly row: VerifyRowV4;
+} | {
+    readonly kind: 'createSkipped';
+    readonly row: SkippedRowV4;
+} | {
+    readonly kind: 'transition';
+    readonly id: string;
+    readonly event: V4Event;
+    readonly expectedVersion: number;
+} | {
+    readonly kind: 'remove';
+    readonly id: string;
+    readonly terminal: V4Terminal;
+    readonly unit?: CommitUnitRef;
+    readonly expectedVersion: number;
+};
+export type V4WriteError = 'row-invalid' | 'row-duplicate' | 'row-not-found' | 'version-conflict' | 'illegal-transition';
+export type V4WriteResult = {
+    readonly ok: true;
+    readonly rows: readonly V4Row[];
+    readonly row: V4Row | null;
+} | {
+    readonly ok: false;
+    readonly code: V4WriteError;
+    readonly message: string;
+};
+export declare function transitionV4(row: V4Row, event: V4Event, expectedVersion: number, at?: string): V4Transition;
+export declare function isV4Row(value: unknown): value is V4Row;
+export declare function v3ToV4(row: V3Row): V4Row;
+export declare function applyV4Write(rows: readonly V4Row[], write: V4Write, at: string): V4WriteResult;
+export declare function v4ToLegacy(row: V4Row): MergeRow;
+//# sourceMappingURL=row-v4.d.ts.map

package/lib/types/domain/row-v4.js

@@ -0,0 +1,159 @@
+function bad(code, message) { return { ok: false, code, message }; }
+function conflict(message) { return { ok: false, code: 'version-conflict', message }; }
+function illegal(message) { return { ok: false, code: 'illegal-transition', message }; }
+function advance(row, at, patch) { return { ...row, ...patch, version: row.version + 1, updatedAt: at }; }
+export function transitionV4(row, event, expectedVersion, at = new Date().toISOString()) {
+    if (row.version !== expectedVersion)
+        return conflict('expected ' + String(expectedVersion) + ', got ' + String(row.version));
+    switch (row.state) {
+        case 'verify':
+            if (event.type === 'verify-passed')
+                return { ok: true, row: advance(row, at, { state: 'pending', target: event.target, decision: event.decision, ...(event.sourceRevision === undefined ? {} : { sourceRevision: event.sourceRevision }), ...(event.promptVersion === undefined ? {} : { promptVersion: event.promptVersion }), ...(event.promptHash === undefined ? {} : { promptHash: event.promptHash }), attempts: 0 }), version: expectedVersion + 1 };
+            if (event.type === 'auto-approved')
+                return { ok: true, row: advance(row, at, { state: 'approved', target: event.target, decision: event.decision, attempts: 0, ...(event.runId === undefined ? {} : { runId: event.runId }) }), version: expectedVersion + 1 };
+            if (event.type === 'failed')
+                return { ok: true, row: advance(row, at, { failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 };
+            if (event.type === 'skipped')
+                return { ok: true, row: advance(row, at, { state: 'skipped', reason: event.reason, attempts: row.attempts, ...(event.skipSource === undefined ? {} : { skipSource: event.skipSource }) }), version: expectedVersion + 1 };
+            if (event.type === 'superseded')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            return illegal('verify/' + event.type);
+        case 'pending':
+            if (event.type === 'approved')
+                return { ok: true, row: advance(row, at, { state: 'approved', runId: event.runId }), version: expectedVersion + 1 };
+            if (event.type === 'auto-approved')
+                return { ok: true, row: advance(row, at, { state: 'approved', ...(event.runId === undefined ? {} : { runId: event.runId }) }), version: expectedVersion + 1 };
+            if (event.type === 'staged')
+                return { ok: true, row: advance(row, at, { state: 'fuse' }), version: expectedVersion + 1 };
+            if (event.type === 'skipped')
+                return { ok: true, row: advance(row, at, { state: 'skipped', reason: event.reason, ...(event.origin === undefined ? {} : { origin: event.origin }), ...(event.skipSource === undefined ? {} : { skipSource: event.skipSource }) }), version: expectedVersion + 1 };
+            if (event.type === 'expired')
+                return { ok: true, row: advance(row, at, { expired: event.kind }), version: expectedVersion + 1 };
+            if (event.type === 'failed')
+                return { ok: true, row: advance(row, at, { failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 };
+            if (event.type === 'superseded')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            return illegal('pending/' + event.type);
+        case 'approved':
+            if (event.type === 'staged')
+                return { ok: true, row: advance(row, at, { state: 'fuse' }), version: expectedVersion + 1 };
+            if (event.type === 'committed')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            if (event.type === 'skipped')
+                return { ok: true, row: advance(row, at, { state: 'skipped', reason: event.reason, ...(event.skipSource === undefined ? {} : { skipSource: event.skipSource }) }), version: expectedVersion + 1 };
+            if (event.type === 'failed')
+                return event.failure.retryable
+                    ? { ok: true, row: advance(row, at, { state: 'fuse', failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 }
+                    : { ok: true, row: advance(row, at, { state: 'skipped', reason: event.failure.code, failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 };
+            if (event.type === 'superseded')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            return illegal('approved/' + event.type);
+        case 'fuse':
+            if (event.type === 'committed')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            if (event.type === 'skipped')
+                return { ok: true, row: advance(row, at, { state: 'skipped', reason: event.reason, ...(event.skipSource === undefined ? {} : { skipSource: event.skipSource }) }), version: expectedVersion + 1 };
+            if (event.type === 'failed')
+                return event.failure.retryable
+                    ? { ok: true, row: advance(row, at, { state: 'fuse', failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 }
+                    : { ok: true, row: advance(row, at, { state: 'skipped', reason: event.failure.code, failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 };
+            if (event.type === 'superseded')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            return illegal('fuse/' + event.type);
+        case 'skipped':
+            if (event.type === 'restored' || event.type === 'superseded')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            if (event.type === 'mark-skipped-expired')
+                return row.expiredAt !== undefined ? { ok: true, row, version: expectedVersion } : { ok: true, row: { ...row, expiredAt: event.at }, version: expectedVersion + 1 };
+            return illegal('skipped is terminal');
+    }
+}
+function object(value) { return value !== null && typeof value === 'object'; }
+function string(value) { return typeof value === 'string' && value.length > 0; }
+function number(value) { return typeof value === 'number' && Number.isFinite(value); }
+export function isV4Row(value) {
+    if (!object(value))
+        return false;
+    if (!string(value.id) || !string(value.pairKey) || !string(value.a) || !string(value.b) || !number(value.version))
+        return false;
+    if (!string(value.createdAt) || !string(value.updatedAt) || (value.origin !== 'agent' && value.origin !== 'human' && value.origin !== 'system'))
+        return false;
+    if (typeof value.attempts !== 'number')
+        return false;
+    if (value.state === 'verify')
+        return value.verifySubState === 'candidate' || value.verifySubState === 'screened' || value.verifySubState === 'unverified';
+    if (value.state === 'pending' || value.state === 'approved' || value.state === 'fuse')
+        return string(value.target) && object(value.decision);
+    if (value.state === 'skipped')
+        return string(value.reason);
+    return false;
+}
+export function v3ToV4(row) {
+    const base = { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, version: row.version, createdAt: row.createdAt, updatedAt: row.updatedAt, origin: row.origin, attempts: row.attempts, ...(row.failure === undefined ? {} : { failure: row.failure }), ...(row.runId === undefined ? {} : { runId: row.runId }) };
+    if (row.state === 'verify')
+        return { ...base, state: 'verify', verifySubState: row.verifySubState, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }) };
+    if (row.state === 'pending')
+        return { ...base, state: 'pending', target: row.target, decision: row.decision, ...(row.targetRevision === undefined ? {} : { targetRevision: row.targetRevision }), ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), ...(row.expired === undefined ? {} : { expired: row.expired }) };
+    if (row.state === 'approved')
+        return { ...base, state: 'approved', target: row.target, decision: row.decision, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), ...(row.runId === undefined ? {} : { runId: row.runId }) };
+    if (row.state === 'fuse')
+        return { ...base, state: 'fuse', target: row.target, decision: row.decision, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), ...(row.runId === undefined ? {} : { runId: row.runId }) };
+    return { ...base, state: 'skipped', reason: row.reason, ...(row.expiredAt === undefined ? {} : { expiredAt: row.expiredAt }) };
+}
+export function applyV4Write(rows, write, at) {
+    if (write.kind === 'transition') {
+        const index = rows.findIndex(row => row.id === write.id);
+        if (index < 0)
+            return bad('row-not-found', 'row not found: ' + write.id);
+        const moved = transitionV4(rows[index], write.event, write.expectedVersion, at);
+        if (!moved.ok)
+            return bad(moved.code, moved.message);
+        if (moved.row === null)
+            return { ok: true, rows: rows.filter((_, atIndex) => atIndex !== index), row: null };
+        const next = [...rows];
+        next[index] = moved.row;
+        return { ok: true, rows: next, row: moved.row };
+    }
+    if (write.kind === 'remove') {
+        const index = rows.findIndex(row => row.id === write.id);
+        if (index < 0)
+            return bad('row-not-found', 'row not found: ' + write.id);
+        const current = rows[index];
+        if (write.terminal === 'committed' && (write.unit === undefined || write.unit.unitId.length === 0 || write.unit.evidenceSha256.length === 0))
+            return bad('row-invalid', 'committed remove requires commit evidence');
+        const event = write.terminal === 'committed' ? { type: 'committed', unitId: write.unit } : { type: write.terminal };
+        const moved = transitionV4(current, event, write.expectedVersion, at);
+        if (!moved.ok)
+            return bad(moved.code, moved.message);
+        return moved.row === null ? { ok: true, rows: rows.filter((_, atIndex) => atIndex !== index), row: null } : { ok: true, rows: rows.map((row, atIndex) => atIndex === index ? moved.row : row), row: moved.row };
+    }
+    if (write.row.version !== 0)
+        return bad('row-invalid', 'create requires version 0');
+    if (write.kind === 'createVerify' && (write.row.state !== 'verify' || write.row.verifySubState !== 'unverified'))
+        return bad('row-invalid', 'createVerify requires verify/unverified');
+    if (write.kind === 'createSkipped' && write.row.state !== 'skipped')
+        return bad('row-invalid', 'createSkipped requires skipped');
+    if (!isV4Row(write.row))
+        return bad('row-invalid', 'created row is invalid');
+    if (rows.some(row => row.id === write.row.id))
+        return bad('row-duplicate', 'duplicate row id: ' + write.row.id);
+    return { ok: true, rows: [...rows, write.row], row: write.row };
+}
+export function v4ToLegacy(row) {
+    const queue = row.state === 'verify' ? 'verify' : row.state === 'pending' ? 'pending' : row.state === 'skipped' ? 'skipped' : 'fuse';
+    const target = row.state === 'pending' || row.state === 'approved' || row.state === 'fuse' ? { requested: row.target } : undefined;
+    return {
+        id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, state: row.state, queue,
+        ...(row.state === 'skipped' ? { reason: row.reason } : {}),
+        ...(target === undefined ? {} : { target }),
+        ...(row.failure === undefined ? {} : { failure: row.failure }),
+        ...(row.state === 'pending' || row.state === 'approved' || row.state === 'fuse' ? { decision: row.decision } : {}),
+        ...((row.state === 'pending' || row.state === 'approved' || row.state === 'fuse') && row.sourceRevision !== undefined ? { sourceRevision: row.sourceRevision } : {}),
+        ...((row.state === 'pending' || row.state === 'approved' || row.state === 'fuse') && row.targetRevision !== undefined ? { targetRevision: row.targetRevision } : {}),
+        ...(row.runId === undefined ? {} : { runId: row.runId }),
+        ...(row.origin === undefined ? {} : { origin: row.origin }),
+        ...(row.attempts === undefined ? {} : { attempts: row.attempts }),
+        createdAt: row.createdAt, updatedAt: row.updatedAt,
+    };
+}
+//# sourceMappingURL=row-v4.js.map

package/lib/types/domain/run-coordinator.d.ts

@@ -0,0 +1,51 @@
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+export type MergeRunPhase = 'begin' | 'running' | 'awaiting-approval' | 'settled' | 'cancelled' | 'undone';
+export interface MergeRunMeta {
+    readonly version: 1;
+    readonly runId: string;
+    readonly pairCount?: number;
+    /** The pair a single-pair command (pair/approve/resume) is working on; absent for scan. */
+    readonly pairKey?: string;
+    readonly parentRunId?: string;
+    readonly phase: MergeRunPhase;
+    readonly stopReason?: string;
+    readonly approval?: 'pending' | 'approved' | 'rejected';
+    readonly reportRef?: string;
+    readonly undonePairs?: readonly string[];
+    readonly undoneAt?: string;
+    readonly degraded?: boolean;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface PairIndexEntry {
+    readonly version: 1;
+    readonly runId: string;
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly target: string;
+    readonly targetRevision?: string;
+    readonly sourceRevisions?: Readonly<Record<string, string>>;
+    readonly state: 'pending' | 'approved' | 'fused' | 'skipped';
+    readonly updatedAt: string;
+}
+export interface RunCoordinatorRead {
+    readonly runId: string;
+    readonly meta: MergeRunMeta | null;
+    readonly pairs: readonly PairIndexEntry[];
+    readonly consistency: 'eventual';
+}
+export interface RunCoordinator {
+    begin(meta: MergeRunMeta): Promise<void>;
+    recordPair(entry: PairIndexEntry): Promise<void>;
+    read(runId: string): Promise<RunCoordinatorRead>;
+}
+export declare function runMetaPath(home: string, runId: string): string;
+export declare function writeRunMeta(io: EvolutionIoLike, home: string, meta: MergeRunMeta): Promise<void>;
+export declare function readRunMeta(io: EvolutionIoLike, home: string, runId: string): Promise<MergeRunMeta | null>;
+/** Every run-meta record on disk (the in-flight index for pair/target serialisation). */
+export declare function readRunMetas(io: EvolutionIoLike, home: string): Promise<readonly MergeRunMeta[]>;
+/** The run currently working on this pair, if any (pairKey is written at run begin). */
+export declare function inFlightPairRun(metas: readonly MergeRunMeta[], pairKeyValue: string): MergeRunMeta | undefined;
+export { recordPair } from './pair-index-store.ts';
+//# sourceMappingURL=run-coordinator.d.ts.map

package/lib/types/domain/run-coordinator.js

@@ -0,0 +1,45 @@
+import { readTextOrNull, listOrEmpty } from "./read-probe.js";
+/** 1b-1 additive types for the merge run lifecycle; no writer is active in this phase. */
+import { join } from 'node:path';
+import { transactIo } from '@lmzhen/dsh-evolution-core';
+export function runMetaPath(home, runId) { return join(home, 'merge', 'run-meta', encodeURIComponent(runId) + '.json'); }
+export async function writeRunMeta(io, home, meta) {
+    await transactIo(io, runMetaPath(home, meta.runId), () => JSON.stringify(meta, null, 2) + '\n');
+}
+export async function readRunMeta(io, home, runId) {
+    const raw = await readTextOrNull(io, runMetaPath(home, runId));
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Every run-meta record on disk (the in-flight index for pair/target serialisation). */
+export async function readRunMetas(io, home) {
+    const root = join(home, 'merge', 'run-meta');
+    const names = await io.exists(root) ? await listOrEmpty(io, root) : [];
+    const metas = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const raw = await readTextOrNull(io, join(root, name));
+        if (raw === null)
+            continue;
+        try {
+            const meta = JSON.parse(raw);
+            if (typeof meta.runId === 'string' && typeof meta.phase === 'string')
+                metas.push(meta);
+        }
+        catch { /* malformed meta is not an in-flight claim */ }
+    }
+    return metas;
+}
+/** The run currently working on this pair, if any (pairKey is written at run begin). */
+export function inFlightPairRun(metas, pairKeyValue) {
+    return metas.find(meta => meta.phase === 'running' && meta.pairKey === pairKeyValue);
+}
+export { recordPair } from "./pair-index-store.js";
+//# sourceMappingURL=run-coordinator.js.map