@lmzhen/dsh-evolution-merge 0.30.18 → 0.30.20

package/lib/types/merge-routes.js

@@ -1,6 +1,7 @@
 import { HOST_ROUTES, json, methodNotAllowed } from '@lmzhen/dsh-evolution-core/http-routes';
-import { buildFacts } from "./facts.js";
+import { buildFacts as buildLegacyFacts } from "./facts.js";
 import { toBodyView, toHistoryView, toQueuePage } from "./wire-projection.js";
+import { buildBodyView, buildFacts as buildSnapshotFacts, buildHistoryView, buildQueuePage } from "./surface/merge-view.js";
 const MERGE_PATHS = HOST_ROUTES.merge;
 const MERGE_BASE = MERGE_PATHS.view.slice(0, -'view'.length);
 export const MERGE_ROUTES = {
@@ -11,6 +12,13 @@ export const MERGE_ROUTES = {
 };
 export function makeMergeRoutes(deps, _audit) {
     const absent = () => json(404, { wireVersion: 1, code: 'E-325', message: 'merge service is not mounted' });
+    const blocked = (readiness) => json(503, { wireVersion: 1, code: 'merge-state-blocked', readiness });
+    const notReady = async (source) => {
+        if (source.readiness === undefined)
+            return null;
+        const readiness = await source.readiness();
+        return readiness.ok ? null : blocked(readiness);
+    };
     const bad = (message) => json(400, { wireVersion: 1, code: 'merge-bad-query', message });
     const get = (request) => (request.method === 'GET' ? null : methodNotAllowed(['GET']));
     const url = (request) => new URL(request.url, 'http://local');
@@ -26,10 +34,19 @@ export function makeMergeRoutes(deps, _audit) {
                 const source = deps.getSource();
                 if (source === undefined)
                     return absent();
+                if (source.snapshot !== undefined) {
+                    const snapshot = await source.snapshot();
+                    if (snapshot.blocked !== undefined)
+                        return json(503, { wireVersion: 1, code: 'merge-state-blocked', readiness: snapshot.blocked.readiness });
+                    return json(200, buildSnapshotFacts(snapshot));
+                }
+                const readiness = await notReady(source);
+                if (readiness !== null)
+                    return readiness;
                 const readAt = Date.now();
-                const rows = await source.rows();
-                const runs = await source.runs(undefined, 20);
-                return json(200, buildFacts({ rows, runs, approval: source.approval?.() === true, readAt }));
+                const rows = await source.rows?.() ?? [];
+                const runs = await source.runs?.(undefined, 20) ?? [];
+                return json(200, buildLegacyFacts({ rows, runs, approval: source.approval?.() === true, readAt }));
             },
         },
         {
@@ -51,8 +68,22 @@ export function makeMergeRoutes(deps, _audit) {
                 if (expiredOnly && queue !== 'pending')
                     return bad('expired is only allowed for pending');
                 const limit = Number.parseInt(query.get('limit') ?? '50', 10);
+                if (source.snapshot !== undefined) {
+                    const snapshot = await source.snapshot();
+                    if (snapshot.blocked !== undefined)
+                        return json(503, { wireVersion: 1, code: 'merge-state-blocked', readiness: snapshot.blocked.readiness });
+                    try {
+                        return json(200, buildQueuePage(snapshot, queue, expiredOnly, query.get('cursor') ?? undefined, Number.isFinite(limit) ? limit : 50));
+                    }
+                    catch (error) {
+                        return bad(error instanceof Error ? error.message : 'queue cursor is stale');
+                    }
+                }
+                const readiness = await notReady(source);
+                if (readiness !== null)
+                    return readiness;
                 const offset = Number.parseInt(query.get('cursor') ?? '0', 10);
-                const rows = await source.rows();
+                const rows = await source.rows?.() ?? [];
                 const page = toQueuePage(rows, queue, expiredOnly, Date.now(), Number.isFinite(limit) ? limit : 50);
                 return json(200, Number.isFinite(offset) && offset > 0 ? { ...page, rows: page.rows.slice(offset) } : page);
             },
@@ -70,10 +101,35 @@ export function makeMergeRoutes(deps, _audit) {
                     return absent();
                 const query = url(request).searchParams;
                 const id = query.get('id');
+                const name = query.get('name');
                 const side = query.get('side');
+                if (id !== null && name !== null)
+                    return bad('id and name are mutually exclusive');
+                if ((id === null || id === '') && (name === null || name === ''))
+                    return json(404, { wireVersion: 1, code: 'merge-body-not-found', message: 'merge body requires id or name' });
+                if (source.snapshot !== undefined) {
+                    const snapshot = await source.snapshot();
+                    if (snapshot.blocked !== undefined)
+                        return json(503, { wireVersion: 1, code: 'merge-state-blocked', readiness: snapshot.blocked.readiness });
+                    const refs = id !== null && id !== '' ? snapshot.bodyRefs.filter(ref => ref.rowId === id) : snapshot.bodyRefs.filter(ref => ref.name === name);
+                    if (refs.length === 0)
+                        return json(404, { wireVersion: 1, code: 'merge-body-not-found', message: 'merge body not found' });
+                    if (name !== null && refs.length > 1)
+                        return bad('name matches multiple merge rows');
+                    const row = snapshot.rows.find(item => item.row.id === refs[0].rowId);
+                    if (row?.stage?.state === 'lost' || row?.stage?.state === 'expired')
+                        return json(404, { wireVersion: 1, code: 'merge-body-not-found', message: 'merge stage is lost' });
+                    const sideFilter = side === 'a' ? 'live' : side === 'b' ? 'archive' : side === 'live' || side === 'archive' ? side : undefined;
+                    const ref = (sideFilter === undefined ? refs[0] : refs.find(item => item.side === sideFilter)) ?? refs[0];
+                    const content = source.bodyRef === undefined ? null : await source.bodyRef(ref);
+                    return json(200, buildBodyView(snapshot, ref, content ?? ''));
+                }
+                const readiness = await notReady(source);
+                if (readiness !== null)
+                    return readiness;
                 if (id === null || id === '' || (side !== 'a' && side !== 'b'))
                     return bad('id and side=a|b are required');
-                const content = await source.body(id, side);
+                const content = await source.body?.(id, side) ?? null;
                 return content === null
                     ? json(200, { wireVersion: 1, code: 'merge-body-missing', message: 'merge body not found: ' + id })
                     : json(200, toBodyView(id, side === 'a' ? 'live' : 'archive', content, Date.now()));
@@ -90,7 +146,16 @@ export function makeMergeRoutes(deps, _audit) {
                 const source = deps.getSource();
                 if (source === undefined)
                     return absent();
-                return json(200, toHistoryView(await source.history(), Date.now()));
+                if (source.snapshot !== undefined) {
+                    const snapshot = await source.snapshot();
+                    if (snapshot.blocked !== undefined)
+                        return json(503, { wireVersion: 1, code: 'merge-state-blocked', readiness: snapshot.blocked.readiness });
+                    return json(200, buildHistoryView(snapshot));
+                }
+                const readiness = await notReady(source);
+                if (readiness !== null)
+                    return readiness;
+                return json(200, toHistoryView(await source.history?.() ?? [], Date.now()));
             },
         },
     ];

package/lib/types/merge-tool.d.ts

@@ -18,5 +18,5 @@ export interface ToolDefinitionLike {
     };
     readonly execute: (args: Record<string, unknown>, exec: unknown) => Promise<string>;
 }
-export declare function createMergeStageTool(io: EvolutionIoLike, home: string, context: (exec: unknown) => StageToolContext | undefined): ToolDefinitionLike;
+export declare function createMergeStageTool(io: EvolutionIoLike, home: string, context: (exec: unknown) => StageToolContext | undefined, diagnose?: (exec: unknown) => unknown): ToolDefinitionLike;
 //# sourceMappingURL=merge-tool.d.ts.map

package/lib/types/merge-tool.js

@@ -33,7 +33,7 @@ function operation(args) {
     }
     return shapeError('op must be list/read/write/copy');
 }
-export function createMergeStageTool(io, home, context) {
+export function createMergeStageTool(io, home, context, diagnose) {
     return {
         name: MERGE_STAGE_TOOL_NAME,
         description: 'Read source copies and write the merged skill into the staging tree. list/read use area=sources|merged plus source (for sources); write/copy paths are relative to merged/<target> (for example path=SKILL.md, from=SKILL.md, to=references/x.md). Write/copy are only allowed in the author phase.',
@@ -61,7 +61,7 @@ export function createMergeStageTool(io, home, context) {
                 return JSON.stringify(op);
             const ctx = context(exec);
             if (ctx === undefined)
-                return JSON.stringify({ ok: false, code: 'not-merge-child', message: 'merge_stage is only available to an active merge child' });
+                return JSON.stringify({ ok: false, code: 'not-merge-child', message: 'merge_stage is only available to an active merge child', ...(diagnose === undefined ? {} : { diagnostic: diagnose(exec) }) });
             return JSON.stringify(await applyStageTool(io, home, ctx, op));
         },
     };

package/lib/types/metrics.js

@@ -14,7 +14,7 @@ export function buildMergeMetrics(rows, runs, counters = {}) {
         samples.push({ name: 'merge_queue_depth', labels: { queue, kind: 'active' }, value: counts.active[queue] });
     samples.push({ name: 'merge_queue_depth', labels: { queue: 'pending', kind: 'expired' }, value: counts.expired });
     for (const run of runs) {
-        const state = run.mergeStatus ?? run.state;
+        const state = run.state;
         samples.push({ name: 'merge_run_total', labels: { state }, value: 1 });
         if (run.endedAt !== undefined)
             samples.push({ name: 'merge_run_duration_ms', labels: { state }, value: Math.max(0, run.endedAt - run.startedAt) });

package/lib/types/new-child-authoring.d.ts

@@ -25,7 +25,9 @@ export interface NewChildAuthoringOptions {
     readonly onChild?: (context: StageToolContext) => void;
     readonly onChildClosed?: (childId: string) => void;
     readonly unit?: UnitTransaction | undefined;
+    readonly limits?: import('@lmzhen/dsh-evolution-core').SkillLimits;
 }
 export declare function runNewChildAuthoring(options: NewChildAuthoringOptions, row: MergeRow, decision: MergeDecision, signal: AbortSignal): Promise<ScanRound2Outcome>;
+/** Bind the round-2 port to one run: approve/resume open a NEW child per run. */
 export declare function createNewChildRound2(options: Omit<NewChildAuthoringOptions, 'runId'>): (row: MergeRow, decision: MergeDecision, signal: AbortSignal, runId: string) => Promise<ScanRound2Outcome>;
 //# sourceMappingURL=new-child-authoring.d.ts.map

package/lib/types/new-child-authoring.js

@@ -1,10 +1,20 @@
 import { buildRound2Prompt, STANDBY_PROMPT } from "./prompts.js";
-import { createStaging, readStaging, setStagingTarget, stageKeyOf, stagingRoot } from "./staging.js";
+import { stageKeyOf, stagingRoot } from "./staging.js";
+import { createStageTree, readStageEntry, readStageTree, setStageTreeTarget, dropStage } from "./domain/stage-aggregate.js";
 import { pairKey } from "./contracts.js";
 import { readStagedTree } from "./staged-tree.js";
 import { validateStagedTree, hasBlockingFinding } from "./rules.js";
+import { DEFAULT_SKILL_LIMITS } from '@lmzhen/dsh-evolution-core';
+import { limitsSnapshotOf } from "./domain/merge-limits.js";
+import { buildValidationPlan } from "./domain/validation-plan.js";
 import { commitStagedRun } from "./commit-execute.js";
+import { manifestFilesOf, missingManifestFile, parseAuthoringManifest } from "./domain/authoring-manifest.js";
+import { MERGE_PROMPT_VERSION, promptHashOf } from "./prompts.js";
+/** Commit-side causes that mean "the world moved"; they must not be retried blindly. */
+const STALE_CAUSES = new Set(['target-changed', 'source-changed', 'support-changed', 'target-taken', 'target-gone']);
 export async function runNewChildAuthoring(options, row, decision, signal) {
+    if (decision.target.includes('/') || decision.target.includes(':'))
+        return { kind: 'failed', failure: { stage: 'author', code: 'target-invalid', message: 'target must be a bare skill name: ' + decision.target, retryable: false, retryFrom: 'none' } };
     const targetCard = options.cards.find(card => card.name === decision.target);
     const createMode = decision.mode === 'create-umbrella';
     if (!createMode && targetCard !== undefined) {
@@ -15,13 +25,24 @@ export async function runNewChildAuthoring(options, row, decision, signal) {
     }
     if (!createMode && await options.isBlocked?.(decision.target) === true)
         return { kind: 'failed', failure: { stage: 'author', code: 'target-blocked', message: 'target is blocked by curator: ' + decision.target, retryable: false, retryFrom: 'none' } };
+    const at = options.now();
+    // NFR-06: an expired stage is never reused and never re-presented. Drop its tree and
+    // index and author into a fresh one; the recorded decision anchors still guard the
+    // sources at commit, so re-staging cannot smuggle a stale merge through.
+    const stageEntry = await readStageEntry(options.io, options.home, row.id);
+    const expiredStage = stageEntry !== null && stageEntry.expiresAt <= at;
+    // The row's own staging ref wins; otherwise this run authors into its own stage key.
+    // The index entry is consulted for TTL only — switching the authoring key to it would
+    // break the approve flow, where the reserved entry and the run's tree are separate.
     const stageKey = row.stagingRef ?? stageKeyOf(options.runId, pairKey(row.a, row.b));
-    const existing = await readStaging(options.io, options.home, stageKey);
+    if (expiredStage && stageEntry !== null)
+        await dropStage(options.io, options.home, row.id, stageEntry.ref);
+    const existing = expiredStage ? { kind: 'absent' } : await readStageTree(options.io, options.home, stageKey);
     if (existing.kind === 'present') {
-        await setStagingTarget(options.io, options.home, stageKey, decision.target, decision.mode);
+        await setStageTreeTarget(options.io, options.home, stageKey, decision.target, decision.mode);
     }
     else {
-        const staging = await createStaging(options.io, options.home, {
+        const staging = await createStageTree(options.io, options.home, {
             runId: stageKey,
             target: decision.target,
             mode: decision.mode,
@@ -39,7 +60,7 @@ export async function runNewChildAuthoring(options, row, decision, signal) {
         parent: options.parent,
         label: 'merge-round2',
         promptText: STANDBY_PROMPT,
-        kind: 'maintainer',
+        kind: 'reviewer',
         allow: options.allow,
         cwd: stagingRoot(options.home, stageKey),
         timeoutMs: options.timeoutMs,
@@ -62,21 +83,46 @@ export async function runNewChildAuthoring(options, row, decision, signal) {
         const tree = await readStagedTree(options.io, options.home, stageKey);
         if (tree.kind !== 'present')
             return { kind: 'failed', failure: { stage: 'author', code: 'staging-missing', message: tree.kind === 'unknown' ? tree.reason : 'staged tree absent', retryable: true, retryFrom: 'agent2' } };
-        const findings = validateStagedTree(tree.value);
-        if (hasBlockingFinding(findings))
-            return { kind: 'failed', failure: { stage: 'validate', code: 'rule-gate', message: 'staged tree failed the rule gate', retryable: true, retryFrom: 'agent2' } };
+        const manifest = parseAuthoringManifest(turn.turn.text);
+        const stagedPaths = tree.value.files.map(file => file.path);
+        const manifestFiles = manifestFilesOf(manifest, stagedPaths);
+        const missing = missingManifestFile(manifestFiles, stagedPaths);
+        if (missing !== null)
+            return { kind: 'failed', failure: { stage: 'author', code: 'merge-manifest-missing', message: 'manifest file missing from staged tree: ' + missing, retryable: true, retryFrom: 'agent2' } };
+        const limitsSnapshot = limitsSnapshotOf(options.limits ?? DEFAULT_SKILL_LIMITS);
+        const validationPlan = buildValidationPlan({ tree: tree.value, target: decision.target, limits: limitsSnapshot, cards: options.cards, promptVersion: MERGE_PROMPT_VERSION, promptHash: promptHashOf(buildRound2Prompt(row, decision)), supportFiles: tree.value.files.map(file => ({ path: file.path, content: file.content, source: 'staged' })), manifestFiles, existingSupport: (options.cards.find(card => card.name === decision.target)?.files ?? []).map(file => file.path), supportSources: options.cards.flatMap(card => (card.files ?? []).map(file => ({ path: file.path, content: file.content, source: card.name }))) });
+        const findings = [...validateStagedTree(tree.value, limitsSnapshot.skillLimits), ...validationPlan.findings];
+        if (hasBlockingFinding(findings)) {
+            const lengths = { bodyBytes: Buffer.byteLength(tree.value.body, 'utf8'), fileBytes: tree.value.files.reduce((sum, file) => sum + Buffer.byteLength(file.content, 'utf8'), 0), totalBytes: Buffer.byteLength(tree.value.body, 'utf8') + tree.value.files.reduce((sum, file) => sum + Buffer.byteLength(file.content, 'utf8'), 0) };
+            // FR-EXEC-11/14: only a LIMIT finding is over-limit; every other blocking rule
+            // (manifest mismatch, support conflict, validation plan) is a validation block and
+            // must land in skipped, not bounce back to fuse as a retryable generic failure.
+            const limit = findings.find(finding => finding.rule === 'limit');
+            return limit === undefined
+                ? { kind: 'failed', failure: { stage: 'validate', code: 'merge-validation', message: 'staged tree failed the rule gate', retryable: false, retryFrom: 'none' } }
+                : { kind: 'failed', failure: { stage: 'validate', code: 'merge-over-limit', message: limit.message, retryable: false, retryFrom: 'none', lengths } };
+        }
         const commit = await commitStagedRun(options.io, options.home, stageKey, options.commitPort, {
             origin: 'foreground', summary: 'merge ' + row.a + ' + ' + row.b, now: options.now,
             ...(options.isBlocked === undefined ? {} : { isBlocked: options.isBlocked }),
             ...(options.unit === undefined ? {} : { unit: options.unit }),
+            ...(options.limits === undefined ? {} : { limits: options.limits }),
+            validationPlan: { planVersion: validationPlan.planVersion, stageDigest: validationPlan.stageDigest, revision: validationPlan.revision },
+            ...(decision.targetRevisionRef === undefined ? {} : { targetRevision: decision.targetRevisionRef }),
+            ...(decision.sourceRevisions === undefined ? {} : { sourceRevisions: decision.sourceRevisions }),
+            ...(decision.supportDigest === undefined ? {} : { supportDigest: decision.supportDigest }),
         });
-        if (!commit.ok)
-            return { kind: 'failed', failure: { stage: 'commit', code: 'commit-failed', message: commit.message, retryable: true, retryFrom: 'agent2' } };
+        if (!commit.ok) {
+            const code = commit.code ?? 'commit-failed';
+            return { kind: 'failed', failure: { stage: 'commit', code, message: commit.message, retryable: !STALE_CAUSES.has(code), retryFrom: STALE_CAUSES.has(code) ? 'none' : 'agent2' } };
+        }
         const receipt = commit.receipt;
+        const lengths = { bodyBytes: Buffer.byteLength(tree.value.body, 'utf8'), fileBytes: tree.value.files.reduce((sum, file) => sum + Buffer.byteLength(file.content, 'utf8'), 0), totalBytes: Buffer.byteLength(tree.value.body, 'utf8') + tree.value.files.reduce((sum, file) => sum + Buffer.byteLength(file.content, 'utf8'), 0) };
         return {
             kind: 'merged',
             ...(receipt?.unitId === undefined ? {} : { unitId: receipt.unitId }),
             archived: receipt?.archived ?? [],
+            lengths,
             target: { requested: decision.target, actual: commit.plan.target, created: receipt?.create ?? false },
         };
     }
@@ -88,6 +134,7 @@ export async function runNewChildAuthoring(options, row, decision, signal) {
         options.onChildClosed?.(opened.childId);
     }
 }
+/** Bind the round-2 port to one run: approve/resume open a NEW child per run. */
 export function createNewChildRound2(options) {
     return (row, decision, signal, runId) => runNewChildAuthoring({ ...options, runId }, row, decision, signal);
 }

package/lib/types/params.d.ts

@@ -1,13 +1,11 @@
-/**
- * Merge parameter resolution. E2/E3 values arrive as one JSON object; this is the only
- * validator. Invalid values throw loudly (no silent clamp), matching the screening contract.
- */
 export interface MergeParams {
     readonly mergeApproval: boolean;
     readonly mergeSkippedTtlDays: number;
     readonly mergeRunTimeoutMinutes: number;
     readonly mergePairTimeoutMinutes: number;
     readonly mergeModelsRoot: string;
+    readonly platformWrite?: boolean;
+    readonly limitsSnapshot?: import('./domain/merge-limits.ts').MergeLimitsSnapshot;
 }
 export declare const MERGE_PARAM_DEFAULTS: MergeParams;
 export declare function resolveMergeParams(input?: unknown): MergeParams;

package/lib/types/params.js

@@ -1,9 +1,15 @@
+/**
+ * Merge parameter resolution. E2/E3 values arrive as one JSON object; this is the only
+ * validator. Invalid values throw loudly (no silent clamp), matching the screening contract.
+ */
+import { resolveLimitsSnapshot } from "./domain/merge-limits.js";
 export const MERGE_PARAM_DEFAULTS = {
     mergeApproval: false,
     mergeSkippedTtlDays: 0,
     mergeRunTimeoutMinutes: 0,
     mergePairTimeoutMinutes: 15,
     mergeModelsRoot: '',
+    platformWrite: false,
 };
 const KEYS = new Set(Object.keys(MERGE_PARAM_DEFAULTS));
 function materialize(value) {
@@ -32,6 +38,13 @@ export function resolveMergeParams(input = {}) {
         mergeApproval: approval,
         mergeSkippedTtlDays: record.mergeSkippedTtlDays === undefined ? MERGE_PARAM_DEFAULTS.mergeSkippedTtlDays : nonNegative('mergeSkippedTtlDays', record.mergeSkippedTtlDays),
         mergeRunTimeoutMinutes: record.mergeRunTimeoutMinutes === undefined ? MERGE_PARAM_DEFAULTS.mergeRunTimeoutMinutes : nonNegative('mergeRunTimeoutMinutes', record.mergeRunTimeoutMinutes),
+        platformWrite: record.platformWrite === undefined ? (MERGE_PARAM_DEFAULTS.platformWrite ?? false) : (() => {
+            const value = materialize(record.platformWrite);
+            if (typeof value !== 'boolean')
+                throw new Error('platformWrite must be a boolean');
+            return value;
+        })(),
+        limitsSnapshot: resolveLimitsSnapshot(),
         mergeModelsRoot: record.mergeModelsRoot === undefined ? MERGE_PARAM_DEFAULTS.mergeModelsRoot : (() => {
             const value = materialize(record.mergeModelsRoot);
             if (typeof value !== 'string')

package/lib/types/pending-actions.d.ts

@@ -1,6 +1,6 @@
 /**
- * Pending approval actions. The row lookup and transition happen in one v3
- * transactRows transaction, so two clients approving the same row cannot both win.
+ * Pending approval actions. The row lookup and transition happen in one PairLedger transaction,
+ * so two clients approving the same row cannot both win.
  */
 import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 import type { MergeRow } from './contracts.ts';

package/lib/types/pending-actions.js

@@ -1,8 +1,8 @@
-import { v3ToLegacy } from "./domain/row-v3-bridge.js";
-import { transactRows } from "./state.js";
+import { v4ToLegacy } from "./domain/row-v4.js";
+import { pairLedger } from "./domain/pair-ledger.js";
 async function act(io, home, now, id, type) {
     void now;
-    return await transactRows(io, home, tx => {
+    return await pairLedger(io, home).transact(tx => {
         const row = tx.rows().find(item => item.id === id);
         if (row === undefined)
             return { ok: false, reason: 'not-found', message: 'pending row not found: ' + id };
@@ -16,7 +16,7 @@ async function act(io, home, now, id, type) {
             return { ok: false, reason: 'invalid', message: moved.message };
         if (moved.row === null)
             return { ok: false, reason: 'invalid', message: 'transition produced no row' };
-        return { ok: true, row: v3ToLegacy(moved.row) };
+        return { ok: true, row: v4ToLegacy(moved.row) };
     });
 }
 export async function approvePending(io, home, now, id) {

package/lib/types/prompts.d.ts

@@ -1,11 +1,9 @@
-/**
- * Round-1/round-2 prompt builders. B draft body, with only the file-tool ->
- * merge_stage substitution and the fresh-mode bridge sentence.
- */
 import type { MergeDecision, MergeRow } from './contracts.ts';
 import type { SkillCard } from './skill-card.ts';
 export declare const MERGE_PROMPT_VERSION = "merge-b/v1";
+export declare function promptHashOf(prompt: string): string;
 export declare const STANDBY_PROMPT = "You are a merge worker. Wait for instructions.";
+export declare function sourceBlock(card: SkillCard | undefined, label: string): string[];
 export declare function buildRound1Prompt(candidate: {
     readonly a: string;
     readonly b: string;

package/lib/types/prompts.js

@@ -1,7 +1,12 @@
+/**
+ * Round-1/round-2 prompt builders. B draft body, with only the file-tool ->
+ * merge_stage substitution and the fresh-mode bridge sentence.
+ */
+import { createHash } from 'node:crypto';
 export const MERGE_PROMPT_VERSION = 'merge-b/v1';
+export function promptHashOf(prompt) { return createHash('sha256').update(prompt).digest('hex'); }
 export const STANDBY_PROMPT = 'You are a merge worker. Wait for instructions.';
 function sourcePath(name) { return 'sources/' + name; }
-function mergedPath(target) { return 'merged/' + target; }
 function wireDecision(decision) {
     return {
         shouldMerge: decision.shouldMerge,
@@ -14,15 +19,18 @@ function wireDecision(decision) {
         b_summary: decision.bSummary,
     };
 }
+export function sourceBlock(card, label) {
+    if (card === undefined)
+        return ['### ' + label + '（missing）'];
+    return ['### ' + label + '（name=' + card.name + '）', 'SKILL.md:', '```', card.body, '```', ...(card.files ?? []).flatMap(file => ['#### ' + file.path, '```', file.content, '```'])];
+}
 export function buildRound1Prompt(candidate, cards) {
-    void cards;
     return [
         '你是技能合并决策 agent。第 1 轮只做判断，不要写文件、不要修改任何源目录。',
         '',
-        '在当前工作目录下用 merge_stage 的 list/read 完整阅读两个源技能：',
-        '- A: ' + sourcePath(candidate.a) + '（name=' + candidate.a + '）',
-        '- B: ' + sourcePath(candidate.b) + '（name=' + candidate.b + '）',
-        '包含 SKILL.md 与 references/templates/scripts 等支撑文件。',
+        '两个源技能的完整正文已内嵌在下方（不需要读文件；源路径 ' + sourcePath(candidate.a) + ' / ' + sourcePath(candidate.b) + ' 仅作标识）：',
+        ...sourceBlock(cards.find(card => card.name === candidate.a), 'A: ' + candidate.a),
+        ...sourceBlock(cards.find(card => card.name === candidate.b), 'B: ' + candidate.b),
         '',
         '判断规则：',
         '1) 两者是否语义等价/互补到值得合并，而不是词面相似；',
@@ -36,7 +44,7 @@ export function buildRound1Prompt(candidate, cards) {
 export function buildRound2Prompt(row, decision, mode = 'continue') {
     const decisionJson = JSON.stringify(wireDecision(decision));
     const head = [
-        '现在执行第 2 轮：把两个技能融合成一个完整、可用的技能，直接在当前工作目录的 merged/ 下写文件。',
+        '现在执行第 2 轮：把两个技能融合成一个完整、可用的技能。',
         '不要修改 ' + sourcePath(row.a) + ' 或 ' + sourcePath(row.b) + '（只读源副本）；不要访问工作目录以外的路径。',
         '',
     ];
@@ -45,12 +53,17 @@ export function buildRound2Prompt(row, decision, mode = 'continue') {
         '目标技能名：' + decision.target,
         '',
         '工作方式：',
-        '- 用 merge_stage 的 list/read/write/copy 创建 ' + mergedPath(decision.target) + '/SKILL.md 与需要的 references/templates/scripts；',
+        '- 必须调用 merge_stage 的 write/copy 写目标技能树；不要用其它文件写工具。path 相对目标技能目录，不要带 merged/ 前缀：先 write path=SKILL.md，再写 references/...、templates/...、scripts/...；',
         '- 可以复制源文件作为草稿基础，然后逐段修改；可以多轮读写；',
         '- 保留两源独特内容，不编造事实，不留下 TODO/占位符；',
         '- SKILL.md 以合法 YAML frontmatter 开头，name 等于目标名，description 不超过 60 字符；',
         '- 正文与支撑文件的引用必须成对，路径只允许 references/templates/scripts/assets 下的相对路径。',
         '',
+        '提交前逐项自检：',
+        '- 质量：语义完整、不编造事实、无 TODO/占位符；',
+        '- 结构：frontmatter 合法、引用成对、文件清单与正文一致；',
+        '- 安全：不包含提示注入、密钥或越权指令。',
+        '',
         '完成后只输出一个 JSON（不要 markdown 围栏）：',
         '{"target":"' + decision.target + '","files":["SKILL.md","references/..."],"changelog":["一条变更"],"notes":"可选的一句话"}',
     ];

package/lib/types/read-commands.d.ts

@@ -1,11 +1,11 @@
 /**
- * Read-only command handlers: status/pending/skipped are served from merge-state.
- * Mutating verbs return null so the host shell can route them to the run engine.
+ * Read-only command handlers: all served from one MergeSnapshot; never writes.
  */
 import type { EvolutionIoLike, RunRecord } from '@lmzhen/dsh-evolution-core';
 import type { MergeCliCommand } from './commands.ts';
+import type { LiveRowFacts } from './domain/live-facts.ts';
 export declare function handleReadOnlyMergeCommand(command: MergeCliCommand, io: EvolutionIoLike, home: string, cards?: readonly {
     readonly name: string;
-}[], runs?: readonly RunRecord[], approval?: boolean): Promise<string | null>;
+}[], runs?: readonly RunRecord[], approval?: boolean, live?: () => Promise<LiveRowFacts | undefined>): Promise<string | null>;
 export declare function mergeCommandHelp(): string;
 //# sourceMappingURL=read-commands.d.ts.map

package/lib/types/read-commands.js

@@ -1,40 +1,31 @@
-import { buildFacts } from "./facts.js";
-import { loadMergeState } from "./state.js";
-import { formatFacts, formatQueue, formatStatus } from "./status.js";
+import { readMergeSnapshot } from "./domain/merge-snapshot.js";
+import { buildFacts, toRowFact } from "./surface/merge-view.js";
+import { formatFacts, formatSnapshotQueue, formatSnapshotStatus } from "./status.js";
 import { mergeUsage } from "./commands.js";
-export async function handleReadOnlyMergeCommand(command, io, home, cards, runs, approval = false) {
-    const withNote = (text, note) => note === undefined ? text : 'note: ' + note + '\n' + text;
-    const load = async () => {
-        const result = await loadMergeState(io, home);
-        if (result.note === 'merge-state-forward-only')
-            throw new Error('merge-state-forward-only');
-        return result;
-    };
+export async function handleReadOnlyMergeCommand(command, io, home, cards, runs, approval = false, live) {
+    if (!['status', 'pending', 'candidates', 'skipped'].includes(command.verb))
+        return null;
+    const snapshot = await readMergeSnapshot({ io, home, runs: runs ?? [], approval, ...(live === undefined ? {} : { live }) });
+    if (snapshot.blocked !== undefined)
+        throw new Error(snapshot.blocked.code + ': ' + snapshot.blocked.message);
+    const rows = snapshot.rows.map(toRowFact);
     if (command.verb === 'status') {
-        const loaded = await load();
         if (command.id !== undefined) {
-            const row = loaded.state.rows.find(item => item.id === command.id);
-            return withNote(row === undefined ? 'merge row not found: ' + command.id : formatStatus([row]), loaded.note);
+            const row = rows.find(item => item.id === command.id);
+            return row === undefined ? 'merge row not found: ' + command.id : formatSnapshotStatus([row]);
         }
-        const facts = buildFacts({ rows: loaded.state.rows, runs: runs ?? [], approval, readAt: Date.now(), ...(loaded.note === undefined ? {} : { notes: [loaded.note] }) });
-        return withNote(formatFacts(facts), loaded.note);
+        return formatFacts(buildFacts(snapshot));
     }
     if (command.verb === 'pending') {
-        const loaded = await load();
-        const rows = command.expired === true ? loaded.state.rows.filter(row => row.expired !== undefined) : loaded.state.rows;
-        const live = cards === undefined ? rows : rows.filter(row => cards.some(card => card.name === row.a) && cards.some(card => card.name === row.b));
-        return withNote(command.expired === true ? formatStatus(live) : formatQueue(live, 'pending'), loaded.note);
+        const live = command.expired === true ? rows.filter(row => row.expired !== undefined) : rows.filter(row => row.queue === 'pending' && row.expired === undefined);
+        const filtered = cards === undefined ? live : live.filter(row => cards.some(card => card.name === row.a) && cards.some(card => card.name === row.b));
+        return command.expired === true ? formatSnapshotStatus(filtered) : formatSnapshotQueue(filtered, 'pending');
     }
     if (command.verb === 'candidates') {
-        const loaded = await load();
-        const rows = command.retry === true ? loaded.state.rows.filter(row => row.state === 'approved') : loaded.state.rows;
-        return withNote(formatQueue(rows, command.retry === true ? 'fuse' : 'verify'), loaded.note);
+        const queue = command.retry === true ? 'fuse' : 'verify';
+        return formatSnapshotQueue(rows.filter(row => row.queue === queue && (command.id === undefined || row.id === command.id)), queue);
     }
-    if (command.verb === 'skipped') {
-        const loaded = await load();
-        return withNote(formatQueue(loaded.state.rows, 'skipped'), loaded.note);
-    }
-    return null;
+    return formatSnapshotQueue(rows.filter(row => row.queue === 'skipped'), 'skipped');
 }
 export function mergeCommandHelp() {
     return mergeUsage();

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

@@ -0,0 +1,34 @@
+import type { EvolutionIoLike, UnitTransaction } from '@lmzhen/dsh-evolution-core';
+export type RecoveryBranch = 'A' | 'B' | 'C' | 'D';
+export interface RecoveryReport {
+    readonly unitId: string;
+    readonly runId: string;
+    readonly phase: string;
+    readonly branch: RecoveryBranch;
+    readonly action: 'rollback' | 'rollForward' | 'finalize' | 'blocked' | 'none';
+    readonly ok: boolean;
+    readonly code?: string | undefined;
+    readonly message?: string | undefined;
+    readonly evidenceSha256?: string;
+}
+export declare function recoverCommitUnits(options: {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly unit: UnitTransaction;
+    readonly now: () => number;
+    readonly isActive?: (runId: string) => boolean;
+    readonly runs?: {
+        settle(id: string, outcome: {
+            state: 'succeeded' | 'failed' | 'cancelled';
+            resultRef?: string;
+            failure?: string;
+        }): Promise<void>;
+        settleRecovered?(id: string, outcome: {
+            state: 'succeeded' | 'failed' | 'cancelled';
+            resultRef?: string;
+            failure?: string;
+        }): Promise<boolean>;
+    };
+    readonly onProjectionPhase?: (phase: string) => void | Promise<void>;
+}): Promise<readonly RecoveryReport[]>;
+//# sourceMappingURL=recovery-coordinator.d.ts.map