@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.19

package/lib/types/command-defs.js

@@ -0,0 +1,33 @@
+/** Merge CommandDef data; parser/help/surface/fallback live in evolution-commands. */
+import { readFileSync } from 'node:fs';
+const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export const MERGE_PACKAGE_VERSION = manifest.version ?? '0.30.18';
+export const MERGE_ALIAS_DEF = { id: 'merge.alias', words: ['merge'], summaryKey: 'merge.alias', helpKey: 'merge.alias.help', flags: [], positional: [], readOnly: false, needsRun: false, fallback: '/merge', deprecatedAt: '0.31' };
+const pos = (name, kind, required = true) => ({ name, kind, required });
+const flag = (name, kind, valueName, required = false) => ({ name, kind, ...(valueName === undefined ? {} : { valueName }), ...(required ? { required: true } : {}) });
+const action = (id, command, confirm = false) => ({ id, command, confirm });
+const cmd = (id, words, flags, positional, readOnly, needsRun, rowActions, fallback) => ({ id, words, summaryKey: id, helpKey: id + '.help', flags, positional, readOnly, needsRun, rowActions, fallback });
+export const MERGE_COMMAND_DEFS = [
+    ({ ...({ ...cmd('merge.doctor', ['doctor'], [], [], false, false, [], '/evolution merge doctor'), usage: false }), surface: false }),
+    ({ ...cmd('merge.reconcile', ['reconcile'], [], [], false, false, [], '/evolution merge reconcile'), surface: false }),
+    cmd('merge.scan', ['scan'], [], [], false, true, [], '/evolution merge scan'),
+    cmd('merge.pair', ['pair'], [], [pos('a', 'skill'), pos('b', 'skill')], false, true, [action('pair', '/evolution merge pair {a} {b}', true)], '/evolution merge pair <a> <b>'),
+    cmd('merge.pair.force', ['pair'], [flag('force', 'boolean')], [pos('a', 'skill'), pos('b', 'skill')], false, true, [action('pair', '/evolution merge pair {a} {b}', true)], '/evolution merge pair --force <a> <b>'),
+    cmd('merge.status', ['status'], [], [pos('id', 'id', false)], true, false, [action('status', '/evolution merge status {runId}')], '/evolution merge status'),
+    cmd('merge.report', ['report'], [], [pos('id', 'id', false)], true, false, [action('report', '/evolution merge report {runId}')], '/evolution merge report'),
+    cmd('merge.cancel', ['cancel'], [], [pos('id', 'id', false)], false, false, [action('cancel', '/evolution merge cancel {runId}')], '/evolution merge cancel <id>'),
+    cmd('merge.runs', ['runs'], [], [], true, false, [], '/evolution merge runs'),
+    cmd('merge.pending', ['pending'], [], [], true, false, [], '/evolution merge pending'),
+    cmd('merge.pending.expired', ['pending'], [flag('expired', 'boolean')], [], true, false, [], '/evolution merge pending --expired'),
+    cmd('merge.approve', ['approve'], [], [pos('id', 'id')], false, true, [action('approve', '/evolution merge approve {id}')], '/evolution merge approve <id>'),
+    cmd('merge.reject', ['reject'], [], [pos('id', 'id')], false, false, [action('reject', '/evolution merge reject {id}', true)], '/evolution merge reject <id>'),
+    cmd('merge.skipped', ['skipped'], [], [], true, false, [], '/evolution merge skipped'),
+    cmd('merge.skipped.restore', ['skipped'], [flag('restore', 'value', 'id')], [], false, false, [action('restore', '/evolution merge skipped --restore {id}', true)], '/evolution merge skipped --restore <id>'),
+    cmd('merge.candidates', ['candidates'], [], [], true, false, [], '/evolution merge candidates'),
+    cmd('merge.candidates.retry', ['candidates'], [flag('retry', 'boolean')], [pos('id', 'id', false)], false, true, [action('retry-candidates', '/evolution merge candidates --retry {id}')], '/evolution merge candidates --retry <id>'),
+    cmd('merge.resume', ['resume'], [flag('clear', 'value', 'id')], [pos('id', 'id', false)], true, false, [action('retry-resume', '/evolution merge resume --retry {id}')], '/evolution merge resume'),
+    cmd('merge.resume.retry', ['resume'], [flag('retry', 'boolean'), flag('clear', 'value', 'id')], [pos('id', 'id', false)], false, true, [action('retry-resume', '/evolution merge resume --retry {id}')], '/evolution merge resume --retry <id>'),
+    cmd('merge.discard', ['discard'], [], [pos('id', 'id')], false, false, [action('discard', '/evolution merge discard {id}', true)], '/evolution merge discard <id>'),
+    cmd('merge.undo', ['undo'], [flag('run', 'value', 'id', true)], [pos('target', 'target')], false, false, [], '/evolution merge undo <target> --run <id>'),
+];
+//# sourceMappingURL=command-defs.js.map

package/lib/types/command-surface.d.ts

@@ -0,0 +1,5 @@
+/** Generated merge CommandSurface from command-defs; no handwritten table. */
+import type { CommandSpec, CommandSurface } from './wire.ts';
+export declare const MERGE_COMMANDS: readonly CommandSpec[];
+export declare const MERGE_COMMAND_SURFACE: CommandSurface;
+//# sourceMappingURL=command-surface.d.ts.map

package/lib/types/command-surface.js

@@ -0,0 +1,11 @@
+import { buildSurface } from '@lmzhen/dsh-evolution-commands';
+import { MERGE_COMMAND_DEFS } from "./command-defs.js";
+const generated = buildSurface(MERGE_COMMAND_DEFS, '/evolution merge');
+export const MERGE_COMMANDS = generated.commands.map(command => ({
+    id: command.id, words: command.words, flags: command.flags, positional: command.positional,
+    summary: command.id, readOnly: command.readOnly, needsRun: command.needsRun, defaults: command.defaults,
+    rowActions: command.rowActions.map(action => ({ id: action.id, command: action.command, confirm: action.confirm })),
+    fallback: command.fallback,
+}));
+export const MERGE_COMMAND_SURFACE = { wireVersion: 1, prefix: '/evolution merge', commands: MERGE_COMMANDS, fallback: generated.fallback.map(item => ({ id: item.id, command: item.command })) };
+//# sourceMappingURL=command-surface.js.map

package/lib/types/commands.d.ts

@@ -1,7 +1,3 @@
-/**
- * Pure command-surface parser for the /evolution merge prefix. The command layer only
- * validates shape; run/state effects are injected by the host shell.
- */
 export type MergeCliCommand = {
     readonly verb: 'scan';
 } | {
@@ -22,12 +18,15 @@ export type MergeCliCommand = {
     readonly verb: 'runs';
 } | {
     readonly verb: 'doctor';
+} | {
+    readonly verb: 'reconcile';
 } | {
     readonly verb: 'pending';
     readonly expired?: true;
 } | {
     readonly verb: 'candidates';
     readonly retry?: true;
+    readonly id?: string;
 } | {
     readonly verb: 'approve';
     readonly id: string;

package/lib/types/commands.js

@@ -1,79 +1,40 @@
-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>\ndefaults: mergeApproval=false, mergeSkippedTtlDays=0, mergeRunTimeoutMinutes=0, mergePairTimeoutMinutes=15, mergeModelsRoot=""';
-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('--')));
-}
+/** Merge command adapter over the family command catalog. No parser/usage table here. */
+import { parseCommand } from '@lmzhen/dsh-evolution-commands';
+import { MERGE_COMMAND_DEFS } from "./command-defs.js";
+function text(value) { return typeof value === 'string' ? value : undefined; }
 export function parseMergeCommand(argv) {
-    const [verb, ...rest] = argv;
-    if (verb === undefined || verb === 'help' || verb === '--help' || verb === '-h')
+    const parsed = parseCommand(MERGE_COMMAND_DEFS, argv);
+    if (!parsed.ok)
+        return parsed;
+    if (parsed.help === true)
         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 };
+    const v = parsed.values;
+    switch (parsed.id) {
+        case 'merge.scan': return { ok: true, command: { verb: 'scan' } };
+        case 'merge.doctor': return { ok: true, command: { verb: 'doctor' } };
+        case 'merge.reconcile': return { ok: true, command: { verb: 'reconcile' } };
+        case 'merge.pair': return { ok: true, command: { verb: 'pair', a: text(v.a) ?? '', b: text(v.b) ?? '' } };
+        case 'merge.pair.force': return { ok: true, command: { verb: 'pair', a: text(v.a) ?? '', b: text(v.b) ?? '', force: true } };
+        case 'merge.status': return { ok: true, command: { verb: 'status', ...(text(v.id) === undefined ? {} : { id: text(v.id) }) } };
+        case 'merge.report': return { ok: true, command: { verb: 'report', ...(text(v.id) === undefined ? {} : { id: text(v.id) }) } };
+        case 'merge.cancel': return { ok: true, command: { verb: 'cancel', ...(text(v.id) === undefined ? {} : { id: text(v.id) }) } };
+        case 'merge.runs': return { ok: true, command: { verb: 'runs' } };
+        case 'merge.pending': return { ok: true, command: { verb: 'pending' } };
+        case 'merge.pending.expired': return { ok: true, command: { verb: 'pending', expired: true } };
+        case 'merge.approve': return { ok: true, command: { verb: 'approve', id: text(v.id) ?? '' } };
+        case 'merge.reject': return { ok: true, command: { verb: 'reject', id: text(v.id) ?? '' } };
+        case 'merge.skipped': return { ok: true, command: { verb: 'skipped' } };
+        case 'merge.skipped.restore': return { ok: true, command: { verb: 'skipped', restore: text(v.restore) ?? '' } };
+        case 'merge.candidates': return { ok: true, command: { verb: 'candidates' } };
+        case 'merge.candidates.retry': return { ok: true, command: { verb: 'candidates', retry: true, ...(text(v.id) === undefined ? {} : { id: text(v.id) }) } };
+        case 'merge.resume': return { ok: true, command: { verb: 'resume', ...(text(v.id) === undefined ? {} : { id: text(v.id) }), ...(text(v.clear) === undefined ? {} : { clear: text(v.clear) }) } };
+        case 'merge.resume.retry': return { ok: true, command: { verb: 'resume', retry: true, ...(text(v.id) === undefined ? {} : { id: text(v.id) }), ...(text(v.clear) === undefined ? {} : { clear: text(v.clear) }) } };
+        case 'merge.discard': return { ok: true, command: { verb: 'discard', id: text(v.id) ?? '' } };
+        case 'merge.undo': return { ok: true, command: { verb: 'undo', target: text(v.target) ?? '', run: text(v.run) ?? '' } };
+        default: return { ok: false, code: 'usage', message: 'unknown merge command: ' + parsed.id };
     }
 }
 export function mergeUsage() {
-    return USAGE;
+    return 'usage: ' + MERGE_COMMAND_DEFS.filter(def => def.id !== 'merge.doctor' && def.usage !== false).map(def => def.fallback).join(' | ') + '\ndefaults: mergeApproval=false, mergeSkippedTtlDays=0, mergeRunTimeoutMinutes=0, mergePairTimeoutMinutes=15, mergeModelsRoot=""';
 }
 //# sourceMappingURL=commands.js.map

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

@@ -3,24 +3,39 @@
  *
  * Source bodies come from the LIVE tree (the plan's CAS baseline), the target body from
  * the merged tree. This function is pure except for the injected reads; it never commits.
+ * It also re-checks the round-1 decision anchors against the live tree BEFORE the commit
+ * port is called, so a source/target change is refused with a typed cause rather than a
+ * generic commit message.
  */
-import type { CommitMergePlan, WriteOrigin } from '@lmzhen/dsh-evolution-core';
+import type { CommitMergePlan, WriteOrigin, SkillLimits } from '@lmzhen/dsh-evolution-core';
+import { type RevisionFile } from '@lmzhen/dsh-evolution-core';
 import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { RevisionRef } from './contracts.ts';
 export interface CommitAssemblyPort {
     /** Current SKILL.md body, or null when the skill is not live. */
     readSkill(name: string): Promise<string | null>;
+    /** Every support file of a live skill; absent means the port cannot enumerate them. */
+    readSupportFiles?(name: string): Promise<readonly RevisionFile[]>;
     /** Whether the name is already occupied by an archived (tombstoned) skill. */
     isArchived?(name: string): Promise<boolean>;
+    /** Whether a directory exists for the name (including a SKILL.md-less ghost). */
+    isNameOccupied?(name: string): Promise<boolean>;
 }
 export interface CommitAssemblyOptions {
     readonly origin: WriteOrigin;
     readonly summary: string;
+    readonly limits?: SkillLimits;
+    /** Round-1 decision anchors re-checked here (the store repeats the check under its lock). */
+    readonly targetRevision?: RevisionRef;
+    readonly sourceRevisions?: Readonly<Record<string, RevisionRef>>;
+    readonly supportDigest?: string;
 }
 export type CommitAssemblyResult = {
     readonly ok: true;
     readonly plan: CommitMergePlan;
 } | {
     readonly ok: false;
+    readonly code?: 'target-changed' | 'source-changed' | 'support-changed';
     readonly message: string;
 };
 export declare function assembleStagedCommit(io: EvolutionIoLike, home: string, runId: string, port: CommitAssemblyPort, options: CommitAssemblyOptions): Promise<CommitAssemblyResult>;

package/lib/types/commit-assembly.js

@@ -1,7 +1,55 @@
-import { isPresent } from '@lmzhen/dsh-evolution-core';
+import { isPresent, revisionAnchorOf, revisionFingerprint, revisionSupportDigest } from '@lmzhen/dsh-evolution-core';
 import { readStaging } from "./staging.js";
 import { readStagedTree } from "./staged-tree.js";
 import { buildCommitPlan } from "./commit-plan.js";
+function sameAnchor(expected, live) {
+    if (expected.kind === 'absent')
+        return live.kind === 'absent';
+    return live.kind === 'present' && expected.sha256 === live.sha256;
+}
+async function liveRevision(port, name, body) {
+    if (port.readSupportFiles === undefined)
+        return { verified: false };
+    let files;
+    try {
+        files = body === null ? [] : await port.readSupportFiles(name);
+    }
+    catch {
+        return { verified: false };
+    }
+    return { verified: true, anchor: revisionAnchorOf(name, body, files), fingerprint: body === null ? null : revisionFingerprint(name, body, files) };
+}
+/** Why the staging tree no longer matches the decision, or null when it still does. */
+async function decisionRevisionFailure(port, requested, targetCurrent, sources, options) {
+    if (options.targetRevision === undefined && options.sourceRevisions === undefined && options.supportDigest === undefined)
+        return null;
+    const target = await liveRevision(port, requested, targetCurrent);
+    if (!target.verified)
+        return null;
+    if (options.targetRevision !== undefined && !sameAnchor(options.targetRevision, target.anchor)) {
+        return { code: 'target-changed', message: '目标技能「' + requested + '」的内容在决策之后被改过；拒绝提交（未写入任何内容）。' };
+    }
+    const fingerprints = target.fingerprint === null ? [] : [target.fingerprint];
+    for (const source of sources) {
+        // The staging manifest lists the target among its sources; the digest is over the
+        // participating skills (target + absorbed sources), so the target appears once.
+        if (source.name === requested)
+            continue;
+        const live = await liveRevision(port, source.name, source.body);
+        if (!live.verified)
+            continue;
+        const expected = options.sourceRevisions?.[source.name];
+        if (expected !== undefined && !sameAnchor(expected, live.anchor)) {
+            return { code: 'source-changed', message: '来源技能「' + source.name + '」的内容在决策之后被改过；拒绝提交（未写入任何内容）。' };
+        }
+        if (live.fingerprint !== null)
+            fingerprints.push(live.fingerprint);
+    }
+    if (options.supportDigest !== undefined && revisionSupportDigest(fingerprints) !== options.supportDigest) {
+        return { code: 'support-changed', message: '参与合并的技能支撑文件在决策之后被改过；拒绝提交（未写入任何内容）。' };
+    }
+    return null;
+}
 export async function assembleStagedCommit(io, home, runId, port, options) {
     const staging = await readStaging(io, home, runId);
     if (!isPresent(staging))
@@ -10,15 +58,31 @@ export async function assembleStagedCommit(io, home, runId, port, options) {
     if (!isPresent(tree))
         return { ok: false, message: 'merged tree is not readable for run ' + runId };
     const requested = staging.value.manifest.target;
+    const requestedCurrent = await port.readSkill(requested);
     let target = requested;
-    let targetCurrent = await port.readSkill(requested);
+    let targetCurrent = requestedCurrent;
+    if (staging.value.manifest.mode !== 'create-umbrella' && targetCurrent === null) {
+        return { ok: false, message: 'target is gone; refusing to re-create it: ' + 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 });
+    }
+    const revisionFailure = await decisionRevisionFailure(port, requested, requestedCurrent, sources, options);
+    if (revisionFailure !== null)
+        return { ok: false, code: revisionFailure.code, message: revisionFailure.message };
     const requestedArchived = targetCurrent === null && await port.isArchived?.(requested) === true;
-    if (staging.value.manifest.mode === 'create-umbrella' && (targetCurrent !== null || requestedArchived)) {
+    const requestedOccupied = targetCurrent === null && await port.isNameOccupied?.(requested) === true;
+    if (staging.value.manifest.mode === 'create-umbrella' && (targetCurrent !== null || requestedArchived || requestedOccupied)) {
         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) {
+                && await port.isArchived?.(candidate) !== true
+                && await port.isNameOccupied?.(candidate) !== true) {
                 target = candidate;
                 targetCurrent = null;
                 break;
@@ -27,13 +91,6 @@ export async function assembleStagedCommit(io, home, runId, port, options) {
         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,
@@ -43,6 +100,10 @@ export async function assembleStagedCommit(io, home, runId, port, options) {
         sourceBodies: sources,
         origin: options.origin,
         summary: options.summary,
+        ...(options.limits === undefined ? {} : { limits: options.limits }),
+        ...(options.targetRevision === undefined ? {} : { targetRevision: options.targetRevision }),
+        ...(options.sourceRevisions === undefined ? {} : { sourceRevisions: options.sourceRevisions }),
+        ...(options.supportDigest === undefined ? {} : { supportDigest: options.supportDigest }),
     });
 }
 //# sourceMappingURL=commit-assembly.js.map

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

@@ -3,11 +3,14 @@
  * receipt. A failed commit returns without a receipt; a landed commit with a failed receipt
  * stays successful and carries a warning.
  */
-import type { CommitMergePlan, CommitMergeResult, EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { CommitMergePlan, CommitMergeResult, EvolutionIoLike, SkillLimits } from '@lmzhen/dsh-evolution-core';
 import { type CommitAssemblyPort } from './commit-assembly.ts';
 import { type CommitReceipt } from './commit-receipt.ts';
+import type { UnitTransaction } from '@lmzhen/dsh-evolution-core';
 export interface CommitPort extends CommitAssemblyPort {
-    commitMerge(plan: CommitMergePlan): Promise<CommitMergeResult>;
+    /** Transitional G2: when set, commit-execute prefers this over commitMerge. */
+    unit?: UnitTransaction;
+    commitMerge?(plan: CommitMergePlan): Promise<CommitMergeResult>;
     readSupportFiles?(name: string): Promise<readonly {
         readonly path: string;
         readonly content: string;
@@ -17,6 +20,14 @@ export interface CommitStagedOptions {
     readonly origin: CommitMergePlan['origin'];
     readonly summary: string;
     readonly now: () => number;
+    readonly isBlocked?: (name: string) => boolean | Promise<boolean>;
+    readonly limits?: SkillLimits;
+    readonly validationPlan?: import('./contracts.ts').MergeValidationPlanRef;
+    readonly targetRevision?: import('./contracts.ts').RevisionRef;
+    readonly sourceRevisions?: Readonly<Record<string, import('./contracts.ts').RevisionRef>>;
+    readonly supportDigest?: string;
+    /** G2 transitional: when present, commit through core UnitTransaction. */
+    readonly unit?: UnitTransaction;
 }
 export type CommitStagedResult = {
     readonly ok: true;
@@ -28,6 +39,7 @@ export type CommitStagedResult = {
     readonly ok: false;
     readonly message: string;
     readonly plan?: CommitMergePlan;
+    readonly code?: CommitMergeResult['code'];
 };
 export declare function commitStagedRun(io: EvolutionIoLike, home: string, runId: string, port: CommitPort, options: CommitStagedOptions): Promise<CommitStagedResult>;
 //# sourceMappingURL=commit-execute.d.ts.map

package/lib/types/commit-execute.js

@@ -2,23 +2,59 @@ 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";
-import { snapshotPath, writeCommitSnapshot } from "./commit-snapshot.js";
+import { evidenceSha256 as digestEvidence } from "./domain/evidence-hash.js";
+import { snapshotPath } from "./commit-snapshot.js";
 export async function commitStagedRun(io, home, runId, port, options) {
-    const assembled = await assembleStagedCommit(io, home, runId, port, { origin: options.origin, summary: options.summary });
+    const assembled = await assembleStagedCommit(io, home, runId, port, {
+        origin: options.origin,
+        summary: options.summary,
+        ...(options.limits === undefined ? {} : { limits: options.limits }),
+        ...(options.targetRevision === undefined ? {} : { targetRevision: options.targetRevision }),
+        ...(options.sourceRevisions === undefined ? {} : { sourceRevisions: options.sourceRevisions }),
+        ...(options.supportDigest === undefined ? {} : { supportDigest: options.supportDigest }),
+    });
     if (!assembled.ok)
-        return { ok: false, message: assembled.message };
-    try {
-        await writeCommitSnapshot(io, home, runId, assembled.plan, options.now(), port);
-    }
-    catch (error) {
-        return { ok: false, message: 'commit snapshot failed; refusing to write: ' + (error instanceof Error ? error.message : String(error)), plan: assembled.plan };
+        return { ok: false, message: assembled.message, ...(assembled.code === undefined ? {} : { code: assembled.code }) };
+    if (await options.isBlocked?.(assembled.plan.target) === true) {
+        return { ok: false, message: 'target is blocked by curator: ' + assembled.plan.target, plan: assembled.plan };
     }
-    const journal = { runId, target: assembled.plan.target, create: !assembled.plan.targetExists, sources: assembled.plan.sources, phase: 'sources-archived', updatedAt: new Date(options.now()).toISOString() };
-    try {
-        await writeJournal(io, home, journal);
+    const journal = { runId, target: assembled.plan.target, create: !assembled.plan.targetExists, sources: assembled.plan.sources, phase: 'prepared', updatedAt: new Date(options.now()).toISOString() };
+    let result;
+    let evidenceSha256;
+    const transaction = options.unit ?? port.unit ?? legacyUnitAdapter(port, assembled.plan, options, runId);
+    if (transaction === undefined)
+        return { ok: false, message: 'commit port missing: UnitTransaction or commitMerge required', plan: assembled.plan };
+    {
+        const first = assembled.plan.sources[0] ?? assembled.plan.target;
+        const unitPlan = { runId, pairKey: pairKey(assembled.plan.target, first), target: assembled.plan.target, targetExists: assembled.plan.targetExists, sources: assembled.plan.sources, body: assembled.plan.body, supportFiles: assembled.plan.supportFiles, expectedTargetBody: assembled.plan.expectedTargetBody, expectedSourceBodies: assembled.plan.expectedSourceBodies, origin: options.origin, summary: options.summary, ...(options.limits === undefined ? {} : { skillLimits: options.limits }), ...(options.validationPlan === undefined ? {} : { validationPlan: options.validationPlan }), ...(options.targetRevision === undefined ? {} : { targetRevision: options.targetRevision }), ...(options.sourceRevisions === undefined ? {} : { sourceRevisions: options.sourceRevisions }), ...(options.supportDigest === undefined ? {} : { supportDigest: options.supportDigest }) };
+        try {
+            await writeJournal(io, home, journal);
+        }
+        catch { /* compat mirror; unit journal is authority */ }
+        const prepared = await transaction.prepare(unitPlan);
+        if (!prepared.ok)
+            return { ok: false, message: prepared.message, plan: assembled.plan };
+        const committed = await transaction.commit(prepared.prepared);
+        if (!committed.ok) {
+            try {
+                await writeJournal(io, home, { ...journal, phase: 'failed', updatedAt: new Date(options.now()).toISOString() });
+            }
+            catch { }
+            ;
+            return { ok: false, message: committed.message, plan: assembled.plan, ...(committed.code === 'target-changed' || committed.code === 'source-changed' || committed.code === 'support-changed' ? { code: committed.code } : {}) };
+        }
+        const unitId = committed.evidence.unitId;
+        if (committed.evidence.unitId !== prepared.prepared.unitId && !prepared.prepared.unitId.startsWith('legacy:'))
+            return { ok: false, message: 'unit evidence does not match prepared unitId', plan: assembled.plan };
+        const finalize = transaction.finalize;
+        if (finalize !== undefined) {
+            const finalized = await finalize.call(transaction, unitId);
+            if (!finalized.ok)
+                return { ok: false, message: 'unit committed but finalize failed: ' + finalized.message, plan: assembled.plan };
+        }
+        evidenceSha256 = digestEvidence(committed.evidence);
+        result = { ok: true, message: 'merged', unitId, archived: committed.evidence.sources.filter(source => source.archived).map(source => source.name), mutations: committed.evidence.mutations };
     }
-    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() });
@@ -26,7 +62,7 @@ export async function commitStagedRun(io, home, runId, port, options) {
         catch { }
         return { ok: false, message: result.message, plan: assembled.plan };
     }
-    const committed = { ...journal, phase: 'committed', updatedAt: new Date(options.now()).toISOString() };
+    const committed = { ...journal, phase: 'committed', updatedAt: new Date(options.now()).toISOString(), ...(result.unitId === undefined ? {} : { unitId: result.unitId }) };
     try {
         await writeJournal(io, home, committed);
     }
@@ -35,6 +71,8 @@ export async function commitStagedRun(io, home, runId, port, options) {
         return { ok: true, plan: assembled.plan, result, warning: 'commit landed without a unitId; receipt not written' };
     const receipt = {
         runId,
+        ...(evidenceSha256 === undefined ? {} : { evidenceSha256 }),
+        ...(options.validationPlan === undefined ? {} : { validationPlan: options.validationPlan }),
         parentRunId: runId.split('/pairs/')[0] ?? runId,
         unitId: result.unitId,
         target: assembled.plan.target,
@@ -61,4 +99,28 @@ export async function commitStagedRun(io, home, runId, port, options) {
         };
     }
 }
+function legacyUnitAdapter(port, plan, options, runId) {
+    if (port.commitMerge === undefined)
+        return undefined;
+    let evidence;
+    const unitId = 'legacy:' + plan.target + ':' + String(options.now());
+    return {
+        async prepare() { return { ok: true, prepared: { unitId, planDigest: unitId } }; },
+        async commit() {
+            if (port.commitMerge === undefined)
+                return { ok: false, code: 'unit-commit-failed', message: 'commitMerge missing' };
+            const result = await port.commitMerge(plan);
+            if (!result.ok)
+                return { ok: false, code: result.code ?? 'unit-commit-failed', message: result.message };
+            const actualUnitId = result.unitId ?? unitId;
+            evidence = { schemaVersion: 1, unitId: actualUnitId, runId, planDigest: actualUnitId, state: 'complete', target: { before: plan.expectedTargetBody, after: plan.body, supportDigest: '', created: !plan.targetExists }, sources: plan.expectedSourceBodies.map(source => ({ name: source.name, before: source.body, after: null, archived: (result.archived ?? []).includes(source.name), absorbedInto: plan.target })), mutations: result.mutations ?? 0, at: options.now() };
+            return { ok: true, evidence };
+        },
+        async verify() { return evidence ?? null; },
+        async rollback() { return { ok: false, code: 'unit-committed', message: 'legacy commit cannot roll back' }; },
+        async finalize() { return evidence === undefined ? { ok: false, code: 'unit-plan-missing', message: 'legacy unit has no evidence' } : { ok: true, evidence }; },
+        async rollForward() { return evidence === undefined ? { ok: false, code: 'unit-plan-missing', message: 'legacy unit has no evidence' } : { ok: true, evidence }; },
+        async cancel() { return { ok: false, phase: 'none' }; },
+    };
+}
 //# sourceMappingURL=commit-execute.js.map

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

@@ -5,7 +5,8 @@
  * This module only turns those bytes into a CommitMergePlan; it never reads the live tree and
  * never decides whether a merge is allowed (validateStagedTree does that).
  */
-import type { CommitMergePlan, WriteOrigin } from '@lmzhen/dsh-evolution-core';
+import type { CommitMergePlan, WriteOrigin, SkillLimits } from '@lmzhen/dsh-evolution-core';
+import type { RevisionRef } from './contracts.ts';
 export type ResolveTargetResult = {
     readonly ok: true;
     readonly name: string;
@@ -33,6 +34,11 @@ export interface BuildCommitPlanInput {
     }[];
     readonly origin: WriteOrigin;
     readonly summary: string;
+    readonly limits?: SkillLimits;
+    /** Round-1 anchors; carried on the plan so every committer (unit or legacy port) re-checks them. */
+    readonly targetRevision?: RevisionRef;
+    readonly sourceRevisions?: Readonly<Record<string, RevisionRef>>;
+    readonly supportDigest?: string;
 }
 export type BuildCommitPlanResult = {
     readonly ok: true;

package/lib/types/commit-plan.js

@@ -48,8 +48,12 @@ export function buildCommitPlan(input) {
             supportFiles: input.mergedFiles,
             expectedTargetBody: input.targetCurrent,
             expectedSourceBodies: sources,
+            ...(input.targetRevision === undefined ? {} : { targetRevision: input.targetRevision }),
+            ...(input.sourceRevisions === undefined ? {} : { sourceRevisions: input.sourceRevisions }),
+            ...(input.supportDigest === undefined ? {} : { supportDigest: input.supportDigest }),
             origin: input.origin,
             summary: input.summary,
+            ...(input.limits === undefined ? {} : { limits: input.limits }),
         },
     };
 }

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

@@ -1,8 +1,11 @@
 import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { MergeValidationPlanRef } from './contracts.ts';
 export interface CommitReceipt {
     readonly runId: string;
     readonly parentRunId?: string;
     readonly unitId: string;
+    readonly evidenceSha256?: string;
+    readonly validationPlan?: MergeValidationPlanRef;
     readonly target: string;
     readonly create: boolean;
     readonly sources: readonly string[];

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

@@ -2,9 +2,14 @@ import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 import type { CommitJournal } from './domain/commit-journal.ts';
 export interface CommitRecoveryReport {
     readonly runId: string;
-    readonly phase: CommitJournal['phase'];
+    readonly phase: CommitJournal['phase'] | 'unknown';
     readonly action: string;
     readonly ok: boolean;
+    readonly target?: string;
+    readonly sources?: readonly string[];
+    readonly journalPath?: string;
+    readonly snapshotPath?: string;
+    readonly unitId?: string;
 }
-export declare function recoverCommitJournals(io: EvolutionIoLike, home: string, now: number, skillRoot: string, restoreSource?: (name: string) => Promise<boolean>, isActive?: (runId: string) => boolean): Promise<readonly CommitRecoveryReport[]>;
+export declare function recoverCommitJournals(io: EvolutionIoLike, home: string, now: number, isActive?: (runId: string) => boolean): Promise<readonly CommitRecoveryReport[]>;
 //# sourceMappingURL=commit-recovery.d.ts.map