@lmzhen/dsh-evolution-merge 0.30.18 → 0.30.19

package/lib/types/state.d.ts

@@ -1,7 +1,7 @@
 import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 import { type MergePairState, type MergeQueue, type MergeRow, type MergeState } from './contracts.ts';
-import { type RowWriteResult } from './domain/row-tx.ts';
-import { type SkippedRowV3, type V3Event, type V3Row, type VerifyRowV3 } from './domain/row-v3.ts';
+import type { RowWriteResult } from './domain/row-tx.ts';
+import type { SkippedRowV3, V3Event, V3Row, VerifyRowV3 } from './domain/row-v3.ts';
 export declare function mergeStatePath(home: string): string;
 export interface LoadMergeStateResult {
     readonly ok: boolean;
@@ -19,9 +19,9 @@ export interface RowTx {
     transition(id: string, event: V3Event, expectedVersion: number): RowWriteResult;
 }
 /** G3-5 runtime write API: only createVerify/createSkipped/transition. v2 writes are rejected. */
-export declare function transactRows<T>(io: EvolutionIoLike, home: string, fn: (tx: RowTx) => T): Promise<T>;
+export declare function transactRows<T>(_io: EvolutionIoLike, _home: string, _fn: (tx: RowTx) => T): Promise<T>;
 /** The ONE write point. The callback returns the whole row set, not a delta. */
-export declare function mutateMergeState<T>(io: EvolutionIoLike, home: string, now: () => number, fn: (rows: readonly MergeRow[]) => {
+export declare function mutateMergeState<T>(_io: EvolutionIoLike, _home: string, _now: () => number, _fn: (rows: readonly MergeRow[]) => {
     rows: readonly MergeRow[];
     result: T;
 }): Promise<T>;
@@ -44,7 +44,7 @@ export type UpsertResult = {
 export declare function upsertRow(io: EvolutionIoLike, home: string, now: () => number, row: MergeRow, expect?: UpsertExpect, cas?: string | null): Promise<UpsertResult>;
 export declare function moveRow(io: EvolutionIoLike, home: string, now: () => number, id: string, patch: MoveRowPatch): Promise<MergeRow | undefined>;
 /** G3-5 v3-aware drop: only terminal events. */
-export declare function dropRowV3(io: EvolutionIoLike, home: string, id: string, event: 'committed' | 'superseded' | 'restored', unitId?: string): Promise<boolean>;
+export declare function dropRowV3(_io: EvolutionIoLike, _home: string, _id: string, _event: 'committed' | 'superseded' | 'restored', _unitId?: string): Promise<boolean>;
 export declare function dropRow(io: EvolutionIoLike, home: string, now: () => number, id: string): Promise<boolean>;
 export declare function rowsOf(io: EvolutionIoLike, home: string, queue?: MergeQueue): Promise<readonly MergeRow[]>;
 //# sourceMappingURL=state.d.ts.map

package/lib/types/state.js

@@ -7,13 +7,10 @@
  * mismatch is repaired by the next write, never by a GET.
  */
 import { join } from 'node:path';
-import { transactIo } from '@lmzhen/dsh-evolution-core';
 import { MERGE_STATE_VERSION, queueOf, } from "./contracts.js";
 import { parseLedger } from "./domain/ledger.js";
-import { legacyToV3 } from "./domain/row-v3-bridge.js";
-import { applyRowWrite } from "./domain/row-tx.js";
-import { isV3Row } from "./domain/row-v3.js";
-import { deleteStagingIndex } from "./domain/staging-index.js";
+import { parseV4State } from "./domain/schema4.js";
+import { v4ToLegacy } from "./domain/row-v4.js";
 export function mergeStatePath(home) {
     return join(home, 'merge', 'merge-state.json');
 }
@@ -36,6 +33,20 @@ export async function loadMergeState(io, home) {
     catch {
         return { ok: false, state: { schemaVersion: MERGE_STATE_VERSION, rows: [] } };
     }
+    if (raw !== null) {
+        try {
+            const header = JSON.parse(raw);
+            if (header.schemaVersion === 4) {
+                const v4 = parseV4State(raw);
+                if (v4 === null)
+                    return { ok: false, state: { schemaVersion: MERGE_STATE_VERSION, rows: [] }, note: 'merge-state-needs-repair' };
+                return { ok: true, state: { schemaVersion: MERGE_STATE_VERSION, rows: v4.rows.map(v4ToLegacy) } };
+            }
+            if (typeof header.schemaVersion === 'number' && header.schemaVersion > 4)
+                return { ok: false, state: { schemaVersion: MERGE_STATE_VERSION, rows: [] }, note: 'merge-state-forward-only' };
+        }
+        catch { /* parseState below reports the detailed note */ }
+    }
     const parsed = parseState(raw);
     return {
         ok: parsed.ok,
@@ -57,61 +68,12 @@ export async function loadStateSchema(io, home) {
     }
 }
 /** G3-5 runtime write API: only createVerify/createSkipped/transition. v2 writes are rejected. */
-export async function transactRows(io, home, fn) {
-    let result;
-    await transactIo(io, mergeStatePath(home), (current) => {
-        let rows = [];
-        if (current !== null) {
-            let parsed;
-            try {
-                parsed = JSON.parse(current);
-            }
-            catch {
-                throw new Error('merge-state-needs-repair');
-            }
-            const body = parsed;
-            if (body.schemaVersion !== 3 || !Array.isArray(body.rows) || !body.rows.every(isV3Row)) {
-                throw new Error(body.schemaVersion === 2 ? 'merge-state-migration-required' : 'merge-state-needs-repair');
-            }
-            rows = body.rows;
-        }
-        const apply = (write) => {
-            const next = applyRowWrite(rows, write, new Date().toISOString());
-            if (next.ok)
-                rows = next.rows;
-            return next;
-        };
-        const tx = {
-            rows: () => rows,
-            createVerify: row => apply({ kind: 'createVerify', row }),
-            createSkipped: row => apply({ kind: 'createSkipped', row }),
-            transition: (id, event, expectedVersion) => apply({ kind: 'transition', id, event, expectedVersion }),
-        };
-        result = fn(tx);
-        return JSON.stringify({ schemaVersion: 3, rows }, null, 2);
-    });
-    return result;
+export async function transactRows(_io, _home, _fn) {
+    throw new Error('legacy-writer-removed');
 }
 /** The ONE write point. The callback returns the whole row set, not a delta. */
-export async function mutateMergeState(io, home, now, fn) {
-    let result;
-    let ran = false;
-    await transactIo(io, mergeStatePath(home), (current) => {
-        ran = true;
-        const parsed = parseState(current);
-        if (!parsed.ok || parsed.note === 'merge-state-forward-only')
-            throw new Error(parsed.note ?? 'merge-state-invalid');
-        const out = fn(parsed.rows);
-        result = out.result;
-        const rows = out.rows.map(row => legacyToV3(row));
-        if (rows.some(row => row === null))
-            throw new Error('merge-state-v3-row-invalid');
-        return JSON.stringify({ schemaVersion: 3, rows }, null, 2);
-    });
-    // transactIo only returns after fn ran; a skipped write is not a state outcome.
-    void ran;
-    void now;
-    return result;
+export async function mutateMergeState(_io, _home, _now, _fn) {
+    throw new Error('legacy-writer-removed');
 }
 export async function upsertRow(io, home, now, row, expect = 'any', cas) {
     return await mutateMergeState(io, home, now, (rows) => {
@@ -159,17 +121,8 @@ export async function moveRow(io, home, now, id, patch) {
     });
 }
 /** G3-5 v3-aware drop: only terminal events. */
-export async function dropRowV3(io, home, id, event, unitId = 'unknown') {
-    const dropped = await transactRows(io, home, tx => {
-        const row = tx.rows().find(item => item.id === id);
-        if (row === undefined)
-            return false;
-        const moved = tx.transition(id, event === 'committed' ? { type: 'committed', unitId } : { type: event }, row.version);
-        return moved.ok;
-    });
-    if (dropped)
-        await deleteStagingIndex(io, home, id);
-    return dropped;
+export async function dropRowV3(_io, _home, _id, _event, _unitId = 'unknown') {
+    throw new Error('legacy-writer-removed');
 }
 export async function dropRow(io, home, now, id) {
     return await mutateMergeState(io, home, now, (rows) => {

package/lib/types/status.d.ts

@@ -3,7 +3,7 @@
  * writes, no report reads. The UI and command parser share this vocabulary.
  */
 import type { MergeQueue, MergeRow } from './contracts.ts';
-import type { Facts, RunsView } from './wire.ts';
+import type { Facts, RunDetail, RunsView } from './wire.ts';
 export interface MergeCounts {
     readonly verify: number;
     readonly pending: number;
@@ -14,5 +14,10 @@ export declare function countRows(rows: readonly MergeRow[]): MergeCounts;
 export declare function formatStatus(rows: readonly MergeRow[]): string;
 export declare function formatFacts(facts: Facts): string;
 export declare function formatRunsView(view: RunsView): string;
+/** CLI face of the RunDetail wire projection: one run, its current pair and every pair outcome. */
+export declare function formatRunDetail(detail: RunDetail): string;
 export declare function formatQueue(rows: readonly MergeRow[], queue: MergeQueue): string;
+/** Snapshot-compatible formatting, no legacy MergeRow. */
+export declare function formatSnapshotStatus(rows: readonly import('./wire.ts').RowFact[]): string;
+export declare function formatSnapshotQueue(rows: readonly import('./wire.ts').RowFact[], queue: import('./wire.ts').QueueId): string;
 //# sourceMappingURL=status.d.ts.map

package/lib/types/status.js

@@ -37,10 +37,57 @@ export function formatRunsView(view) {
         return 'merge runs: empty';
     return fitToolText(['merge runs: ' + String(view.runs.length)].concat(view.runs.map(run => '- ' + run.id + ' [' + run.state + ']' + (run.endedAt === undefined ? '' : ' ' + new Date(run.endedAt).toISOString()))).join('\n'));
 }
+/** CLI face of the RunDetail wire projection: one run, its current pair and every pair outcome. */
+export function formatRunDetail(detail) {
+    const lines = ['merge run ' + detail.id + ' [' + detail.state + '] command=' + detail.command
+            + (detail.stage === undefined ? '' : ' stage=' + detail.stage)
+            + (detail.progress === null || detail.progress === undefined ? '' : ' progress=' + String(detail.progress.done) + '/' + String(detail.progress.total))
+            + (detail.currentPairKey === undefined ? '' : ' currentPair=' + detail.currentPairKey.replace('\u0000', ' + '))];
+    lines.push('started=' + new Date(detail.startedAt).toISOString()
+        + (detail.endedAt === undefined ? '' : ' ended=' + new Date(detail.endedAt).toISOString())
+        + (detail.parentRunId === undefined ? '' : ' parent=' + detail.parentRunId)
+        + (detail.resultRef === undefined ? '' : ' resultRef=' + detail.resultRef)
+        + (detail.reportRef === undefined ? '' : ' report=' + detail.reportRef)
+        + (detail.meta?.phase === undefined ? '' : ' phase=' + detail.meta.phase)
+        + (detail.meta?.approval === undefined ? '' : ' approval=' + detail.meta.approval)
+        + (detail.stopReason === undefined ? '' : ' stopReason=' + detail.stopReason)
+        + (detail.failure === undefined ? '' : ' failure=' + detail.failure.code));
+    for (const pair of detail.pairs) {
+        lines.push('- ' + pair.a + ' + ' + pair.b + ': ' + pair.outcome
+            + (pair.stage === undefined ? '' : ' stage=' + pair.stage)
+            + (pair.code === undefined ? '' : ' code=' + pair.code)
+            + (pair.target === undefined ? '' : ' target=' + pair.target.requested));
+    }
+    if (detail.pairsTruncated)
+        lines.push('(pairs truncated)');
+    return fitToolText(lines.join('\n'));
+}
 export function formatQueue(rows, queue) {
     const selected = rows.filter(row => queueOf(row.state) === queue);
     if (selected.length === 0)
         return 'merge ' + queue + ': empty';
     return fitToolText(['merge ' + queue + ': ' + String(selected.length)].concat(selected.map(row => '- ' + describe(row))).join('\n'));
 }
+const REASON_TEXT = {
+    kept: '门禁判定保留，不合并。',
+    'gate-keep': '门禁判定保留，不合并。',
+    rejected: '人工拒绝合并。',
+    'merge-over-limit': '超出合并限制，未合并。',
+    'validation-failed': '合并校验未通过，未合并。',
+};
+function humanReason(reason) { return REASON_TEXT[reason] ?? reason; }
+/** Snapshot-compatible formatting, no legacy MergeRow. */
+export function formatSnapshotStatus(rows) {
+    const counts = { verify: 0, pending: 0, fuse: 0, skipped: 0 };
+    for (const row of rows)
+        counts[row.queue] += 1;
+    const lines = ['merge: verify ' + String(counts.verify) + ', pending ' + String(counts.pending) + ', fuse ' + String(counts.fuse) + ', skipped ' + String(counts.skipped)];
+    for (const row of rows)
+        lines.push('- ' + row.a + ' + ' + row.b + ' [' + row.state + ']' + (row.reason === undefined ? '' : ' — ' + humanReason(row.reason)));
+    return fitToolText(lines.join('\n'));
+}
+export function formatSnapshotQueue(rows, queue) {
+    const selected = rows.filter(row => row.queue === queue);
+    return selected.length === 0 ? 'merge ' + queue + ': empty' : fitToolText(['merge ' + queue + ': ' + String(selected.length)].concat(selected.map(row => '- ' + row.a + ' + ' + row.b + ' [' + row.state + ']' + (row.reason === undefined ? '' : ' — ' + humanReason(row.reason)))).join('\n'));
+}
 //# sourceMappingURL=status.js.map

package/lib/types/surface/body.d.ts

@@ -0,0 +1,4 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { BodyRef } from '../domain/merge-snapshot.ts';
+export declare function resolveBody(io: EvolutionIoLike, home: string, ref: BodyRef, rowBody: () => Promise<string | null>): Promise<string | null>;
+//# sourceMappingURL=body.d.ts.map

package/lib/types/surface/body.js

@@ -0,0 +1,16 @@
+import { readTextOrNull } from "../domain/read-probe.js";
+/** Body resolution over a snapshot ref: stage body wins; lost/expired stage returns null. */
+import { join } from 'node:path';
+import { readStageEntry } from "../domain/stage-aggregate.js";
+export async function resolveBody(io, home, ref, rowBody) {
+    const stage = await readStageEntry(io, home, ref.rowId).catch(() => null);
+    if (stage !== null && (stage.state === 'lost' || stage.state === 'expired'))
+        return null;
+    if (stage !== null && stage.state === 'present') {
+        const staged = await readTextOrNull(io, join(home, 'merge', 'runs', stage.ref, 'merged', ref.name));
+        if (staged !== null)
+            return staged;
+    }
+    return await rowBody();
+}
+//# sourceMappingURL=body.js.map

package/lib/types/surface/merge-view.d.ts

@@ -0,0 +1,14 @@
+/** Pure wireVersion=1 builders over one MergeSnapshot. No IO, no writes. */
+import type { MergeSnapshot, SnapshotRow, BodyRef } from '../domain/merge-snapshot.ts';
+import type { Facts, QueuePage, RowFact, BodyView, HistoryView, RunView, RunDetail, RunsView, DoctorView, QueueId } from '../wire.ts';
+export declare function toRowFact(row: SnapshotRow): RowFact;
+export declare function buildFacts(snapshot: MergeSnapshot): Facts;
+export declare function parseCursor(cursor: string, snapshot: MergeSnapshot): number;
+export declare function buildQueuePage(snapshot: MergeSnapshot, queue: QueueId, expiredOnly: boolean, cursor?: string, limit?: number): QueuePage;
+export declare function buildBodyView(snapshot: MergeSnapshot, ref: BodyRef, text: string): BodyView;
+export declare function buildHistoryView(snapshot: MergeSnapshot): HistoryView;
+export declare function buildRunView(snapshot: MergeSnapshot, runId: string): RunView | null;
+export declare function buildRunDetail(snapshot: MergeSnapshot, runId: string): RunDetail | null;
+export declare function buildRunsView(snapshot: MergeSnapshot): RunsView;
+export declare function buildDoctorView(snapshot: MergeSnapshot): DoctorView;
+//# sourceMappingURL=merge-view.d.ts.map

package/lib/types/surface/merge-view.js

@@ -0,0 +1,126 @@
+import { MERGE_COMMAND_SURFACE } from "../command-surface.js";
+const base = '/evolution merge ';
+function counts(rows) {
+    const active = { verify: 0, pending: 0, fuse: 0, skipped: 0 };
+    let expired = 0;
+    for (const item of rows) {
+        const skippedExpired = item.row.state === 'skipped' && item.row.expiredAt !== undefined;
+        if (item.expired || skippedExpired)
+            expired += 1;
+        else
+            active[item.queue] += 1;
+    }
+    return { active, expired };
+}
+const rowActionTemplates = new Map(MERGE_COMMAND_SURFACE.commands.flatMap(command => command.rowActions.map(action => [action.id, action])));
+function renderAction(id, context, enabled = true, confirmOverride, reason) {
+    const template = rowActionTemplates.get(id);
+    if (template === undefined)
+        throw new Error('missing CommandDef rowAction: ' + id);
+    const command = template.command.replaceAll('{id}', context.id).replaceAll('{a}', context.a).replaceAll('{b}', context.b).replaceAll('{runId}', context.runId ?? context.id);
+    return { id, command, confirm: confirmOverride ?? template.confirm === true, enabled, ...(enabled ? {} : { disabledReason: reason ?? 'invalid' }) };
+}
+function actions(row) {
+    const context = { id: row.row.id, a: row.row.a, b: row.row.b, ...(row.row.runId === undefined ? {} : { runId: row.row.runId }) };
+    if (row.row.state === 'pending' && row.row.expired !== undefined)
+        return [renderAction('discard', context, true, true), renderAction('pair', context, true, true)];
+    if (row.row.state === 'pending')
+        return [renderAction('approve', context), renderAction('reject', context, true, true), renderAction('discard', context, true, true)];
+    if (row.row.state === 'approved' || row.row.state === 'fuse')
+        return [renderAction('retry-resume', context, true, true), renderAction('discard', context, true, true), renderAction('status', context)];
+    if (row.row.state === 'skipped')
+        return [renderAction('restore', context, true, true)];
+    return [renderAction('pair', context)];
+}
+function verifyState(row) {
+    if (row.row.state !== 'verify')
+        return undefined;
+    if (row.row.failure?.code === 'cancelled')
+        return 'cancelled';
+    if (row.row.failure !== undefined)
+        return 'failed';
+    if (row.row.verifySubState === 'screened')
+        return 'running';
+    return 'queued';
+}
+export function toRowFact(row) {
+    const state = row.row;
+    const target = state.state === 'pending' || state.state === 'approved' || state.state === 'fuse' ? { requested: state.target, ...(state.state === 'approved' || state.state === 'fuse' ? { actual: state.target } : {}) } : undefined;
+    const summary = state.state === 'pending' ? { a: state.decision.aSummary ?? null, b: state.decision.bSummary ?? null, rationale: state.decision.rationale } : undefined;
+    const stage = row.stage;
+    const staging = stage === null ? undefined : stage.state === 'reserved' || stage.state === 'present' ? { state: 'kept', ...(stage.expiresAt === undefined ? {} : { expiresAt: stage.expiresAt }) } : undefined;
+    const stageField = stage === null ? undefined : stage.state === 'present' || stage.state === 'reserved' ? 'present' : stage.state === 'lost' ? 'lost' : 'expired';
+    const expiredKind = row.expiredKind ?? (state.state === 'pending' ? state.expired : undefined);
+    const expired = expiredKind !== undefined ? { kind: expiredKind, at: Date.parse(state.updatedAt) } : state.state === 'skipped' && state.expiredAt !== undefined ? { kind: 'skipped-ttl', at: state.expiredAt } : undefined;
+    return {
+        id: state.id, state: state.state, queue: row.queue,
+        ...(verifyState(row) === undefined ? {} : { verifySubState: verifyState(row) }),
+        ...(stageField === undefined ? {} : { stage: stageField }),
+        a: state.a, b: state.b,
+        ...(target === undefined ? {} : { target }),
+        ...(summary === undefined ? {} : { summary }),
+        ...(state.state === 'skipped' ? { reason: state.reason } : {}),
+        ...(state.origin === undefined ? {} : { origin: state.origin }),
+        ...(state.failure === undefined ? {} : { failure: { stage: state.failure.stage, code: state.failure.code, retryable: state.failure.retryable, retryFrom: state.failure.retryFrom, detail: state.failure.message } }),
+        ...(staging === undefined ? {} : { staging }),
+        ...(expired === undefined ? {} : { expired }),
+        ...(state.attempts === undefined ? {} : { attempts: state.attempts }),
+        ...(state.state === 'skipped' && state.expiredAt !== undefined ? { expiresAt: state.expiredAt } : {}),
+        bodies: row.bodies,
+        createdAt: Date.parse(state.createdAt),
+        updatedAt: Date.parse(state.updatedAt),
+        actions: actions(row),
+    };
+}
+function runView(run, readAt, includeResultRef = false) {
+    void includeResultRef;
+    const record = run.record;
+    const metaPhase = run.meta?.phase;
+    const state = metaPhase === 'undone' ? 'undone' : run.meta?.approval === 'pending' ? 'awaiting-approval' : record.state;
+    const stopReason = run.meta?.stopReason ?? (record.state === 'cancelled' ? 'cancelled' : record.state === 'failed' ? 'failed' : record.state === 'succeeded' ? 'completed' : undefined);
+    return { wireVersion: 1, readAt, id: record.id, state, command: record.command ?? 'scan', ...(record.stage === undefined ? {} : { stage: record.stage }), progress: record.progress === undefined ? null : { done: record.progress.done, total: record.progress.total }, startedAt: record.startedAt, ...(record.endedAt === undefined ? {} : { endedAt: record.endedAt }), ...(stopReason === undefined ? {} : { stopReason }), ...(record.failure === undefined ? {} : { failure: { stage: 'settle', code: 'run-failed', retryable: false, retryFrom: 'none', detail: record.failure } }), ...(record.parentRunId === undefined ? {} : { parentRunId: record.parentRunId }), ...(run.pairs[0]?.pairKey === undefined ? {} : { currentPairKey: run.pairs[0].pairKey }), ...(record.resultRef === undefined ? {} : { resultRef: record.resultRef }), actions: [{ id: 'status', command: base + 'status ' + record.id, confirm: false, enabled: true }, { id: 'report', command: base + 'report ' + record.id, confirm: false, enabled: record.resultRef !== undefined }, { id: 'cancel', command: base + 'cancel ' + record.id, confirm: false, enabled: record.state === 'running' }] };
+}
+export function buildFacts(snapshot) {
+    const ordered = [...snapshot.runs].sort((a, b) => b.record.startedAt - a.record.startedAt);
+    const active = ordered.find(run => run.record.state === 'running');
+    const last = ordered.find(run => run.record.state !== 'running');
+    return { wireVersion: 1, readAt: snapshot.readAt, approval: { mergeApproval: snapshot.approval.mergeApproval, ...(snapshot.approval.platformWrite === undefined ? {} : { platformWrite: snapshot.approval.platformWrite }) }, counts: counts(snapshot.rows), active: active === undefined ? null : runView(active, snapshot.readAt), last: last === undefined ? null : runView(last, snapshot.readAt), startCommands: { scan: base + 'scan', pair: base + 'pair <a> <b>' }, fallback: MERGE_COMMAND_SURFACE.fallback, notes: snapshot.notes, degraded: snapshot.degraded };
+}
+function encodeCursor(snapshot, offset) { return Buffer.from(JSON.stringify({ revision: snapshot.queueRevision, offset }), 'utf8').toString('base64url'); }
+export function parseCursor(cursor, snapshot) {
+    try {
+        const value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (value.revision !== snapshot.queueRevision || typeof value.offset !== 'number' || value.offset < 0)
+            throw new Error('stale');
+        return value.offset;
+    }
+    catch {
+        throw new Error('queue cursor is stale; reload');
+    }
+}
+export function buildQueuePage(snapshot, queue, expiredOnly, cursor, limit = 50) {
+    const selected = snapshot.rows.filter(row => row.queue === queue && (queue === 'skipped' ? true : expiredOnly ? row.expired : !row.expired));
+    const offset = cursor === undefined ? 0 : parseCursor(cursor, snapshot);
+    const page = selected.slice(offset, offset + Math.max(0, Math.min(200, limit)));
+    const next = offset + page.length < selected.length ? encodeCursor(snapshot, offset + page.length) : undefined;
+    return { wireVersion: 1, readAt: snapshot.readAt, queue, expiredOnly, counts: counts(snapshot.rows), rows: page.map(toRowFact), ...(next === undefined ? {} : { nextCursor: next }), notes: snapshot.notes };
+}
+export function buildBodyView(snapshot, ref, text) {
+    const max = 64 * 1024;
+    const truncated = Buffer.byteLength(text, 'utf8') > max;
+    const body = truncated ? text.slice(0, max) : text;
+    return { wireVersion: 1, readAt: snapshot.readAt, name: ref.name, side: ref.side, text: body, markdown: true, truncated, totalBytes: Buffer.byteLength(text, 'utf8') };
+}
+export function buildHistoryView(snapshot) { return { wireVersion: 1, readAt: snapshot.readAt, items: snapshot.history }; }
+export function buildRunView(snapshot, runId) { const run = snapshot.runs.find(item => item.record.id === runId); return run === undefined ? null : runView(run, snapshot.readAt); }
+export function buildRunDetail(snapshot, runId) {
+    const run = snapshot.runs.find(item => item.record.id === runId);
+    if (run === undefined)
+        return null;
+    return { ...runView(run, snapshot.readAt, true), ...(run.meta === null ? {} : { meta: { phase: run.meta.phase, ...(run.meta.approval === undefined ? {} : { approval: run.meta.approval }) } }), ...(run.reportRef === null ? {} : { reportRef: run.reportRef }), pairs: run.pairs.map(pair => ({ pairKey: pair.pairKey, a: pair.pairKey.split('\u0000')[0] ?? '', b: pair.pairKey.split('\u0000')[1] ?? '', outcome: pair.result === 'kept' ? 'kept' : pair.result === 'failed' ? 'failed' : pair.result === 'cancelled' ? 'cancelled' : 'merged', ...(pair.target === undefined ? {} : { target: { requested: pair.target } }) })), pairsTruncated: false };
+}
+export function buildRunsView(snapshot) { return { wireVersion: 1, readAt: snapshot.readAt, runs: [...snapshot.runs].sort((a, b) => b.record.startedAt - a.record.startedAt).map(run => runView(run, snapshot.readAt, true)) }; }
+export function buildDoctorView(snapshot) {
+    return { wireVersion: 1, readAt: snapshot.readAt, counts: snapshot.doctor.counts, ...(snapshot.runs[0] === undefined ? {} : { latestRun: runView(snapshot.runs[0], snapshot.readAt) }), staging: snapshot.doctor.staging, approval: snapshot.approval, ...(snapshot.blocked === undefined ? {} : { blocked: { code: snapshot.blocked.code, message: snapshot.blocked.message } }), rows: snapshot.doctor.rows };
+}
+//# sourceMappingURL=merge-view.js.map

package/lib/types/undo-operation.d.ts

@@ -0,0 +1,24 @@
+/** Batch 2b undo operation: per-pair preflight, journal, restore, receipt and settlement. */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type MergeUndoPort } from './undo-merge.ts';
+export type UndoErrorCode = 'undo-unavailable-legacy-receipt' | 'undo-evidence-hash-mismatch' | 'undo-target-drift' | 'undo-source-drift' | 'undo-partial-state' | 'undo-unit-not-committed';
+export interface UndoResult {
+    readonly ok: boolean;
+    readonly code?: UndoErrorCode;
+    readonly message: string;
+    readonly undone: readonly string[];
+}
+export declare function runUndoOperation(options: {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly runId: string;
+    readonly port: MergeUndoPort;
+    readonly now: () => number;
+    readonly pairKey?: string;
+    readonly finalizeUnit?: (unitId: string) => Promise<{
+        readonly ok: boolean;
+        readonly message?: string;
+    }>;
+    readonly onPhase?: (phase: string, pairKey: string) => void | Promise<void>;
+}): Promise<UndoResult>;
+//# sourceMappingURL=undo-operation.d.ts.map

package/lib/types/undo-operation.js

@@ -0,0 +1,135 @@
+import { contentHash } from '@lmzhen/dsh-evolution-core';
+import { readCommitReceipts } from "./commit-receipt.js";
+import { undoMergeReceipt } from "./undo-merge.js";
+import { writeUndoJournal } from "./domain/undo-journal.js";
+import { readUndoReceipt, writeUndoReceipt } from "./domain/undo-receipt.js";
+import { recordPair } from "./domain/pair-index-store.js";
+import { readRunMeta, writeRunMeta } from "./domain/run-coordinator.js";
+import { readUnitEvidence } from '@lmzhen/dsh-evolution-core';
+import { evidenceSha256 as unitEvidenceDigest } from "./domain/evidence-hash.js";
+function digest(value) { return value === null ? null : contentHash(value); }
+function sortReceipts(receipts) {
+    const remaining = [...receipts];
+    const out = [];
+    while (remaining.length > 0) {
+        const last = [...remaining].sort((a, b) => {
+            if (b.at !== a.at)
+                return b.at - a.at;
+            if (b.sources.includes(a.target))
+                return 1;
+            if (a.sources.includes(b.target))
+                return -1;
+            return b.sources.length - a.sources.length;
+        })[0];
+        out.push(last);
+        remaining.splice(remaining.indexOf(last), 1);
+    }
+    return out;
+}
+async function preflight(io, home, port, receipt) {
+    const evidence = await readUnitEvidence(io, home, receipt.unitId);
+    if (evidence === null)
+        return { ok: false, code: 'undo-unavailable-legacy-receipt', message: 'commit evidence is missing; undo unavailable for legacy receipt', undone: [] };
+    const expectedSha = receipt.evidenceSha256 ?? unitEvidenceDigest(evidence);
+    if (unitEvidenceDigest(evidence) !== expectedSha)
+        return { ok: false, code: 'undo-evidence-hash-mismatch', message: 'commit receipt evidence hash does not match evidence', undone: [] };
+    const targetNow = await port.readSkill(receipt.target);
+    const targetAfter = evidence.target.after;
+    const targetBefore = evidence.target.before;
+    const targetAllowed = targetNow === targetAfter || (receipt.create ? targetNow === null : targetNow === targetBefore);
+    if (!targetAllowed)
+        return { ok: false, code: 'undo-target-drift', message: 'target no longer matches the committed unit', undone: [] };
+    const sourcesNow = {};
+    for (const source of evidence.sources) {
+        const live = await port.readSkill(source.name);
+        sourcesNow[source.name] = live;
+        if (live !== null && live !== source.before)
+            return { ok: false, code: 'undo-source-drift', message: 'source no longer matches the archived unit: ' + source.name, undone: [] };
+    }
+    const targetDone = receipt.create ? targetNow === null : targetNow === targetBefore;
+    const sourcesDone = evidence.sources.every(source => sourcesNow[source.name] === source.before);
+    return { receipt, evidence, targetNow, sourcesNow, done: targetDone && sourcesDone, targetDone, sourcesDone };
+}
+async function settleRun(io, home, runId, pairKey, allPairs, at) {
+    const current = await readRunMeta(io, home, runId);
+    const previous = current?.undonePairs ?? [];
+    const undone = [...new Set([...previous, pairKey])];
+    const all = allPairs.length > 0 ? allPairs.every(key => undone.includes(key)) : true;
+    await writeRunMeta(io, home, {
+        version: 1, runId, phase: all ? 'undone' : 'settled',
+        ...(current?.parentRunId === undefined ? {} : { parentRunId: current.parentRunId }),
+        ...(current?.pairCount === undefined ? {} : { pairCount: current.pairCount }),
+        ...(current?.approval === undefined ? {} : { approval: current.approval }),
+        ...(current?.reportRef === undefined ? {} : { reportRef: current.reportRef }),
+        undonePairs: undone,
+        ...(all ? { undoneAt: new Date(at).toISOString() } : {}),
+        createdAt: current?.createdAt ?? new Date(at).toISOString(), updatedAt: new Date(at).toISOString(),
+    });
+}
+export async function runUndoOperation(options) {
+    const allReceipts = (await readCommitReceipts(options.io, options.home)).filter(receipt => (receipt.parentRunId ?? receipt.runId) === options.runId);
+    const allPairKeys = allReceipts.map(receipt => receipt.pairKey ?? receipt.unitId);
+    const receipts = options.pairKey === undefined ? allReceipts : allReceipts.filter(receipt => receipt.pairKey === options.pairKey);
+    if (receipts.length === 0)
+        return { ok: false, message: 'merge run has no commit receipt: ' + options.runId, undone: [] };
+    const pairs = receipts.map(receipt => ({ pairKey: receipt.pairKey ?? receipt.unitId, unitId: receipt.unitId, phase: 'pending' }));
+    await writeUndoJournal(options.io, options.home, { version: 1, runId: options.runId, phase: 'prepared', pairs, updatedAt: new Date(options.now()).toISOString() });
+    const undone = [];
+    for (const receipt of sortReceipts(receipts)) {
+        const pairKey = receipt.pairKey ?? receipt.unitId;
+        if (options.finalizeUnit !== undefined) {
+            const finalized = await options.finalizeUnit(receipt.unitId);
+            if (!finalized.ok)
+                return { ok: false, message: finalized.message ?? 'unit finalize failed', undone };
+        }
+        const existing = await readUndoReceipt(options.io, options.home, options.runId, pairKey);
+        if (existing !== null) {
+            await options.onPhase?.('pair-index', pairKey);
+            await recordPair(options.io, options.home, { pairKey, runId: options.runId, result: 'undone', target: receipt.target });
+            await options.onPhase?.('run-meta', pairKey);
+            await settleRun(options.io, options.home, options.runId, pairKey, allPairKeys, options.now());
+            undone.push(pairKey);
+            continue;
+        }
+        const checked = await preflight(options.io, options.home, options.port, receipt);
+        if ('ok' in checked)
+            return { ...checked, undone };
+        if (checked.done) {
+            await options.onPhase?.('receipt', pairKey);
+            await writeUndoReceipt(options.io, options.home, { version: 1, runId: options.runId, ...(receipt.parentRunId === undefined ? {} : { parentRunId: receipt.parentRunId }), pairKey, unitId: receipt.unitId, evidenceSha256: receipt.evidenceSha256 ?? unitEvidenceDigest(checked.evidence), target: receipt.target, sources: checked.evidence.sources.map(source => source.name), restoredTargetHash: receipt.create ? null : digest(checked.evidence.target.before), restoredSourceHashes: Object.fromEntries(checked.evidence.sources.map(source => [source.name, contentHash(source.before)])), at: options.now() });
+            await options.onPhase?.('pair-index', pairKey);
+            await recordPair(options.io, options.home, { pairKey, runId: options.runId, result: 'undone', target: receipt.target });
+            await options.onPhase?.('run-meta', pairKey);
+            await settleRun(options.io, options.home, options.runId, pairKey, allPairKeys, options.now());
+            undone.push(pairKey);
+            continue;
+        }
+        if (!checked.targetDone || !checked.sourcesDone) {
+            const targetStage = checked.targetDone ? 'skip' : 'restore';
+            const sourceStage = checked.sourcesDone ? 'skip' : 'restore';
+            if (targetStage === 'skip' && sourceStage === 'skip') { /* unreachable, done */ }
+        }
+        if (checked.targetDone !== checked.sourcesDone && (checked.targetDone || checked.sourcesDone)) {
+            return { ok: false, code: 'undo-partial-state', message: 'undo is partially applied; manual retry required', undone };
+        }
+        const phase = (next) => ({ pairKey, unitId: receipt.unitId, phase: next });
+        await writeUndoJournal(options.io, options.home, { version: 1, runId: options.runId, phase: 'running', pairs: pairs.map(pair => pair.pairKey === pairKey ? phase('restore-target') : pair), updatedAt: new Date(options.now()).toISOString() });
+        await options.onPhase?.('restore-target', pairKey);
+        const executed = await undoMergeReceipt(receipt, options.port);
+        if (!executed.ok)
+            return { ok: false, message: executed.message, undone };
+        await writeUndoJournal(options.io, options.home, { version: 1, runId: options.runId, phase: 'running', pairs: pairs.map(pair => pair.pairKey === pairKey ? phase('restore-source') : pair), updatedAt: new Date(options.now()).toISOString() });
+        await options.onPhase?.('restore-source', pairKey);
+        await writeUndoJournal(options.io, options.home, { version: 1, runId: options.runId, phase: 'running', pairs: pairs.map(pair => pair.pairKey === pairKey ? phase('receipt') : pair), updatedAt: new Date(options.now()).toISOString() });
+        await options.onPhase?.('receipt', pairKey);
+        await writeUndoReceipt(options.io, options.home, { version: 1, runId: options.runId, ...(receipt.parentRunId === undefined ? {} : { parentRunId: receipt.parentRunId }), pairKey, unitId: receipt.unitId, evidenceSha256: receipt.evidenceSha256 ?? unitEvidenceDigest(checked.evidence), target: receipt.target, sources: checked.evidence.sources.map(source => source.name), restoredTargetHash: receipt.create ? null : digest(checked.evidence.target.before), restoredSourceHashes: Object.fromEntries(checked.evidence.sources.map(source => [source.name, contentHash(source.before)])), at: options.now() });
+        await options.onPhase?.('pair-index', pairKey);
+        await recordPair(options.io, options.home, { pairKey, runId: options.runId, result: 'undone', target: receipt.target });
+        await options.onPhase?.('run-meta', pairKey);
+        await settleRun(options.io, options.home, options.runId, pairKey, allPairKeys, options.now());
+        undone.push(pairKey);
+    }
+    await writeUndoJournal(options.io, options.home, { version: 1, runId: options.runId, phase: 'settled', pairs: pairs.map(pair => ({ ...pair, phase: 'done' })), updatedAt: new Date(options.now()).toISOString() });
+    return { ok: true, message: 'undone ' + String(undone.length) + ' pair(s)', undone };
+}
+//# sourceMappingURL=undo-operation.js.map