@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.19

package/lib/types/domain/stage-aggregate.d.ts

@@ -0,0 +1,96 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type StagingEntry } from './staging-index.ts';
+import { readStaging, type CreateStagingInput, type CreateStagingResult } from '../staging.ts';
+/**
+ * Old production staging writers (grep baseline at Batch 1b-1). Their production
+ * path is merge/staging-index + runs/<runId>/pairs/<hash>. adoptLegacy must never
+ * call any of these; it only writes merge/.shadow/staging-index.
+ */
+export declare const LEGACY_STAGING_WRITER_FILES: readonly ["src/scan-ports.ts", "src/scan-run.ts", "src/staging.ts", "src/new-child-authoring.ts", "src/domain/staging-index.ts", "src/state.ts", "src/domain/state-bootstrap.ts"];
+export type StageState = 'reserved' | 'present' | 'expired' | 'lost';
+export interface StageEntry {
+    readonly version: 1;
+    readonly rowId: string;
+    readonly pairKey: string;
+    readonly runId?: string;
+    readonly ref: string;
+    readonly root?: string;
+    readonly manifestPath?: string;
+    readonly state: StageState;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+    readonly updatedAt: number;
+    readonly sourceDigest?: string;
+    readonly targetDigest?: string;
+    readonly manifestDigest?: string;
+    readonly sourceRevision?: string;
+    readonly targetRevision?: string;
+    readonly files?: readonly string[];
+}
+export interface ShadowAdoptResult {
+    readonly entries: readonly StageEntry[];
+    readonly anomalies: readonly string[];
+    readonly shadowPath: string;
+    readonly wrote: boolean;
+}
+export interface StageAggregateRead {
+    readonly entries: readonly StageEntry[];
+    readonly shadowPath: string;
+}
+export declare function shadowStagingIndexPath(home: string, rowId: string): string;
+export declare function shadowStagingRoot(home: string): string;
+/** Read-only adoption into the shadow index; never writes production staging-index. */
+export declare function adoptLegacy(io: EvolutionIoLike, home: string): Promise<ShadowAdoptResult>;
+export declare function readShadowStageAggregate(io: EvolutionIoLike, home: string, rowId?: string): Promise<StageAggregateRead>;
+/** 1b-2b execution order; kept here so 1b-2a tests can pin the contract. */
+export declare const STAGE_WRITE_ORDER: readonly ["index:reserved", "tree", "index:present"];
+export type StageAdmission = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function admitStage(rowState: string): StageAdmission;
+export type ApprovedReservedPlan = {
+    readonly kind: 'transition-fuse';
+    readonly rowId: string;
+    readonly ref: string;
+    readonly expiresAt: number;
+} | {
+    readonly kind: 'write-present';
+    readonly rowId: string;
+    readonly ref: string;
+} | {
+    readonly kind: 'drop-orphan';
+    readonly rowId: string;
+} | {
+    readonly kind: 'none';
+};
+export declare function planApprovedReserved(rowState: string, entry: StageEntry | null): ApprovedReservedPlan;
+/** Production adoption for 1b-2b normalize; writes the existing staging-index, not shadow. */
+export declare function adoptLegacyProduction(io: EvolutionIoLike, home: string): Promise<ShadowAdoptResult>;
+/** Production stage-tree facade. These wrappers keep the low-level tree module private to StageAggregate. */
+export declare function ensureStageTree(io: EvolutionIoLike, home: string, input: CreateStagingInput): Promise<CreateStagingResult>;
+export declare function createStageTree(io: EvolutionIoLike, home: string, input: CreateStagingInput): Promise<CreateStagingResult>;
+export declare function readStageTree(io: EvolutionIoLike, home: string, runId: string): Promise<Awaited<ReturnType<typeof readStaging>>>;
+export declare function setStageTreeTarget(io: EvolutionIoLike, home: string, stageKey: string, target: string, mode?: 'merge-into-existing' | 'create-umbrella' | 'keep'): Promise<boolean>;
+export declare function dropStageTree(io: EvolutionIoLike, home: string, stageKey: string): Promise<void>;
+export declare function writeStageIndex(io: EvolutionIoLike, home: string, entry: StagingEntry): Promise<void>;
+export declare function readStageIndex(io: EvolutionIoLike, home: string, rowId: string, now?: number): Promise<StagingEntry | null>;
+export declare function readStageEntry(io: EvolutionIoLike, home: string, rowId: string): Promise<StageEntry | null>;
+export declare function reserveStage(io: EvolutionIoLike, home: string, entry: StageEntry): Promise<void>;
+export declare function presentStage(io: EvolutionIoLike, home: string, entry: StageEntry): Promise<void>;
+export declare function dropStage(io: EvolutionIoLike, home: string, rowId: string, ref?: string): Promise<void>;
+export interface StageCleanupResult {
+    readonly removed: readonly string[];
+    readonly expired: readonly string[];
+    readonly kept: readonly string[];
+    readonly orphans: readonly string[];
+}
+/** Bounded cleanup: reserved/present TTL, pending/verify stale index removal, terminal/absent rows, orphan trees. */
+export declare function cleanupStage(io: EvolutionIoLike, home: string, now: number, rows: ReadonlyMap<string, {
+    readonly state: string;
+}>, limit?: number): Promise<StageCleanupResult>;
+/** Read all production v2 stage entries. */
+export declare function readAllStages(io: EvolutionIoLike, home: string): Promise<readonly StageEntry[]>;
+//# sourceMappingURL=stage-aggregate.d.ts.map

package/lib/types/domain/stage-aggregate.js

@@ -0,0 +1,293 @@
+import { readTextOrNull, listOrEmpty } from "./read-probe.js";
+/** 1b-1 shadow staging adoption. Production staging is still owned by the old staged writers. */
+import { join } from 'node:path';
+import { readPairLedger } from "./pair-ledger.js";
+import { readStagingIndex, writeStagingIndex } from "./staging-index.js";
+import { createStaging, dropStaging, ensureStaging, readStaging, setStagingTarget } from "../staging.js";
+/**
+ * Old production staging writers (grep baseline at Batch 1b-1). Their production
+ * path is merge/staging-index + runs/<runId>/pairs/<hash>. adoptLegacy must never
+ * call any of these; it only writes merge/.shadow/staging-index.
+ */
+export const LEGACY_STAGING_WRITER_FILES = [
+    'src/scan-ports.ts',
+    'src/scan-run.ts',
+    'src/staging.ts',
+    'src/new-child-authoring.ts',
+    'src/domain/staging-index.ts',
+    'src/state.ts',
+    'src/domain/state-bootstrap.ts',
+];
+export function shadowStagingIndexPath(home, rowId) {
+    return join(home, 'merge', '.shadow', 'staging-index', encodeURIComponent(rowId) + '.json');
+}
+export function shadowStagingRoot(home) {
+    return join(home, 'merge', '.shadow', 'staging-index');
+}
+function stagingTreePath(home, ref) {
+    return join(home, 'merge', 'runs', ref);
+}
+function markerStaging(migration) {
+    if (migration === null || typeof migration !== 'object')
+        return [];
+    const value = migration;
+    if (!Array.isArray(value.staging))
+        return [];
+    const facts = [];
+    for (const item of value.staging) {
+        if (item === null || typeof item !== 'object')
+            continue;
+        const entry = item;
+        if (typeof entry.rowId !== 'string' || typeof entry.pairKey !== 'string' || typeof entry.ref !== 'string' || typeof entry.expiresAt !== 'number' || typeof entry.createdAt !== 'number')
+            continue;
+        facts.push({ rowId: entry.rowId, pairKey: entry.pairKey, ref: entry.ref, expiresAt: entry.expiresAt, ...(typeof entry.runId === 'string' ? { runId: entry.runId } : {}), createdAt: entry.createdAt });
+    }
+    return facts;
+}
+/** Read-only adoption into the shadow index; never writes production staging-index. */
+export async function adoptLegacy(io, home) {
+    const ledger = await readPairLedger(io, home);
+    const entries = new Map();
+    const anomalies = [];
+    const now = Date.now();
+    for (const fact of markerStaging(ledger.migration)) {
+        const present = fact.ref !== '' && await io.exists(stagingTreePath(home, fact.ref));
+        entries.set(fact.rowId, { version: 1, rowId: fact.rowId, pairKey: fact.pairKey, ...(fact.runId === undefined ? {} : { runId: fact.runId }), ref: fact.ref, state: present ? 'present' : 'lost', createdAt: fact.createdAt, expiresAt: fact.expiresAt, updatedAt: now });
+    }
+    for (const row of ledger.rows) {
+        if (row.state === 'fuse' && !entries.has(row.id)) {
+            if (row.staging.kind === 'present')
+                entries.set(row.id, { version: 1, rowId: row.id, pairKey: row.pairKey, ...(row.runId === undefined ? {} : { runId: row.runId }), ref: row.staging.ref, state: 'present', createdAt: now, expiresAt: row.staging.expiresAt, updatedAt: now });
+            else if (row.staging.kind === 'expired')
+                entries.set(row.id, { version: 1, rowId: row.id, pairKey: row.pairKey, ...(row.runId === undefined ? {} : { runId: row.runId }), ref: row.staging.ref ?? '', state: 'expired', createdAt: now, expiresAt: row.staging.expiresAt, updatedAt: now });
+            continue;
+        }
+        if (row.state === 'pending') {
+            if (await readStagingIndex(io, home, row.id, now) !== null)
+                anomalies.push('pending-staging-index:' + row.id);
+            continue;
+        }
+        if (row.state === 'approved' && !entries.has(row.id)) {
+            const old = await readStagingIndex(io, home, row.id, now);
+            if (old !== null)
+                entries.set(row.id, { version: 1, rowId: row.id, pairKey: row.pairKey, ...(row.runId === undefined ? {} : { runId: row.runId }), ref: old.ref, state: 'reserved', createdAt: old.createdAt, expiresAt: old.expiresAt, updatedAt: now });
+        }
+    }
+    const adopted = [...entries.values()].sort((a, b) => a.rowId.localeCompare(b.rowId));
+    let wrote = false;
+    for (const entry of adopted) {
+        const path = shadowStagingIndexPath(home, entry.rowId);
+        const text = JSON.stringify(entry, null, 2) + '\n';
+        const current = await readTextOrNull(io, path);
+        if (current !== null) {
+            try {
+                const previous = JSON.parse(current);
+                if (previous.rowId === entry.rowId && previous.state === entry.state && previous.ref === entry.ref && previous.expiresAt === entry.expiresAt)
+                    continue;
+            }
+            catch { /* malformed shadow entry is replaced below */ }
+        }
+        if (io.transact !== undefined)
+            await io.transact(path, () => text);
+        else
+            await io.writeText(path, text);
+        wrote = true;
+    }
+    return { entries: adopted, anomalies, shadowPath: shadowStagingRoot(home), wrote };
+}
+export async function readShadowStageAggregate(io, home, rowId) {
+    if (rowId !== undefined) {
+        const raw = await readTextOrNull(io, shadowStagingIndexPath(home, rowId));
+        if (raw === null)
+            return { entries: [], shadowPath: shadowStagingRoot(home) };
+        try {
+            return { entries: [JSON.parse(raw)], shadowPath: shadowStagingRoot(home) };
+        }
+        catch {
+            return { entries: [], shadowPath: shadowStagingRoot(home) };
+        }
+    }
+    const listed = await io.exists(shadowStagingRoot(home)) ? await io.list(shadowStagingRoot(home)) : [];
+    const entries = [];
+    for (const name of listed) {
+        const raw = await readTextOrNull(io, join(shadowStagingRoot(home), name));
+        if (raw === null)
+            continue;
+        try {
+            entries.push(JSON.parse(raw));
+        }
+        catch { /* ignore malformed shadow */ }
+    }
+    entries.sort((a, b) => a.rowId.localeCompare(b.rowId));
+    return { entries, shadowPath: shadowStagingRoot(home) };
+}
+/** 1b-2b execution order; kept here so 1b-2a tests can pin the contract. */
+export const STAGE_WRITE_ORDER = ['index:reserved', 'tree', 'index:present'];
+export function admitStage(rowState) {
+    return rowState === 'approved' || rowState === 'fuse' ? { ok: true } : { ok: false, message: 'stage requires approved or fuse: ' + rowState };
+}
+export function planApprovedReserved(rowState, entry) {
+    if (entry === null)
+        return rowState === 'approved' || rowState === 'fuse' ? { kind: 'drop-orphan', rowId: '' } : { kind: 'none' };
+    if (rowState === 'approved' && entry.state === 'reserved')
+        return { kind: 'transition-fuse', rowId: entry.rowId, ref: entry.ref, expiresAt: entry.expiresAt };
+    if (rowState === 'approved' && entry.state === 'present')
+        return { kind: 'transition-fuse', rowId: entry.rowId, ref: entry.ref, expiresAt: entry.expiresAt };
+    if (rowState === 'fuse' && entry.state === 'reserved')
+        return { kind: 'write-present', rowId: entry.rowId, ref: entry.ref };
+    return { kind: 'none' };
+}
+/** Production adoption for 1b-2b normalize; writes the existing staging-index, not shadow. */
+export async function adoptLegacyProduction(io, home) {
+    const ledger = await readPairLedger(io, home);
+    const entries = new Map();
+    const anomalies = [];
+    const now = Date.now();
+    for (const fact of markerStaging(ledger.migration)) {
+        const present = fact.ref !== '' && await io.exists(stagingTreePath(home, fact.ref));
+        entries.set(fact.rowId, { version: 1, rowId: fact.rowId, pairKey: fact.pairKey, ...(fact.runId === undefined ? {} : { runId: fact.runId }), ref: fact.ref, state: present ? 'present' : 'lost', createdAt: fact.createdAt, expiresAt: fact.expiresAt, updatedAt: now });
+    }
+    for (const row of ledger.rows) {
+        if (row.state === 'fuse' && !entries.has(row.id)) {
+            if (row.staging.kind === 'present')
+                entries.set(row.id, { version: 1, rowId: row.id, pairKey: row.pairKey, ...(row.runId === undefined ? {} : { runId: row.runId }), ref: row.staging.ref, state: 'present', createdAt: now, expiresAt: row.staging.expiresAt, updatedAt: now });
+            else if (row.staging.kind === 'expired')
+                entries.set(row.id, { version: 1, rowId: row.id, pairKey: row.pairKey, ...(row.runId === undefined ? {} : { runId: row.runId }), ref: row.staging.ref ?? '', state: 'expired', createdAt: now, expiresAt: row.staging.expiresAt, updatedAt: now });
+            continue;
+        }
+        if (row.state === 'pending') {
+            if (await readStagingIndex(io, home, row.id, now) !== null)
+                anomalies.push('pending-staging-index:' + row.id);
+            continue;
+        }
+        if (row.state === 'approved' && !entries.has(row.id)) {
+            const old = await readStagingIndex(io, home, row.id, now);
+            if (old !== null)
+                entries.set(row.id, { version: 1, rowId: row.id, pairKey: row.pairKey, ...(row.runId === undefined ? {} : { runId: row.runId }), ref: old.ref, state: 'reserved', createdAt: old.createdAt, expiresAt: old.expiresAt, updatedAt: now });
+        }
+    }
+    const adopted = [...entries.values()].sort((a, b) => a.rowId.localeCompare(b.rowId));
+    let wrote = false;
+    for (const entry of adopted) {
+        const current = await readStagingIndex(io, home, entry.rowId, 0);
+        if (current !== null && current.ref === entry.ref && current.expiresAt === entry.expiresAt)
+            continue;
+        await writeStagingIndex(io, home, { rowId: entry.rowId, pairKey: entry.pairKey, ref: entry.ref, expiresAt: entry.expiresAt, ...(entry.runId === undefined ? {} : { runId: entry.runId }), createdAt: entry.createdAt, state: entry.state });
+        wrote = true;
+    }
+    return { entries: adopted, anomalies, shadowPath: join(home, 'merge', 'staging-index'), wrote };
+}
+/** Production stage-tree facade. These wrappers keep the low-level tree module private to StageAggregate. */
+export async function ensureStageTree(io, home, input) { return await ensureStaging(io, home, input); }
+export async function createStageTree(io, home, input) { return await createStaging(io, home, input); }
+export async function readStageTree(io, home, runId) { return await readStaging(io, home, runId); }
+export async function setStageTreeTarget(io, home, stageKey, target, mode) { return await setStagingTarget(io, home, stageKey, target, mode); }
+export async function dropStageTree(io, home, stageKey) { await dropStaging(io, home, stageKey); }
+export async function writeStageIndex(io, home, entry) { await writeStagingIndex(io, home, entry); }
+export async function readStageIndex(io, home, rowId, now = Date.now()) { return await readStagingIndex(io, home, rowId, now); }
+export async function readStageEntry(io, home, rowId) {
+    const raw = await readTextOrNull(io, join(home, 'merge', 'staging-index', encodeURIComponent(rowId) + '.json'));
+    if (raw === null)
+        return null;
+    try {
+        const entry = JSON.parse(raw);
+        if (entry.rowId !== rowId || typeof entry.ref !== 'string' || typeof entry.expiresAt !== 'number')
+            return null;
+        return entry;
+    }
+    catch {
+        return null;
+    }
+}
+export async function reserveStage(io, home, entry) {
+    await writeStageIndex(io, home, { rowId: entry.rowId, pairKey: entry.pairKey, ref: entry.ref, expiresAt: entry.expiresAt, ...(entry.runId === undefined ? {} : { runId: entry.runId }), createdAt: entry.createdAt, state: 'reserved' });
+}
+export async function presentStage(io, home, entry) {
+    await writeStageIndex(io, home, { rowId: entry.rowId, pairKey: entry.pairKey, ref: entry.ref, expiresAt: entry.expiresAt, ...(entry.runId === undefined ? {} : { runId: entry.runId }), createdAt: entry.createdAt, state: 'present' });
+}
+export async function dropStage(io, home, rowId, ref) {
+    await io.remove(join(home, 'merge', 'staging-index', encodeURIComponent(rowId) + '.json')).catch(() => { });
+    if (ref !== undefined && ref !== '')
+        await io.remove(join(home, 'merge', 'runs', ref)).catch(() => { });
+}
+/** Bounded cleanup: reserved/present TTL, pending/verify stale index removal, terminal/absent rows, orphan trees. */
+export async function cleanupStage(io, home, now, rows, limit = 100) {
+    const removed = [];
+    const expired = [];
+    const kept = [];
+    const orphans = [];
+    const refs = new Set();
+    const indexRoot = join(home, 'merge', 'staging-index');
+    const names = await io.exists(indexRoot) ? await listOrEmpty(io, indexRoot) : [];
+    for (const name of names.slice(0, limit)) {
+        if (!name.endsWith('.json'))
+            continue;
+        const raw = await readTextOrNull(io, join(indexRoot, name));
+        if (raw === null)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (typeof entry.rowId !== 'string' || typeof entry.ref !== 'string' || typeof entry.expiresAt !== 'number')
+            continue;
+        if (entry.ref !== '')
+            refs.add(entry.ref);
+        const row = rows.get(entry.rowId);
+        const terminal = row === undefined || row.state === 'skipped';
+        if (terminal || row?.state === 'pending' || row?.state === 'verify') {
+            await dropStage(io, home, entry.rowId, entry.ref);
+            removed.push(entry.rowId);
+            continue;
+        }
+        if (entry.expiresAt <= now) {
+            if (entry.state === 'present') {
+                // The index is the durable record both the read face and the resume path consult:
+                // stamp it expired instead of leaving a present entry that reads as live elsewhere.
+                try {
+                    await writeStagingIndex(io, home, { rowId: entry.rowId, pairKey: typeof entry.pairKey === 'string' ? entry.pairKey : '', ref: entry.ref, expiresAt: entry.expiresAt, createdAt: typeof entry.createdAt === 'number' ? entry.createdAt : now, state: 'expired' });
+                }
+                catch { /* the read face still derives expired */ }
+                expired.push(entry.rowId);
+                continue;
+            }
+            await dropStage(io, home, entry.rowId, entry.ref);
+            removed.push(entry.rowId);
+            continue;
+        }
+        kept.push(entry.rowId);
+    }
+    const runRoot = join(home, 'merge', 'runs');
+    const runNames = await io.exists(runRoot) ? await listOrEmpty(io, runRoot) : [];
+    for (const run of runNames.slice(0, limit)) {
+        const prefix = run + '/';
+        if ([...refs].some(ref => ref === run || ref.startsWith(prefix)))
+            continue;
+        await io.remove(join(runRoot, run)).catch(() => { });
+        orphans.push(run);
+    }
+    return { removed, expired, kept, orphans };
+}
+/** Read all production v2 stage entries. */
+export async function readAllStages(io, home) {
+    const root = join(home, 'merge', 'staging-index');
+    const names = await io.exists(root) ? await listOrEmpty(io, root) : [];
+    const entries = [];
+    for (const name of names) {
+        const raw = await readTextOrNull(io, join(root, name));
+        if (raw === null)
+            continue;
+        try {
+            const entry = JSON.parse(raw);
+            if (typeof entry.rowId !== 'string' || typeof entry.ref !== 'string' || typeof entry.expiresAt !== 'number')
+                continue;
+            entries.push(entry);
+        }
+        catch { /* skip malformed index */ }
+    }
+    return entries.sort((a, b) => a.rowId.localeCompare(b.rowId));
+}
+//# sourceMappingURL=stage-aggregate.js.map

package/lib/types/domain/staging-index.d.ts

@@ -0,0 +1,15 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+export interface StagingEntry {
+    readonly rowId: string;
+    readonly pairKey: string;
+    readonly ref: string;
+    readonly expiresAt: number;
+    readonly runId?: string;
+    readonly createdAt: number;
+    readonly state?: 'reserved' | 'present' | 'expired' | 'lost';
+}
+export declare function stagingIndexPath(home: string, rowId: string): string;
+export declare function readStagingIndex(io: EvolutionIoLike, home: string, rowId: string, now?: number): Promise<StagingEntry | null>;
+export declare function writeStagingIndex(io: EvolutionIoLike, home: string, entry: StagingEntry): Promise<void>;
+export declare function deleteStagingIndex(io: EvolutionIoLike, home: string, rowId: string): Promise<void>;
+//# sourceMappingURL=staging-index.d.ts.map

package/lib/types/domain/staging-index.js

@@ -0,0 +1,41 @@
+/** Durable staging index for v3 pending/approved rows (rowId-keyed). */
+import { join } from 'node:path';
+export function stagingIndexPath(home, rowId) {
+    return join(home, 'merge', 'staging-index', encodeURIComponent(rowId) + '.json');
+}
+export async function readStagingIndex(io, home, rowId, now = Date.now()) {
+    let raw;
+    try {
+        raw = await io.readText(stagingIndexPath(home, rowId));
+    }
+    catch {
+        return null;
+    }
+    if (raw === null)
+        return null;
+    try {
+        const entry = JSON.parse(raw);
+        if (entry.rowId !== rowId || typeof entry.ref !== 'string' || typeof entry.expiresAt !== 'number')
+            return null;
+        if (entry.expiresAt <= now)
+            return null;
+        return entry;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeStagingIndex(io, home, entry) {
+    const text = JSON.stringify(entry, null, 2) + '\n';
+    if (io.transact !== undefined)
+        await io.transact(stagingIndexPath(home, entry.rowId), () => text);
+    else
+        await io.writeText(stagingIndexPath(home, entry.rowId), text);
+}
+export async function deleteStagingIndex(io, home, rowId) {
+    try {
+        await io.remove(stagingIndexPath(home, rowId));
+    }
+    catch { /* missing/already removed */ }
+}
+//# sourceMappingURL=staging-index.js.map

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

@@ -0,0 +1,43 @@
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type QuarantinedRow, type V3State } from './migrate-v3.ts';
+export declare function mergeStatePath(home: string): string;
+export declare function v2BackupPath(home: string): string;
+export declare function migrationJournalPath(home: string): string;
+export declare function migrationReportPath(home: string): string;
+export declare function quarantinePath(home: string): string;
+export type StateBlockCode = 'merge-state-migration-required' | 'merge-state-migration-blocked' | 'merge-state-needs-repair' | 'merge-state-forward-only';
+export interface MigrationReport {
+    readonly version: 1;
+    readonly ready: boolean;
+    readonly migrated: boolean;
+    readonly sourceSha256?: string;
+    readonly targetSha256?: string;
+    readonly rows?: number;
+    readonly quarantined?: number;
+    readonly backupReadOnly?: boolean;
+    readonly at: string;
+    readonly steps: readonly string[];
+}
+export type StateReadiness = {
+    readonly ok: true;
+    readonly schema: 3;
+    readonly migrated: boolean;
+    readonly state: V3State;
+    readonly quarantine: readonly QuarantinedRow[];
+    readonly report: MigrationReport | null;
+} | {
+    readonly ok: false;
+    readonly code: StateBlockCode;
+    readonly message: string;
+};
+export declare class StateBlockedError extends Error {
+    readonly readiness: StateReadiness;
+    constructor(readiness: StateReadiness);
+}
+/** Read-only readiness probe. Never migrates, never writes. */
+export declare function readStateReadiness(io: EvolutionIoLike, home: string): Promise<StateReadiness>;
+/** Compatibility name for the v3 gate; 1b-2b switches the lifecycle to v4. */
+export declare const ensureV3Ready: typeof ensureMergeStateReady;
+/** One readiness/migration gate; used by startup and every write entry. */
+export declare function ensureMergeStateReady(io: EvolutionIoLike, home: string): Promise<StateReadiness>;
+//# sourceMappingURL=state-bootstrap.d.ts.map