@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.19

package/lib/types/stage-tool-registry.js

@@ -9,9 +9,20 @@ export class StageToolRegistry {
     clear() {
         this.bindings.clear();
     }
+    /** Diagnostic view for a refused tool call; names only, no content. */
+    snapshot(exec) {
+        const childId = childIdOf(exec);
+        return { ...(childId === undefined ? {} : { childId }), bound: this.bindings.size, authors: [...this.bindings.values()].filter(context => context.phase === 'author').length, keys: [...this.bindings.keys()] };
+    }
     resolve(exec) {
         const childId = childIdOf(exec);
-        return childId === undefined ? undefined : this.bindings.get(childId);
+        const direct = childId === undefined ? undefined : this.bindings.get(childId);
+        if (direct !== undefined)
+            return direct;
+        // New-child sessions may expose a session id that differs from the channel's childId.
+        // Only a single author-phase binding is unambiguous; never guess with concurrent bindings.
+        const authors = [...this.bindings.values()].filter(context => context.phase === 'author');
+        return authors.length === 1 ? authors[0] : undefined;
     }
 }
 function childIdOf(exec) {

package/lib/types/state.d.ts

@@ -1,5 +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, V3Event, V3Row, VerifyRowV3 } from './domain/row-v3.ts';
 export declare function mergeStatePath(home: string): string;
 export interface LoadMergeStateResult {
     readonly ok: boolean;
@@ -8,8 +10,18 @@ export interface LoadMergeStateResult {
 }
 /** Pure read: never writes, never deletes a row. */
 export declare function loadMergeState(io: EvolutionIoLike, home: string): Promise<LoadMergeStateResult>;
+/** Schema probe for doctor; the only other reader of mergeStatePath. */
+export declare function loadStateSchema(io: EvolutionIoLike, home: string): Promise<number | null>;
+export interface RowTx {
+    rows(): readonly V3Row[];
+    createVerify(row: VerifyRowV3): RowWriteResult;
+    createSkipped(row: SkippedRowV3): RowWriteResult;
+    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>;
 /** 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>;
@@ -31,6 +43,8 @@ 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 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,9 +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 { parseV4State } from "./domain/schema4.js";
+import { v4ToLegacy } from "./domain/row-v4.js";
 export function mergeStatePath(home) {
     return join(home, 'merge', 'merge-state.json');
 }
@@ -32,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,
@@ -39,23 +54,26 @@ export async function loadMergeState(io, home) {
         ...(parsed.note === undefined ? {} : { note: parsed.note }),
     };
 }
+/** Schema probe for doctor; the only other reader of mergeStatePath. */
+export async function loadStateSchema(io, home) {
+    try {
+        const raw = await io.readText(mergeStatePath(home));
+        if (raw === null)
+            return null;
+        const parsed = JSON.parse(raw);
+        return typeof parsed.schemaVersion === 'number' ? parsed.schemaVersion : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** G3-5 runtime write API: only createVerify/createSkipped/transition. v2 writes are rejected. */
+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;
-        return JSON.stringify({ schemaVersion: MERGE_STATE_VERSION, rows: out.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) => {
@@ -102,6 +120,10 @@ export async function moveRow(io, home, now, id, patch) {
         return { rows: copy, result: next };
     });
 }
+/** G3-5 v3-aware drop: only terminal events. */
+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) => {
         const next = rows.filter(item => item.id !== id);

package/lib/types/status.d.ts

@@ -3,6 +3,7 @@
  * writes, no report reads. The UI and command parser share this vocabulary.
  */
 import type { MergeQueue, MergeRow } from './contracts.ts';
+import type { Facts, RunDetail, RunsView } from './wire.ts';
 export interface MergeCounts {
     readonly verify: number;
     readonly pending: number;
@@ -11,5 +12,12 @@ export interface MergeCounts {
 }
 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

@@ -20,10 +20,74 @@ export function formatStatus(rows) {
         lines.push('- ' + describe(row));
     return fitToolText(lines.join('\n'));
 }
+export function formatFacts(facts) {
+    const lines = [
+        'merge: verify ' + String(facts.counts.active.verify) + ', pending ' + String(facts.counts.active.pending) + ', fuse ' + String(facts.counts.active.fuse) + ', skipped ' + String(facts.counts.active.skipped) + ', expired ' + String(facts.counts.expired),
+    ];
+    if (facts.active !== null)
+        lines.push('active: ' + facts.active.id + ' [' + facts.active.state + ']');
+    if (facts.last !== null)
+        lines.push('last: ' + facts.last.id + ' [' + facts.last.state + ']');
+    if (facts.degraded)
+        lines.push('degraded: ' + facts.notes.join(','));
+    return fitToolText(lines.join('\n'));
+}
+export function formatRunsView(view) {
+    if (view.runs.length === 0)
+        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/target-claim.d.ts

@@ -3,5 +3,6 @@ export interface TargetClaim {
     readonly token: string;
     release(): Promise<void>;
 }
+export declare function releaseTargetClaimQuietly(claim: TargetClaim | null | undefined): Promise<void>;
 export declare function acquireTargetClaim(io: EvolutionIoLike, home: string, target: string, now: number): Promise<TargetClaim | null>;
 //# sourceMappingURL=target-claim.d.ts.map

package/lib/types/target-claim.js

@@ -1,9 +1,10 @@
 /** Durable target claim: one approve writer per merge target at a time. */
 import { randomUUID } from 'node:crypto';
-import { join } from 'node:path';
-import { contentHash } from '@lmzhen/dsh-evolution-core';
+import { mkdir, open, readFile, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { contentHash, isProcessAlive } from '@lmzhen/dsh-evolution-core';
 import { acquireClaim, releaseClaim } from "./domain/claim.js";
-const LEASE_MS = 30 * 60_000;
+const PROCESS_STARTED_AT = Date.now() - process.uptime() * 1000;
 function claimPath(home, target) {
     return join(home, 'merge', 'claims', contentHash(target) + '.json');
 }
@@ -13,32 +14,76 @@ function parseClaim(raw) {
     const parsed = JSON.parse(raw);
     if (typeof parsed.token !== 'string' || typeof parsed.expiresAt !== 'number')
         throw new Error('corrupt target claim');
-    return { id: 'claim', token: parsed.token, expiresAt: parsed.expiresAt };
+    return {
+        id: 'claim', token: parsed.token, expiresAt: parsed.expiresAt,
+        ...(typeof parsed.pid === 'number' ? { pid: parsed.pid } : {}),
+        ...(typeof parsed.startedAt === 'number' ? { startedAt: parsed.startedAt } : {}),
+    };
 }
-async function compareAndSwap(io, path, task) {
-    if (io.transact !== undefined) {
-        await io.transact(path, current => task(current));
-        return;
-    }
-    const current = (await io.exists(path)) ? await io.readText(path) : null;
-    const next = task(current);
-    if (next === null) {
-        if (current !== null)
+async function withGuard(path, fn) {
+    const guard = path + '.guard';
+    await mkdir(dirname(path), { recursive: true });
+    for (let attempt = 0; attempt < 500; attempt += 1) {
+        try {
+            const handle = await open(guard, 'wx');
+            await handle.writeFile(String(process.pid));
+            await handle.close();
             try {
-                await io.remove(path);
+                return await fn();
+            }
+            finally {
+                await unlink(guard).catch(() => { });
             }
-            catch { /* already gone */ }
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const pid = Number(await readFile(guard, 'utf8').catch(() => ''));
+            if (Number.isFinite(pid) && pid > 0 && !isProcessAlive(pid))
+                await unlink(guard).catch(() => { });
+            await new Promise(resolve => setTimeout(resolve, 10));
+        }
     }
-    else if (next !== current) {
-        await io.writeText(path, next);
+    throw new Error('target-claim-guard-timeout');
+}
+async function compareAndSwap(io, path, task) {
+    await withGuard(path, async () => {
+        if (io.transact !== undefined) {
+            await io.transact(path, current => task(current));
+            return;
+        }
+        const current = (await io.exists(path)) ? await io.readText(path) : null;
+        const next = task(current);
+        if (next === null) {
+            if (current !== null)
+                try {
+                    await io.remove(path);
+                }
+                catch { /* already gone */ }
+        }
+        else if (next !== current) {
+            await io.writeText(path, next);
+        }
+    });
+}
+export async function releaseTargetClaimQuietly(claim) {
+    if (claim === null || claim === undefined)
+        return;
+    try {
+        await claim.release();
     }
+    catch { /* best effort; dead-holder reclaim or TTL handles it */ }
 }
 export async function acquireTargetClaim(io, home, target, now) {
     const path = claimPath(home, target);
     const token = randomUUID();
     let granted;
     await compareAndSwap(io, path, (raw) => {
-        const claim = acquireClaim(parseClaim(raw), now, LEASE_MS, token);
+        const current = parseClaim(raw);
+        const reused = current !== undefined && current.pid === process.pid && current.startedAt !== undefined && Math.abs(current.startedAt - PROCESS_STARTED_AT) > 1_000;
+        const abandoned = reused || (current !== undefined && current.expiresAt > now
+            && current.pid !== undefined && current.pid !== process.pid && !isProcessAlive(current.pid));
+        const claim = acquireClaim(abandoned ? undefined : current, now, Number.MAX_SAFE_INTEGER, token, process.pid, PROCESS_STARTED_AT);
         if (claim === undefined)
             return raw;
         granted = claim;

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