@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.19

package/lib/types/merge-routes.js

@@ -1,6 +1,7 @@
 import { HOST_ROUTES, json, methodNotAllowed } from '@lmzhen/dsh-evolution-core/http-routes';
-import { buildMergeView, pageQueue, toRunFact } from "./routes.js";
-import { renderMarkdown } from "./domain/markdown.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 = {
@@ -10,7 +11,15 @@ export const MERGE_ROUTES = {
     history: (MERGE_PATHS.history ?? MERGE_BASE + 'history'),
 };
 export function makeMergeRoutes(deps, _audit) {
-    const absent = () => json(503, { ok: false, error: { code: 'merge-service-absent', message: 'merge service is not mounted' } });
+    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');
     return [
@@ -25,12 +34,19 @@ export function makeMergeRoutes(deps, _audit) {
                 const source = deps.getSource();
                 if (source === undefined)
                     return absent();
-                const runs = await source.runs(undefined, 20);
-                const latestMerge = runs.find(run => run.kind === 'merge');
-                return json(200, {
-                    ok: true,
-                    data: buildMergeView(await source.rows(), source.commands(), latestMerge === undefined ? undefined : toRunFact(latestMerge), source.approval?.()),
-                });
+                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, buildLegacyFacts({ rows, runs, approval: source.approval?.() === true, readAt }));
             },
         },
         {
@@ -46,15 +62,30 @@ export function makeMergeRoutes(deps, _audit) {
                     return absent();
                 const query = url(request).searchParams;
                 const queue = query.get('queue') ?? 'verify';
-                if (queue !== 'verify' && queue !== 'pending' && queue !== 'fuse' && queue !== 'skipped') {
-                    return json(400, { ok: false, error: { code: 'bad-queue', message: 'queue must be verify/pending/fuse/skipped' } });
-                }
-                const cursor = Number.parseInt(query.get('cursor') ?? '0', 10);
+                if (queue !== 'verify' && queue !== 'pending' && queue !== 'fuse' && queue !== 'skipped')
+                    return bad('queue must be verify/pending/fuse/skipped');
+                const expiredOnly = query.get('expired') === '1';
+                if (expiredOnly && queue !== 'pending')
+                    return bad('expired is only allowed for pending');
                 const limit = Number.parseInt(query.get('limit') ?? '50', 10);
-                return json(200, {
-                    ok: true,
-                    data: pageQueue(await source.rows(), queue, Number.isFinite(cursor) ? cursor : 0, Number.isFinite(limit) ? limit : 50),
-                });
+                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 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,14 +101,38 @@ 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 || id === '' || (side !== 'a' && side !== 'b')) {
-                    return json(400, { ok: false, error: { code: 'bad-body-query', message: 'id and side=a|b are required' } });
+                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 content = await source.body(id, side);
+                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) ?? null;
                 return content === null
-                    ? json(404, { ok: false, error: { code: 'body-not-found', message: 'merge body not found: ' + id } })
-                    : json(200, { ok: true, data: { content, markdown: true, html: renderMarkdown(content) } });
+                    ? 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()));
             },
         },
         {
@@ -91,7 +146,16 @@ export function makeMergeRoutes(deps, _audit) {
                 const source = deps.getSource();
                 if (source === undefined)
                     return absent();
-                return json(200, { ok: true, data: { items: await source.history() } });
+                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.d.ts

@@ -0,0 +1,16 @@
+/** RG6 merge metrics projection: stable names/labels from state + runs. */
+import type { RunRecord } from '@lmzhen/dsh-evolution-core';
+import type { MergeRow } from './contracts.ts';
+export interface MetricSample {
+    readonly name: string;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly value: number;
+}
+export interface MergeMetricCounters {
+    readonly lockWaitMs?: number;
+    readonly claimConflict?: number;
+    readonly recoveryFail?: number;
+}
+export declare const MERGE_METRIC_NAMES: readonly ["merge_queue_depth", "merge_run_total", "merge_run_duration_ms", "merge_lock_wait_ms", "merge_claim_conflict_total", "merge_recovery_fail_total"];
+export declare function buildMergeMetrics(rows: readonly MergeRow[], runs: readonly RunRecord[], counters?: MergeMetricCounters): readonly MetricSample[];
+//# sourceMappingURL=metrics.d.ts.map

package/lib/types/metrics.js

@@ -0,0 +1,27 @@
+import { countsOf } from "./facts.js";
+export const MERGE_METRIC_NAMES = [
+    'merge_queue_depth',
+    'merge_run_total',
+    'merge_run_duration_ms',
+    'merge_lock_wait_ms',
+    'merge_claim_conflict_total',
+    'merge_recovery_fail_total',
+];
+export function buildMergeMetrics(rows, runs, counters = {}) {
+    const counts = countsOf(rows);
+    const samples = [];
+    for (const queue of ['verify', 'pending', 'fuse', 'skipped'])
+        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.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) });
+    }
+    samples.push({ name: 'merge_lock_wait_ms', labels: {}, value: counters.lockWaitMs ?? 0 });
+    samples.push({ name: 'merge_claim_conflict_total', labels: {}, value: counters.claimConflict ?? 0 });
+    samples.push({ name: 'merge_recovery_fail_total', labels: {}, value: counters.recoveryFail ?? 0 });
+    return samples;
+}
+//# sourceMappingURL=metrics.js.map

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

@@ -2,7 +2,7 @@
  * Round2 with a NEW child (approval after the pending window). The child gets the round2
  * prompt and writes the staging tree; the plugin then runs the same gate/commit path.
  */
-import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { EvolutionIoLike, UnitTransaction } from '@lmzhen/dsh-evolution-core';
 import type { MergeDecision, MergeRow } from './contracts.ts';
 import type { SkillCard } from './skill-card.ts';
 import type { ConversationChannelLike } from './channel-port.ts';
@@ -21,9 +21,13 @@ export interface NewChildAuthoringOptions {
     readonly timeoutMs: number;
     readonly commitPort: CommitPort;
     readonly now: () => number;
+    readonly isBlocked?: (name: string) => boolean | Promise<boolean>;
     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,20 +1,48 @@
 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);
-    if (targetCard?.protectionUnknown === true || targetCard?.protectedBy === 'pinned')
-        return { kind: 'failed', failure: { stage: 'author', code: 'target-pinned', message: 'target is pinned: ' + decision.target, retryable: false, retryFrom: 'none' } };
+    const createMode = decision.mode === 'create-umbrella';
+    if (!createMode && targetCard !== undefined) {
+        if (targetCard.managed !== true)
+            return { kind: 'failed', failure: { stage: 'author', code: 'target-not-managed', message: 'target is not family-managed: ' + decision.target, retryable: false, retryFrom: 'none' } };
+        if (targetCard.protectionUnknown === true || targetCard.protectedBy != null)
+            return { kind: 'failed', failure: { stage: 'author', code: 'target-protected', message: 'target is protected: ' + decision.target, retryable: false, retryFrom: 'none' } };
+    }
+    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,
@@ -32,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,
@@ -55,17 +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 commit = await commitStagedRun(options.io, options.home, stageKey, options.commitPort, { origin: 'subagent', summary: 'merge ' + row.a + ' + ' + row.b, now: options.now });
-        if (!commit.ok)
-            return { kind: 'failed', failure: { stage: 'commit', code: 'commit-failed', message: commit.message, 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) {
+            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 },
         };
     }
@@ -77,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 the transition happen in one
- * mutateMergeState 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,22 +1,22 @@
-import { transition } from "./coordinator.js";
-import { mutateMergeState } 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) {
-    return await mutateMergeState(io, home, now, (rows) => {
-        const index = rows.findIndex(row => row.id === id);
-        if (index < 0)
-            return { rows, result: { ok: false, reason: 'not-found', message: 'pending row not found: ' + id } };
-        const current = rows[index];
-        if (current.state !== 'pending')
-            return { rows, result: { ok: false, reason: 'not-pending', message: 'row is not pending: ' + current.state } };
+    void now;
+    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 };
+        if (row.state !== 'pending')
+            return { ok: false, reason: 'not-pending', message: 'row is not pending: ' + row.state };
         const event = type === 'approve'
-            ? { type: 'approve', at: new Date(now()).toISOString() }
-            : { type: 'reject', at: new Date(now()).toISOString() };
-        const next = transition(current, event);
-        if (!next.ok || next.row === null)
-            return { rows, result: { ok: false, reason: 'invalid', message: next.ok ? 'transition produced no row' : next.message } };
-        const copy = [...rows];
-        copy[index] = next.row;
-        return { rows: copy, result: { ok: true, row: next.row } };
+            ? { type: 'approved', runId: row.runId ?? 'approve:' + id }
+            : { type: 'skipped', reason: 'rejected', origin: 'human' };
+        const moved = tx.transition(id, event, row.version);
+        if (!moved.ok)
+            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: 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/propose.d.ts

@@ -0,0 +1,26 @@
+/**
+ * C3 semantic proposer: one library-level model call (sharded when the library is large)
+ * that proposes candidate pairs. It never judges merge quality; L0–L2 does that.
+ */
+import type { MergeCandidate } from './contracts.ts';
+import type { SkillCard } from './screening.ts';
+export interface ModelPort {
+    callJson(request: {
+        readonly system: string;
+        readonly user: string;
+        readonly maxTokens: number;
+        readonly signal: AbortSignal;
+    }): Promise<unknown>;
+}
+export interface ProposeOptions {
+    readonly shardSize?: number;
+    readonly maxPairs?: number;
+    readonly signal: AbortSignal;
+}
+export interface ProposeResult {
+    readonly candidates: readonly MergeCandidate[];
+    readonly shards: number;
+    readonly degraded: readonly string[];
+}
+export declare function proposePairs(cards: readonly SkillCard[], port: ModelPort, options: ProposeOptions): Promise<ProposeResult>;
+//# sourceMappingURL=propose.d.ts.map