@lmzhen/dsh-evolution-merge 0.29.0 → 0.30.1

package/lib/types/adapters/channel.js

@@ -0,0 +1,29 @@
+function convert(outcome) {
+    if (outcome.kind !== 'ok')
+        return outcome;
+    return {
+        kind: 'ok',
+        childId: String(outcome.childId),
+        turn: { text: outcome.turn.text, stopReason: outcome.turn.stopReason },
+    };
+}
+export function subagentChannelAdapter(channel) {
+    return {
+        async open(spec) {
+            if (channel.open === undefined)
+                return { kind: 'unavailable', code: 'E-323', reason: 'subagent channel has no open()' };
+            return convert(await channel.open(spec));
+        },
+        async continueTurn(childId, promptText, options) {
+            if (channel.continueTurn === undefined)
+                return { kind: 'unavailable', code: 'E-323', reason: 'subagent channel has no continueTurn()' };
+            return convert(await channel.continueTurn(childId, promptText, options));
+        },
+        async dispose(childId) {
+            if (channel.dispose === undefined)
+                return;
+            await channel.dispose(childId);
+        },
+    };
+}
+//# sourceMappingURL=channel.js.map

package/lib/types/adapters/engine-screen.d.ts

@@ -34,7 +34,7 @@ export interface CandidateSelection {
         readonly b: string;
         readonly reason?: string;
     }[];
-    readonly reportOnly: number;
+    readonly reportOnly: readonly unknown[];
     readonly candidatePairs?: number;
 }
 export type ScreeningCandidates = readonly MergeCandidate[] & {

package/lib/types/adapters/engine-screen.js

@@ -0,0 +1,45 @@
+/**
+ * G3 screen adapter: cards -> corpus snapshot -> EnginePort.screen.
+ *
+ * The vendor engine reads a corpus from disk; host cards are content. This module
+ * writes only SKILL.md support-free snapshots under the run directory. It does not
+ * decide candidates: the Q02 selector is injected so engine/report-map stays the
+ * single source of that policy.
+ */
+import { join } from 'node:path';
+function safeName(name, index) {
+    const cleaned = name.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+    return (cleaned === '' ? 'skill-' + String(index) : cleaned) + '__' + String(index);
+}
+/** Write the exact card bodies as a support-free corpus snapshot and return its root. */
+export async function snapshotCards(io, home, runId, cards) {
+    const root = join(home, 'merge', 'runs', runId, 'corpus');
+    for (let index = 0; index < cards.length; index += 1) {
+        const card = cards[index];
+        if (card === undefined)
+            continue;
+        await io.writeText(join(root, safeName(card.name, index), 'SKILL.md'), card.body);
+    }
+    return root;
+}
+export function createEngineScreening(deps) {
+    return async (cards, runId, signal) => {
+        const corpusDir = await snapshotCards(deps.io, deps.home, runId, cards);
+        const outDir = join(deps.home, 'merge', 'runs', runId, 'engine');
+        const result = await deps.engine.screen({
+            corpusDir,
+            outDir,
+            ...(deps.cfg === undefined ? {} : { cfg: deps.cfg }),
+            ...(deps.runner === undefined ? {} : { runner: deps.runner }),
+            signal,
+        });
+        if (!result.ok) {
+            throw new Error('engine screen failed: ' + result.error.code + (result.error.stage === undefined ? '' : ' @' + result.error.stage) + (result.error.detail === undefined ? '' : ': ' + result.error.detail));
+        }
+        const selection = deps.select(result.report);
+        if (deps.onSelection !== undefined)
+            await deps.onSelection(selection, runId);
+        return Object.assign(selection.candidates.slice(), selection.candidatePairs === undefined ? {} : { candidatePairs: selection.candidatePairs });
+    };
+}
+//# sourceMappingURL=engine-screen.js.map

package/lib/types/adapters/library.js

@@ -0,0 +1,14 @@
+export function skillLibraryPort(skills) {
+    const archivedNames = skills.archivedNames;
+    return {
+        readSkill: name => skills.read(name),
+        isArchived: async (name) => {
+            if (typeof archivedNames !== 'function')
+                return false;
+            const names = await archivedNames.call(skills);
+            return names === null ? true : names.includes(name);
+        },
+        commitMerge: plan => skills.commitMerge(plan),
+    };
+}
+//# sourceMappingURL=library.js.map

package/lib/types/adapters/model-runner.js

@@ -0,0 +1,34 @@
+function append(chunk, text) {
+    if (chunk.type === 'text-delta' || chunk.type === 'text')
+        return text + (chunk.text ?? '');
+    if (chunk.type === 'finish' && chunk.reason?.kind === 'error') {
+        throw new Error('model call failed: ' + (chunk.reason.failure?.message ?? 'unknown'));
+    }
+    return text;
+}
+export function createEngineRunner(llm, route) {
+    return async (prompt) => {
+        const selection = route();
+        let text = '';
+        if (llm.stream !== undefined) {
+            for await (const chunk of llm.stream({
+                provider: selection.provider,
+                model: selection.model,
+                messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
+                temperature: 0,
+            }))
+                text = append(chunk, text);
+            return text;
+        }
+        if (llm.prepareCall === undefined)
+            throw new Error('llm service has neither stream nor prepareCall');
+        const call = await llm.prepareCall({ provider: selection.provider, model: selection.model, temperature: 0 });
+        for await (const chunk of call.stream({
+            ...call.config,
+            messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
+        }))
+            text = append(chunk, text);
+        return text;
+    };
+}
+//# sourceMappingURL=model-runner.js.map

package/lib/types/adapters/select.d.ts

@@ -0,0 +1,3 @@
+import type { CandidateSelection } from './engine-screen.ts';
+export declare function selectWithErrors(report: Record<string, unknown>): CandidateSelection;
+//# sourceMappingURL=select.d.ts.map

package/lib/types/adapters/select.js

@@ -0,0 +1,35 @@
+/** Host selector correction: engine selector does not route judge errors to candidates. */
+import { pairKeyOf, selectCandidates, toEngineCandidate } from '@lmzhen/dsh-evolution-merge-engine';
+export function selectWithErrors(report) {
+    const base = selectCandidates(report);
+    const doc = (report.reportDoc ?? report);
+    const rows = Array.isArray(doc.pairs_final) ? doc.pairs_final : [];
+    const errors = new Set();
+    for (const row of rows) {
+        if (row.error !== true)
+            continue;
+        const a = typeof row.a === 'string' ? row.a : '';
+        const b = typeof row.b === 'string' ? row.b : '';
+        if (a !== '' && b !== '')
+            errors.add(pairKeyOf(a, b));
+    }
+    const candidates = base.candidates.filter(candidate => !errors.has(pairKeyOf(candidate.a, candidate.b)));
+    const skipped = base.skipped.filter(item => !errors.has(item.pairKey));
+    const reportOnly = base.reportOnly.filter((row) => {
+        const value = row;
+        if (typeof value.a !== 'string' || typeof value.b !== 'string')
+            return true;
+        return !errors.has(pairKeyOf(value.a, value.b));
+    });
+    for (const row of rows) {
+        if (row.error !== true)
+            continue;
+        const a = typeof row.a === 'string' ? row.a : '';
+        const b = typeof row.b === 'string' ? row.b : '';
+        if (a === '' || b === '')
+            continue;
+        candidates.push(toEngineCandidate(row, typeof row.reason === 'string' ? row.reason : 'judge-error'));
+    }
+    return { ...base, candidates, skipped, reportOnly };
+}
+//# sourceMappingURL=select.js.map

package/lib/types/adapters/undo.js

@@ -0,0 +1,35 @@
+/**
+ * SkillLibrary-backed undo sink. Blobs are content-addressed but the library exposes them by
+ * version, so the first readBlob call indexes all version bodies once; an undo is rare enough
+ * that this is preferable to adding a second hash index.
+ */
+import { contentHash } from '@lmzhen/dsh-evolution-core';
+export function skillLibraryUndoPort(skills) {
+    let blobs;
+    const readBlob = async (hash) => {
+        if (blobs === undefined) {
+            blobs = new Map();
+            for (const summary of await skills.list()) {
+                for (const version of await skills.listVersions(summary.name)) {
+                    const body = await skills.readVersion(summary.name, version.v);
+                    if (body !== null)
+                        blobs.set(contentHash(body), body);
+                }
+            }
+        }
+        return blobs.get(hash) ?? null;
+    };
+    const sink = {
+        readSkill: name => skills.read(name),
+        readSupport: (name, path) => skills.readSupportFile(name, path),
+        readBlob,
+        async hasArchived(name) { return (await skills.read(name)) === null; },
+        restoreFromArchive: name => skills.restoreFromArchive(name),
+        archive: (name, reason) => skills.archive(name, { reason }),
+        updateSkill: (name, body, anchor) => skills.update(name, body, undefined, anchor),
+        writeSupportFile: (name, path, content, anchor) => skills.writeSupportFile(name, path, content, undefined, anchor),
+        removeSupportFile: (name, path, anchor) => skills.removeSupportFile(name, path, undefined, anchor),
+    };
+    return { ...sink, listVersions: name => skills.listVersions(name) };
+}
+//# sourceMappingURL=undo.js.map

package/lib/types/approve-command.js

@@ -0,0 +1,42 @@
+import { approvePending } from "./pending-actions.js";
+import { withMergeRun } from "./run-shell.js";
+import { recordRound2Outcome } from "./round2-outcome.js";
+export async function runApproveCommand(options) {
+    const taken = await approvePending(options.io, options.home, options.now, options.rowId);
+    if (!taken.ok)
+        return { ok: false, message: taken.message };
+    const row = taken.row;
+    const decision = row.decision;
+    if (decision === undefined)
+        return { ok: false, message: 'pending row has no decision' };
+    return await withMergeRun({
+        io: options.io,
+        home: options.home,
+        registry: options.registry,
+        command: 'approve',
+        approval: { platformWrite: options.platformWrite, mergeApproval: true },
+        now: options.now,
+        async body(ctx) {
+            const stage = (name) => ctx.stage(name, { done: 0, total: 1 });
+            await stage('author');
+            let outcome;
+            try {
+                outcome = await options.ports.round2(row, decision, ctx.signal, ctx.runId);
+            }
+            catch (error) {
+                outcome = { kind: 'failed', failure: { stage: 'author', code: 'merge-failed', message: error instanceof Error ? error.message : String(error), retryable: true, retryFrom: 'agent2' } };
+            }
+            const base = { scope: { candidatePairs: 1, queueBefore: { verify: 0, pending: 0, fuse: 1, skipped: 0 } }, notes: [] };
+            const record = await recordRound2Outcome(options.io, options.home, options.now, row, outcome);
+            return {
+                ...base,
+                stopReason: record.merged ? 'completed' : 'failed',
+                pairs: [record.pair],
+                totals: record.merged
+                    ? { merged: 1, kept: 0, pending: 0, failed: 0 }
+                    : { merged: 0, kept: 0, pending: 0, failed: 1 },
+            };
+        },
+    });
+}
+//# sourceMappingURL=approve-command.js.map

package/lib/types/authoring-flow.js

@@ -0,0 +1,48 @@
+import { createStaging, setStagingTarget } from "./staging.js";
+import { readStagedTree } from "./staged-tree.js";
+import { validateStagedTree, hasBlockingFinding } from "./rules.js";
+import { commitStagedRun } from "./commit-execute.js";
+export async function runAuthoring(options) {
+    const targetCard = options.cards.find(card => card.name === options.target);
+    if (targetCard?.protectionUnknown === true || targetCard?.protectedBy === 'pinned')
+        return { ok: false, message: 'target is pinned: ' + options.target };
+    const stageKey = options.stageKey ?? options.runId;
+    if (options.reuseStaging === true) {
+        if (!await setStagingTarget(options.io, options.home, stageKey, options.target, options.mode))
+            return { ok: false, message: 'staging missing or unreadable: ' + stageKey };
+    }
+    else {
+        const created = await createStaging(options.io, options.home, {
+            runId: stageKey,
+            target: options.target,
+            ...(options.mode === undefined ? {} : { mode: options.mode }),
+            sources: options.cards.map(card => ({ name: card.name, body: card.body, files: card.files ?? [] })),
+            promptVersion: 'merge-b/v1',
+            ttlDays: 7,
+            now: options.now,
+        });
+        if (!created.ok)
+            return { ok: false, message: created.message };
+    }
+    try {
+        await options.author({ home: options.home, runId: stageKey });
+    }
+    catch (error) {
+        return { ok: false, message: 'author failed: ' + (error instanceof Error ? error.message : String(error)) };
+    }
+    const tree = await readStagedTree(options.io, options.home, stageKey);
+    if (tree.kind !== 'present')
+        return { ok: false, message: 'staged tree is not readable: ' + (tree.kind === 'unknown' ? tree.reason : 'absent') };
+    const findings = validateStagedTree(tree.value);
+    if (hasBlockingFinding(findings))
+        return { ok: false, message: 'staged tree failed the rule gate', findings };
+    const commit = await commitStagedRun(options.io, options.home, stageKey, options.commitPort, {
+        origin: 'subagent',
+        summary: options.summary,
+        now: options.now,
+    });
+    if (!commit.ok)
+        return { ok: false, message: commit.message };
+    return { ok: true, tree: tree.value, commit };
+}
+//# sourceMappingURL=authoring-flow.js.map

package/lib/types/channel-port.js

@@ -0,0 +1,74 @@
+import { parseDecision } from "./decision.js";
+import { buildRound1Prompt, buildRound2Prompt, STANDBY_PROMPT } from "./prompts.js";
+export async function runRound1OverChannel(options, candidate, signal) {
+    let childId;
+    const dispose = async () => {
+        if (childId !== undefined) {
+            const id = childId;
+            childId = undefined;
+            try {
+                await options.channel.dispose(id);
+            }
+            catch { /* teardown must not replace the outcome */ }
+        }
+    };
+    const opened = await options.channel.open({
+        parent: options.parent,
+        label: 'merge-round1',
+        promptText: STANDBY_PROMPT,
+        kind: 'reviewer',
+        allow: options.allow,
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        timeoutMs: options.timeoutMs,
+        signal,
+    });
+    if (opened.kind === 'unavailable')
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: opened.code, message: opened.reason, retryable: true, retryFrom: 'agent1' } }, dispose };
+    if (opened.kind === 'aborted')
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: 'aborted', message: 'round1 aborted', retryable: false, retryFrom: 'none' } }, dispose };
+    childId = opened.childId;
+    if (opened.turn.stopReason !== 'completed') {
+        await dispose();
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: opened.turn.stopReason, message: 'standby did not complete', retryable: true, retryFrom: 'agent1' } }, dispose };
+    }
+    try {
+        options.onChildOpened?.(opened.childId);
+    }
+    catch (error) {
+        await dispose();
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: 'child-bind', message: String(error), retryable: true, retryFrom: 'agent1' } }, dispose };
+    }
+    const round1 = await options.channel.continueTurn(opened.childId, buildRound1Prompt(candidate, options.cards), { timeoutMs: options.timeoutMs, signal });
+    if (round1.kind !== 'ok') {
+        await dispose();
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: round1.kind, message: round1.kind === 'unavailable' ? round1.reason : 'round1 aborted', retryable: round1.kind !== 'aborted', retryFrom: round1.kind === 'aborted' ? 'none' : 'agent1' } }, dispose };
+    }
+    if (round1.turn.stopReason !== 'completed') {
+        await dispose();
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: round1.turn.stopReason, message: 'round1 did not complete', retryable: true, retryFrom: 'agent1' } }, dispose };
+    }
+    const parsed = parseDecision(round1.turn.text, candidate);
+    if (!parsed.ok) {
+        await dispose();
+        return { outcome: { kind: 'failed', failure: { stage: 'decide', code: parsed.code, message: parsed.message, retryable: true, retryFrom: 'agent1' } }, dispose };
+    }
+    if (!parsed.decision.shouldMerge || parsed.decision.mode === 'keep') {
+        await dispose();
+        return { outcome: { kind: 'keep', decision: parsed.decision }, dispose };
+    }
+    const child = opened.childId;
+    return {
+        outcome: { kind: 'merge', decision: parsed.decision },
+        childId: child,
+        dispose,
+        async author(row, decision, turnSignal) {
+            const turn = await options.channel.continueTurn(child, buildRound2Prompt(row, decision), { timeoutMs: options.timeoutMs, signal: turnSignal });
+            if (turn.kind !== 'ok')
+                throw new Error(turn.kind === 'unavailable' ? turn.reason : 'round2 aborted');
+            if (turn.turn.stopReason !== 'completed')
+                throw new Error('round2 did not complete: ' + turn.turn.stopReason);
+            return turn.turn.text;
+        },
+    };
+}
+//# sourceMappingURL=channel-port.js.map

package/lib/types/commands.d.ts

@@ -8,6 +8,7 @@ export type MergeCliCommand = {
     readonly verb: 'pair';
     readonly a: string;
     readonly b: string;
+    readonly force?: true;
 } | {
     readonly verb: 'status';
     readonly id?: string;
@@ -23,6 +24,10 @@ export type MergeCliCommand = {
     readonly verb: 'doctor';
 } | {
     readonly verb: 'pending';
+    readonly expired?: true;
+} | {
+    readonly verb: 'candidates';
+    readonly retry?: true;
 } | {
     readonly verb: 'approve';
     readonly id: string;
@@ -33,9 +38,13 @@ export type MergeCliCommand = {
     readonly verb: 'resume';
     readonly id?: string;
     readonly clear?: string;
+    readonly retry?: true;
 } | {
     readonly verb: 'skipped';
     readonly restore?: string;
+} | {
+    readonly verb: 'discard';
+    readonly id: string;
 } | {
     readonly verb: 'undo';
     readonly target: string;

package/lib/types/commands.js

@@ -0,0 +1,79 @@
+const USAGE = 'usage: /evolution merge scan | pair [--force] <a> <b> | status [id] | report [id] | cancel [id] | runs | doctor | pending [--expired] | candidates [--retry] | approve <id> | reject <id> | resume [id] [--retry] [--clear <id>] | skipped [--restore <id>] | discard <id> | undo <target> --run <id>';
+function flags(args, allowed) {
+    const values = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (!token.startsWith('--') || token === '--force' || token === '--expired' || token === '--retry')
+            continue;
+        const name = token.slice(2);
+        if (!allowed.includes(name))
+            return { values, error: 'unknown flag: --' + name };
+        const value = args[index + 1];
+        if (value === undefined || value.startsWith('--'))
+            return { values, error: 'missing value for --' + name };
+        values.set(name, value);
+        index += 1;
+    }
+    return { values };
+}
+function switches(args) {
+    return new Set(args.filter(token => token === '--force' || token === '--expired' || token === '--retry').map(token => token.slice(2)));
+}
+function positional(args) {
+    const filtered = args.filter(token => token !== '--force' && token !== '--expired' && token !== '--retry');
+    return filtered.filter((token, index) => !token.startsWith('--') && !(index > 0 && filtered[index - 1].startsWith('--')));
+}
+export function parseMergeCommand(argv) {
+    const [verb, ...rest] = argv;
+    if (verb === undefined || verb === 'help' || verb === '--help' || verb === '-h')
+        return { ok: true, command: { verb: 'scan' }, help: true };
+    const pos = positional(rest);
+    const marked = switches(rest);
+    switch (verb) {
+        case 'scan': return pos.length === 0 ? { ok: true, command: { verb: 'scan' } } : { ok: false, code: 'usage', message: USAGE };
+        case 'pair': return pos.length === 2 ? { ok: true, command: { verb: 'pair', a: pos[0], b: pos[1], ...(marked.has('force') ? { force: true } : {}) } } : { ok: false, code: 'usage', message: USAGE };
+        case 'status': return pos.length <= 1 ? { ok: true, command: { verb: 'status', ...(pos[0] === undefined ? {} : { id: pos[0] }) } } : { ok: false, code: 'usage', message: USAGE };
+        case 'report': return pos.length <= 1 ? { ok: true, command: { verb: 'report', ...(pos[0] === undefined ? {} : { id: pos[0] }) } } : { ok: false, code: 'usage', message: USAGE };
+        case 'cancel': return pos.length <= 1 ? { ok: true, command: { verb: 'cancel', ...(pos[0] === undefined ? {} : { id: pos[0] }) } } : { ok: false, code: 'usage', message: USAGE };
+        case 'runs': return pos.length === 0 ? { ok: true, command: { verb: 'runs' } } : { ok: false, code: 'usage', message: USAGE };
+        case 'doctor': return pos.length === 0 ? { ok: true, command: { verb: 'doctor' } } : { ok: false, code: 'usage', message: USAGE };
+        case 'pending': return pos.length === 0 ? { ok: true, command: { verb: 'pending', ...(marked.has('expired') ? { expired: true } : {}) } } : { ok: false, code: 'usage', message: USAGE };
+        case 'candidates': return pos.length === 0 ? { ok: true, command: { verb: 'candidates', ...(marked.has('retry') ? { retry: true } : {}) } } : { ok: false, code: 'usage', message: USAGE };
+        case 'approve': return pos.length === 1 ? { ok: true, command: { verb: 'approve', id: pos[0] } } : { ok: false, code: 'usage', message: USAGE };
+        case 'reject': return pos.length === 1 ? { ok: true, command: { verb: 'reject', id: pos[0] } } : { ok: false, code: 'usage', message: USAGE };
+        case 'resume': {
+            const parsed = flags(rest, ['clear']);
+            if (parsed.error !== undefined)
+                return { ok: false, code: 'usage', message: parsed.error };
+            const clear = parsed.values.get('clear');
+            if (pos.length > 1)
+                return { ok: false, code: 'usage', message: USAGE };
+            return { ok: true, command: { verb: 'resume', ...(pos[0] === undefined ? {} : { id: pos[0] }), ...(clear === undefined ? {} : { clear }), ...(marked.has('retry') ? { retry: true } : {}) } };
+        }
+        case 'skipped': {
+            const parsed = flags(rest, ['restore']);
+            if (parsed.error !== undefined)
+                return { ok: false, code: 'usage', message: parsed.error };
+            if (pos.length > 0)
+                return { ok: false, code: 'usage', message: USAGE };
+            const restore = parsed.values.get('restore');
+            return { ok: true, command: { verb: 'skipped', ...(restore === undefined ? {} : { restore }) } };
+        }
+        case 'discard': return pos.length === 1 ? { ok: true, command: { verb: 'discard', id: pos[0] } } : { ok: false, code: 'usage', message: USAGE };
+        case 'undo': {
+            const parsed = flags(rest, ['run']);
+            if (parsed.error !== undefined)
+                return { ok: false, code: 'usage', message: parsed.error };
+            const target = pos[0];
+            const run = parsed.values.get('run');
+            if (target === undefined || run === undefined || pos.length !== 1)
+                return { ok: false, code: 'usage', message: USAGE };
+            return { ok: true, command: { verb: 'undo', target, run } };
+        }
+        default: return { ok: false, code: 'usage', message: 'unknown merge command: ' + verb + '\n' + USAGE };
+    }
+}
+export function mergeUsage() {
+    return USAGE;
+}
+//# sourceMappingURL=commands.js.map

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