@lmzhen/dsh-evolution-merge 0.28.0 → 0.30.0

package/lib/types/domain/row.d.ts

@@ -0,0 +1,113 @@
+import { type MergeState } from './state.ts';
+import type { MergeDecision, MergeFailure } from '../contracts.ts';
+export interface MergeRowV2 {
+    readonly id: string;
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly state: MergeState;
+    readonly queue: 'verify' | 'pending' | 'fuse' | 'skipped';
+    readonly failure?: MergeFailure;
+    readonly decision?: MergeDecision;
+    readonly sourceRevision?: string;
+    readonly targetRevision?: string;
+    readonly runId?: string;
+    readonly unitId?: string;
+    readonly origin?: 'agent' | 'human' | 'system';
+    readonly attempts?: number;
+    readonly stagingRef?: string;
+    readonly stagingExpiresAt?: number;
+    readonly target?: {
+        readonly requested: string;
+        readonly actual?: string;
+        readonly created?: boolean;
+    };
+    readonly reason?: string;
+    readonly expired?: 'target-taken' | 'source-changed';
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export type MergeRowEvent = {
+    readonly type: 'candidate';
+    readonly a: string;
+    readonly b: string;
+    readonly at: string;
+} | {
+    readonly type: 'round1-start';
+    readonly at: string;
+} | {
+    readonly type: 'round1-keep';
+    readonly at: string;
+} | {
+    readonly type: 'round1-merge';
+    readonly approval: 'on' | 'off';
+    readonly decision?: MergeDecision;
+    readonly stagingRef?: string;
+    readonly stagingExpiresAt?: number;
+    readonly at: string;
+} | {
+    readonly type: 'round1-fail';
+    readonly failure: MergeFailure;
+    readonly at: string;
+} | {
+    readonly type: 'approve';
+    readonly runId?: string;
+    readonly at: string;
+} | {
+    readonly type: 'reject';
+    readonly at: string;
+} | {
+    readonly type: 'round2-start';
+    readonly at: string;
+} | {
+    readonly type: 'round2-fail';
+    readonly failure: MergeFailure;
+    readonly at: string;
+} | {
+    readonly type: 'round2-success';
+    readonly unitId?: string;
+    readonly at: string;
+} | {
+    readonly type: 'restore';
+    readonly at: string;
+} | {
+    readonly type: 'discard';
+    readonly at: string;
+} | {
+    readonly type: 'source-gone';
+    readonly at: string;
+} | {
+    readonly type: 'target-taken';
+    readonly at: string;
+} | {
+    readonly type: 'source-changed';
+    readonly at: string;
+} | {
+    readonly type: 'staging-expired';
+    readonly at: string;
+} | {
+    readonly type: 'round2-cancel';
+    readonly at: string;
+} | {
+    readonly type: 'timeout';
+    readonly at: string;
+} | {
+    readonly type: 'cancel';
+    readonly at: string;
+} | {
+    readonly type: 'gate-keep';
+    readonly a: string;
+    readonly b: string;
+    readonly reason?: string;
+    readonly at: string;
+};
+export type RowTransitionResult = {
+    readonly ok: true;
+    readonly row: MergeRowV2 | null;
+} | {
+    readonly ok: false;
+    readonly code: 'invalid-transition';
+    readonly message: string;
+};
+export declare function transitionRow(current: MergeRowV2 | undefined, event: MergeRowEvent): RowTransitionResult;
+//# sourceMappingURL=row.d.ts.map

package/lib/types/domain/row.js

@@ -0,0 +1,111 @@
+/** Pure v2 row transitions for G1 cutover. No IO. */
+import { pairKey, rowIdOf } from "../contracts.js";
+import { queueOf, transition as stateTransition } from "./state.js";
+function base(row, at) {
+    return {
+        id: row.id, pairKey: row.pairKey, a: row.a, b: row.b,
+        state: row.state, queue: row.queue, createdAt: row.createdAt, updatedAt: at,
+        ...(row.runId === undefined ? {} : { runId: row.runId }),
+        ...(row.unitId === undefined ? {} : { unitId: row.unitId }),
+        ...(row.origin === undefined ? {} : { origin: row.origin }),
+        ...(row.decision === undefined ? {} : { decision: row.decision }),
+        ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }),
+        ...(row.targetRevision === undefined ? {} : { targetRevision: row.targetRevision }),
+        ...(row.attempts === undefined ? {} : { attempts: row.attempts }),
+        ...(row.stagingRef === undefined ? {} : { stagingRef: row.stagingRef }),
+        ...(row.stagingExpiresAt === undefined ? {} : { stagingExpiresAt: row.stagingExpiresAt }),
+        ...(row.expired === undefined ? {} : { expired: row.expired }),
+        ...(row.target === undefined ? {} : { target: row.target }),
+        ...(row.reason === undefined ? {} : { reason: row.reason }),
+    };
+}
+function next(row, at, state, patch = {}) {
+    return { ok: true, row: { ...base(row, at), state, queue: queueOf(state), ...patch } };
+}
+function invalid(event, state) {
+    return { ok: false, code: 'invalid-transition', message: 'cannot apply ' + event.type + ' to ' + (state ?? 'no row') };
+}
+export function transitionRow(current, event) {
+    if (event.type === 'candidate') {
+        if (current !== undefined)
+            return { ok: true, row: current };
+        const key = pairKey(event.a, event.b);
+        return { ok: true, row: { id: rowIdOf(key), pairKey: key, a: event.a, b: event.b, state: 'verify', queue: 'verify', createdAt: event.at, updatedAt: event.at } };
+    }
+    if (event.type === 'source-gone')
+        return { ok: true, row: null };
+    if (event.type === 'gate-keep') {
+        if (current !== undefined)
+            return { ok: true, row: current };
+        const key = pairKey(event.a, event.b);
+        return { ok: true, row: { id: rowIdOf(key), pairKey: key, a: event.a, b: event.b, state: 'skipped', queue: 'skipped', origin: 'agent', createdAt: event.at, updatedAt: event.at } };
+    }
+    if (current === undefined)
+        return invalid(event, undefined);
+    if (event.type === 'discard') {
+        return current.state === 'pending' || current.state === 'approved' || current.state === 'fuse'
+            ? { ok: true, row: null }
+            : invalid(event, current.state);
+    }
+    if (event.type === 'restore') {
+        return current.state === 'skipped' ? next(current, event.at, 'verify') : invalid(event, current.state);
+    }
+    if (event.type === 'target-taken' || event.type === 'source-changed') {
+        return current.state === 'pending' || current.state === 'approved' || current.state === 'fuse'
+            ? next(current, event.at, current.state, { expired: event.type })
+            : invalid(event, current.state);
+    }
+    if (event.type === 'staging-expired') {
+        return current.state === 'fuse' || current.state === 'approved'
+            ? next(current, event.at, 'approved')
+            : invalid(event, current.state);
+    }
+    if (event.type === 'round2-cancel' || event.type === 'timeout' || event.type === 'cancel') {
+        return current.state === 'fuse' ? next(current, event.at, 'approved') : { ok: true, row: current };
+    }
+    const mapped = event.type === 'round2-success'
+        ? { type: 'round2-merged' }
+        : event.type === 'round2-fail'
+            ? { type: 'round2-fail' }
+            : event.type === 'round1-merge'
+                ? { type: 'round1-merge', approval: event.approval === 'on' }
+                : event.type === 'round1-start'
+                    ? { type: 'round1-start' }
+                    : event.type === 'round2-start'
+                        ? { type: 'round2-start' }
+                        : event.type === 'round1-keep'
+                            ? { type: 'round1-keep' }
+                            : event.type === 'round1-fail'
+                                ? { type: 'round1-fail' }
+                                : event.type === 'approve'
+                                    ? { type: 'approve' }
+                                    : { type: 'reject' };
+    const moved = stateTransition(current.state, mapped);
+    if (!moved.ok)
+        return invalid(event, current.state);
+    if (moved.state === null)
+        return { ok: true, row: null };
+    const patch = {};
+    if (event.type === 'round1-merge') {
+        if (event.decision !== undefined)
+            patch.decision = event.decision;
+        if (event.stagingRef !== undefined)
+            patch.stagingRef = event.stagingRef;
+        if (event.stagingExpiresAt !== undefined)
+            patch.stagingExpiresAt = event.stagingExpiresAt;
+    }
+    if (event.type === 'approve' && event.runId !== undefined)
+        patch.runId = event.runId;
+    if (event.type === 'round1-fail' || event.type === 'round2-fail') {
+        patch.failure = event.failure;
+        patch.attempts = (current.attempts ?? 0) + 1;
+    }
+    if (event.type === 'round1-keep')
+        patch.origin = 'agent';
+    if (event.type === 'reject')
+        patch.origin = 'human';
+    if (event.type === 'round2-success' && event.unitId !== undefined)
+        patch.unitId = event.unitId;
+    return next(current, event.at, moved.state, patch);
+}
+//# sourceMappingURL=row.js.map

package/lib/types/domain/run-record.d.ts

@@ -0,0 +1,45 @@
+/** Pure RunRecord v2 types and derived 9-state projection. No IO. */
+export type RunStatus = 'running' | 'succeeded' | 'failed' | 'cancelled' | 'interrupted' | 'orphan';
+export type MergeStatus = 'running' | 'succeeded' | 'failed' | 'cancelled' | 'awaiting-approval' | 'undone' | 'superseded' | 'interrupted' | 'orphan';
+export type PairResult = 'pending' | 'merged' | 'kept' | 'failed' | 'cancelled' | 'undone';
+export interface PairRecord {
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly result: PairResult;
+    readonly target?: {
+        readonly requested: string;
+        readonly actual?: string;
+        readonly created?: boolean;
+    };
+    readonly stagingRef?: string;
+    readonly committed?: boolean;
+}
+export interface PairIndexEntry {
+    readonly pairKey: string;
+    readonly runId: string;
+    readonly result: PairResult;
+    readonly target?: string;
+    readonly reportRef?: string;
+}
+export interface RunRecordV2 {
+    readonly id: string;
+    readonly kind: 'merge';
+    readonly status: RunStatus;
+    readonly stage?: 'screening' | 'decide' | 'author' | 'commit' | 'settle';
+    readonly approval?: 'on' | 'off';
+    readonly parentRunId?: string;
+    readonly pairKey?: string;
+    readonly plane?: 'local' | 'foreign';
+    readonly startedAt: number;
+    readonly updatedAt: number;
+    readonly endedAt?: number;
+    readonly resultRef?: string;
+    readonly failure?: string;
+    readonly stagingRef?: string;
+    readonly pairs: readonly PairRecord[];
+    readonly supersededAt?: number;
+}
+export declare function deriveMergeStatus(record: RunRecordV2): MergeStatus;
+export declare function allCommittedUndone(record: RunRecordV2): boolean;
+//# sourceMappingURL=run-record.d.ts.map

package/lib/types/domain/run-record.js

@@ -0,0 +1,24 @@
+export function deriveMergeStatus(record) {
+    if (record.supersededAt !== undefined)
+        return 'superseded';
+    if (record.status === 'interrupted')
+        return 'interrupted';
+    if (record.status === 'orphan')
+        return 'orphan';
+    if (record.status === 'failed' || record.status === 'cancelled')
+        return record.status;
+    if (record.status === 'running') {
+        return record.approval === 'on' && record.pairs.some(pair => pair.result === 'pending')
+            ? 'awaiting-approval'
+            : 'running';
+    }
+    const committed = record.pairs.filter(pair => pair.committed === true);
+    if (committed.length > 0 && committed.every(pair => pair.result === 'undone'))
+        return 'undone';
+    return 'succeeded';
+}
+export function allCommittedUndone(record) {
+    const committed = record.pairs.filter(pair => pair.committed === true);
+    return committed.length > 0 && committed.every(pair => pair.result === 'undone');
+}
+//# sourceMappingURL=run-record.js.map

package/lib/types/domain/state.d.ts

@@ -0,0 +1,57 @@
+/** Pure merge decision state machine. No IO, no host imports. */
+export type MergeState = 'verify' | 'pending' | 'approved' | 'fuse' | 'skipped';
+export type MergeQueue = 'verify' | 'pending' | 'fuse' | 'skipped';
+export type MergeEvent = {
+    readonly type: 'candidate';
+} | {
+    readonly type: 'round1-start';
+} | {
+    readonly type: 'round1-keep';
+} | {
+    readonly type: 'round1-merge';
+    readonly approval: boolean;
+} | {
+    readonly type: 'round1-fail';
+} | {
+    readonly type: 'approve';
+} | {
+    readonly type: 'reject';
+} | {
+    readonly type: 'round2-start';
+} | {
+    readonly type: 'round2-fail';
+} | {
+    readonly type: 'round2-merged';
+} | {
+    readonly type: 'round2-cancel';
+} | {
+    readonly type: 'staging-expired';
+} | {
+    readonly type: 'source-gone';
+} | {
+    readonly type: 'target-taken';
+} | {
+    readonly type: 'source-changed';
+} | {
+    readonly type: 'cancel';
+} | {
+    readonly type: 'timeout';
+};
+export type TransitionResult = {
+    readonly ok: true;
+    readonly state: MergeState;
+} | {
+    readonly ok: true;
+    readonly state: null;
+    readonly removed: true;
+} | {
+    readonly ok: false;
+    readonly code: 'invalid-transition';
+    readonly message: string;
+};
+export declare function queueOf(state: MergeState): MergeQueue;
+export declare function isTerminal(state: MergeState): boolean;
+/** Single transition point; callers must not mutate fields outside this function. */
+export declare function transition(state: MergeState, event: MergeEvent): TransitionResult;
+export declare function allowedEvents(state: MergeState): readonly MergeEvent['type'][];
+//# sourceMappingURL=state.d.ts.map

package/lib/types/domain/state.js

@@ -0,0 +1,65 @@
+export function queueOf(state) {
+    switch (state) {
+        case 'verify': return 'verify';
+        case 'pending': return 'pending';
+        case 'approved':
+        case 'fuse': return 'fuse';
+        case 'skipped': return 'skipped';
+    }
+}
+export function isTerminal(state) {
+    return state === 'skipped';
+}
+function fail(state, event) {
+    return { ok: false, code: 'invalid-transition', message: 'cannot apply ' + event.type + ' to ' + state };
+}
+/** Single transition point; callers must not mutate fields outside this function. */
+export function transition(state, event) {
+    switch (event.type) {
+        case 'candidate':
+            return state === 'verify' ? { ok: true, state: 'verify' } : fail(state, event);
+        case 'round1-start':
+            return state === 'verify' ? { ok: true, state: 'verify' } : fail(state, event);
+        case 'round1-keep':
+            return state === 'verify' ? { ok: true, state: 'skipped' } : fail(state, event);
+        case 'round1-merge':
+            return state === 'verify'
+                ? { ok: true, state: event.approval ? 'pending' : 'approved' }
+                : fail(state, event);
+        case 'round1-fail':
+            return state === 'verify' ? { ok: true, state: 'verify' } : fail(state, event);
+        case 'approve':
+            return state === 'pending' ? { ok: true, state: 'approved' } : fail(state, event);
+        case 'reject':
+            return state === 'pending' || state === 'approved' || state === 'fuse'
+                ? { ok: true, state: 'skipped' }
+                : fail(state, event);
+        case 'round2-start':
+            return state === 'approved' ? { ok: true, state: 'fuse' } : fail(state, event);
+        case 'round2-fail':
+        case 'round2-cancel':
+            return state === 'fuse' || state === 'approved' ? { ok: true, state: 'approved' } : fail(state, event);
+        case 'round2-merged':
+            return state === 'fuse' || state === 'approved' ? { ok: true, state: null, removed: true } : fail(state, event);
+        case 'staging-expired':
+            return state === 'fuse' ? { ok: true, state: 'approved' } : fail(state, event);
+        case 'source-gone':
+            return { ok: true, state: null, removed: true };
+        case 'target-taken':
+        case 'source-changed':
+            return state === 'pending' ? { ok: true, state: 'pending' } : fail(state, event);
+        case 'cancel':
+        case 'timeout':
+            return state === 'verify' || state === 'approved' || state === 'fuse' ? { ok: true, state } : fail(state, event);
+    }
+}
+export function allowedEvents(state) {
+    switch (state) {
+        case 'verify': return ['candidate', 'round1-start', 'round1-keep', 'round1-merge', 'round1-fail', 'source-gone', 'cancel', 'timeout'];
+        case 'pending': return ['approve', 'reject', 'target-taken', 'source-changed', 'source-gone'];
+        case 'approved': return ['round2-start', 'reject', 'staging-expired', 'source-gone', 'cancel', 'timeout'];
+        case 'fuse': return ['round2-fail', 'round2-merged', 'round2-cancel', 'staging-expired', 'reject', 'source-gone', 'cancel', 'timeout'];
+        case 'skipped': return [];
+    }
+}
+//# sourceMappingURL=state.js.map

package/lib/types/gate-cache.js

@@ -0,0 +1,36 @@
+/**
+ * File-backed gate cache: <home>/merge/gate-cache.json.
+ * Reads are three-state; a malformed file is reported, not overwritten. Writes are one
+ * transact so two runs cannot interleave a partial cache.
+ */
+import { join } from 'node:path';
+import { probeText, transactIo } from '@lmzhen/dsh-evolution-core';
+import { GateCache } from "./ladder.js";
+export const GATE_CACHE_VERSION = 1;
+export function gateCachePath(home) {
+    return join(home, 'merge', 'gate-cache.json');
+}
+export async function loadGateCache(io, home) {
+    const probe = await probeText(io, gateCachePath(home));
+    if (probe.kind === 'absent')
+        return { cache: new GateCache() };
+    if (probe.kind === 'unknown')
+        return { cache: new GateCache(), note: probe.reason };
+    try {
+        const parsed = JSON.parse(probe.value);
+        if (parsed.schemaVersion !== GATE_CACHE_VERSION || typeof parsed.entries !== 'object' || parsed.entries === null) {
+            return { cache: new GateCache(), note: 'gate cache has an unexpected shape' };
+        }
+        return { cache: GateCache.fromObject(parsed.entries) };
+    }
+    catch (error) {
+        return { cache: new GateCache(), note: 'gate cache is not JSON: ' + (error instanceof Error ? error.message : String(error)) };
+    }
+}
+export async function saveGateCache(io, home, cache) {
+    await transactIo(io, gateCachePath(home), () => JSON.stringify({ schemaVersion: GATE_CACHE_VERSION, entries: cache.toObject() }, null, 2) + '\n');
+}
+export function hasGateCache(cache) {
+    return cache.size > 0;
+}
+//# sourceMappingURL=gate-cache.js.map

package/lib/types/index.d.ts

@@ -6,11 +6,13 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     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;
@@ -20,6 +22,7 @@ export interface MergePresentationScope {
         }, 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;
@@ -27,6 +30,7 @@ export interface MergePresentationContext {
 /** 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';
@@ -42,8 +46,9 @@ export * from './commit-receipt.ts';
 export * from './commit-execute.ts';
 export * from './undo-merge.ts';
 export * from './adapters/library.ts';
-export * from './adapters/model.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';
@@ -53,12 +58,6 @@ export * from './round2-outcome.ts';
 export * from './approve-command.ts';
 export * from './pair-command.ts';
 export * from './resume-command.ts';
-export * from './screening.ts';
-export * from './propose.ts';
-export * from './ladder.ts';
-export * from './gate-cache.ts';
-export * from './gate-filter.ts';
-export * from './screening-port.ts';
 export * from './decision.ts';
 export * from './prompts.ts';
 export * from './channel-port.ts';