@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.19

package/lib/types/domain/state-bootstrap.js

@@ -0,0 +1,267 @@
+import { readTextOrNull } from "./read-probe.js";
+/** G3 Batch -1 state bootstrap: one readiness gate, backup/journal migration. */
+import { createHash } from 'node:crypto';
+import { chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { transactIo } from '@lmzhen/dsh-evolution-core';
+import { migrateV2ToV3 } from "./migrate-v3.js";
+import { isV3Row } from "./row-v3.js";
+import { stagingIndexPath, writeStagingIndex } from "./staging-index.js";
+export function mergeStatePath(home) { return join(home, 'merge', 'merge-state.json'); }
+export function v2BackupPath(home) { return join(home, 'merge', 'merge-state.v2.bak.json'); }
+export function migrationJournalPath(home) { return join(home, 'merge', 'merge-state.migration.json'); }
+export function migrationReportPath(home) { return join(home, 'merge', 'merge-state.migration.report.json'); }
+export function quarantinePath(home) { return join(home, 'merge', 'merge-state.quarantine.json'); }
+export class StateBlockedError extends Error {
+    readiness;
+    constructor(readiness) {
+        super(readiness.ok ? 'merge state is ready' : readiness.code + ': ' + readiness.message);
+        this.name = 'StateBlockedError';
+        this.readiness = readiness;
+    }
+}
+const hash = (text) => createHash('sha256').update(text).digest('hex');
+const json = (value) => JSON.stringify(value, null, 2) + '\n';
+const now = () => new Date().toISOString();
+function blocked(code, message) { return { ok: false, code, message }; }
+function parseBody(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed !== null && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readMarker(body) {
+    const value = body.migration;
+    if (value === undefined)
+        return null;
+    if (value === null || typeof value !== 'object')
+        return null;
+    const marker = value;
+    if (marker.migratedFromV2 !== true || typeof marker.sourceSha256 !== 'string' || typeof marker.targetSha256 !== 'string' || !Array.isArray(marker.staging) || typeof marker.at !== 'string')
+        return null;
+    return marker;
+}
+function rowsSha(rows) {
+    return hash(json({ schemaVersion: 3, rows }));
+}
+async function missingIndex(io, home, staging) {
+    for (const entry of staging)
+        if (!(await io.exists(stagingIndexPath(home, entry.rowId))))
+            return entry.rowId;
+    return null;
+}
+function v3State(body) {
+    const rows = body.rows;
+    if (!Array.isArray(rows) || !rows.every(isV3Row))
+        return null;
+    return { schemaVersion: 3, rows: rows };
+}
+async function readJournal(io, home) {
+    const raw = await readTextOrNull(io, migrationJournalPath(home));
+    if (raw === null)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        if (value.version !== 1 || typeof value.sourceSha256 !== 'string' || typeof value.targetSha256 !== 'string' || !Array.isArray(value.staging))
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+async function readReport(io, home) {
+    const raw = await readTextOrNull(io, migrationReportPath(home));
+    if (raw === null)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        return value.version === 1 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeReport(io, home, report) {
+    await transactIo(io, migrationReportPath(home), () => json(report));
+}
+async function completeJournal(io, home, journal, current) {
+    if (hash(current) !== journal.targetSha256)
+        return blocked('merge-state-needs-repair', 'migration journal does not match the v3 state');
+    for (const entry of journal.staging)
+        await writeStagingIndex(io, home, entry);
+    const report = { version: 1, ready: true, migrated: false, sourceSha256: journal.sourceSha256, targetSha256: journal.targetSha256, rows: journal.rows, quarantined: journal.quarantine.length, at: now(), steps: ['journal:index', 'journal:ready'] };
+    await writeReport(io, home, report);
+    await io.remove(migrationJournalPath(home)).catch(() => { });
+    const body = parseBody(current);
+    const state = body === null ? null : v3State(body);
+    return state === null ? blocked('merge-state-needs-repair', 'v3 state is invalid') : { ok: true, schema: 3, migrated: false, state, quarantine: journal.quarantine, report };
+}
+/** Read-only readiness probe. Never migrates, never writes. */
+export async function readStateReadiness(io, home) {
+    let raw;
+    try {
+        raw = await io.readText(mergeStatePath(home));
+    }
+    catch {
+        return blocked('merge-state-needs-repair', 'state file is unreadable');
+    }
+    if (raw === null)
+        return { ok: true, schema: 3, migrated: false, state: { schemaVersion: 3, rows: [] }, quarantine: [], report: await readReport(io, home) };
+    const body = parseBody(raw);
+    if (body === null)
+        return blocked('merge-state-needs-repair', 'state file is not a JSON object');
+    const version = body.schemaVersion;
+    if (typeof version === 'number' && version > 3)
+        return blocked('merge-state-forward-only', 'state schema ' + String(version) + ' is newer than this build');
+    if (version === 3) {
+        const state = v3State(body);
+        if (state === null)
+            return blocked('merge-state-needs-repair', 'v3 state has an invalid row');
+        const journal = await readJournal(io, home);
+        const report = await readReport(io, home);
+        const marker = readMarker(body);
+        if (body.migration !== undefined && marker === null)
+            return blocked('merge-state-needs-repair', 'migration marker is invalid');
+        if (journal !== null)
+            return blocked('merge-state-migration-blocked', 'migration journal is pending');
+        if (report !== null && report.ready !== true)
+            return blocked('merge-state-migration-blocked', 'migration report is not ready');
+        if (marker !== null && rowsSha(state.rows) === marker.targetSha256) {
+            if (report === null)
+                return blocked('merge-state-migration-blocked', 'migration report is missing');
+            const missing = await missingIndex(io, home, marker.staging);
+            if (missing !== null)
+                return blocked('merge-state-migration-blocked', 'staging index is missing: ' + missing);
+        }
+        return { ok: true, schema: 3, migrated: false, state, quarantine: [], report };
+    }
+    return blocked('merge-state-migration-required', 'v2 state requires v3 migration');
+}
+/** Compatibility name for the v3 gate; 1b-2b switches the lifecycle to v4. */
+export const ensureV3Ready = ensureMergeStateReady;
+/** One readiness/migration gate; used by startup and every write entry. */
+export async function ensureMergeStateReady(io, home) {
+    let outcome;
+    let migrated = false;
+    try {
+        await transactIo(io, mergeStatePath(home), async (current) => {
+            if (current === null) {
+                outcome = { ok: true, schema: 3, migrated: false, state: { schemaVersion: 3, rows: [] }, quarantine: [], report: await readReport(io, home) };
+                return null;
+            }
+            const body = parseBody(current);
+            if (body === null) {
+                outcome = blocked('merge-state-needs-repair', 'state file is not a JSON object');
+                return current;
+            }
+            const version = body.schemaVersion;
+            if (typeof version === 'number' && version > 3) {
+                outcome = blocked('merge-state-forward-only', 'state schema ' + String(version) + ' is newer than this build');
+                return current;
+            }
+            if (version === 3) {
+                const state = v3State(body);
+                if (state === null) {
+                    outcome = blocked('merge-state-needs-repair', 'v3 state has an invalid row');
+                    return current;
+                }
+                const journal = await readJournal(io, home);
+                if (journal !== null) {
+                    outcome = await completeJournal(io, home, journal, current);
+                    return current;
+                }
+                const report = await readReport(io, home);
+                const marker = readMarker(body);
+                if (body.migration !== undefined && marker === null) {
+                    outcome = blocked('merge-state-needs-repair', 'migration marker is invalid');
+                    return current;
+                }
+                if (report !== null && report.ready !== true) {
+                    outcome = blocked('merge-state-migration-blocked', 'migration report is not ready');
+                    return current;
+                }
+                if (marker !== null && rowsSha(state.rows) === marker.targetSha256) {
+                    if (report === null) {
+                        outcome = blocked('merge-state-migration-blocked', 'migration report is missing');
+                        return current;
+                    }
+                    for (const entry of marker.staging)
+                        if (!(await io.exists(stagingIndexPath(home, entry.rowId))))
+                            await writeStagingIndex(io, home, entry);
+                }
+                outcome = { ok: true, schema: 3, migrated: false, state, quarantine: [], report };
+                return current;
+            }
+            const mapped = migrateV2ToV3(body);
+            if (!mapped.ok) {
+                outcome = blocked('merge-state-migration-blocked', mapped.message);
+                return current;
+            }
+            const sourceSha256 = hash(current);
+            const backup = v2BackupPath(home);
+            const existingBackup = await readTextOrNull(io, backup);
+            if (existingBackup !== null && existingBackup !== current) {
+                outcome = blocked('merge-state-migration-blocked', 'v2 backup exists with different bytes');
+                return current;
+            }
+            if (existingBackup === null)
+                await transactIo(io, backup, () => current);
+            try {
+                await chmod(backup, 0o444);
+            }
+            catch {
+                outcome = blocked('merge-state-migration-blocked', 'v2 backup is not read-only');
+                return current;
+            }
+            const staging = [];
+            for (const row of body.rows) {
+                if (typeof row.id !== 'string' || typeof row.pairKey !== 'string' || typeof row.stagingRef !== 'string')
+                    continue;
+                if (row.state !== 'pending' && row.state !== 'approved')
+                    continue;
+                staging.push({
+                    rowId: row.id, pairKey: row.pairKey, ref: row.stagingRef,
+                    expiresAt: typeof row.stagingExpiresAt === 'number' ? row.stagingExpiresAt : Date.now() + 7 * 86_400_000,
+                    ...(typeof row.runId === 'string' ? { runId: row.runId } : {}),
+                    createdAt: typeof row.updatedAt === 'string' && !Number.isNaN(Date.parse(row.updatedAt)) ? Date.parse(row.updatedAt) : Date.now(),
+                });
+            }
+            const marker = { migratedFromV2: true, sourceSha256, targetSha256: rowsSha(mapped.state.rows), staging, at: now() };
+            const targetText = json({ ...mapped.state, migration: marker });
+            const targetSha256 = hash(targetText);
+            const journal = { version: 1, sourceSha256, targetSha256, rows: mapped.state.rows.length, quarantine: mapped.quarantine, staging, backupPath: backup, at: now() };
+            await transactIo(io, migrationJournalPath(home), () => json(journal));
+            for (const entry of staging)
+                await writeStagingIndex(io, home, entry);
+            if (mapped.quarantine.length > 0)
+                await transactIo(io, quarantinePath(home), () => json(mapped.quarantine));
+            const prepared = { version: 1, ready: false, migrated: true, sourceSha256, targetSha256, rows: mapped.state.rows.length, quarantined: mapped.quarantine.length, backupReadOnly: true, at: now(), steps: ['backup', 'journal', 'staging-index', 'quarantine', 'v3-write'] };
+            await writeReport(io, home, prepared);
+            migrated = true;
+            outcome = { ok: true, schema: 3, migrated: true, state: mapped.state, quarantine: mapped.quarantine, report: prepared };
+            return targetText;
+        });
+    }
+    catch (error) {
+        return blocked('merge-state-migration-blocked', 'state migration failed: ' + (error instanceof Error ? error.message : String(error)));
+    }
+    if (outcome === undefined)
+        return blocked('merge-state-migration-blocked', 'state migration did not produce a result');
+    if (migrated && outcome.ok) {
+        try {
+            const report = { ...outcome.report, ready: true, at: now(), steps: ['backup', 'journal', 'staging-index', 'quarantine', 'v3-write', 'ready'] };
+            await writeReport(io, home, report);
+            await io.remove(migrationJournalPath(home)).catch(() => { });
+            outcome = { ...outcome, report };
+        }
+        catch {
+            // The v3 state is committed; leave the journal/report for the next ensure.
+        }
+    }
+    return outcome;
+}
+//# sourceMappingURL=state-bootstrap.js.map

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

@@ -0,0 +1,4 @@
+/** G3 schema-3 migration path constants; the only production gate is state-bootstrap. */
+import { v2BackupPath } from './state-bootstrap.ts';
+export { v2BackupPath };
+//# sourceMappingURL=state-v3.d.ts.map

package/lib/types/domain/state-v3.js

@@ -0,0 +1,4 @@
+/** G3 schema-3 migration path constants; the only production gate is state-bootstrap. */
+import { v2BackupPath } from "./state-bootstrap.js";
+export { v2BackupPath };
+//# sourceMappingURL=state-v3.js.map

package/lib/types/domain/undo-journal.d.ts

@@ -0,0 +1,19 @@
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+export type UndoPairPhase = 'pending' | 'restore-target' | 'restore-source' | 'receipt' | 'done';
+export interface UndoPairState {
+    readonly pairKey: string;
+    readonly unitId: string;
+    readonly phase: UndoPairPhase;
+    readonly message?: string;
+}
+export interface UndoJournal {
+    readonly version: 1;
+    readonly runId: string;
+    readonly phase: 'prepared' | 'running' | 'settled';
+    readonly pairs: readonly UndoPairState[];
+    readonly updatedAt: string;
+}
+export declare function undoJournalPath(home: string, runId: string): string;
+export declare function readUndoJournal(io: EvolutionIoLike, home: string, runId: string): Promise<UndoJournal | null>;
+export declare function writeUndoJournal(io: EvolutionIoLike, home: string, journal: UndoJournal): Promise<void>;
+//# sourceMappingURL=undo-journal.d.ts.map

package/lib/types/domain/undo-journal.js

@@ -0,0 +1,20 @@
+import { readTextOrNull } from "./read-probe.js";
+/** Per-run undo journal: one pair at a time, durable phase before each write. */
+import { join } from 'node:path';
+import { transactIo } from '@lmzhen/dsh-evolution-core';
+export function undoJournalPath(home, runId) { return join(home, 'merge', 'undo-journal', encodeURIComponent(runId) + '.json'); }
+export async function readUndoJournal(io, home, runId) {
+    const raw = await readTextOrNull(io, undoJournalPath(home, runId));
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeUndoJournal(io, home, journal) {
+    await transactIo(io, undoJournalPath(home, journal.runId), () => JSON.stringify(journal, null, 2) + '\n');
+}
+//# sourceMappingURL=undo-journal.js.map

package/lib/types/domain/undo-receipt.d.ts

@@ -0,0 +1,18 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+export interface UndoReceipt {
+    readonly version: 1;
+    readonly runId: string;
+    readonly parentRunId?: string;
+    readonly pairKey: string;
+    readonly unitId: string;
+    readonly evidenceSha256: string;
+    readonly target: string;
+    readonly sources: readonly string[];
+    readonly restoredTargetHash: string | null;
+    readonly restoredSourceHashes: Readonly<Record<string, string>>;
+    readonly at: number;
+}
+export declare function undoReceiptPath(home: string, runId: string, pairKey: string): string;
+export declare function readUndoReceipt(io: EvolutionIoLike, home: string, runId: string, pairKey: string): Promise<UndoReceipt | null>;
+export declare function writeUndoReceipt(io: EvolutionIoLike, home: string, receipt: UndoReceipt): Promise<void>;
+//# sourceMappingURL=undo-receipt.d.ts.map

package/lib/types/domain/undo-receipt.js

@@ -0,0 +1,22 @@
+import { readTextOrNull } from "./read-probe.js";
+/** Undo receipt: immutable per-pair settlement, separate from the commit receipt. */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+export function undoReceiptPath(home, runId, pairKey) {
+    return join(home, 'merge', 'undo-receipts', encodeURIComponent(runId), createHash('sha256').update(pairKey).digest('hex') + '.json');
+}
+export async function readUndoReceipt(io, home, runId, pairKey) {
+    const raw = await readTextOrNull(io, undoReceiptPath(home, runId, pairKey));
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeUndoReceipt(io, home, receipt) {
+    await io.writeText(undoReceiptPath(home, receipt.runId, receipt.pairKey), JSON.stringify(receipt, null, 2) + '\n');
+}
+//# sourceMappingURL=undo-receipt.js.map

package/lib/types/domain/validation-plan.d.ts

@@ -0,0 +1,65 @@
+import type { SkillCard } from '../skill-card.ts';
+import type { MergeLimitsSnapshot } from './merge-limits.ts';
+import type { StagedTree, RuleFinding } from '../rules.ts';
+export interface StagedFile {
+    readonly path: string;
+    readonly content: string;
+    readonly digest: string;
+    readonly bytes: number;
+}
+export interface ValidationPlan {
+    readonly planVersion: 1;
+    readonly stageDigest: string;
+    readonly target: string;
+    readonly body: string;
+    readonly files: readonly StagedFile[];
+    readonly supportFiles: readonly {
+        readonly path: string;
+        readonly digest: string;
+        readonly source: string;
+    }[];
+    readonly manifestFiles: readonly string[];
+    readonly q09: {
+        readonly forwardRefs: readonly string[];
+        readonly reverseRefs: readonly string[];
+        readonly orphanFiles: readonly string[];
+    };
+    readonly supportConflicts: readonly {
+        readonly path: string;
+        readonly sources: readonly string[];
+    }[];
+    readonly threat: {
+        readonly body: boolean;
+        readonly files: readonly string[];
+    };
+    readonly sourceRevisions: Readonly<Record<string, string>>;
+    readonly targetRevision: string | null;
+    readonly limitsDigest: string;
+    readonly promptVersion?: string;
+    readonly promptHash?: string;
+    readonly revision: string;
+    readonly findings: readonly RuleFinding[];
+}
+export declare function buildValidationPlan(input: {
+    readonly tree: StagedTree;
+    readonly target: string;
+    readonly limits: MergeLimitsSnapshot;
+    readonly cards?: readonly SkillCard[];
+    readonly sourceRevisions?: Readonly<Record<string, string>>;
+    readonly targetRevision?: string | null;
+    readonly manifestFiles?: readonly string[];
+    readonly existingSupport?: readonly string[];
+    readonly supportFiles?: readonly {
+        readonly path: string;
+        readonly content: string;
+        readonly source: string;
+    }[];
+    readonly supportSources?: readonly {
+        readonly path: string;
+        readonly content: string;
+        readonly source: string;
+    }[];
+    readonly promptVersion?: string;
+    readonly promptHash?: string;
+}): ValidationPlan;
+//# sourceMappingURL=validation-plan.d.ts.map

package/lib/types/domain/validation-plan.js

@@ -0,0 +1,49 @@
+/** Immutable post-stage validation plan: Q09/support/threat/revision facts. */
+import { createHash } from 'node:crypto';
+import { scanContentThreats, supportRefs } from '@lmzhen/dsh-evolution-core';
+function digest(value) { return createHash('sha256').update(value).digest('hex'); }
+export function buildValidationPlan(input) {
+    const files = input.tree.files.map(file => ({ path: file.path, content: file.content, digest: digest(file.content), bytes: Buffer.byteLength(file.content, 'utf8') }));
+    const manifestFiles = [...new Set(input.manifestFiles ?? files.map(file => file.path))].sort();
+    const supportFiles = (input.supportFiles ?? files.map(file => ({ path: file.path, content: file.content, source: 'staged' }))).map(file => ({ path: file.path, digest: digest(file.content), source: file.source })).sort((a, b) => a.path.localeCompare(b.path));
+    const refs = new Set(supportRefs(input.tree.body));
+    const staged = new Set(files.map(file => file.path));
+    const manifest = new Set(manifestFiles);
+    const forwardRefs = [...refs].filter(ref => !staged.has(ref)).sort();
+    const reverseRefs = files.map(file => file.path).filter(path => !refs.has(path) && manifest.has(path)).sort();
+    const existing = new Set(input.existingSupport ?? []);
+    const orphanFiles = [...existing].filter(path => !staged.has(path)).sort();
+    const byPath = new Map();
+    for (const file of input.supportSources ?? []) {
+        const entry = byPath.get(file.path) ?? { contents: new Set(), sources: [] };
+        entry.contents.add(file.content);
+        entry.sources.push(file.source);
+        byPath.set(file.path, entry);
+    }
+    const supportConflicts = [...byPath.entries()].filter(([, value]) => value.contents.size > 1).map(([path, value]) => ({ path, sources: value.sources }));
+    const sourceThreatFiles = (input.cards ?? []).flatMap(card => (card.files ?? []).filter(file => scanContentThreats(file.content) !== null).map(file => card.name + '/' + file.path));
+    const threat = { body: scanContentThreats(input.tree.body) !== null || (input.cards ?? []).some(card => scanContentThreats(card.body) !== null), files: [...files.filter(file => scanContentThreats(file.content) !== null).map(file => file.path), ...sourceThreatFiles] };
+    const sourceRevisions = input.sourceRevisions ?? Object.fromEntries((input.cards ?? []).map(card => [card.name, digest(card.body)]));
+    const revision = digest(JSON.stringify({ target: input.target, body: digest(input.tree.body), files: files.map(file => [file.path, file.digest]), q09: { forwardRefs, reverseRefs, orphanFiles }, supportConflicts, threat, sourceRevisions, targetRevision: input.targetRevision ?? null }));
+    const findings = [];
+    const stageDigest = digest(JSON.stringify(files.map(file => [file.path, file.digest])));
+    if (forwardRefs.length > 0)
+        findings.push({ rule: 'q09-forward', path: forwardRefs.join(','), severity: 'block', message: 'body references unstaged support' });
+    if (reverseRefs.length > 0)
+        findings.push({ rule: 'q09-reverse', path: reverseRefs.join(','), severity: 'block', message: 'staged manifest file is not referenced by body' });
+    if (orphanFiles.length > 0)
+        findings.push({ rule: 'q09-orphan', path: orphanFiles.join(','), severity: 'block', message: 'target tree support is not declared by plan' });
+    if (supportConflicts.length > 0)
+        findings.push({ rule: 'support-conflict', path: supportConflicts.map(item => item.path).join(','), severity: 'block', message: 'same support path has different contents' });
+    if (threat.body)
+        findings.push({ rule: 'threat', path: 'SKILL.md', severity: 'block', message: 'body tripped content threat scanner' });
+    for (const path of threat.files)
+        findings.push({ rule: 'threat', path, severity: 'block', message: 'support file tripped content threat scanner' });
+    if (Buffer.byteLength(input.tree.body, 'utf8') > input.limits.skillLimits.maxSkillFileBytes)
+        findings.push({ rule: 'limit', path: 'SKILL.md', severity: 'block', message: 'body exceeds maxSkillFileBytes' });
+    for (const file of files)
+        if (file.bytes > input.limits.skillLimits.maxSkillFileBytes)
+            findings.push({ rule: 'limit', path: file.path, severity: 'block', message: 'file exceeds maxSkillFileBytes' });
+    return { planVersion: 1, stageDigest, target: input.target, body: input.tree.body, files, supportFiles, manifestFiles, q09: { forwardRefs, reverseRefs, orphanFiles }, supportConflicts, threat, sourceRevisions, targetRevision: input.targetRevision ?? null, limitsDigest: input.limits.limitsDigest, ...(input.promptVersion === undefined ? {} : { promptVersion: input.promptVersion }), ...(input.promptHash === undefined ? {} : { promptHash: input.promptHash }), revision, findings };
+}
+//# sourceMappingURL=validation-plan.js.map

package/lib/types/facts.d.ts

@@ -0,0 +1,26 @@
+/** G5-2 Facts pure projection. Reads a snapshot; never writes. */
+import type { EvolutionIoLike, RunRecord } from '@lmzhen/dsh-evolution-core';
+import type { MergeRow } from './contracts.ts';
+import type { Facts, MergeCounts, RunView } from './wire.ts';
+import type { MergeRunMeta } from './domain/run-coordinator.ts';
+export declare function countsOf(rows: readonly MergeRow[]): MergeCounts;
+export declare function toRunView(record: RunRecord, readAt: number, meta?: MergeRunMeta | null): RunView;
+export interface FactsInput {
+    readonly rows: readonly MergeRow[];
+    readonly runs: readonly RunRecord[];
+    readonly runMeta?: ReadonlyMap<string, MergeRunMeta>;
+    readonly approval: boolean;
+    readonly readAt: number;
+    readonly notes?: readonly string[];
+}
+export interface ReadFactsOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly runs: readonly RunRecord[];
+    readonly approval: boolean;
+    readonly readAt: number;
+}
+/** GET projection: reads state + runs; never writes. */
+export declare function readFacts(options: ReadFactsOptions): Promise<Facts>;
+export declare function buildFacts(input: FactsInput): Facts;
+//# sourceMappingURL=facts.d.ts.map

package/lib/types/facts.js

@@ -0,0 +1,65 @@
+import { MERGE_COMMAND_SURFACE } from "./command-surface.js";
+import { readMergeSnapshot } from "./domain/merge-snapshot.js";
+import { buildFacts as buildSnapshotFacts } from "./surface/merge-view.js";
+const queueOf = (row) => row.state === 'approved' ? 'fuse' : row.queue;
+const isExpired = (row) => row.expired !== undefined;
+export function countsOf(rows) {
+    const active = { verify: 0, pending: 0, fuse: 0, skipped: 0 };
+    let expired = 0;
+    for (const row of rows) {
+        if (isExpired(row)) {
+            expired += 1;
+            continue;
+        }
+        active[queueOf(row)] += 1;
+    }
+    return { active, expired };
+}
+export function toRunView(record, readAt, meta = null) {
+    const state = record.state;
+    void meta;
+    return {
+        wireVersion: 1,
+        readAt,
+        id: record.id,
+        state,
+        command: record.command ?? 'scan',
+        ...(record.stage === undefined ? {} : { stage: record.stage }),
+        progress: record.progress === undefined ? null : { done: record.progress.done, total: record.progress.total },
+        startedAt: record.startedAt,
+        ...(record.endedAt === undefined ? {} : { endedAt: record.endedAt }),
+        ...(record.failure === undefined ? {} : { failure: { stage: 'settle', code: 'run-failed', retryable: false, retryFrom: 'none', detail: record.failure } }),
+        ...(record.parentRunId === undefined ? {} : { parentRunId: record.parentRunId }),
+        actions: [
+            { id: 'status', command: '/evolution merge status ' + record.id, confirm: false, enabled: true },
+            { id: 'report', command: '/evolution merge report ' + record.id, confirm: false, enabled: record.resultRef !== undefined },
+            { id: 'cancel', command: '/evolution merge cancel ' + record.id, confirm: false, enabled: state === 'running' },
+        ],
+    };
+}
+/** GET projection: reads state + runs; never writes. */
+export async function readFacts(options) {
+    const snapshot = await readMergeSnapshot({ io: options.io, home: options.home, runs: options.runs, approval: options.approval, now: () => options.readAt });
+    if (snapshot.blocked !== undefined)
+        throw new Error(snapshot.blocked.code + ': ' + snapshot.blocked.message);
+    return buildSnapshotFacts(snapshot);
+}
+export function buildFacts(input) {
+    const ordered = [...input.runs].sort((a, b) => b.startedAt - a.startedAt);
+    const active = ordered.find(run => run.state === 'running');
+    const last = ordered.find(run => run.state !== 'running');
+    const notes = input.notes ?? [];
+    return {
+        wireVersion: 1,
+        readAt: input.readAt,
+        approval: { mergeApproval: input.approval },
+        counts: countsOf(input.rows),
+        active: active === undefined ? null : toRunView(active, input.readAt, input.runMeta?.get(active.id) ?? null),
+        last: last === undefined ? null : toRunView(last, input.readAt, input.runMeta?.get(last.id) ?? null),
+        startCommands: { scan: '/evolution merge scan', pair: '/evolution merge pair <a> <b>' },
+        fallback: MERGE_COMMAND_SURFACE.fallback,
+        notes,
+        degraded: notes.length > 0,
+    };
+}
+//# sourceMappingURL=facts.js.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