@lmzhen/dsh-evolution-merge 0.30.18 → 0.30.19

package/lib/types/domain/merge-snapshot.d.ts

@@ -0,0 +1,99 @@
+import type { EvolutionIoLike, RunRecord } from '@lmzhen/dsh-evolution-core';
+import { type V4Readiness } from './schema4.ts';
+import { type StageEntry } from './stage-aggregate.ts';
+import { type MergeRunMeta } from './run-coordinator.ts';
+import type { MergeReport } from '../contracts.ts';
+import type { V4Row } from './row-v4.ts';
+import { type LiveRowFacts, type PendingExpiryKind } from './live-facts.ts';
+import type { QueueId, MergeCounts, DoctorFact } from '../wire.ts';
+export interface SnapshotRow {
+    readonly row: V4Row;
+    readonly stage: StageEntry | null;
+    readonly bodies: readonly BodyRef[];
+    readonly queue: QueueId;
+    readonly expired: boolean;
+    readonly expiredKind?: PendingExpiryKind;
+}
+export interface BodyRef {
+    readonly rowId: string;
+    readonly name: string;
+    readonly side: 'live' | 'archive';
+}
+export interface SnapshotRun {
+    readonly record: RunRecord;
+    readonly meta: MergeRunMeta | null;
+    readonly pairs: readonly {
+        readonly pairKey: string;
+        readonly runId: string;
+        readonly result: string;
+        readonly target?: string;
+    }[];
+    readonly report: MergeReport | null;
+    readonly reportRef: string | null;
+}
+export interface SnapshotDoctor {
+    readonly counts: MergeCounts;
+    readonly staging: {
+        readonly state: 'ok' | 'absent' | 'unreadable';
+        readonly dirs: number;
+        readonly oldestAgeMs?: number;
+        readonly detail?: string;
+    };
+    readonly rows: readonly DoctorFact[];
+}
+export interface HistoryItem {
+    readonly name: string;
+    readonly kind: 'merged' | 'deleted' | 'split' | 'other';
+    readonly reason: string;
+    readonly reasonCode?: string;
+    readonly lastVersion: number;
+    readonly archivedAt: number;
+    readonly sourceRunId?: string;
+    readonly runId?: string;
+    readonly absorbedInto?: string;
+    readonly generation?: number;
+}
+export interface MergeSnapshot {
+    readonly wireVersion: 1;
+    readonly schemaVersion: 4;
+    readonly readAt: number;
+    readonly queueRevision: string;
+    readonly consistency: 'eventual';
+    readonly blocked?: {
+        readonly code: string;
+        readonly message: string;
+        readonly readiness: V4Readiness;
+    };
+    readonly rows: readonly SnapshotRow[];
+    readonly stages: readonly StageEntry[];
+    readonly runs: readonly SnapshotRun[];
+    readonly reports: readonly {
+        readonly runId: string;
+        readonly path: string;
+        readonly report: MergeReport;
+    }[];
+    readonly report: MergeReport | null;
+    readonly history: readonly HistoryItem[];
+    readonly bodyRefs: readonly BodyRef[];
+    readonly doctor: SnapshotDoctor;
+    readonly approval: {
+        readonly mergeApproval: boolean;
+        readonly platformWrite?: boolean;
+    };
+    readonly notes: readonly string[];
+    readonly degraded: boolean;
+}
+export interface ReadSnapshotOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly runs: readonly RunRecord[];
+    readonly approval: boolean;
+    readonly platformWrite?: boolean;
+    readonly now?: () => number;
+    readonly history?: () => Promise<readonly HistoryItem[]>;
+    readonly notes?: readonly string[];
+    /** Lazy live-library facts; only invoked when a pending row still needs derivation. */
+    readonly live?: () => Promise<LiveRowFacts | undefined>;
+}
+export declare function readMergeSnapshot(options: ReadSnapshotOptions): Promise<MergeSnapshot>;
+//# sourceMappingURL=merge-snapshot.d.ts.map

package/lib/types/domain/merge-snapshot.js

@@ -0,0 +1,82 @@
+/** 1b-3 one read aggregate over schema4 and its sidecars. No writes. */
+import { createHash } from 'node:crypto';
+import { readV4Readiness } from "./schema4.js";
+import { readPairLedgerV4 } from "./pair-ledger.js";
+import { readAllStages } from "./stage-aggregate.js";
+import { readRunMeta } from "./run-coordinator.js";
+import { loadPairIndex } from "./pair-index-store.js";
+import { mergeReportPath, readMergeReport } from "../report.js";
+import { readCommitReceipts } from "../commit-receipt.js";
+import { pendingExpiry, persistedExpiry } from "./live-facts.js";
+const emptyCounts = { active: { verify: 0, pending: 0, fuse: 0, skipped: 0 }, expired: 0 };
+const queueOf = (state) => state === 'approved' || state === 'fuse' ? 'fuse' : state === 'verify' ? 'verify' : state === 'pending' ? 'pending' : 'skipped';
+export async function readMergeSnapshot(options) {
+    const now = options.now ?? (() => Date.now());
+    const readAt = now();
+    const readiness = await readV4Readiness(options.io, options.home);
+    if (!readiness.ok) {
+        return { wireVersion: 1, schemaVersion: 4, readAt, queueRevision: 'blocked', consistency: 'eventual', blocked: { code: readiness.code, message: readiness.message, readiness }, rows: [], stages: [], runs: [], reports: [], report: null, history: [], bodyRefs: [], doctor: { counts: emptyCounts, staging: { state: 'absent', dirs: 0 }, rows: [] }, approval: { mergeApproval: options.approval, ...(options.platformWrite === undefined ? {} : { platformWrite: options.platformWrite }) }, notes: options.notes ?? [], degraded: true };
+    }
+    const ledger = await readPairLedgerV4(options.io, options.home);
+    // Read-time derivation only: a stage past its TTL reads as expired even when the
+    // index still says present. Reconcile is the writer that persists the correction.
+    const stages = (await readAllStages(options.io, options.home)).map(entry => entry.state === 'present' && entry.expiresAt <= readAt ? { ...entry, state: 'expired' } : entry);
+    const rows = [];
+    const bodyRefs = [];
+    // FR-LIFE-14: pending rows whose sources/target moved read as expired even before the
+    // reconcile writer stamps them. The live library is read ONLY when such a row exists,
+    // and the derivation never writes (GET routes stay zero-write).
+    const needsLive = options.live !== undefined && (ledger?.rows ?? []).some(row => (row.state === 'pending' && row.expired === undefined) || row.state === 'verify' || row.state === 'fuse' || row.state === 'approved');
+    const live = needsLive ? await options.live().catch(() => undefined) : undefined;
+    for (const row of ledger?.rows ?? []) {
+        const stage = stages.find(item => item.rowId === row.id) ?? null;
+        const queue = queueOf(row.state);
+        const bodies = [{ rowId: row.id, name: row.a, side: 'live' }, { rowId: row.id, name: row.b, side: 'archive' }];
+        const expiredKind = persistedExpiry(row) ?? pendingExpiry(row, live);
+        rows.push({ row, stage, bodies, queue, expired: expiredKind !== null, ...(expiredKind === null ? {} : { expiredKind }) });
+        bodyRefs.push(...bodies);
+    }
+    const pairIndex = await loadPairIndex(options.io, options.home);
+    const runs = [];
+    for (const record of options.runs) {
+        const meta = await readRunMeta(options.io, options.home, record.id);
+        const pairs = [...pairIndex.values()].filter(item => item.runId === record.id).map(item => ({ pairKey: item.pairKey, runId: item.runId, result: item.result, ...(item.target === undefined ? {} : { target: item.target }) }));
+        const reportPath = mergeReportPath(options.home, record.id);
+        const probe = await readMergeReport(options.io, options.home, record.id);
+        const report = probe.kind === 'present' ? probe.value : null;
+        runs.push({ record, meta, pairs, report, reportRef: report === null ? null : reportPath });
+    }
+    const reports = runs.filter(run => run.report !== null).map(run => ({ runId: run.record.id, path: run.reportRef, report: run.report }));
+    const history = options.history === undefined ? await readHistory(options.io, options.home) : await options.history();
+    const historyDegraded = options.history === undefined;
+    const counts = { active: { verify: 0, pending: 0, fuse: 0, skipped: 0 }, expired: 0 };
+    for (const item of rows)
+        if (item.expired)
+            counts.expired += 1;
+        else
+            counts.active[item.queue] += 1;
+    const stagingLost = stages.filter(item => item.state === 'lost' || item.state === 'expired').length;
+    const doctor = { counts, staging: { state: stages.length === 0 ? 'absent' : 'ok', dirs: stages.length, ...(stagingLost === 0 ? {} : { detail: String(stagingLost) + ' lost/expired stage(s)' }) }, rows: [
+            { key: 'state', status: 'ok', detail: String(rows.length) + ' rows' },
+            { key: 'staging-index', status: stages.length === 0 ? 'warn' : 'ok', detail: String(stages.length) + ' entries; ' + String(stagingLost) + ' lost/expired' },
+            { key: 'consistency', status: rows.some(item => item.expired) ? 'warn' : 'ok', detail: String(counts.expired) + ' expired' },
+        ] };
+    const queueRevision = createHash('sha256').update(JSON.stringify({ schemaVersion: 4, rows: rows.map(item => [item.row.id, item.row.version, item.row.state, item.row.updatedAt]), stages: stages.map(item => [item.rowId, item.version, item.state, item.updatedAt, item.ref, item.expiresAt]) })).digest('hex');
+    const notes = [...(options.notes ?? [])];
+    if (historyDegraded)
+        notes.push('history archive port unavailable; receipts only');
+    const ledgerConflicts = [...pairIndex.values()].filter(entry => (entry.result === 'merged' || entry.result === 'undone')
+        && rows.some(item => item.row.pairKey === entry.pairKey && (item.row.state === 'verify' || item.row.state === 'pending' || item.row.state === 'approved' || item.row.state === 'fuse')));
+    if (ledgerConflicts.length > 0)
+        notes.push('ledger-conflict: pair-index says completed but the ledger still has it active (' + String(ledgerConflicts.length) + ')');
+    return { wireVersion: 1, schemaVersion: 4, readAt, queueRevision, consistency: 'eventual', rows, stages, runs, reports, report: reports.at(-1)?.report ?? null, history, bodyRefs, doctor, approval: { mergeApproval: options.approval, ...(options.platformWrite === undefined ? {} : { platformWrite: options.platformWrite }) }, notes, degraded: notes.length > 0 };
+}
+async function readHistory(io, home) {
+    const receipts = await readCommitReceipts(io, home);
+    const out = [];
+    for (const receipt of receipts)
+        for (const source of receipt.sources)
+            out.push({ name: source, kind: 'merged', reason: 'Merged into ' + receipt.target, reasonCode: 'merged', lastVersion: 1, archivedAt: receipt.at, sourceRunId: receipt.runId });
+    return out.map((item, index) => ({ ...item, generation: index + 1 }));
+}
+//# sourceMappingURL=merge-snapshot.js.map

package/lib/types/domain/pair-ledger.d.ts

@@ -0,0 +1,34 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { V4Row } from './row-v4.ts';
+import { type V3Row } from './row-v3.ts';
+import { type V4RowTx } from './schema4.ts';
+export type PairRow = V3Row;
+export interface PairLedgerRead {
+    readonly schemaVersion: 3;
+    readonly ledgerVersion?: number;
+    readonly migration?: unknown;
+    readonly rows: readonly V3Row[];
+}
+export interface PairLedger {
+    read(): Promise<PairLedgerRead>;
+    transact<T>(fn: (tx: V4RowTx) => T): Promise<T>;
+    normalize(): Promise<NormalizeResult>;
+}
+export interface NormalizeResult {
+    readonly ok: boolean;
+    readonly migrated: boolean;
+    readonly backupRef?: string;
+    readonly message?: string;
+}
+/** Read-only 1b-1 bypass. It does not normalize, back up, or write state. */
+export declare function readPairLedger(io: EvolutionIoLike, home: string): Promise<PairLedgerRead>;
+/** 1b-2a write skeleton. Production stays on the v3 gate until 1b-2b. */
+export declare function pairLedger(io: EvolutionIoLike, home: string): PairLedger;
+/** v3-to-v4 normalize: backup -> production stage adopt -> v4 state. Not called in 1b-2a. */
+export declare function normalizePairLedger(io: EvolutionIoLike, home: string): Promise<NormalizeResult>;
+/** Read schema4 rows only; no legacy projection. */
+export declare function readPairLedgerV4(io: EvolutionIoLike, home: string): Promise<{
+    readonly rows: readonly V4Row[];
+    readonly revision: string;
+} | null>;
+//# sourceMappingURL=pair-ledger.d.ts.map

package/lib/types/domain/pair-ledger.js

@@ -0,0 +1,96 @@
+import { readTextOrNull } from "./read-probe.js";
+/** 1b-1 additive read view; the production row writer stays in state.ts until 1b-2. */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { readStateReadiness, mergeStatePath, StateBlockedError } from "./state-bootstrap.js";
+import { transactIo } from '@lmzhen/dsh-evolution-core';
+import { createPre1bBackup } from "./pre-1b-backup.js";
+import { adoptLegacyProduction } from "./stage-aggregate.js";
+import { normalizeV3State, parseV4State, readV4Readiness } from "./schema4.js";
+import { isV3Row } from "./row-v3.js";
+import { transactMergeState } from "./schema4.js";
+/** Read-only 1b-1 bypass. It does not normalize, back up, or write state. */
+export async function readPairLedger(io, home) {
+    const ready = await readStateReadiness(io, home);
+    if (!ready.ok)
+        throw new StateBlockedError(ready);
+    let header = {};
+    try {
+        const raw = await io.readText(join(home, 'merge', 'merge-state.json'));
+        if (raw !== null) {
+            const parsed = JSON.parse(raw);
+            header = parsed;
+        }
+    }
+    catch { /* readiness already validated the state; header is optional */ }
+    return {
+        schemaVersion: 3,
+        ...(typeof header.ledgerVersion === 'number' ? { ledgerVersion: header.ledgerVersion } : {}),
+        ...(header.migration === undefined ? {} : { migration: header.migration }),
+        rows: ready.state.rows,
+    };
+}
+/** 1b-2a write skeleton. Production stays on the v3 gate until 1b-2b. */
+export function pairLedger(io, home) {
+    return {
+        read: () => readPairLedger(io, home),
+        transact: async (fn) => {
+            const current = await readV4Readiness(io, home);
+            if (!current.ok) {
+                const normalized = await normalizePairLedger(io, home);
+                if (!normalized.ok)
+                    throw new Error(normalized.message ?? 'normalize failed');
+            }
+            return await transactMergeState(io, home, fn);
+        },
+        normalize: () => normalizePairLedger(io, home),
+    };
+}
+/** v3-to-v4 normalize: backup -> production stage adopt -> v4 state. Not called in 1b-2a. */
+export async function normalizePairLedger(io, home) {
+    const v4 = await readV4Readiness(io, home);
+    if (v4.ok)
+        return { ok: true, migrated: false };
+    if (v4.code !== 'merge-state-normalize-required' && v4.code !== 'merge-state-v4-required')
+        return { ok: false, migrated: false, message: v4.code + ': ' + v4.message };
+    let v3 = await readStateReadiness(io, home);
+    if (!v3.ok)
+        return { ok: false, migrated: false, message: v3.code + ': ' + v3.message };
+    if (v4.code === 'merge-state-v4-required') {
+        await transactIo(io, mergeStatePath(home), current => current === null ? JSON.stringify({ schemaVersion: 3, rows: [] }) + '\n' : current);
+        v3 = await readStateReadiness(io, home);
+        if (!v3.ok)
+            return { ok: false, migrated: false, message: v3.code + ': ' + v3.message };
+    }
+    const backup = await createPre1bBackup(io, home);
+    if (!backup.ok)
+        return { ok: false, migrated: false, message: backup.code + ': ' + backup.message };
+    await adoptLegacyProduction(io, home);
+    let wrote = false;
+    await transactIo(io, mergeStatePath(home), current => {
+        if (current === null)
+            throw new Error('merge-state-v4-required');
+        const header = JSON.parse(current);
+        if (header.schemaVersion === 4)
+            return current;
+        if (header.schemaVersion !== 3 || !Array.isArray(header.rows) || !header.rows.every(isV3Row))
+            throw new Error('merge-state-normalize-required');
+        const v4State = normalizeV3State({ schemaVersion: 3, rows: header.rows, ...(header.migration === undefined ? {} : { migration: header.migration }) }, { backupRef: backup.id, at: new Date().toISOString() });
+        wrote = true;
+        return JSON.stringify(v4State, null, 2) + '\n';
+    });
+    return { ok: true, migrated: wrote, backupRef: backup.id };
+}
+/** Read schema4 rows only; no legacy projection. */
+export async function readPairLedgerV4(io, home) {
+    const raw = await readTextOrNull(io, mergeStatePath(home));
+    if (raw === null)
+        return null;
+    const state = parseV4State(raw);
+    if (state === null)
+        return null;
+    const rows = state.rows;
+    const revision = createHash('sha256').update(JSON.stringify(rows.map(row => [row.id, row.version, row.state, row.updatedAt]))).digest('hex');
+    return { rows, revision };
+}
+//# sourceMappingURL=pair-ledger.js.map

package/lib/types/domain/pre-1b-backup.d.ts

@@ -0,0 +1,43 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+export interface Pre1bFileEntry {
+    readonly source: string;
+    readonly copy: string;
+    readonly sha256: string;
+    readonly bytes: number;
+    readonly mode: string;
+}
+export interface Pre1bTreeEntry {
+    readonly source: string;
+    readonly copy: string;
+    readonly sha256: string;
+    readonly files: number;
+    readonly bytes: number;
+}
+export interface Pre1bBackupManifest {
+    readonly version: 1;
+    readonly backupId: string;
+    readonly sourceSchema: 3;
+    readonly sourceStateSha256: string;
+    readonly createdAt: string;
+    readonly state: Pre1bFileEntry;
+    readonly trees: readonly Pre1bTreeEntry[];
+    readonly files: readonly Pre1bFileEntry[];
+    readonly readonly: true;
+}
+export type Pre1bBackupResult = {
+    readonly ok: true;
+    readonly id: string;
+    readonly path: string;
+    readonly manifest: Pre1bBackupManifest;
+} | {
+    readonly ok: false;
+    readonly code: 'pre-1b-backup-conflict' | 'pre-1b-backup-invalid' | 'pre-1b-backup-failed';
+    readonly message: string;
+};
+export declare function pre1bRoot(home: string): string;
+export declare function pre1bDir(home: string, id: string): string;
+export declare function pre1bManifestPath(home: string, id: string): string;
+export declare function readPre1bManifest(io: EvolutionIoLike, home: string, id: string): Promise<Pre1bBackupManifest | null>;
+/** Create or reuse the single pre-1b backup. Never writes merge-state. */
+export declare function createPre1bBackup(io: EvolutionIoLike, home: string, at?: string): Promise<Pre1bBackupResult>;
+//# sourceMappingURL=pre-1b-backup.d.ts.map

package/lib/types/domain/pre-1b-backup.js

@@ -0,0 +1,140 @@
+import { readTextOrNull } from "./read-probe.js";
+/** Batch 1b-2a pre-1b backup manifest. Read-only, idempotent, no production normalize. */
+import { createHash } from 'node:crypto';
+import { chmod, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+export function pre1bRoot(home) { return join(home, 'merge', '.backup', 'pre-1b'); }
+export function pre1bDir(home, id) { return join(pre1bRoot(home), id); }
+export function pre1bManifestPath(home, id) { return join(pre1bDir(home, id), 'manifest.json'); }
+const hash = (text) => createHash('sha256').update(text).digest('hex');
+const statePath = (home) => join(home, 'merge', 'merge-state.json');
+async function walk(io, root, rel = '') {
+    const path = rel === '' ? root : join(root, rel);
+    if (!await io.exists(path))
+        return [];
+    try {
+        const text = await io.readText(path);
+        if (text !== null)
+            return [rel];
+    }
+    catch (error) {
+        const code = error instanceof Error && 'code' in error ? String(error.code) : '';
+        if (code !== 'EISDIR' && code !== 'ENOTDIR')
+            throw error;
+    }
+    const names = await io.list(path);
+    const found = [];
+    for (const name of names.sort())
+        found.push(...await walk(io, root, rel === '' ? name : join(rel, name)));
+    return found;
+}
+async function chmodReadOnly(path) {
+    await chmod(path, 0o444);
+    const info = await stat(path);
+    const mode = (info.mode & 0o777).toString(8).padStart(4, '0');
+    if ((info.mode & 0o222) !== 0)
+        throw new Error('backup is not read-only: ' + path);
+    return mode;
+}
+export async function readPre1bManifest(io, home, id) {
+    const raw = await readTextOrNull(io, pre1bManifestPath(home, id));
+    if (raw === null)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        if (value.version !== 1 || value.readonly !== true || value.sourceSchema !== 3 || typeof value.sourceStateSha256 !== 'string' || !Array.isArray(value.trees) || !Array.isArray(value.files) || value.state === undefined)
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+/** Create or reuse the single pre-1b backup. Never writes merge-state. */
+export async function createPre1bBackup(io, home, at = new Date().toISOString()) {
+    const raw = await readTextOrNull(io, statePath(home));
+    if (raw === null)
+        return { ok: false, code: 'pre-1b-backup-invalid', message: 'merge state is missing' };
+    let state;
+    try {
+        state = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, code: 'pre-1b-backup-invalid', message: 'merge state is not JSON' };
+    }
+    if (state.schemaVersion !== 3)
+        return { ok: false, code: 'pre-1b-backup-invalid', message: 'pre-1b backup requires schema3 state' };
+    const stateSha = hash(raw);
+    const id = 'pre-1b-' + stateSha.slice(0, 16);
+    const existing = await readPre1bManifest(io, home, id);
+    if (existing !== null)
+        return { ok: true, id, path: pre1bManifestPath(home, id), manifest: existing };
+    const target = pre1bDir(home, id);
+    const stateBytes = await io.readText(statePath(home));
+    if (stateBytes === null)
+        return { ok: false, code: 'pre-1b-backup-failed', message: 'merge state disappeared' };
+    const files = [];
+    const trees = [];
+    try {
+        const sources = [
+            { source: join(home, 'merge', 'staging-index'), kind: 'tree' },
+            { source: join(home, 'merge', 'runs'), kind: 'tree' },
+            { source: join(home, 'merge', 'run-meta'), kind: 'tree' },
+            { source: join(home, 'reports'), kind: 'tree' },
+            { source: join(home, 'merge', 'receipts'), kind: 'tree' },
+            { source: join(home, 'merge', 'journals'), kind: 'tree' },
+            { source: join(home, 'merge', 'unit-journals'), kind: 'tree' },
+            { source: join(home, 'merge', 'units'), kind: 'tree' },
+            { source: join(home, 'merge', 'merge-state.v2.bak.json'), kind: 'file' },
+            { source: join(home, 'merge', 'merge-state.migration.json'), kind: 'file' },
+            { source: join(home, 'merge', 'merge-state.migration.report.json'), kind: 'file' },
+            { source: join(home, 'merge', 'merge-state.quarantine.json'), kind: 'file' },
+            { source: join(home, 'merge', 'pair-index.json'), kind: 'file' },
+            { source: join(home, 'merge', 'recovery.json'), kind: 'file' },
+            { source: join(home, 'runs.json'), kind: 'file' },
+        ];
+        for (const item of sources) {
+            if (item.kind === 'file') {
+                const text = await readTextOrNull(io, item.source);
+                if (text === null)
+                    continue;
+                const rel = item.source.slice(home.length + 1);
+                const copy = join(target, 'snapshot', rel);
+                await io.copy(item.source, copy);
+                const mode = await chmodReadOnly(copy);
+                files.push({ source: item.source, copy, sha256: hash(text), bytes: Buffer.byteLength(text, 'utf8'), mode });
+            }
+            else {
+                const rels = await walk(io, item.source);
+                if (rels.length === 0)
+                    continue;
+                let bytes = 0;
+                const hashes = [];
+                for (const rel of rels) {
+                    const source = join(item.source, rel);
+                    const text = await io.readText(source);
+                    if (text === null)
+                        continue;
+                    bytes += Buffer.byteLength(text, 'utf8');
+                    hashes.push(rel + ':' + hash(text));
+                    const copy = join(target, 'snapshot', item.source.slice(home.length + 1), rel);
+                    await io.copy(source, copy);
+                    await chmodReadOnly(copy);
+                }
+                trees.push({ source: item.source, copy: join(target, 'snapshot', item.source.slice(home.length + 1)), sha256: hash(hashes.sort().join('\n')), files: hashes.length, bytes });
+            }
+        }
+        const stateCopy = join(target, 'snapshot', 'merge', 'merge-state.json');
+        await io.copy(statePath(home), stateCopy);
+        const stateMode = await chmodReadOnly(stateCopy);
+        const stateEntry = { source: statePath(home), copy: stateCopy, sha256: stateSha, bytes: Buffer.byteLength(raw, 'utf8'), mode: stateMode };
+        const manifest = { version: 1, backupId: id, sourceSchema: 3, sourceStateSha256: stateSha, createdAt: at, state: stateEntry, trees, files, readonly: true };
+        await io.writeText(pre1bManifestPath(home, id), JSON.stringify(manifest, null, 2) + '\n');
+        await chmodReadOnly(pre1bManifestPath(home, id));
+        return { ok: true, id, path: pre1bManifestPath(home, id), manifest };
+    }
+    catch (error) {
+        return { ok: false, code: 'pre-1b-backup-failed', message: error instanceof Error ? error.message : String(error) };
+    }
+}
+//# sourceMappingURL=pre-1b-backup.js.map

package/lib/types/domain/provider-key.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeProviderKey(value: unknown): string;
+//# sourceMappingURL=provider-key.d.ts.map

package/lib/types/domain/provider-key.js

@@ -0,0 +1,11 @@
+/** Provider lexical normalization shared by plan/report. */
+const PROVIDER = /^[a-z0-9][a-z0-9._-]*$/;
+export function normalizeProviderKey(value) {
+    if (typeof value !== 'string')
+        throw new Error('provider must be a string');
+    const normalized = value.trim().toLowerCase();
+    if (normalized === '' || normalized.includes('/') || normalized.includes(':') || !PROVIDER.test(normalized))
+        throw new Error('provider key is invalid: ' + String(value));
+    return normalized;
+}
+//# sourceMappingURL=provider-key.js.map

package/lib/types/domain/read-probe.d.ts

@@ -0,0 +1,5 @@
+/** Three-state reads for merge diagnostics: callers that render absence as none. */
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+export declare function readTextOrNull(io: EvolutionIoLike, path: string): Promise<string | null>;
+export declare function listOrEmpty(io: EvolutionIoLike, path: string): Promise<readonly string[]>;
+//# sourceMappingURL=read-probe.d.ts.map

package/lib/types/domain/read-probe.js

@@ -0,0 +1,11 @@
+/** Three-state reads for merge diagnostics: callers that render absence as none. */
+import { probeList, probeText } from '@lmzhen/dsh-evolution-core';
+export async function readTextOrNull(io, path) {
+    const probe = await probeText(io, path);
+    return probe.kind === 'present' ? probe.value : null;
+}
+export async function listOrEmpty(io, path) {
+    const probe = await probeList(io, path);
+    return probe.kind === 'present' ? probe.value : [];
+}
+//# sourceMappingURL=read-probe.js.map

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

@@ -0,0 +1,47 @@
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type LiveRowFacts } from './live-facts.ts';
+import type { V4Row } from './row-v4.ts';
+export declare const RECONCILE_REPORT_VERSION = 1;
+export type ReconcileActionKind = 'skipped-expired' | 'pending-expired' | 'approved-fused' | 'source-gone';
+export type ReconcileActionCode = 'skipped-ttl' | 'target-taken' | 'source-changed' | 'stage-present' | 'stage-lost' | 'stage-expired' | 'source-gone';
+/** One durable row transition reconcile performed. */
+export interface ReconcileAction {
+    readonly kind: ReconcileActionKind;
+    readonly rowId: string;
+    readonly from: V4Row['state'];
+    readonly to: V4Row['state'] | 'removed';
+    readonly code: ReconcileActionCode;
+    readonly detail?: string;
+}
+/** The persisted report a CLI/doctor consumer reads; `state:'blocked'` means nothing was written. */
+export interface ReconcileReport {
+    readonly version: typeof RECONCILE_REPORT_VERSION;
+    readonly at: number;
+    readonly state: 'ok' | 'blocked';
+    readonly code?: string;
+    readonly message?: string;
+    readonly actions: readonly ReconcileAction[];
+    readonly notes: readonly string[];
+}
+export interface ReconcileOptions {
+    readonly io: EvolutionIoLike;
+    readonly home: string;
+    readonly now: () => number;
+    /** Skipped rows past this TTL get their durable expiredAt stamp. */
+    readonly ttlDays?: number;
+    /** Live managed skill names. When supplied, active rows whose sources vanished are cleared. */
+    readonly managed?: ReadonlySet<string>;
+    /** Live revision facts; when supplied, pending rows that went stale are stamped expired. */
+    readonly live?: LiveRowFacts;
+}
+export declare function reconcileReportPath(home: string): string;
+/** Read the last reconcile report; a malformed report is absent, never a throw. */
+export declare function readReconcileReport(io: EvolutionIoLike, home: string): Promise<ReconcileReport | null>;
+/**
+ * Converge the row layer once, atomically, then persist the report.
+ * A blocked state writes no rows and no report; every other run is idempotent.
+ */
+export declare function reconcileMergeState(options: ReconcileOptions): Promise<ReconcileReport>;
+/** One-line text face for the CLI/doctor consumers. */
+export declare function formatReconcileReport(report: ReconcileReport): string;
+//# sourceMappingURL=reconcile.d.ts.map