@lmzhen/dsh-evolution-merge 0.28.0 → 0.30.0

package/lib/types/commit-assembly.js

@@ -0,0 +1,48 @@
+import { isPresent } from '@lmzhen/dsh-evolution-core';
+import { readStaging } from "./staging.js";
+import { readStagedTree } from "./staged-tree.js";
+import { buildCommitPlan } from "./commit-plan.js";
+export async function assembleStagedCommit(io, home, runId, port, options) {
+    const staging = await readStaging(io, home, runId);
+    if (!isPresent(staging))
+        return { ok: false, message: 'staging is not present for run ' + runId };
+    const tree = await readStagedTree(io, home, runId);
+    if (!isPresent(tree))
+        return { ok: false, message: 'merged tree is not readable for run ' + runId };
+    const requested = staging.value.manifest.target;
+    let target = requested;
+    let targetCurrent = await port.readSkill(requested);
+    const requestedArchived = targetCurrent === null && await port.isArchived?.(requested) === true;
+    if (staging.value.manifest.mode === 'create-umbrella' && (targetCurrent !== null || requestedArchived)) {
+        target = requested;
+        for (let suffix = 2; suffix <= 99; suffix += 1) {
+            const candidate = requested + '-v' + String(suffix);
+            if (await port.readSkill(candidate) === null
+                && await port.isArchived?.(candidate) !== true) {
+                target = candidate;
+                targetCurrent = null;
+                break;
+            }
+        }
+        if (target === requested)
+            return { ok: false, message: 'no free umbrella target for ' + requested };
+    }
+    const sources = [];
+    for (const name of staging.value.manifest.sources) {
+        const body = await port.readSkill(name);
+        if (body === null)
+            return { ok: false, message: 'source skill is not live: ' + name };
+        sources.push({ name, body });
+    }
+    return buildCommitPlan({
+        target,
+        create: targetCurrent === null,
+        mergedBody: tree.value.body,
+        mergedFiles: tree.value.files,
+        targetCurrent,
+        sourceBodies: sources,
+        origin: options.origin,
+        summary: options.summary,
+    });
+}
+//# sourceMappingURL=commit-assembly.js.map

package/lib/types/commit-execute.js

@@ -0,0 +1,52 @@
+import { assembleStagedCommit } from "./commit-assembly.js";
+import { writeCommitReceipt } from "./commit-receipt.js";
+import { pairKey } from "./contracts.js";
+import { writeJournal } from "./domain/commit-journal-store.js";
+export async function commitStagedRun(io, home, runId, port, options) {
+    const assembled = await assembleStagedCommit(io, home, runId, port, { origin: options.origin, summary: options.summary });
+    if (!assembled.ok)
+        return { ok: false, message: assembled.message };
+    const journal = { runId, target: assembled.plan.target, create: !assembled.plan.targetExists, sources: assembled.plan.sources, phase: 'prepared', updatedAt: new Date(options.now()).toISOString() };
+    try {
+        await writeJournal(io, home, journal);
+    }
+    catch { /* journal is best-effort; receipt remains the commit record */ }
+    const result = await port.commitMerge(assembled.plan);
+    if (!result.ok) {
+        try {
+            await writeJournal(io, home, { ...journal, phase: 'failed', updatedAt: new Date(options.now()).toISOString() });
+        }
+        catch { }
+        return { ok: false, message: result.message, plan: assembled.plan };
+    }
+    if (result.unitId === undefined)
+        return { ok: true, plan: assembled.plan, result, warning: 'commit landed without a unitId; receipt not written' };
+    const receipt = {
+        runId,
+        parentRunId: runId.split('/pairs/')[0] ?? runId,
+        unitId: result.unitId,
+        target: assembled.plan.target,
+        create: !assembled.plan.targetExists,
+        sources: assembled.plan.sources,
+        ...(assembled.plan.sources[0] === undefined ? {} : { pairKey: pairKey(assembled.plan.target, assembled.plan.sources[0]) }),
+        archived: result.archived ?? [],
+        at: options.now(),
+    };
+    try {
+        await writeCommitReceipt(io, home, receipt);
+        try {
+            await writeJournal(io, home, { ...journal, unitId: result.unitId, phase: 'committed', updatedAt: new Date(options.now()).toISOString() });
+        }
+        catch { }
+        return { ok: true, plan: assembled.plan, result, receipt };
+    }
+    catch (error) {
+        return {
+            ok: true,
+            plan: assembled.plan,
+            result,
+            warning: 'commit landed but receipt write failed: ' + (error instanceof Error ? error.message : String(error)),
+        };
+    }
+}
+//# sourceMappingURL=commit-execute.js.map

package/lib/types/commit-plan.js

@@ -0,0 +1,56 @@
+const MAX_SKILL_NAME_LENGTH = 64;
+/** Pick the first free target: requested, then -v2, -v3, ... (never truncate a name). */
+export function resolveTargetName(requested, exists) {
+    if (requested.length === 0 || requested.length > MAX_SKILL_NAME_LENGTH) {
+        return { ok: false, message: 'target name must be 1..' + String(MAX_SKILL_NAME_LENGTH) + ' characters' };
+    }
+    if (!exists(requested))
+        return { ok: true, name: requested, suffix: 1 };
+    for (let suffix = 2; suffix <= 99; suffix += 1) {
+        const candidate = requested + '-v' + String(suffix);
+        if (candidate.length > MAX_SKILL_NAME_LENGTH)
+            break;
+        if (!exists(candidate))
+            return { ok: true, name: candidate, suffix };
+    }
+    return { ok: false, message: 'no free target name for ' + requested + ' (tried up to -v99)' };
+}
+/** Rewrite only the frontmatter name; body bytes stay otherwise intact. */
+export function rewriteFrontmatterName(body, name) {
+    const lines = body.split('\n');
+    if (lines[0]?.trim() !== '---')
+        return body;
+    const end = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+    if (end < 0)
+        return body;
+    for (let index = 1; index < end; index += 1) {
+        if (/^name\s*:/.test(lines[index] ?? '')) {
+            lines[index] = 'name: ' + name;
+            return lines.join('\n');
+        }
+    }
+    return body;
+}
+export function buildCommitPlan(input) {
+    if (input.create !== (input.targetCurrent === null))
+        return { ok: false, message: 'create flag disagrees with the live target' };
+    const sources = input.sourceBodies.filter(source => source.name !== input.target);
+    if (sources.length === 0)
+        return { ok: false, message: 'a merge needs at least one source different from the target' };
+    const body = rewriteFrontmatterName(input.mergedBody, input.target);
+    return {
+        ok: true,
+        plan: {
+            target: input.target,
+            targetExists: !input.create,
+            sources: sources.map(source => source.name),
+            body,
+            supportFiles: input.mergedFiles,
+            expectedTargetBody: input.targetCurrent,
+            expectedSourceBodies: sources,
+            origin: input.origin,
+            summary: input.summary,
+        },
+    };
+}
+//# sourceMappingURL=commit-plan.js.map

package/lib/types/commit-receipt.d.ts

@@ -1,14 +1,19 @@
 import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 export interface CommitReceipt {
     readonly runId: string;
+    readonly parentRunId?: string;
     readonly unitId: string;
     readonly target: string;
     readonly create: boolean;
     readonly sources: readonly string[];
+    readonly pairKey?: string;
     readonly archived: readonly string[];
     readonly at: number;
 }
 export declare function commitReceiptPath(home: string, runId: string): string;
+export declare function durableReceiptDir(home: string, parentRunId: string): string;
+export declare function durableReceiptPath(home: string, parentRunId: string, stageKey: string): string;
 export declare function writeCommitReceipt(io: EvolutionIoLike, home: string, receipt: CommitReceipt): Promise<string>;
-export declare function readCommitReceipt(io: EvolutionIoLike, home: string, runId: string): Promise<CommitReceipt | null>;
+export declare function readCommitReceipts(io: EvolutionIoLike, home: string): Promise<readonly CommitReceipt[]>;
+export declare function readCommitReceipt(io: EvolutionIoLike, home: string, runId: string, target?: string): Promise<CommitReceipt | null>;
 //# sourceMappingURL=commit-receipt.d.ts.map

package/lib/types/commit-receipt.js

@@ -0,0 +1,85 @@
+/**
+ * Commit receipt: <run>/commit.json, written immediately after a successful commit.
+ * It is the idempotency/recovery marker — merge resume and run start read it before
+ * replaying a commit. Receipt write failure must not turn a landed commit into a failure;
+ * the caller reports the warning instead.
+ */
+import { join } from 'node:path';
+import { stagingRoot } from "./staging.js";
+export function commitReceiptPath(home, runId) {
+    return join(stagingRoot(home, runId), 'commit.json');
+}
+export function durableReceiptDir(home, parentRunId) {
+    return join(home, 'merge', 'receipts', parentRunId);
+}
+export function durableReceiptPath(home, parentRunId, stageKey) {
+    const leaf = stageKey.split('/').pop() ?? stageKey;
+    return join(durableReceiptDir(home, parentRunId), leaf + '.json');
+}
+function parseReceipt(raw) {
+    if (raw === null)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.runId !== 'string' || typeof parsed.unitId !== 'string' || typeof parsed.target !== 'string'
+            || typeof parsed.create !== 'boolean' || !Array.isArray(parsed.sources) || !Array.isArray(parsed.archived) || typeof parsed.at !== 'number') {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeCommitReceipt(io, home, receipt) {
+    const path = commitReceiptPath(home, receipt.runId);
+    await io.writeText(path, JSON.stringify(receipt, null, 2) + '\n');
+    const parent = receipt.parentRunId ?? receipt.runId.split('/pairs/')[0] ?? receipt.runId;
+    await io.writeText(durableReceiptPath(home, parent, receipt.runId), JSON.stringify({ ...receipt, parentRunId: parent }, null, 2) + '\n');
+    return path;
+}
+export async function readCommitReceipts(io, home) {
+    const root = join(home, 'merge', 'receipts');
+    const out = [];
+    let runs;
+    try {
+        runs = await io.list(root);
+    }
+    catch {
+        return out;
+    }
+    for (const run of runs.sort()) {
+        const dir = join(root, run);
+        let files;
+        try {
+            files = await io.list(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const file of files.sort()) {
+            if (!file.endsWith('.json'))
+                continue;
+            const receipt = parseReceipt(await io.readText(join(dir, file)));
+            if (receipt !== null)
+                out.push(receipt);
+        }
+    }
+    return out;
+}
+export async function readCommitReceipt(io, home, runId, target) {
+    const direct = parseReceipt(await io.readText(commitReceiptPath(home, runId)));
+    if (direct !== null && (target === undefined || direct.target === target))
+        return direct;
+    try {
+        const names = await io.list(durableReceiptDir(home, runId));
+        for (const name of names.sort()) {
+            const receipt = parseReceipt(await io.readText(join(durableReceiptDir(home, runId), name)));
+            if (receipt !== null && (target === undefined || receipt.target === target))
+                return receipt;
+        }
+    }
+    catch { /* absent */ }
+    return null;
+}
+//# sourceMappingURL=commit-receipt.js.map

package/lib/types/contracts.d.ts

@@ -4,9 +4,9 @@
  * The data layer keeps four states; the user face collapses verify/fuse into one retry
  * queue and keeps the stage as a chip. The API queue must never expose the raw state.
  */
-export declare const MERGE_STATE_VERSION = 1;
-export type MergePairState = 'verify' | 'pending' | 'fuse' | 'skipped';
-export type MergeQueue = 'pending' | 'retry' | 'skipped';
+export declare const MERGE_STATE_VERSION = 2;
+export type MergePairState = 'verify' | 'pending' | 'approved' | 'fuse' | 'skipped';
+export type MergeQueue = 'verify' | 'pending' | 'fuse' | 'skipped';
 export type MergeStage = 'verify' | 'decide' | 'author' | 'commit';
 export type MergeCommand = 'scan' | 'pair' | 'approve' | 'resume';
 export declare const MERGE_PAIR_STATES: readonly MergePairState[];
@@ -41,7 +41,7 @@ export interface MergeCandidate {
     readonly arms?: readonly string[];
     readonly reason?: string;
     readonly gate?: MergeGateFact;
-    readonly source?: 'lexical' | 'proposed';
+    readonly source?: 'lexical' | 'proposed' | 'engine';
 }
 export interface MergeDecision {
     readonly shouldMerge: boolean;
@@ -50,6 +50,8 @@ export interface MergeDecision {
     readonly sources: readonly string[];
     readonly rationale: string;
     readonly confidence?: number;
+    readonly aSummary?: string;
+    readonly bSummary?: string;
 }
 export interface MergeUsage {
     readonly inputTokens?: number;
@@ -86,7 +88,7 @@ export interface MergeReportPair {
     readonly timing?: MergeTiming;
 }
 export interface MergeReport {
-    readonly schemaVersion: 1;
+    readonly schemaVersion: 2;
     readonly runId: string;
     readonly kind: 'merge';
     readonly command: MergeRunCommand;
@@ -116,13 +118,24 @@ export interface MergeRow {
     readonly b: string;
     readonly state: MergePairState;
     readonly queue: MergeQueue;
+    readonly expired?: 'target-taken' | 'source-changed';
+    readonly reason?: string;
+    readonly target?: {
+        readonly requested: string;
+        readonly actual?: string;
+        readonly created?: boolean;
+    };
     readonly failure?: MergeFailure;
     /** Round-1 decision, persisted for the later approve round. */
     readonly decision?: MergeDecision;
+    readonly sourceRevision?: string;
+    readonly targetRevision?: string;
     readonly runId?: string;
     readonly unitId?: string;
-    readonly origin?: 'agent' | 'human';
+    readonly origin?: 'agent' | 'human' | 'system';
     readonly attempts?: number;
+    readonly stagingRef?: string;
+    readonly stagingExpiresAt?: number;
     readonly createdAt: string;
     readonly updatedAt: string;
 }
@@ -132,5 +145,6 @@ export interface MergeState {
 }
 export declare function emptyMergeState(): MergeState;
 /** One record can be retried only when the failure says so and names a stage. */
-export declare function canRetry(record: Pick<MergeRow, 'state' | 'failure'>): boolean;
+export declare const MERGE_MAX_ATTEMPTS = 3;
+export declare function canRetry(record: Pick<MergeRow, 'state' | 'failure' | 'attempts'>): boolean;
 //# sourceMappingURL=contracts.d.ts.map

package/lib/types/contracts.js

@@ -0,0 +1,57 @@
+/**
+ * Frozen merge-domain vocabulary. No io, no host, no imports from the plugin shell.
+ *
+ * The data layer keeps four states; the user face collapses verify/fuse into one retry
+ * queue and keeps the stage as a chip. The API queue must never expose the raw state.
+ */
+export const MERGE_STATE_VERSION = 2;
+export const MERGE_PAIR_STATES = ['verify', 'pending', 'approved', 'fuse', 'skipped'];
+export const MERGE_QUEUES = ['verify', 'pending', 'fuse', 'skipped'];
+/** User-facing queue of one data state. verify/fuse share retry, not two tabs. */
+export function queueOf(state) {
+    switch (state) {
+        case 'verify': return 'verify';
+        case 'pending': return 'pending';
+        case 'approved':
+        case 'fuse': return 'fuse';
+        case 'skipped': return 'skipped';
+    }
+}
+/** Coarse stage chip; skipped has no active stage. */
+export function stageOf(state) {
+    switch (state) {
+        case 'verify': return 'verify';
+        case 'pending': return 'decide';
+        case 'approved':
+        case 'fuse': return 'author';
+        case 'skipped': return null;
+    }
+}
+/** Stable pair identity; NUL cannot appear in a skill name. */
+export function pairKey(a, b) {
+    return a < b ? a + '\u0000' + b : b + '\u0000' + a;
+}
+/** Deterministic, URL-safe id derived from the pair key (FNV-1a 32). */
+export function rowIdOf(key) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < key.length; index += 1) {
+        hash ^= key.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return 'mr_' + hash.toString(36).padStart(7, '0');
+}
+export function emptyMergeState() {
+    return { schemaVersion: MERGE_STATE_VERSION, rows: [] };
+}
+/** One record can be retried only when the failure says so and names a stage. */
+export const MERGE_MAX_ATTEMPTS = 3;
+export function canRetry(record) {
+    if (record.state === 'skipped')
+        return false;
+    if ((record.attempts ?? 0) >= MERGE_MAX_ATTEMPTS)
+        return false;
+    if (record.failure === undefined)
+        return record.state !== 'pending';
+    return record.failure.retryable && record.failure.retryFrom !== 'none';
+}
+//# sourceMappingURL=contracts.js.map

package/lib/types/coordinator.d.ts

@@ -18,6 +18,8 @@ export type MergeEvent = {
     readonly type: 'round1-merge';
     readonly approval: 'on' | 'off';
     readonly decision?: MergeDecision;
+    readonly stagingRef?: string;
+    readonly stagingExpiresAt?: number;
     readonly at: string;
 } | {
     readonly type: 'round1-fail';
@@ -34,6 +36,9 @@ export type MergeEvent = {
     readonly type: 'round2-fail';
     readonly failure: MergeFailure;
     readonly at: string;
+} | {
+    readonly type: 'round2-cancel';
+    readonly at: string;
 } | {
     readonly type: 'round2-success';
     readonly unitId?: string;
@@ -44,6 +49,12 @@ export type MergeEvent = {
 } | {
     readonly type: 'source-gone';
     readonly at: string;
+} | {
+    readonly type: 'gate-keep';
+    readonly a: string;
+    readonly b: string;
+    readonly reason?: string;
+    readonly at: string;
 };
 export type TransitionResult = {
     readonly ok: true;

package/lib/types/coordinator.js

@@ -0,0 +1,131 @@
+/**
+ * Pure merge transition table. No io, no run shell, no subagents.
+ *
+ * Every transition returns the whole next row (or a drop), so the caller can persist it
+ * through mutateMergeState in one transaction. Invalid transitions are refused by name;
+ * a caller never "repairs" a row by guessing which state the operator meant.
+ */
+import { pairKey, queueOf, rowIdOf, } from "./contracts.js";
+function invalid(event, state) {
+    return {
+        ok: false,
+        code: 'invalid-transition',
+        message: 'cannot apply ' + event.type + ' to ' + (state ?? 'no row'),
+    };
+}
+/** Drop fields that must not survive a transition; optional fields stay absent. */
+function base(row, at) {
+    return {
+        id: row.id,
+        pairKey: row.pairKey,
+        a: row.a,
+        b: row.b,
+        state: row.state,
+        queue: row.queue,
+        createdAt: row.createdAt,
+        updatedAt: at,
+        ...(row.runId === undefined ? {} : { runId: row.runId }),
+        ...(row.unitId === undefined ? {} : { unitId: row.unitId }),
+        ...(row.origin === undefined ? {} : { origin: row.origin }),
+        ...(row.decision === undefined ? {} : { decision: row.decision }),
+        ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }),
+        ...(row.targetRevision === undefined ? {} : { targetRevision: row.targetRevision }),
+        ...(row.attempts === undefined ? {} : { attempts: row.attempts }),
+        ...(row.stagingRef === undefined ? {} : { stagingRef: row.stagingRef }),
+        ...(row.stagingExpiresAt === undefined ? {} : { stagingExpiresAt: row.stagingExpiresAt }),
+        ...(row.expired === undefined ? {} : { expired: row.expired }),
+        ...(row.reason === undefined ? {} : { reason: row.reason }),
+        ...(row.target === undefined ? {} : { target: row.target }),
+    };
+}
+function next(row, at, state, patch = {}) {
+    return {
+        ok: true,
+        row: {
+            ...base(row, at),
+            state,
+            queue: queueOf(state),
+            ...patch,
+        },
+    };
+}
+export function transition(current, event) {
+    if (event.type === 'candidate') {
+        if (current !== undefined)
+            return { ok: true, row: current };
+        const key = pairKey(event.a, event.b);
+        return {
+            ok: true,
+            row: {
+                id: rowIdOf(key),
+                pairKey: key,
+                a: event.a,
+                b: event.b,
+                state: 'verify',
+                queue: 'verify',
+                createdAt: event.at,
+                updatedAt: event.at,
+            },
+        };
+    }
+    if (event.type === 'source-gone')
+        return { ok: true, row: null };
+    if (event.type === 'gate-keep') {
+        if (current !== undefined)
+            return { ok: true, row: current };
+        const key = pairKey(event.a, event.b);
+        return {
+            ok: true,
+            row: {
+                id: rowIdOf(key),
+                pairKey: key,
+                a: event.a,
+                b: event.b,
+                state: 'skipped',
+                queue: 'skipped',
+                origin: 'agent',
+                createdAt: event.at,
+                updatedAt: event.at,
+            },
+        };
+    }
+    if (current === undefined)
+        return invalid(event, undefined);
+    switch (event.type) {
+        case 'round1-keep':
+            return current.state === 'verify' ? next(current, event.at, 'skipped', { origin: 'agent' }) : invalid(event, current.state);
+        case 'round1-merge':
+            if (current.state !== 'verify')
+                return invalid(event, current.state);
+            return event.approval === 'on'
+                ? next(current, event.at, 'pending', { ...(event.decision === undefined ? {} : { decision: event.decision }), ...(event.stagingRef === undefined ? {} : { stagingRef: event.stagingRef }), ...(event.stagingExpiresAt === undefined ? {} : { stagingExpiresAt: event.stagingExpiresAt }) })
+                : next(current, event.at, 'approved', { ...(event.decision === undefined ? {} : { decision: event.decision }), ...(event.stagingRef === undefined ? {} : { stagingRef: event.stagingRef }), ...(event.stagingExpiresAt === undefined ? {} : { stagingExpiresAt: event.stagingExpiresAt }) });
+        case 'round1-fail':
+            return current.state === 'verify'
+                ? next(current, event.at, 'verify', { failure: event.failure, attempts: (current.attempts ?? 0) + 1 })
+                : invalid(event, current.state);
+        case 'approve':
+            return current.state === 'pending'
+                ? next(current, event.at, 'approved', { ...(event.runId === undefined ? {} : { runId: event.runId }) })
+                : invalid(event, current.state);
+        case 'reject':
+            return current.state === 'pending' ? next(current, event.at, 'skipped', { origin: 'human' }) : invalid(event, current.state);
+        case 'round2-cancel':
+            return current.state === 'fuse' || current.state === 'approved'
+                ? next(current, event.at, 'approved')
+                : invalid(event, current.state);
+        case 'round2-fail':
+            return current.state === 'fuse' || current.state === 'approved'
+                ? next(current, event.at, 'approved', { failure: event.failure, attempts: (current.attempts ?? 0) + 1 })
+                : invalid(event, current.state);
+        case 'round2-success':
+            return current.state === 'fuse' || current.state === 'approved'
+                ? { ok: true, row: null }
+                : invalid(event, current.state);
+        case 'restore':
+            return current.state === 'skipped'
+                ? next(current, event.at, 'verify')
+                : invalid(event, current.state);
+    }
+}
+//# sourceMappingURL=coordinator.js.map

package/lib/types/decision.js

@@ -0,0 +1,61 @@
+function extractJson(text) {
+    const fenced = /\`\`\`(?:json)?\s*([\s\S]*?)\`\`\`/i.exec(text);
+    const body = fenced?.[1] ?? text;
+    const start = body.indexOf('{');
+    if (start < 0)
+        return undefined;
+    let depth = 0;
+    for (let index = start; index < body.length; index += 1) {
+        if (body[index] === '{')
+            depth += 1;
+        else if (body[index] === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                try {
+                    return JSON.parse(body.slice(start, index + 1));
+                }
+                catch {
+                    return undefined;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+export function parseDecision(text, pair) {
+    if (text === undefined || text.trim() === '')
+        return { ok: false, code: 'decision-invalid', message: 'empty decision text' };
+    const value = extractJson(text);
+    if (typeof value !== 'object' || value === null)
+        return { ok: false, code: 'decision-invalid', message: 'decision is not a JSON object' };
+    const record = value;
+    const shouldMerge = record.shouldMerge === true || record.should_merge === true;
+    const mode = record.mode;
+    if (mode !== 'merge-into-existing' && mode !== 'create-umbrella' && mode !== 'keep') {
+        return { ok: false, code: 'decision-invalid', message: 'mode must be merge-into-existing, create-umbrella or keep' };
+    }
+    const target = typeof record.target === 'string' ? record.target.trim() : '';
+    const sources = Array.isArray(record.sources) ? record.sources.filter((item) => typeof item === 'string').map(item => item.trim()).filter(Boolean) : [];
+    const rationale = typeof record.rationale === 'string' ? record.rationale.trim() : '';
+    if (!shouldMerge || mode === 'keep') {
+        return { ok: true, decision: { shouldMerge: false, mode: 'keep', target, sources, rationale } };
+    }
+    if (target === '')
+        return { ok: false, code: 'decision-invalid', message: 'merge decision needs target' };
+    if (sources.length === 0)
+        return { ok: false, code: 'decision-invalid', message: 'merge decision needs sources' };
+    if (!sources.includes(pair.a) || !sources.includes(pair.b))
+        return { ok: false, code: 'decision-invalid', message: 'sources must include both pair skills' };
+    return {
+        ok: true,
+        decision: {
+            shouldMerge: true,
+            mode,
+            target,
+            sources,
+            rationale,
+            ...(typeof record.confidence === 'number' ? { confidence: record.confidence } : {}),
+        },
+    };
+}
+//# sourceMappingURL=decision.js.map

package/lib/types/doctor.d.ts

@@ -6,5 +6,5 @@ export interface MergeDoctorRow {
     readonly status: 'ok' | 'warn' | 'unknown';
     readonly detail: string;
 }
-export declare function mergeDoctor(io: EvolutionIoLike, home: string): Promise<readonly MergeDoctorRow[]>;
+export declare function mergeDoctor(io: EvolutionIoLike, home: string, configuredRoot?: string): Promise<readonly MergeDoctorRow[]>;
 //# sourceMappingURL=doctor.d.ts.map