@lmzhen/dsh-evolution-merge 0.0.0 → 0.29.0

package/lib/types/doctor.d.ts

@@ -0,0 +1,10 @@
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+export declare const MERGE_DOCTOR_SCHEMA_VERSION = 3;
+export interface MergeDoctorRow {
+    readonly key: string;
+    readonly label: string;
+    readonly status: 'ok' | 'warn' | 'unknown';
+    readonly detail: string;
+}
+export declare function mergeDoctor(io: EvolutionIoLike, home: string, configuredRoot?: string): Promise<readonly MergeDoctorRow[]>;
+//# sourceMappingURL=doctor.d.ts.map

package/lib/types/gate-cache.d.ts

@@ -0,0 +1,12 @@
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { GateCache } from './ladder.ts';
+export declare const GATE_CACHE_VERSION = 1;
+export declare function gateCachePath(home: string): string;
+export interface LoadGateCacheResult {
+    readonly cache: GateCache;
+    readonly note?: string;
+}
+export declare function loadGateCache(io: EvolutionIoLike, home: string): Promise<LoadGateCacheResult>;
+export declare function saveGateCache(io: EvolutionIoLike, home: string, cache: GateCache): Promise<void>;
+export declare function hasGateCache(cache: GateCache): boolean;
+//# sourceMappingURL=gate-cache.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,81 @@
+import z from '@deepseek-ai/schemastery';
+import type { Context } from '@deepseek-ai/cordis';
+/** E3 knobs are volatile (user layer); the E2 pair timeout is deployment-only. */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    mergeApproval: z<boolean, boolean, "volatile-defined">;
+    mergeSkippedTtlDays: z<number, number, "volatile-defined">;
+    mergeRunTimeoutMinutes: z<number, number, "volatile-defined">;
+    mergePairTimeoutMinutes: z<number, number, "defined">;
+    mergeModelsRoot: z<string, string, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    mergeApproval: z<boolean, boolean, "volatile-defined">;
+    mergeSkippedTtlDays: z<number, number, "volatile-defined">;
+    mergeRunTimeoutMinutes: z<number, number, "volatile-defined">;
+    mergePairTimeoutMinutes: z<number, number, "defined">;
+    mergeModelsRoot: z<string, string, "defined">;
+}>>, "plain">;
+export interface MergePresentationScope {
+    effect(run: () => () => void, label?: string): unknown;
+    settings?: {
+        configure?: (presentation: {
+            auto?: boolean;
+        }, owner?: unknown) => unknown;
+    };
+}
+export declare function engineConfigFromEnv(configuredRoot?: string): Record<string, unknown> | undefined;
+export interface MergePresentationContext {
+    inject(names: string[], run: (scope: MergePresentationScope) => void): void;
+    readonly fiber?: unknown;
+}
+/** Suppress the platform auto form; the registry renders the merge card instead. */
+export declare function configureMergePresentation(ctx: MergePresentationContext): void;
+export * from './contracts.ts';
+export * from './skill-card.ts';
+export * from './state.ts';
+export * from './coordinator.ts';
+export * from './report.ts';
+export * from './staging.ts';
+export * from './staging-files.ts';
+export * from './rules.ts';
+export * from './commit-plan.ts';
+export * from './stage-tool.ts';
+export * from './stage-tool-registry.ts';
+export * from './staged-tree.ts';
+export * from './commit-assembly.ts';
+export * from './commit-receipt.ts';
+export * from './commit-execute.ts';
+export * from './undo-merge.ts';
+export * from './adapters/library.ts';
+export * from './adapters/model-runner.ts';
+export * from './adapters/channel.ts';
+export * from './adapters/engine-screen.ts';
+export * from './adapters/undo.ts';
+export * from './run-shell.ts';
+export * from './scan-run.ts';
+export * from './pending-actions.ts';
+export * from './scan-command.ts';
+export * from './round2-outcome.ts';
+export * from './approve-command.ts';
+export * from './pair-command.ts';
+export * from './resume-command.ts';
+export * from './decision.ts';
+export * from './prompts.ts';
+export * from './channel-port.ts';
+export * from './authoring-flow.ts';
+export * from './merge-tool.ts';
+export * from './commands.ts';
+export * from './scan-ports.ts';
+export * from './new-child-authoring.ts';
+export * from './status.ts';
+export * from './skipped.ts';
+export * from './read-commands.ts';
+export * from './routes.ts';
+export * from './merge-routes.ts';
+export * from './merge-command.ts';
+export * from './params.ts';
+export * from './doctor.ts';
+export * from './supersede.ts';
+export * from './runtime.ts';
+export declare const inject: string[];
+export declare function apply(ctx: Context, rawConfig?: Record<string, unknown>): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/ladder.d.ts

@@ -0,0 +1,65 @@
+export type GateLevel = 'L0' | 'L1' | 'L2';
+export type GateVerdictValue = 1 | 0 | -1;
+export interface GateFacts {
+    readonly name: string;
+    readonly description: string;
+    readonly body: string;
+}
+export interface GateCandidate {
+    readonly a: string;
+    readonly b: string;
+    readonly score?: number;
+}
+export interface GateEvidence {
+    readonly path: string;
+    readonly line: number;
+    readonly quote: string;
+}
+export interface GateVerdict {
+    readonly level: GateLevel;
+    readonly verdict: GateVerdictValue;
+    readonly reason: string;
+    readonly evidence: readonly GateEvidence[];
+    readonly cached: boolean;
+}
+export interface GateModelPort {
+    callJson(request: {
+        readonly system: string;
+        readonly user: string;
+        readonly maxTokens: number;
+        readonly signal: AbortSignal;
+    }): Promise<unknown>;
+}
+export type LadderRoute = 'merge' | 'undecided' | 'keep' | 'error';
+export interface LadderResult {
+    readonly route: LadderRoute;
+    readonly verdicts: readonly GateVerdict[];
+    readonly calls: number;
+    readonly droppedAt?: GateLevel;
+    readonly error?: string;
+}
+export declare class GateCache {
+    private readonly entries;
+    get(key: string): GateVerdict | undefined;
+    put(key: string, value: GateVerdict): void;
+    get size(): number;
+    toObject(): Record<string, GateVerdict>;
+    static fromObject(value: unknown): GateCache;
+}
+export declare function gateCacheKey(level: GateLevel, payload: string, model: string): string;
+export declare function parseVerdict(level: GateLevel, raw: unknown, cached?: boolean): GateVerdict | undefined;
+export interface RunLadderOptions {
+    readonly level: GateLevel;
+    readonly candidate: GateCandidate;
+    readonly facts: readonly GateFacts[];
+    readonly model: GateModelPort;
+    readonly modelName: string;
+    readonly signal: AbortSignal;
+    readonly cache?: GateCache;
+    /** Audit path starts at L2 after an L0 keep. */
+    readonly startLevel?: GateLevel;
+}
+/** Deterministic 10% L0 audit selection from the run seed + pair key. */
+export declare function selectedForAudit(pairKey: string, seed: string, rate?: number): boolean;
+export declare function runLadder(options: RunLadderOptions): Promise<LadderResult>;
+//# sourceMappingURL=ladder.d.ts.map

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

@@ -0,0 +1,39 @@
+/**
+ * Model/CLI-facing /merge command definition. The host shell registers it; this module owns
+ * parsing, read-only verb dispatch and the uniform error/success envelope.
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type MergeCliCommand } from './commands.ts';
+export interface MergeCommandResult {
+    readonly ok: boolean;
+    readonly text: string;
+}
+export interface MergeCommandContext {
+    /** The invoking agent, when a command (not a route) initiated the run. */
+    readonly parent?: unknown;
+}
+export interface MergeCommandService {
+    execute(command: MergeCliCommand, context?: MergeCommandContext): Promise<MergeCommandResult>;
+}
+export interface CommandInvocationLike {
+    readonly rawInput: string;
+    readonly agent?: unknown;
+}
+export interface CommandResultLike {
+    readonly kind: 'success' | 'error';
+    readonly text: string;
+}
+export interface MergeCommandDefinitionLike {
+    readonly name: string;
+    readonly description: string;
+    readonly input: {
+        readonly hint: string;
+    };
+    readonly handler: (invocation: CommandInvocationLike) => Promise<CommandResultLike>;
+}
+export declare function createReadOnlyMergeService(io: EvolutionIoLike, home: string): MergeCommandService;
+export declare function runMergeCommand(service: MergeCommandService, rawInput: string, invocation?: {
+    readonly agent?: unknown;
+}): Promise<MergeCommandResult>;
+export declare function createMergeCommand(service: MergeCommandService): MergeCommandDefinitionLike;
+//# sourceMappingURL=merge-command.d.ts.map

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

@@ -0,0 +1,24 @@
+/**
+ * Four read-only merge routes: view / rows / run / runs. The host loads rows and runs; these
+ * handlers only project. A missing merge service answers 503 instead of pretending empty.
+ */
+import type { RunRecord } from '@lmzhen/dsh-evolution-core';
+import { type ConnectionFetchRouteLike, type DecisionAudit } from '@lmzhen/dsh-evolution-core/http-routes';
+import type { MergeRow } from './contracts.ts';
+export declare const MERGE_ROUTES: {
+    readonly view: "/api/dsh-evolution/merge/view";
+    readonly rows: "/api/dsh-evolution/merge/rows";
+    readonly run: "/api/dsh-evolution/merge/run";
+    readonly runs: "/api/dsh-evolution/merge/runs";
+};
+export interface MergeRouteSource {
+    rows(): Promise<readonly MergeRow[]>;
+    run(id: string): Promise<RunRecord | undefined>;
+    runs(cursor?: string, limit?: number): Promise<readonly RunRecord[]>;
+    commands(): readonly string[];
+    approval?(): boolean;
+}
+export declare function makeMergeRoutes(deps: {
+    getSource: () => MergeRouteSource | undefined;
+}, _audit: DecisionAudit): ConnectionFetchRouteLike[];
+//# sourceMappingURL=merge-routes.d.ts.map

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

@@ -0,0 +1,22 @@
+/**
+ * Model-facing merge_stage tool definition. The plugin shell supplies the context factory;
+ * this module owns the argument schema and the JSON result. All policy remains in applyStageTool.
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type StageToolContext } from './stage-tool.ts';
+export declare const MERGE_STAGE_TOOL_NAME = "merge_stage";
+export interface ToolDefinitionLike {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly output: {
+        readonly schema: Record<string, unknown>;
+        readonly render: (args: unknown, value: string) => readonly {
+            readonly type: 'text';
+            readonly text: string;
+        }[];
+    };
+    readonly execute: (args: Record<string, unknown>, exec: unknown) => Promise<string>;
+}
+export declare function createMergeStageTool(io: EvolutionIoLike, home: string, context: (exec: unknown) => StageToolContext | undefined): ToolDefinitionLike;
+//# sourceMappingURL=merge-tool.d.ts.map

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

@@ -0,0 +1,29 @@
+/**
+ * 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 { MergeDecision, MergeRow } from './contracts.ts';
+import type { SkillCard } from './skill-card.ts';
+import type { ConversationChannelLike } from './channel-port.ts';
+import { type CommitPort } from './commit-execute.ts';
+import type { StageToolContext } from './stage-tool.ts';
+import type { ScanRound2Outcome } from './scan-run.ts';
+export interface NewChildAuthoringOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly runId: string;
+    readonly cards: readonly SkillCard[];
+    readonly channel: ConversationChannelLike;
+    readonly parent: unknown;
+    readonly allow: readonly string[];
+    readonly cwd?: string;
+    readonly timeoutMs: number;
+    readonly commitPort: CommitPort;
+    readonly now: () => number;
+    readonly onChild?: (context: StageToolContext) => void;
+    readonly onChildClosed?: (childId: string) => void;
+}
+export declare function runNewChildAuthoring(options: NewChildAuthoringOptions, row: MergeRow, decision: MergeDecision, signal: AbortSignal): Promise<ScanRound2Outcome>;
+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/pair-command.d.ts

@@ -0,0 +1,20 @@
+/**
+ * pair command: one explicit candidate through the same scan shell.
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { ScanPorts } from './scan-run.ts';
+import type { MergeRegistryPort, WithMergeRunResult } from './run-shell.ts';
+export interface RunPairCommandOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly registry: MergeRegistryPort;
+    readonly ports: ScanPorts;
+    readonly a: string;
+    readonly b: string;
+    readonly approval: boolean;
+    readonly platformWrite: boolean;
+    readonly timeoutMinutes?: number;
+    readonly now: () => number;
+}
+export declare function runPairCommand(options: RunPairCommandOptions): Promise<WithMergeRunResult>;
+//# sourceMappingURL=pair-command.d.ts.map

package/lib/types/params.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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;
+}
+export declare const MERGE_PARAM_DEFAULTS: MergeParams;
+export declare function resolveMergeParams(input?: unknown): MergeParams;
+//# sourceMappingURL=params.d.ts.map

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

@@ -0,0 +1,17 @@
+/**
+ * Pending approval actions. The row lookup and the transition happen in one
+ * mutateMergeState 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';
+export type PendingActionResult = {
+    readonly ok: true;
+    readonly row: MergeRow;
+} | {
+    readonly ok: false;
+    readonly reason: 'not-found' | 'not-pending' | 'invalid';
+    readonly message: string;
+};
+export declare function approvePending(io: EvolutionIoLike, home: string, now: () => number, id: string): Promise<PendingActionResult>;
+export declare function rejectPending(io: EvolutionIoLike, home: string, now: () => number, id: string): Promise<PendingActionResult>;
+//# sourceMappingURL=pending-actions.d.ts.map

package/lib/types/prompts.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 const STANDBY_PROMPT = "You are a merge worker. Wait for instructions.";
+export declare function buildRound1Prompt(candidate: {
+    readonly a: string;
+    readonly b: string;
+}, cards: readonly SkillCard[]): string;
+export declare function buildRound2Prompt(row: MergeRow, decision: MergeDecision, mode?: 'continue' | 'fresh'): string;
+export declare function buildStandbyPrompt(): string;
+//# sourceMappingURL=prompts.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { MergeCliCommand } from './commands.ts';
+export declare function handleReadOnlyMergeCommand(command: MergeCliCommand, io: EvolutionIoLike, home: string): Promise<string | null>;
+export declare function mergeCommandHelp(): string;
+//# sourceMappingURL=read-commands.d.ts.map

package/lib/types/report.d.ts

@@ -0,0 +1,10 @@
+import { type EvolutionIoLike, type Probe } from '@lmzhen/dsh-evolution-core';
+import type { MergeReport, MergeReportPair } from './contracts.ts';
+export declare function mergeReportPath(home: string, runId: string): string;
+export declare function mergeReportDigestPath(home: string, runId: string): string;
+/** Write JSON first, then the digest; returns the JSON path (the registry resultRef). */
+export declare function writeMergeReport(io: EvolutionIoLike, home: string, report: MergeReport): Promise<string>;
+export declare function readMergeReport(io: EvolutionIoLike, home: string, runId: string): Promise<Probe<MergeReport>>;
+/** Pairs this run actually merged (for merge undo / reports). */
+export declare function committedPairs(io: EvolutionIoLike, home: string, runId: string): Promise<readonly MergeReportPair[]>;
+//# sourceMappingURL=report.d.ts.map

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

@@ -0,0 +1,24 @@
+/**
+ * resume command: verify rows re-enter round1; fuse rows re-enter round2 with the persisted
+ * decision. pending/skipped rows are not resumable.
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type MergeRegistryPort, type WithMergeRunResult } from './run-shell.ts';
+import type { ScanPorts, ScanRound2Outcome } from './scan-run.ts';
+import type { MergeDecision, MergeRow } from './contracts.ts';
+export interface RunResumeCommandOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly registry: MergeRegistryPort;
+    readonly ports: ScanPorts;
+    /** Per-run ports for the verify branch (staging needs the new runId). */
+    readonly makePorts?: (runId: string) => ScanPorts;
+    /** Optional new-child authoring port (approve-after-pending path). */
+    readonly round2WithRun?: (row: MergeRow, decision: MergeDecision, signal: AbortSignal, runId: string) => Promise<ScanRound2Outcome>;
+    readonly rowId: string;
+    readonly platformWrite: boolean;
+    readonly timeoutMinutes?: number;
+    readonly now: () => number;
+}
+export declare function runResumeCommand(options: RunResumeCommandOptions): Promise<WithMergeRunResult>;
+//# sourceMappingURL=resume-command.d.ts.map

package/lib/types/round2-outcome.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared round2 outcome recorder for approve and resume: one place decides whether the
+ * row is dropped (commit landed) or kept in fuse with a failure. No report/registry logic.
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { MergeReportPair, MergeRow } from './contracts.ts';
+import type { ScanRound2Outcome } from './scan-run.ts';
+export interface Round2Record {
+    readonly pair: MergeReportPair;
+    readonly merged: boolean;
+}
+export declare function recordRound2Outcome(io: EvolutionIoLike, home: string, now: () => number, row: MergeRow, outcome: ScanRound2Outcome): Promise<Round2Record>;
+//# sourceMappingURL=round2-outcome.d.ts.map

package/lib/types/routes.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Read-only view models for the four merge routes. Pure functions; the host loads rows and
+ * runs, the client renders these shapes. No io, no write paths.
+ */
+import type { RunRecord } from '@lmzhen/dsh-evolution-core';
+import type { MergeQueue, MergeRow } from './contracts.ts';
+import { type MergeCounts } from './status.ts';
+export interface MergeRowView {
+    readonly id: string;
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly state: MergeRow['state'];
+    readonly queue: MergeQueue;
+    readonly stage: string | null;
+    readonly label: string;
+    readonly updatedAt: string;
+    readonly createdAt: string;
+    readonly target?: string;
+    readonly confidence?: number;
+    readonly failure?: {
+        readonly stage: string;
+        readonly code: string;
+        readonly message: string;
+        readonly retryable: boolean;
+    };
+    readonly attempts?: number;
+    readonly origin?: 'agent' | 'human';
+    readonly stagingExpiresAt?: number;
+    readonly actions: readonly string[];
+}
+export declare function toRowView(row: MergeRow): MergeRowView;
+export interface MergeView {
+    readonly schemaVersion: 1;
+    readonly counts: MergeCounts;
+    readonly tabs: readonly {
+        readonly queue: MergeQueue;
+        readonly count: number;
+    }[];
+    readonly commands: readonly string[];
+    readonly latestRun?: MergeRunFact;
+    readonly approval?: boolean;
+}
+export declare function buildMergeView(rows: readonly MergeRow[], commands: readonly string[], latestRun?: MergeRunFact, approval?: boolean): MergeView;
+export interface QueuePage {
+    readonly queue: MergeQueue;
+    readonly items: readonly MergeRowView[];
+    readonly nextCursor?: string;
+}
+export declare function pageQueue(rows: readonly MergeRow[], queue: MergeQueue, cursor?: number, limit?: number): QueuePage;
+export interface MergeRunFact {
+    readonly id: string;
+    readonly state: RunRecord['state'];
+    readonly command?: RunRecord['command'];
+    readonly stage?: RunRecord['stage'];
+    readonly progress?: RunRecord['progress'];
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly resultRef?: string;
+    readonly failure?: string;
+    readonly supersededAt?: number;
+}
+export declare function toRunFact(run: RunRecord): MergeRunFact;
+//# sourceMappingURL=routes.d.ts.map

package/lib/types/rules.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Deterministic gate for a staged merge tree. No io, no model.
+ *
+ * block = commit must not proceed; warn = report only. The path and reference checks reuse
+ * the skill-store's own `validateSupportPath` / `supportRefs`, so there is one whitelist.
+ */
+import { type SkillLimits } from '@lmzhen/dsh-evolution-core';
+export interface StagedTree {
+    readonly target: string;
+    readonly body: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+}
+export interface RuleFinding {
+    readonly rule: string;
+    readonly path: string;
+    readonly severity: 'block' | 'warn';
+    readonly message: string;
+}
+export declare function validateStagedTree(tree: StagedTree, limits?: SkillLimits): readonly RuleFinding[];
+export declare function hasBlockingFinding(findings: readonly RuleFinding[]): boolean;
+//# sourceMappingURL=rules.d.ts.map

package/lib/types/run-shell.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Merge run shell: registry lifecycle + report-before-settle.
+ *
+ * The pair executor is injected. This module owns the invariants every command shares:
+ * begin a merge run, publish stage/progress, write the report, then settle with resultRef.
+ * A body failure still produces a failed report (unless the report itself cannot be written).
+ */
+import type { EvolutionIoLike, RunHandle, RunKind, RunStage } from '@lmzhen/dsh-evolution-core';
+import type { MergeReport, MergeReportPair, MergeRunCommand } from './contracts.ts';
+export interface MergeRegistryPort {
+    begin(kind: RunKind, seed?: {
+        command?: MergeRunCommand;
+        total?: number;
+        parentRunId?: string;
+    }): Promise<Pick<RunHandle, 'id' | 'signal' | 'startedAt'>>;
+    stage(id: string, stage: RunStage, progress?: {
+        done: number;
+        total: number;
+    }): Promise<void>;
+    settle(id: string, outcome: {
+        state: 'succeeded' | 'failed' | 'cancelled';
+        resultRef?: string;
+        failure?: string;
+    }): Promise<void>;
+}
+export interface MergeRunBodyContext {
+    readonly runId: string;
+    readonly startedAt: number;
+    readonly signal: AbortSignal;
+    readonly stage: (stage: RunStage, progress?: {
+        done: number;
+        total: number;
+    }) => Promise<void>;
+}
+export interface MergeRunReportDraft {
+    readonly stopReason: MergeReport['stopReason'];
+    readonly scope: MergeReport['scope'];
+    readonly pairs: readonly MergeReportPair[];
+    readonly totals: MergeReport['totals'];
+    readonly notes: readonly string[];
+    readonly remaining?: MergeReport['remaining'];
+}
+export interface WithMergeRunOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly registry: MergeRegistryPort;
+    readonly command: MergeRunCommand;
+    readonly approval: MergeReport['approval'];
+    readonly now: () => number;
+    readonly total?: number;
+    readonly body: (ctx: MergeRunBodyContext) => Promise<MergeRunReportDraft>;
+}
+export type WithMergeRunResult = {
+    readonly ok: true;
+    readonly runId: string;
+    readonly reportPath: string;
+    readonly report: MergeReport;
+} | {
+    readonly ok: false;
+    readonly runId?: string;
+    readonly message: string;
+    readonly reportPath?: string;
+};
+export declare function withMergeRun(options: WithMergeRunOptions): Promise<WithMergeRunResult>;
+//# sourceMappingURL=run-shell.d.ts.map

package/lib/types/runtime.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The merge command runtime: cards -> screening -> channel ports -> scan/approve.
+ * Plugin wiring supplies the channel, model and library; this module keeps the orchestration
+ * out of apply() and makes the mutating verbs testable with fakes.
+ */
+import { type EvolutionIoLike, type SkillLibrary } from '@lmzhen/dsh-evolution-core';
+import { type MergeCandidate } from './contracts.ts';
+import type { MergeParams } from './params.ts';
+import type { SkillCard } from './skill-card.ts';
+import type { MergeRegistryPort } from './run-shell.ts';
+import type { MergeCommandService } from './merge-command.ts';
+import type { StageToolContext } from './stage-tool.ts';
+import type { ConversationChannelLike } from './channel-port.ts';
+export interface MergeStageBindingPort {
+    bind(context: StageToolContext): void;
+    unbind(childId: string): void;
+}
+export interface MergeRuntimeDeps {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly registry: MergeRegistryPort;
+    readonly skills: SkillLibrary;
+    readonly now: () => number;
+    readonly params: MergeParams;
+    readonly platformWrite: boolean;
+    readonly channel: ConversationChannelLike;
+    readonly parent: unknown;
+    readonly allow: readonly string[];
+    readonly cwd?: string;
+    readonly timeoutMinutes: number;
+    readonly cards: (signal: AbortSignal) => Promise<readonly SkillCard[]>;
+    /** Run-scoped engine screening. */
+    readonly screeningForRun: (cards: readonly SkillCard[], runId: string, signal: AbortSignal) => Promise<readonly MergeCandidate[]>;
+    readonly stage?: MergeStageBindingPort;
+}
+export declare function createMergeRuntime(deps: MergeRuntimeDeps): MergeCommandService;
+//# sourceMappingURL=runtime.d.ts.map

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

@@ -0,0 +1,21 @@
+/**
+ * scan command wiring: the registry/report shell around runScan.
+ * Pair/approve/resume commands get their own thin wrappers on the same shell.
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type ScanPorts } from './scan-run.ts';
+import { type MergeRegistryPort, type WithMergeRunResult } from './run-shell.ts';
+export interface RunScanCommandOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly registry: MergeRegistryPort;
+    readonly ports?: ScanPorts;
+    /** Build per-run ports when staging needs the runId (channel authoring). */
+    readonly makePorts?: (runId: string) => ScanPorts;
+    readonly approval: boolean;
+    readonly platformWrite: boolean;
+    readonly timeoutMinutes?: number;
+    readonly now: () => number;
+}
+export declare function runScanCommand(options: RunScanCommandOptions): Promise<WithMergeRunResult>;
+//# sourceMappingURL=scan-command.d.ts.map