@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.19

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

package/lib/types/unit-claim.d.ts

@@ -0,0 +1,5 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { UnitClaimPort } from '@lmzhen/dsh-evolution-core';
+/** Commit-phase claim: 24h is only stale recovery; commit releases immediately, no approve TTL. */
+export declare function targetClaimUnitPort(io: EvolutionIoLike, home: string, now: () => number): UnitClaimPort;
+//# sourceMappingURL=unit-claim.d.ts.map

package/lib/types/unit-claim.js

@@ -0,0 +1,15 @@
+import { acquireTargetClaim, releaseTargetClaimQuietly } from "./target-claim.js";
+/** Commit-phase claim: 24h is only stale recovery; commit releases immediately, no approve TTL. */
+export function targetClaimUnitPort(io, home, now) {
+    return {
+        async acquire(target) {
+            const claim = await acquireTargetClaim(io, home, target, now());
+            if (claim === null)
+                throw new Error('target-claim-busy: ' + target);
+            return {
+                async release() { await releaseTargetClaimQuietly(claim); },
+            };
+        },
+    };
+}
+//# sourceMappingURL=unit-claim.js.map

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

@@ -0,0 +1,36 @@
+/** G5-4 wire projections from merge rows to the frozen envelopes. */
+import type { RunRecord } from '@lmzhen/dsh-evolution-core';
+import type { MergeRow } from './contracts.ts';
+import type { BodyView, DoctorView, HistoryView, MergeCounts, QueueId, QueuePage, RowFact, RunView, RunsView } from './wire.ts';
+/** Host-owned row actions; client only renders/copies them. */
+export declare function actionRefs(row: MergeRow): RowFact['actions'];
+export declare function toRowFact(row: MergeRow, actions?: RowFact['actions']): RowFact;
+export declare function toQueuePage(rows: readonly MergeRow[], queue: QueueId, expiredOnly: boolean, readAt: number, limit?: number): QueuePage;
+export declare function toRunsView(runs: readonly RunRecord[], readAt: number): RunsView;
+export interface DoctorSourceFact {
+    readonly key: string;
+    readonly status: 'ok' | 'warn' | 'fail' | 'unknown';
+    readonly count?: number;
+    readonly detail?: string;
+}
+export declare function toDoctorView(input: {
+    readonly readAt: number;
+    readonly counts: MergeCounts;
+    readonly latestRun?: RunView;
+    readonly approval: {
+        mergeApproval: boolean;
+        writeApproval?: boolean;
+    };
+    readonly staging: DoctorView['staging'];
+    readonly rows: readonly DoctorSourceFact[];
+}): DoctorView;
+export declare function toBodyView(name: string, side: 'live' | 'archive', text: string, readAt: number): BodyView;
+export declare function toHistoryView(items: readonly {
+    name: string;
+    kind: 'merged' | 'deleted' | 'split' | 'other';
+    reason: string;
+    lastVersion: number;
+    archivedAt: string;
+    sourceRunId?: string;
+}[], readAt: number): HistoryView;
+//# sourceMappingURL=wire-projection.d.ts.map

package/lib/types/wire-projection.js

@@ -0,0 +1,69 @@
+import { countsOf, toRunView } from "./facts.js";
+const queueOf = (row) => row.state === 'approved' ? 'fuse' : row.queue;
+const expiredOf = (row) => row.expired !== undefined;
+/** Host-owned row actions; client only renders/copies them. */
+export function actionRefs(row) {
+    const base = '/evolution merge ';
+    const disabled = row.expired === undefined ? undefined : 'expired';
+    const action = (id, confirm = false, enabled = true) => ({ id, command: base + id + ' ' + row.id, confirm, enabled, ...(enabled ? {} : { disabledReason: disabled ?? 'invalid' }) });
+    if (row.state === 'pending' && row.expired !== undefined)
+        return [{ id: 'discard', command: base + 'discard ' + row.id, confirm: true, enabled: true }, { id: 'pair', command: base + 'pair ' + row.a + ' ' + row.b, confirm: true, enabled: true }];
+    if (row.state === 'pending')
+        return [action('approve'), action('reject', true), action('discard', true)];
+    if (row.state === 'approved' || row.state === 'fuse')
+        return [action('discard', true), action('status')];
+    if (row.state === 'skipped')
+        return [action('restore', true)];
+    return [action('pair')];
+}
+export function toRowFact(row, actions = actionRefs(row)) {
+    return {
+        id: row.id,
+        state: row.state,
+        queue: queueOf(row),
+        ...(row.state === 'verify' ? { verifySubState: 'queued' } : {}),
+        a: row.a,
+        b: row.b,
+        ...(row.target === undefined ? {} : { target: { requested: row.target.requested, ...(row.target.actual === undefined ? {} : { actual: row.target.actual }), ...(row.target.created === undefined ? {} : { created: row.target.created }) } }),
+        ...(row.state === 'pending' ? { summary: { a: null, b: null, rationale: row.decision?.rationale ?? null } } : {}),
+        ...(row.reason === undefined ? {} : { reason: row.reason }),
+        ...(row.state === 'skipped' ? { origin: row.origin ?? 'system' } : {}),
+        ...(row.failure === undefined ? {} : { failure: { stage: row.failure.stage === 'screening' ? 'screening' : row.failure.stage === 'decide' ? 'decide' : row.failure.stage === 'author' ? 'author' : row.failure.stage === 'validate' ? 'validate' : 'commit', code: row.failure.code, retryable: row.failure.retryable, retryFrom: row.failure.retryFrom } }),
+        ...(row.stagingRef === undefined ? {} : { staging: { state: 'kept', ...(row.stagingExpiresAt === undefined ? {} : { expiresAt: row.stagingExpiresAt }) } }),
+        ...(row.expired === undefined ? {} : { expired: { kind: row.expired, at: Date.parse(row.updatedAt) } }),
+        ...(row.attempts === undefined ? {} : { attempts: row.attempts }),
+        ...(row.decision?.confidence === undefined ? {} : { confidence: row.decision.confidence }),
+        ...(row.state === 'skipped' && row.stagingExpiresAt !== undefined ? { expiresAt: row.stagingExpiresAt } : {}),
+        createdAt: Date.parse(row.createdAt),
+        updatedAt: Date.parse(row.updatedAt),
+        actions,
+    };
+}
+export function toQueuePage(rows, queue, expiredOnly, readAt, limit = 50) {
+    const filtered = rows.filter(row => queueOf(row) === queue && (expiredOnly ? expiredOf(row) : !expiredOf(row)));
+    const page = filtered.slice(0, Math.max(0, Math.min(200, limit)));
+    const counts = countsOf(rows);
+    return { wireVersion: 1, readAt, queue, expiredOnly, counts, rows: page.map(row => toRowFact(row)), ...(filtered.length > page.length ? { nextCursor: String(page.length) } : {}), notes: [] };
+}
+export function toRunsView(runs, readAt) {
+    const ordered = [...runs].sort((a, b) => b.startedAt - a.startedAt).slice(0, 50);
+    return { wireVersion: 1, readAt, runs: ordered.map(run => toRunView(run, readAt)) };
+}
+export function toDoctorView(input) {
+    return {
+        wireVersion: 1,
+        readAt: input.readAt,
+        counts: input.counts,
+        ...(input.latestRun === undefined ? {} : { latestRun: input.latestRun }),
+        staging: input.staging,
+        approval: input.approval,
+        rows: input.rows.map(row => ({ key: row.key, status: row.status, ...(row.count === undefined ? {} : { count: row.count }), ...(row.detail === undefined ? {} : { detail: row.detail }) })),
+    };
+}
+export function toBodyView(name, side, text, readAt) {
+    return { wireVersion: 1, readAt, name, side, text, markdown: true, truncated: false, totalBytes: Buffer.byteLength(text, 'utf8') };
+}
+export function toHistoryView(items, readAt) {
+    return { wireVersion: 1, readAt, items: items.map(item => ({ name: item.name, kind: item.kind, reason: item.reason, lastVersion: item.lastVersion, archivedAt: Date.parse(item.archivedAt), ...(item.sourceRunId === undefined ? {} : { sourceRunId: item.sourceRunId }) })) };
+}
+//# sourceMappingURL=wire-projection.js.map

package/lib/types/wire.d.ts

@@ -0,0 +1,273 @@
+/** Merge wire contract v1. Read-only envelopes shared with the client. */
+export declare const WIRE_VERSION: 1;
+export type QueueId = 'verify' | 'pending' | 'fuse' | 'skipped';
+export type WireRowState = 'verify' | 'pending' | 'approved' | 'fuse' | 'skipped';
+export type RowStage = 'screening' | 'decide' | 'author' | 'validate' | 'commit';
+export type RunStage = RowStage | 'settle';
+export type VerifySubState = 'queued' | 'running' | 'failed' | 'cancelled';
+export type StagingState = 'none' | 'kept' | 'cleared-source-ok' | 'cleared-source-gone';
+export type SkipOrigin = 'agent' | 'human' | 'system';
+export type SkipKind = 'agent-keep' | 'human-reject' | 'over-limit' | 'forced';
+export type ExpiredKind = 'target-taken' | 'source-changed' | 'source-gone' | 'skipped-ttl';
+export type WireRunState = 'running' | 'succeeded' | 'failed' | 'cancelled' | 'awaiting-approval' | 'undone' | 'superseded' | 'interrupted' | 'orphan';
+export type ActionId = 'approve' | 'reject' | 'retry-candidates' | 'retry-resume' | 'resume' | 'discard' | 'restore' | 'pair' | 'status' | 'report' | 'cancel';
+export interface MergeCounts {
+    readonly active: {
+        readonly verify: number;
+        readonly pending: number;
+        readonly fuse: number;
+        readonly skipped: number;
+    };
+    readonly expired: number;
+}
+export interface FailureFact {
+    readonly stage: RowStage | 'settle';
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly retryFrom: 'agent1' | 'agent2' | 'none';
+    readonly detail?: string;
+}
+export interface SummarySlots {
+    readonly a: string | null;
+    readonly b: string | null;
+    readonly rationale: string | null;
+}
+export interface CommandRef {
+    readonly id: string;
+    readonly command: string;
+}
+export interface ActionRef {
+    readonly id: ActionId;
+    readonly command: string;
+    readonly confirm: boolean;
+    readonly enabled: boolean;
+    readonly disabledReason?: string;
+}
+export interface RowFact {
+    readonly id: string;
+    readonly state: WireRowState;
+    readonly queue: QueueId;
+    readonly verifySubState?: VerifySubState;
+    /** Optional Batch4 projection; old staging remains compatibility. */
+    readonly stage?: 'present' | 'lost' | 'expired';
+    readonly a: string;
+    readonly b: string;
+    readonly target?: {
+        readonly requested: string;
+        readonly actual?: string;
+        readonly created?: boolean;
+    };
+    readonly summary?: SummarySlots;
+    readonly reason?: string;
+    readonly origin?: SkipOrigin;
+    readonly skipKind?: SkipKind;
+    readonly confidence?: number;
+    readonly failure?: FailureFact;
+    readonly staging?: {
+        readonly state: StagingState;
+        readonly expiresAt?: number;
+    };
+    readonly expired?: {
+        readonly kind: ExpiredKind;
+        readonly at: number;
+    };
+    readonly bodies?: readonly {
+        readonly name: string;
+        readonly side: 'live' | 'archive';
+    }[];
+    readonly attempts?: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly expiresAt?: number;
+    readonly actions: readonly ActionRef[];
+}
+export interface Facts {
+    readonly wireVersion: 1;
+    readonly readAt: number;
+    readonly approval: {
+        readonly mergeApproval: boolean;
+        readonly platformWrite?: boolean;
+    };
+    readonly counts: MergeCounts;
+    readonly active: RunView | null;
+    readonly last: RunView | null;
+    readonly startCommands: {
+        readonly scan: string;
+        readonly pair: string;
+    };
+    readonly fallback: readonly CommandRef[];
+    readonly notes: readonly string[];
+    readonly degraded: boolean;
+}
+export interface QueuePage {
+    readonly wireVersion: 1;
+    readonly readAt: number;
+    readonly queue: QueueId;
+    readonly expiredOnly: boolean;
+    readonly counts: MergeCounts;
+    readonly rows: readonly RowFact[];
+    readonly nextCursor?: string;
+    readonly notes: readonly string[];
+}
+export interface RunView {
+    readonly wireVersion: 1;
+    readonly readAt: number;
+    readonly id: string;
+    readonly state: WireRunState;
+    readonly command: 'scan' | 'pair' | 'approve' | 'resume';
+    readonly stage?: RunStage;
+    readonly progress?: {
+        readonly done: number;
+        readonly total: number;
+    } | null;
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly stopReason?: string;
+    readonly failure?: FailureFact;
+    readonly parentRunId?: string;
+    readonly currentPairKey?: string;
+    readonly resultRef?: string;
+    readonly summary?: {
+        readonly merged: number;
+        readonly kept: number;
+        readonly failed: number;
+        readonly pending: number;
+        readonly cancelled: number;
+    };
+    readonly actions: readonly ActionRef[];
+}
+export interface RunPair {
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly outcome: 'merged' | 'kept' | 'pending' | 'failed' | 'rejected' | 'cancelled' | 'undone';
+    readonly stage?: RowStage;
+    readonly code?: string;
+    readonly detail?: string;
+    readonly target?: {
+        readonly requested: string;
+        readonly actual?: string;
+        readonly created?: boolean;
+    };
+    readonly actions?: readonly ActionRef[];
+}
+export interface RunDetail extends RunView {
+    readonly pairs: readonly RunPair[];
+    readonly pairsTruncated: boolean;
+    readonly meta?: {
+        readonly pairKey?: string;
+        readonly phase?: string;
+        readonly approval?: string;
+    };
+    readonly reportRef?: string;
+}
+export interface RunsView {
+    readonly wireVersion: 1;
+    readonly readAt: number;
+    readonly runs: readonly RunView[];
+}
+export interface BodyView {
+    readonly wireVersion: 1;
+    readonly readAt: number;
+    readonly name: string;
+    readonly side: 'live' | 'archive';
+    readonly text: string;
+    readonly markdown: boolean;
+    readonly truncated: boolean;
+    readonly totalBytes: number;
+}
+export interface HistoryItem {
+    readonly name: string;
+    readonly kind: 'merged' | 'deleted' | 'split' | 'other';
+    readonly reason: string;
+    readonly reasonCode?: string;
+    readonly generation?: number;
+    readonly lastVersion: number;
+    readonly archivedAt: number;
+    readonly sourceRunId?: string;
+    readonly runId?: string;
+    readonly absorbedInto?: string;
+}
+export interface HistoryView {
+    readonly wireVersion: 1;
+    readonly readAt: number;
+    readonly items: readonly HistoryItem[];
+}
+export interface DoctorFact {
+    readonly key: string;
+    readonly status: 'ok' | 'warn' | 'fail' | 'unknown';
+    readonly code?: string;
+    readonly count?: number;
+    readonly detail?: string;
+}
+export interface DoctorView {
+    readonly wireVersion: 1;
+    readonly readAt: number;
+    readonly counts: MergeCounts;
+    readonly latestRun?: RunView;
+    readonly staging: {
+        readonly state: 'ok' | 'absent' | 'unreadable';
+        readonly dirs: number;
+        readonly oldestAgeMs?: number;
+        readonly detail?: string;
+    };
+    readonly approval: {
+        readonly mergeApproval: boolean;
+        readonly writeApproval?: boolean;
+    };
+    readonly hostOnly?: {
+        readonly code: 'E-323';
+        readonly detail?: string;
+    };
+    /** Set when the read model cannot read the merge state; the rows are empty placeholders. */
+    readonly blocked?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    readonly rows: readonly DoctorFact[];
+}
+export interface WireFailure {
+    readonly wireVersion: 1;
+    readonly readAt?: number;
+    readonly code: string;
+    readonly message?: string;
+}
+export interface CommandFlagSpec {
+    readonly name: string;
+    readonly kind: 'boolean' | 'value';
+    readonly valueName?: string;
+    readonly required?: boolean;
+    readonly repeatable?: boolean;
+    readonly values?: readonly string[];
+}
+export interface CommandPositionalSpec {
+    readonly name: string;
+    readonly kind: 'skill' | 'target' | 'runId' | 'id' | 'json' | 'text';
+    readonly required: boolean;
+    readonly variadic?: boolean;
+}
+export interface CommandActionRule {
+    readonly id: ActionId;
+    readonly command: string;
+    readonly confirm?: boolean;
+    readonly enabledWhen?: string;
+}
+export interface CommandSpec {
+    readonly id: string;
+    readonly words: readonly string[];
+    readonly flags: readonly CommandFlagSpec[];
+    readonly positional: readonly CommandPositionalSpec[];
+    readonly summary: string;
+    readonly readOnly: boolean;
+    readonly needsRun: boolean;
+    readonly defaults: Readonly<Record<string, string>>;
+    readonly rowActions: readonly CommandActionRule[];
+    readonly fallback: string;
+}
+export interface CommandSurface {
+    readonly wireVersion: 1;
+    readonly prefix: '/evolution merge';
+    readonly commands: readonly CommandSpec[];
+    readonly fallback: readonly CommandRef[];
+}
+//# sourceMappingURL=wire.d.ts.map

package/lib/types/wire.js

@@ -0,0 +1,3 @@
+/** Merge wire contract v1. Read-only envelopes shared with the client. */
+export const WIRE_VERSION = 1;
+//# sourceMappingURL=wire.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-merge",
   "description": "Skill auto-merge domain: screening, two-round authoring, queues and commit orchestration (community build)",
-  "version": "0.30.17",
+  "version": "0.30.19",
   "publishConfig": {
     "access": "public"
   },
@@ -22,13 +22,19 @@
   },
   "files": [
     "lib/**/*.js",
-    "lib/types/**/*.d.ts"
+    "lib/types/**/*.d.ts",
+    "data/**/*",
+    "package.json"
   ],
   "license": "MIT",
+  "scripts": {
+    "verify:publish-manifest": "node scripts/verify-publish-manifest.mjs"
+  },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.5",
-    "@lmzhen/dsh-evolution-core": "^0.30.17",
-    "@lmzhen/dsh-evolution-merge-engine": "^0.30.17"
+    "@lmzhen/dsh-evolution-core": "^0.30.19",
+    "@lmzhen/dsh-evolution-commands": "^0.30.19",
+    "@lmzhen/dsh-evolution-merge-engine": "0.30.19"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5"

package/lib/types/routes.d.ts

@@ -1,70 +0,0 @@
-/**
- * Read-only view models for the four merge routes. Pure functions; the host loads rows and
- * runs, the client renders these shapes. No io, no write paths.
- */
-import type { RunRecord } from '@lmzhen/dsh-evolution-core';
-import type { MergeQueue, MergeRow } from './contracts.ts';
-import { type MergeCounts } from './status.ts';
-export interface MergeRowView {
-    readonly id: string;
-    readonly pairKey: string;
-    readonly a: string;
-    readonly b: string;
-    readonly state: MergeRow['state'];
-    readonly queue: MergeQueue;
-    readonly stage: string | null;
-    readonly label: string;
-    readonly updatedAt: string;
-    readonly createdAt: string;
-    readonly target?: string;
-    readonly confidence?: number;
-    readonly aSummary?: string;
-    readonly bSummary?: string;
-    readonly rationale?: string;
-    readonly failure?: {
-        readonly stage: string;
-        readonly code: string;
-        readonly message: string;
-        readonly retryable: boolean;
-    };
-    readonly attempts?: number;
-    readonly origin?: 'agent' | 'human' | 'system';
-    readonly stagingExpiresAt?: number;
-    readonly expired?: 'target-taken' | 'source-changed';
-    readonly reason?: string;
-    readonly summary?: readonly string[];
-    readonly actions: readonly string[];
-}
-export declare function toRowView(row: MergeRow): MergeRowView;
-export interface MergeView {
-    readonly schemaVersion: 2;
-    readonly counts: MergeCounts;
-    readonly tabs: readonly {
-        readonly queue: MergeQueue;
-        readonly count: number;
-    }[];
-    readonly commands: readonly string[];
-    readonly latestRun?: MergeRunFact;
-    readonly approval?: boolean;
-}
-export declare function buildMergeView(rows: readonly MergeRow[], commands: readonly string[], latestRun?: MergeRunFact, approval?: boolean): MergeView;
-export interface QueuePage {
-    readonly queue: MergeQueue;
-    readonly items: readonly MergeRowView[];
-    readonly nextCursor?: string;
-}
-export declare function pageQueue(rows: readonly MergeRow[], queue: MergeQueue, cursor?: number, limit?: number): QueuePage;
-export interface MergeRunFact {
-    readonly id: string;
-    readonly state: RunRecord['state'];
-    readonly command?: RunRecord['command'];
-    readonly stage?: RunRecord['stage'];
-    readonly progress?: RunRecord['progress'];
-    readonly startedAt: number;
-    readonly endedAt?: number;
-    readonly resultRef?: string;
-    readonly failure?: string;
-    readonly supersededAt?: number;
-}
-export declare function toRunFact(run: RunRecord): MergeRunFact;
-//# sourceMappingURL=routes.d.ts.map