@lmzhen/dsh-evolution-merge 0.0.0-stage → 0.28.0

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

@@ -0,0 +1,44 @@
+/**
+ * The scan pair loop. Registry/report lifecycle stays in withMergeRun; this module owns
+ * candidate → round1 → pending/fuse → commit transitions and returns the report draft.
+ */
+import { type MergeCandidate, type MergeDecision, type MergeFailure, type MergeRow } from './contracts.ts';
+import type { EvolutionIoLike, RunStage } from '@lmzhen/dsh-evolution-core';
+import type { MergeRunReportDraft } from './run-shell.ts';
+export interface ScanRound1Outcome {
+    readonly kind: 'keep' | 'merge' | 'failed';
+    readonly decision?: MergeDecision;
+    readonly failure?: MergeFailure;
+}
+export interface ScanRound2Outcome {
+    readonly kind: 'merged' | 'failed';
+    readonly unitId?: string;
+    readonly archived?: readonly string[];
+    readonly target?: {
+        readonly requested: string;
+        readonly actual: string;
+        readonly created: boolean;
+    };
+    readonly failure?: MergeFailure;
+}
+export interface ScanPorts {
+    screening(signal: AbortSignal): Promise<readonly MergeCandidate[]>;
+    round1(candidate: MergeCandidate, signal: AbortSignal): Promise<ScanRound1Outcome>;
+    round2(row: MergeRow, decision: MergeDecision, signal: AbortSignal): Promise<ScanRound2Outcome>;
+}
+export interface RunScanOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly now: () => number;
+    readonly signal: AbortSignal;
+    readonly approval: boolean;
+    readonly timeoutMinutes?: number;
+    readonly startedAt?: number;
+    readonly ports: ScanPorts;
+    readonly stage?: (stage: RunStage, progress?: {
+        done: number;
+        total: number;
+    }) => Promise<void>;
+}
+export declare function runScan(options: RunScanOptions): Promise<MergeRunReportDraft>;
+//# sourceMappingURL=scan-run.d.ts.map

package/lib/types/screening-port.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The real screening port: lexical floor + optional C3 proposal + optional L0–L2 gate.
+ * Each stage is independently testable; this file only composes their frozen contracts.
+ */
+import { type MergeCandidate } from './contracts.ts';
+import { type SkillCard, type ScreeningOptions } from './screening.ts';
+import { type ModelPort } from './propose.ts';
+import type { GateCache, GateModelPort } from './ladder.ts';
+export interface ScreeningForRunOptions extends Omit<BuildScreeningOptions, 'signal'> {
+    readonly runSeed: string;
+}
+export interface BuildScreeningOptions {
+    readonly cards: readonly SkillCard[];
+    readonly signal: AbortSignal;
+    readonly lexical?: ScreeningOptions;
+    readonly propose?: {
+        readonly model: ModelPort;
+        readonly shardSize?: number;
+        readonly maxPairs?: number;
+    };
+    readonly gate?: {
+        readonly model: GateModelPort;
+        readonly modelName: string;
+        readonly runSeed: string;
+        readonly cache?: GateCache;
+        readonly auditRate?: number;
+    };
+}
+export interface ScreeningPortStats {
+    readonly lexical: number;
+    readonly proposed: number;
+    readonly candidates: number;
+    readonly kept: number;
+    readonly dropped: number;
+    readonly gateCalls: number;
+    readonly gateErrors: number;
+    readonly shards: number;
+}
+export interface ScreeningPortResult {
+    readonly candidates: readonly MergeCandidate[];
+    readonly stats: ScreeningPortStats;
+    readonly degraded: readonly string[];
+}
+export declare function buildScreeningCandidates(options: BuildScreeningOptions): Promise<ScreeningPortResult>;
+/** Build the run-scoped screening function; the run id seeds the 10% audit. */
+export declare function createScreeningForRun(options: ScreeningForRunOptions): (signal: AbortSignal) => Promise<readonly MergeCandidate[]>;
+//# sourceMappingURL=screening-port.d.ts.map

package/lib/types/screening.d.ts

@@ -0,0 +1,30 @@
+import type { MergeCandidate } from './contracts.ts';
+export interface SkillCard {
+    readonly name: string;
+    readonly description: string;
+    readonly body: string;
+}
+export interface ScreeningOptions {
+    /** Body Jaccard at/above this is a candidate on its own. */
+    readonly bodyGate?: number;
+    /** Description Jaccard at/above this is a candidate when the body also clears minAffinity. */
+    readonly summaryGate?: number;
+    /** Minimum body affinity for a summary-led candidate. */
+    readonly minAffinity?: number;
+    /** Upper bound after sorting by score; absent = no cap. */
+    readonly maxCandidates?: number;
+}
+export interface ScreeningStats {
+    readonly skills: number;
+    readonly filtered: number;
+    readonly candidates: number;
+}
+export interface ScreeningResult {
+    readonly candidates: readonly MergeCandidate[];
+    readonly stats: ScreeningStats;
+}
+/** Shannon entropy over characters; a cheap prefilter signal, not a name-quality judge. */
+export declare function nameEntropy(name: string): number;
+export declare function prefilter(cards: readonly SkillCard[]): readonly SkillCard[];
+export declare function lexicalCandidates(cards: readonly SkillCard[], options?: ScreeningOptions): ScreeningResult;
+//# sourceMappingURL=screening.d.ts.map

package/lib/types/skipped.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Skipped filtering: a pair the operator marked as not-worth-merging stays out of automatic
+ * screening until mergeSkippedTtlDays expires. Explicit /merge pair ignores this set.
+ */
+import { type MergeRow } from './contracts.ts';
+export declare function skippedPairKeys(rows: readonly MergeRow[], ttlDays: number, now: number): ReadonlySet<string>;
+export declare function isSkippedPair(keys: ReadonlySet<string>, a: string, b: string): boolean;
+//# sourceMappingURL=skipped.d.ts.map

package/lib/types/stage-tool-registry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Child-scoped stage-tool bindings. A round child is bound only for the window in which its
+ * staging writes are legal; the tool resolves the caller from the platform exec and refuses
+ * when no binding exists.
+ */
+import type { StageToolContext } from './stage-tool.ts';
+export declare class StageToolRegistry {
+    private readonly bindings;
+    bind(childId: string, context: StageToolContext): void;
+    unbind(childId: string): void;
+    clear(): void;
+    resolve(exec: unknown): StageToolContext | undefined;
+}
+//# sourceMappingURL=stage-tool-registry.d.ts.map

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

@@ -0,0 +1,45 @@
+/**
+ * The pure half of the model-facing merge_stage tool.
+ *
+ * Registration/session binding lives in the plugin shell; this function owns the rules a
+ * caller cannot bypass: only the bound merge child, and only the author phase may write.
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type StageArea } from './staging-files.ts';
+export type StagePhase = 'decide' | 'author';
+export interface StageToolContext {
+    readonly runId: string;
+    readonly childId: string;
+    readonly expectedChildId: string;
+    readonly phase: StagePhase;
+}
+export type StageToolOp = {
+    readonly op: 'list';
+    readonly area: StageArea;
+    readonly path?: string;
+    readonly source?: string;
+} | {
+    readonly op: 'read';
+    readonly area: StageArea;
+    readonly path: string;
+    readonly source?: string;
+} | {
+    readonly op: 'write';
+    readonly path: string;
+    readonly content: string;
+} | {
+    readonly op: 'copy';
+    readonly source: string;
+    readonly from: string;
+    readonly to: string;
+};
+export type StageToolResult = {
+    readonly ok: true;
+    readonly value?: unknown;
+} | {
+    readonly ok: false;
+    readonly code: 'not-merge-child' | 'phase' | 'not-found' | 'io' | 'bad-path';
+    readonly message: string;
+};
+export declare function applyStageTool(io: EvolutionIoLike, home: string, ctx: StageToolContext, op: StageToolOp): Promise<StageToolResult>;
+//# sourceMappingURL=stage-tool.d.ts.map

package/lib/types/staged-tree.d.ts

@@ -0,0 +1,4 @@
+import { type EvolutionIoLike, type Probe } from '@lmzhen/dsh-evolution-core';
+import type { StagedTree } from './rules.ts';
+export declare function readStagedTree(io: EvolutionIoLike, home: string, runId: string): Promise<Probe<StagedTree>>;
+//# sourceMappingURL=staged-tree.d.ts.map

package/lib/types/staging-files.d.ts

@@ -0,0 +1,15 @@
+import { type EvolutionIoLike, type Probe } from '@lmzhen/dsh-evolution-core';
+export type StageArea = 'sources' | 'merged';
+export type StageWriteResult = {
+    readonly ok: true;
+    readonly path: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function writeStagedFile(io: EvolutionIoLike, home: string, runId: string, path: string, content: string, source?: string): Promise<StageWriteResult>;
+export declare function readStagedFile(io: EvolutionIoLike, home: string, runId: string, path: string, area: StageArea, source?: string): Promise<Probe<string>>;
+export declare function listStagedFiles(io: EvolutionIoLike, home: string, runId: string, area: StageArea, path?: string, source?: string): Promise<Probe<readonly string[]>>;
+/** Copy one source file into the merged target; the only cross-area operation allowed. */
+export declare function copyStagedFile(io: EvolutionIoLike, home: string, runId: string, source: string, from: string, to: string): Promise<StageWriteResult>;
+//# sourceMappingURL=staging-files.d.ts.map

package/lib/types/staging.d.ts

@@ -0,0 +1,43 @@
+import { type EvolutionIoLike, type Probe } from '@lmzhen/dsh-evolution-core';
+export declare const STAGING_SCHEMA_VERSION = 1;
+export declare function stagingRoot(home: string, runId: string): string;
+export interface StagingSource {
+    readonly name: string;
+    readonly body: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+}
+export interface StagingManifest {
+    readonly schemaVersion: typeof STAGING_SCHEMA_VERSION;
+    readonly runId: string;
+    readonly target: string;
+    readonly sources: readonly string[];
+    readonly promptVersion: string;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+}
+export interface CreateStagingInput {
+    readonly runId: string;
+    readonly target: string;
+    readonly sources: readonly StagingSource[];
+    readonly promptVersion: string;
+    readonly ttlDays: number;
+    readonly now: () => number;
+}
+export type CreateStagingResult = {
+    readonly ok: true;
+    readonly path: string;
+    readonly manifest: StagingManifest;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function createStaging(io: EvolutionIoLike, home: string, input: CreateStagingInput): Promise<CreateStagingResult>;
+export interface StagedView {
+    readonly path: string;
+    readonly manifest: StagingManifest;
+}
+export declare function readStaging(io: EvolutionIoLike, home: string, runId: string): Promise<Probe<StagedView>>;
+//# sourceMappingURL=staging.d.ts.map

package/lib/types/state.d.ts

@@ -0,0 +1,29 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type MergePairState, type MergeQueue, type MergeRow, type MergeState } from './contracts.ts';
+export declare function mergeStatePath(home: string): string;
+export interface LoadMergeStateResult {
+    readonly ok: boolean;
+    readonly state: MergeState;
+    readonly note?: string;
+}
+/** Pure read: never writes, never deletes a row. */
+export declare function loadMergeState(io: EvolutionIoLike, home: string): Promise<LoadMergeStateResult>;
+/** The ONE write point. The callback returns the whole row set, not a delta. */
+export declare function mutateMergeState<T>(io: EvolutionIoLike, home: string, now: () => number, fn: (rows: readonly MergeRow[]) => {
+    rows: readonly MergeRow[];
+    result: T;
+}): Promise<T>;
+export interface MoveRowPatch {
+    readonly queue: MergeQueue;
+    readonly state?: MergePairState;
+    readonly failure?: MergeRow['failure'];
+    readonly runId?: string;
+    readonly unitId?: string;
+    readonly origin?: MergeRow['origin'];
+    readonly attempts?: number;
+}
+export declare function upsertRow(io: EvolutionIoLike, home: string, now: () => number, row: MergeRow): Promise<void>;
+export declare function moveRow(io: EvolutionIoLike, home: string, now: () => number, id: string, patch: MoveRowPatch): Promise<MergeRow | undefined>;
+export declare function dropRow(io: EvolutionIoLike, home: string, now: () => number, id: string): Promise<boolean>;
+export declare function rowsOf(io: EvolutionIoLike, home: string, queue?: MergeQueue): Promise<readonly MergeRow[]>;
+//# sourceMappingURL=state.d.ts.map

package/lib/types/status.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Read-only status projections for the merge command/panel. Pure formatting over rows; no
+ * writes, no report reads. The UI and command parser share this vocabulary.
+ */
+import type { MergeQueue, MergeRow } from './contracts.ts';
+export interface MergeCounts {
+    readonly pending: number;
+    readonly retry: number;
+    readonly skipped: number;
+}
+export declare function countRows(rows: readonly MergeRow[]): MergeCounts;
+export declare function formatStatus(rows: readonly MergeRow[]): string;
+export declare function formatQueue(rows: readonly MergeRow[], queue: MergeQueue): string;
+//# sourceMappingURL=status.d.ts.map

package/lib/types/supersede.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A tree restore invalidates earlier merge runs: their commit receipts may describe a tree
+ * that no longer exists. Mark every non-superseded merge run in this process's registry.
+ */
+import type { RunRecord, RunRegistry } from '@lmzhen/dsh-evolution-core';
+export declare function mergeRunIdsToSupersede(runs: readonly RunRecord[]): readonly string[];
+export declare function supersedeMergeRuns(registry: RunRegistry): Promise<number>;
+//# sourceMappingURL=supersede.d.ts.map

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

@@ -0,0 +1,13 @@
+/**
+ * Execute a merge undo from its commit receipt. The receipt names the unit and archived
+ * sources; this module resolves versions, plans the cross-skill undo and runs the shared
+ * executor. No command/routing logic here.
+ */
+import type { SkillVersion } from '@lmzhen/dsh-evolution-core';
+import { type UnitUndoExecution, type UnitUndoSink } from '@lmzhen/dsh-evolution-core';
+import type { CommitReceipt } from './commit-receipt.ts';
+export interface MergeUndoPort extends UnitUndoSink {
+    listVersions(skill: string): Promise<readonly SkillVersion[]>;
+}
+export declare function undoMergeReceipt(receipt: CommitReceipt, port: MergeUndoPort): Promise<UnitUndoExecution>;
+//# sourceMappingURL=undo-merge.d.ts.map

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@lmzhen/dsh-evolution-merge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Skill auto-merge domain: screening, two-round authoring, queues and commit orchestration (community build)",
+  "version": "0.28.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmzhen/dsh-evolution.git",
+    "directory": "packages/evolution-merge"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "@lmzhen/dsh-evolution-core": "^0.28.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@lmzhen/dsh-evolution-core": "^0.28.0"
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.1 <0.2.2-0"
+  }
+}