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

package/lib/types/adapters/channel.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Adapt the platform SubagentChannel to the merge ConversationChannelLike. The optional
+ * two-turn methods are checked at call time so an older channel degrades to E-323 instead
+ * of throwing a TypeError.
+ */
+import type { ConversationChannelLike } from '../channel-port.ts';
+interface PlatformTurn {
+    readonly childId: unknown;
+    readonly stopReason: string;
+    readonly text: string;
+}
+type PlatformOutcome = {
+    readonly kind: 'ok';
+    readonly childId: unknown;
+    readonly turn: PlatformTurn;
+} | {
+    readonly kind: 'unavailable';
+    readonly code: string;
+    readonly reason: string;
+} | {
+    readonly kind: 'aborted';
+};
+export interface SubagentChannelLike {
+    open?(spec: {
+        parent: unknown;
+        label: string;
+        promptText: string;
+        kind: 'reviewer' | 'maintainer';
+        allow: readonly string[];
+        cwd?: string;
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }): Promise<PlatformOutcome>;
+    continueTurn?(childId: string, promptText: string, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<PlatformOutcome>;
+    dispose?(childId: string): Promise<void>;
+}
+export declare function subagentChannelAdapter(channel: SubagentChannelLike): ConversationChannelLike;
+export {};
+//# sourceMappingURL=channel.d.ts.map

package/lib/types/adapters/library.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Library adapter: the only place the merge domain touches SkillLibrary's commit kernel.
+ * The domain stays port-shaped; this file is the composition seam.
+ */
+import type { SkillLibrary } from '@lmzhen/dsh-evolution-core';
+import type { CommitPort } from '../commit-execute.ts';
+export declare function skillLibraryPort(skills: SkillLibrary): CommitPort;
+//# sourceMappingURL=library.d.ts.map

package/lib/types/adapters/model.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Structural ModelPort adapter over the platform llm service. The platform exposes either
+ * `stream()` (the current shape) or the older prepareCall()/stream pair; both return raw text
+ * because the gate and proposer own JSON extraction.
+ */
+import type { ModelPort } from '../propose.ts';
+export interface ModelRoute {
+    readonly provider: string;
+    readonly model: string;
+}
+export interface LlmChunkLike {
+    readonly type: string;
+    readonly text?: string;
+    readonly usage?: unknown;
+    readonly reason?: {
+        readonly kind?: string;
+        readonly failure?: {
+            readonly message?: string;
+        };
+    };
+}
+export interface LlmCallLike {
+    readonly config: Record<string, unknown>;
+    stream(input: Record<string, unknown>): AsyncIterable<LlmChunkLike>;
+}
+export interface LlmServiceLike {
+    prepareCall?(config: Record<string, unknown>, signal?: AbortSignal): Promise<LlmCallLike>;
+    stream?(options: Record<string, unknown>): AsyncIterable<LlmChunkLike>;
+}
+export declare function createModelPort(llm: LlmServiceLike, route: () => ModelRoute): ModelPort;
+//# sourceMappingURL=model.d.ts.map

package/lib/types/adapters/undo.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SkillLibrary-backed undo sink. Blobs are content-addressed but the library exposes them by
+ * version, so the first readBlob call indexes all version bodies once; an undo is rare enough
+ * that this is preferable to adding a second hash index.
+ */
+import { type SkillLibrary } from '@lmzhen/dsh-evolution-core';
+import type { MergeUndoPort } from '../undo-merge.ts';
+export declare function skillLibraryUndoPort(skills: SkillLibrary): MergeUndoPort;
+//# sourceMappingURL=undo.d.ts.map

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

@@ -0,0 +1,22 @@
+/**
+ * approve command: one pending row is atomically taken to fuse, then a new run executes
+ * round2 with the persisted decision. A second approve loses at approvePending (not-pending).
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { MergeDecision, MergeRow } from './contracts.ts';
+import type { MergeRegistryPort, WithMergeRunResult } from './run-shell.ts';
+import type { ScanRound2Outcome } from './scan-run.ts';
+export interface ApprovePorts {
+    round2(row: MergeRow, decision: MergeDecision, signal: AbortSignal, runId: string): Promise<ScanRound2Outcome>;
+}
+export interface RunApproveCommandOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly registry: MergeRegistryPort;
+    readonly ports: ApprovePorts;
+    readonly rowId: string;
+    readonly platformWrite: boolean;
+    readonly now: () => number;
+}
+export declare function runApproveCommand(options: RunApproveCommandOptions): Promise<WithMergeRunResult>;
+//# sourceMappingURL=approve-command.d.ts.map

package/lib/types/authoring-flow.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Authoring flow: create the staging tree, let the author write it, run the deterministic
+ * rule gate, then commit through the injected CommitPort. The channel adapter and the
+ * author tool live outside; this is the seam they share.
+ */
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type RuleFinding } from './rules.ts';
+import { type CommitPort, type CommitStagedResult } from './commit-execute.ts';
+import type { StagedTree } from './rules.ts';
+import type { SkillCard } from './screening.ts';
+export interface RunAuthoringOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly runId: string;
+    readonly target: string;
+    readonly cards: readonly SkillCard[];
+    readonly author: (staging: {
+        readonly home: string;
+        readonly runId: string;
+    }) => Promise<string>;
+    readonly commitPort: CommitPort;
+    readonly now: () => number;
+    readonly summary: string;
+}
+export type AuthoringResult = {
+    readonly ok: true;
+    readonly tree: StagedTree;
+    readonly commit: CommitStagedResult;
+} | {
+    readonly ok: false;
+    readonly message: string;
+    readonly findings?: readonly RuleFinding[];
+};
+export declare function runAuthoring(options: RunAuthoringOptions): Promise<AuthoringResult>;
+//# sourceMappingURL=authoring-flow.d.ts.map

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

@@ -0,0 +1,60 @@
+/**
+ * Channel adapter for round 1. It opens the merged child, parses the decision, and exposes
+ * an author callback for round 2 when the same child continues. Commit is deliberately
+ * outside this adapter: the caller owns staging -> commitStagedRun.
+ */
+import type { MergeDecision, MergeRow } from './contracts.ts';
+import type { SkillCard } from './screening.ts';
+import type { ScanRound1Outcome } from './scan-run.ts';
+export interface ChannelTurnLike {
+    readonly text: string;
+    readonly stopReason: string;
+}
+export type ChannelTurnOutcome = {
+    readonly kind: 'ok';
+    readonly childId: string;
+    readonly turn: ChannelTurnLike;
+} | {
+    readonly kind: 'unavailable';
+    readonly code: string;
+    readonly reason: string;
+} | {
+    readonly kind: 'aborted';
+};
+export interface ConversationChannelLike {
+    open(spec: {
+        readonly parent: unknown;
+        readonly label: string;
+        readonly promptText: string;
+        readonly kind: 'reviewer' | 'maintainer';
+        readonly allow: readonly string[];
+        readonly cwd?: string;
+        readonly timeoutMs: number;
+        readonly signal?: AbortSignal;
+    }): Promise<ChannelTurnOutcome>;
+    continueTurn(childId: string, promptText: string, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<ChannelTurnOutcome>;
+    dispose(childId: string): Promise<void>;
+}
+export interface ChannelRound1Options {
+    readonly channel: ConversationChannelLike;
+    readonly parent: unknown;
+    readonly cards: readonly SkillCard[];
+    readonly allow: readonly string[];
+    readonly cwd?: string;
+    readonly timeoutMs: number;
+}
+export interface ChannelRound1Result {
+    readonly outcome: ScanRound1Outcome;
+    readonly childId?: string;
+    /** Same-child round 2; absent for keep/fail/unavailable. */
+    readonly author?: (row: MergeRow, decision: MergeDecision, signal: AbortSignal) => Promise<string>;
+    readonly dispose: () => Promise<void>;
+}
+export declare function runRound1OverChannel(options: ChannelRound1Options, candidate: {
+    readonly a: string;
+    readonly b: string;
+}, signal: AbortSignal): Promise<ChannelRound1Result>;
+//# sourceMappingURL=channel-port.d.ts.map

package/lib/types/commands.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Pure command-surface parser for the /evolution merge prefix. The command layer only
+ * validates shape; run/state effects are injected by the host shell.
+ */
+export type MergeCliCommand = {
+    readonly verb: 'scan';
+} | {
+    readonly verb: 'pair';
+    readonly a: string;
+    readonly b: string;
+} | {
+    readonly verb: 'status';
+    readonly id?: string;
+} | {
+    readonly verb: 'report';
+    readonly id?: string;
+} | {
+    readonly verb: 'cancel';
+    readonly id?: string;
+} | {
+    readonly verb: 'runs';
+} | {
+    readonly verb: 'doctor';
+} | {
+    readonly verb: 'pending';
+} | {
+    readonly verb: 'approve';
+    readonly id: string;
+} | {
+    readonly verb: 'reject';
+    readonly id: string;
+} | {
+    readonly verb: 'resume';
+    readonly id?: string;
+    readonly clear?: string;
+} | {
+    readonly verb: 'skipped';
+    readonly restore?: string;
+} | {
+    readonly verb: 'undo';
+    readonly target: string;
+    readonly run: string;
+};
+export type ParseMergeCommandResult = {
+    readonly ok: true;
+    readonly command: MergeCliCommand;
+    readonly help?: boolean;
+} | {
+    readonly ok: false;
+    readonly code: 'usage';
+    readonly message: string;
+};
+export declare function parseMergeCommand(argv: readonly string[]): ParseMergeCommandResult;
+export declare function mergeUsage(): string;
+//# sourceMappingURL=commands.d.ts.map

package/lib/types/commit-assembly.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Turn a fully written staging tree into a CommitMergePlan.
+ *
+ * Source bodies come from the LIVE tree (the plan's CAS baseline), the target body from
+ * the merged tree. This function is pure except for the injected reads; it never commits.
+ */
+import type { CommitMergePlan, WriteOrigin } from '@lmzhen/dsh-evolution-core';
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+export interface CommitAssemblyPort {
+    /** Current SKILL.md body, or null when the skill is not live. */
+    readSkill(name: string): Promise<string | null>;
+}
+export interface CommitAssemblyOptions {
+    readonly origin: WriteOrigin;
+    readonly summary: string;
+}
+export type CommitAssemblyResult = {
+    readonly ok: true;
+    readonly plan: CommitMergePlan;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function assembleStagedCommit(io: EvolutionIoLike, home: string, runId: string, port: CommitAssemblyPort, options: CommitAssemblyOptions): Promise<CommitAssemblyResult>;
+//# sourceMappingURL=commit-assembly.d.ts.map

package/lib/types/commit-execute.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Execute one staged merge: assemble the plan, call the host commit port, then write the
+ * receipt. A failed commit returns without a receipt; a landed commit with a failed receipt
+ * stays successful and carries a warning.
+ */
+import type { CommitMergePlan, CommitMergeResult, EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type CommitAssemblyPort } from './commit-assembly.ts';
+import { type CommitReceipt } from './commit-receipt.ts';
+export interface CommitPort extends CommitAssemblyPort {
+    commitMerge(plan: CommitMergePlan): Promise<CommitMergeResult>;
+}
+export interface CommitStagedOptions {
+    readonly origin: CommitMergePlan['origin'];
+    readonly summary: string;
+    readonly now: () => number;
+}
+export type CommitStagedResult = {
+    readonly ok: true;
+    readonly plan: CommitMergePlan;
+    readonly result: CommitMergeResult;
+    readonly receipt?: CommitReceipt;
+    readonly warning?: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+    readonly plan?: CommitMergePlan;
+};
+export declare function commitStagedRun(io: EvolutionIoLike, home: string, runId: string, port: CommitPort, options: CommitStagedOptions): Promise<CommitStagedResult>;
+//# sourceMappingURL=commit-execute.d.ts.map

package/lib/types/commit-plan.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure commit-plan assembly for a staged merge tree.
+ *
+ * The control plane has already chosen the target name and the child wrote merged/<target>/.
+ * This module only turns those bytes into a CommitMergePlan; it never reads the live tree and
+ * never decides whether a merge is allowed (validateStagedTree does that).
+ */
+import type { CommitMergePlan, WriteOrigin } from '@lmzhen/dsh-evolution-core';
+export type ResolveTargetResult = {
+    readonly ok: true;
+    readonly name: string;
+    readonly suffix: number;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** Pick the first free target: requested, then -v2, -v3, ... (never truncate a name). */
+export declare function resolveTargetName(requested: string, exists: (name: string) => boolean): ResolveTargetResult;
+/** Rewrite only the frontmatter name; body bytes stay otherwise intact. */
+export declare function rewriteFrontmatterName(body: string, name: string): string;
+export interface BuildCommitPlanInput {
+    readonly target: string;
+    readonly create: boolean;
+    readonly mergedBody: string;
+    readonly mergedFiles: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+    readonly targetCurrent: string | null;
+    readonly sourceBodies: readonly {
+        readonly name: string;
+        readonly body: string;
+    }[];
+    readonly origin: WriteOrigin;
+    readonly summary: string;
+}
+export type BuildCommitPlanResult = {
+    readonly ok: true;
+    readonly plan: CommitMergePlan;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function buildCommitPlan(input: BuildCommitPlanInput): BuildCommitPlanResult;
+//# sourceMappingURL=commit-plan.d.ts.map

package/lib/types/commit-receipt.d.ts

@@ -0,0 +1,14 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+export interface CommitReceipt {
+    readonly runId: string;
+    readonly unitId: string;
+    readonly target: string;
+    readonly create: boolean;
+    readonly sources: readonly string[];
+    readonly archived: readonly string[];
+    readonly at: number;
+}
+export declare function commitReceiptPath(home: string, runId: string): string;
+export declare function writeCommitReceipt(io: EvolutionIoLike, home: string, receipt: CommitReceipt): Promise<string>;
+export declare function readCommitReceipt(io: EvolutionIoLike, home: string, runId: string): Promise<CommitReceipt | null>;
+//# sourceMappingURL=commit-receipt.d.ts.map

package/lib/types/contracts.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Frozen merge-domain vocabulary. No io, no host, no imports from the plugin shell.
+ *
+ * The data layer keeps four states; the user face collapses verify/fuse into one retry
+ * queue and keeps the stage as a chip. The API queue must never expose the raw state.
+ */
+export declare const MERGE_STATE_VERSION = 1;
+export type MergePairState = 'verify' | 'pending' | 'fuse' | 'skipped';
+export type MergeQueue = 'pending' | 'retry' | 'skipped';
+export type MergeStage = 'verify' | 'decide' | 'author' | 'commit';
+export type MergeCommand = 'scan' | 'pair' | 'approve' | 'resume';
+export declare const MERGE_PAIR_STATES: readonly MergePairState[];
+export declare const MERGE_QUEUES: readonly MergeQueue[];
+/** User-facing queue of one data state. verify/fuse share retry, not two tabs. */
+export declare function queueOf(state: MergePairState): MergeQueue;
+/** Coarse stage chip; skipped has no active stage. */
+export declare function stageOf(state: MergePairState): MergeStage | null;
+/** Stable pair identity; NUL cannot appear in a skill name. */
+export declare function pairKey(a: string, b: string): string;
+/** Deterministic, URL-safe id derived from the pair key (FNV-1a 32). */
+export declare function rowIdOf(key: string): string;
+export interface MergeFailure {
+    readonly stage: 'screening' | 'decide' | 'author' | 'validate' | 'commit';
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly retryFrom: 'agent1' | 'agent2' | 'none';
+}
+/** One persisted pair. The id is stable for the UI; the pairKey is the natural key. */
+export interface MergeGateFact {
+    readonly level: 'L0' | 'L1' | 'L2';
+    readonly verdict: 1 | 0 | -1;
+    readonly reason: string;
+    readonly cached?: boolean;
+    readonly auditOverride?: boolean;
+}
+export interface MergeCandidate {
+    readonly a: string;
+    readonly b: string;
+    readonly score?: number;
+    readonly arms?: readonly string[];
+    readonly reason?: string;
+    readonly gate?: MergeGateFact;
+    readonly source?: 'lexical' | 'proposed';
+}
+export interface MergeDecision {
+    readonly shouldMerge: boolean;
+    readonly mode: 'merge-into-existing' | 'create-umbrella' | 'keep';
+    readonly target: string;
+    readonly sources: readonly string[];
+    readonly rationale: string;
+    readonly confidence?: number;
+}
+export interface MergeUsage {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly totalTokens?: number;
+    readonly costCny?: number;
+}
+export interface MergeTiming {
+    readonly screeningMs?: number;
+    readonly gateMs?: number;
+    readonly agentMs?: number;
+    readonly commitMs?: number;
+}
+export type MergeRunCommand = MergeCommand;
+export interface MergeReportPair {
+    readonly id: string;
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly queue: MergeQueue;
+    readonly candidate?: MergeCandidate;
+    readonly gate?: MergeGateFact;
+    readonly decision?: MergeDecision;
+    readonly outcome: 'merged' | 'kept' | 'pending' | 'failed' | 'cancelled';
+    readonly target?: {
+        readonly requested: string;
+        readonly actual: string;
+        readonly created: boolean;
+    };
+    readonly archived: readonly string[];
+    readonly unitId?: string;
+    readonly failure?: MergeFailure;
+    readonly usage?: MergeUsage;
+    readonly timing?: MergeTiming;
+}
+export interface MergeReport {
+    readonly schemaVersion: 1;
+    readonly runId: string;
+    readonly kind: 'merge';
+    readonly command: MergeRunCommand;
+    readonly startedAt: number;
+    readonly endedAt: number;
+    readonly stopReason: 'completed' | 'failed' | 'cancelled' | 'timeout';
+    readonly approval: {
+        readonly platformWrite: boolean;
+        readonly mergeApproval: boolean;
+    };
+    readonly scope: {
+        readonly candidatePairs: number;
+        readonly queueBefore: Record<MergeQueue, number>;
+    };
+    readonly pairs: readonly MergeReportPair[];
+    readonly totals: Record<'merged' | 'kept' | 'pending' | 'failed', number>;
+    readonly notes: readonly string[];
+    readonly remaining?: readonly {
+        readonly pairKey: string;
+        readonly queue: MergeQueue;
+    }[];
+}
+export interface MergeRow {
+    readonly id: string;
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly state: MergePairState;
+    readonly queue: MergeQueue;
+    readonly failure?: MergeFailure;
+    /** Round-1 decision, persisted for the later approve round. */
+    readonly decision?: MergeDecision;
+    readonly runId?: string;
+    readonly unitId?: string;
+    readonly origin?: 'agent' | 'human';
+    readonly attempts?: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface MergeState {
+    readonly schemaVersion: typeof MERGE_STATE_VERSION;
+    readonly rows: readonly MergeRow[];
+}
+export declare function emptyMergeState(): MergeState;
+/** One record can be retried only when the failure says so and names a stage. */
+export declare function canRetry(record: Pick<MergeRow, 'state' | 'failure'>): boolean;
+//# sourceMappingURL=contracts.d.ts.map

package/lib/types/coordinator.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Pure merge transition table. No io, no run shell, no subagents.
+ *
+ * Every transition returns the whole next row (or a drop), so the caller can persist it
+ * through mutateMergeState in one transaction. Invalid transitions are refused by name;
+ * a caller never "repairs" a row by guessing which state the operator meant.
+ */
+import { type MergeDecision, type MergeFailure, type MergeRow } from './contracts.ts';
+export type MergeEvent = {
+    readonly type: 'candidate';
+    readonly a: string;
+    readonly b: string;
+    readonly at: string;
+} | {
+    readonly type: 'round1-keep';
+    readonly at: string;
+} | {
+    readonly type: 'round1-merge';
+    readonly approval: 'on' | 'off';
+    readonly decision?: MergeDecision;
+    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-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: 'source-gone';
+    readonly at: string;
+};
+export type TransitionResult = {
+    readonly ok: true;
+    readonly row: MergeRow | null;
+} | {
+    readonly ok: false;
+    readonly code: 'invalid-transition';
+    readonly message: string;
+};
+export declare function transition(current: MergeRow | undefined, event: MergeEvent): TransitionResult;
+//# sourceMappingURL=coordinator.d.ts.map

package/lib/types/decision.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Round-1 decision parser. The child returns text; the plugin owns strict shape checks.
+ * Accepts a whole JSON object or a fenced json block; everything else is decision-invalid.
+ */
+import type { MergeDecision } from './contracts.ts';
+export type DecisionParse = {
+    readonly ok: true;
+    readonly decision: MergeDecision;
+} | {
+    readonly ok: false;
+    readonly code: 'decision-invalid';
+    readonly message: string;
+};
+export declare function parseDecision(text: string | undefined, pair: {
+    readonly a: string;
+    readonly b: string;
+}): DecisionParse;
+//# sourceMappingURL=decision.d.ts.map

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): 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/gate-filter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Gate filter: turn lexical/proposed candidates into the candidates scan may process.
+ * L0 keeps are dropped unless the deterministic 10% audit re-runs L2 and overrides.
+ */
+import type { MergeCandidate } from './contracts.ts';
+import { type GateCache, type GateFacts, type GateModelPort, type GateVerdict } from './ladder.ts';
+export interface GateFilterOptions {
+    readonly facts: readonly GateFacts[];
+    readonly model: GateModelPort;
+    readonly modelName: string;
+    readonly signal: AbortSignal;
+    readonly runSeed: string;
+    readonly cache?: GateCache;
+    readonly auditRate?: number;
+}
+export interface GateDecision {
+    readonly candidate: MergeCandidate;
+    readonly verdicts: readonly GateVerdict[];
+    readonly auditOverride: boolean;
+}
+export interface GateFilterResult {
+    readonly kept: readonly GateDecision[];
+    readonly dropped: readonly GateDecision[];
+    readonly errors: readonly {
+        readonly candidate: MergeCandidate;
+        readonly message: string;
+    }[];
+    readonly calls: number;
+}
+export declare function filterCandidates(candidates: readonly MergeCandidate[], options: GateFilterOptions): Promise<GateFilterResult>;
+//# sourceMappingURL=gate-filter.d.ts.map