@lmzhen/dsh-evolution-merge 0.30.18 → 0.30.20

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

@@ -0,0 +1,53 @@
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type CommitUnitRef, type V4Event, type V4Row, type V4WriteResult } from './row-v4.ts';
+import type { V3Row } from './row-v3.ts';
+export interface MergeStateV4 {
+    readonly schemaVersion: 4;
+    readonly rows: readonly V4Row[];
+    readonly migration?: unknown;
+    readonly pre1b?: {
+        readonly backupRef: string;
+        readonly at: string;
+    };
+}
+export type V4BlockCode = 'merge-state-normalize-required' | 'merge-state-migration-required' | 'merge-state-v4-required' | 'merge-state-forward-only' | 'merge-state-needs-repair' | 'merge-state-backup-missing';
+export type V4Readiness = {
+    readonly ok: true;
+    readonly schema: 4;
+    readonly state: MergeStateV4;
+} | {
+    readonly ok: false;
+    readonly code: V4BlockCode;
+    readonly message: string;
+};
+export declare class V4BlockedError extends Error {
+    readonly readiness: V4Readiness;
+    constructor(readiness: V4Readiness);
+}
+export declare function schema4StatePath(home: string): string;
+/** Pure read-only v4 readiness. Does not normalize, repair, or write. */
+export declare function readV4Readiness(io: EvolutionIoLike, home: string): Promise<V4Readiness>;
+export interface V4RowTx {
+    rows(): readonly V4Row[];
+    createVerify(row: Extract<V4Row, {
+        state: 'verify';
+    }>): V4WriteResult;
+    createSkipped(row: Extract<V4Row, {
+        state: 'skipped';
+    }>): V4WriteResult;
+    transition(id: string, event: V4Event, expectedVersion: number): V4WriteResult;
+    remove(id: string, terminal: 'committed' | 'superseded' | 'restored', unit: CommitUnitRef | undefined, expectedVersion: number): V4WriteResult;
+}
+/** Atomic readiness + V4 row write under one state-file lock. No production caller in 1b-2a. */
+export declare function transactMergeState<T>(io: EvolutionIoLike, home: string, fn: (tx: V4RowTx) => T | Promise<T>): Promise<T>;
+/** Pure v3-to-v4 projection for fixtures; 1b-2b wires it to the production normalize. */
+export declare function normalizeV3State(state: {
+    readonly schemaVersion: 3;
+    readonly rows: readonly V3Row[];
+    readonly migration?: unknown;
+}, pre1b: {
+    readonly backupRef: string;
+    readonly at: string;
+}): MergeStateV4;
+export declare function parseV4State(raw: string): MergeStateV4 | null;
+//# sourceMappingURL=schema4.d.ts.map

package/lib/types/domain/schema4.js

@@ -0,0 +1,129 @@
+/** Batch 1b-2a schema4 state codec, readiness, and atomic row transaction. */
+import { join } from 'node:path';
+import { transactIo } from '@lmzhen/dsh-evolution-core';
+import { isV4Row, applyV4Write, v3ToV4 } from "./row-v4.js";
+import { readPre1bManifest } from "./pre-1b-backup.js";
+export class V4BlockedError extends Error {
+    readiness;
+    constructor(readiness) {
+        super(readiness.ok ? 'merge state v4 is ready' : readiness.code + ': ' + readiness.message);
+        this.name = 'V4BlockedError';
+        this.readiness = readiness;
+    }
+}
+export function schema4StatePath(home) { return join(home, 'merge', 'merge-state.json'); }
+function blocked(code, message) { return { ok: false, code, message }; }
+function object(value) { return value !== null && typeof value === 'object'; }
+function string(value) { return typeof value === 'string' && value.length > 0; }
+function parse(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (!object(value) || value.schemaVersion !== 4 || !Array.isArray(value.rows) || !value.rows.every(isV4Row))
+            return null;
+        return { body: value, rows: value.rows };
+    }
+    catch {
+        return null;
+    }
+}
+async function inspect(io, home, body, rows) {
+    const pre1b = body.pre1b;
+    if (!object(pre1b) || !string(pre1b.backupRef))
+        return blocked('merge-state-needs-repair', 'schema4 state is missing pre1b backup reference');
+    const manifest = await readPre1bManifest(io, home, pre1b.backupRef).catch(() => null);
+    if (manifest === null)
+        return blocked('merge-state-backup-missing', 'pre-1b backup manifest is unreadable: ' + pre1b.backupRef);
+    return { ok: true, schema: 4, state: { schemaVersion: 4, rows, ...(body.migration === undefined ? {} : { migration: body.migration }), pre1b: { backupRef: pre1b.backupRef, at: typeof pre1b.at === 'string' ? pre1b.at : '' } } };
+}
+/** Pure read-only v4 readiness. Does not normalize, repair, or write. */
+export async function readV4Readiness(io, home) {
+    let raw;
+    try {
+        raw = await io.readText(schema4StatePath(home));
+    }
+    catch {
+        return blocked('merge-state-needs-repair', 'merge state is unreadable');
+    }
+    if (raw === null)
+        return blocked('merge-state-v4-required', 'schema4 state is missing');
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return blocked('merge-state-needs-repair', 'merge state is not JSON');
+    }
+    if (!object(value))
+        return blocked('merge-state-needs-repair', 'merge state is not an object');
+    if (typeof value.schemaVersion === 'number' && value.schemaVersion > 4)
+        return blocked('merge-state-forward-only', 'state schema ' + String(value.schemaVersion) + ' is newer than this build');
+    if (value.schemaVersion === 3)
+        return blocked('merge-state-normalize-required', 'schema3 state requires v4 normalize');
+    if (value.schemaVersion === 2 || value.schemaVersion === 1)
+        return blocked('merge-state-migration-required', 'legacy state requires schema migration');
+    if (value.schemaVersion !== 4)
+        return blocked('merge-state-needs-repair', 'merge state has no supported schemaVersion');
+    const parsed = parse(raw);
+    if (parsed === null)
+        return blocked('merge-state-needs-repair', 'schema4 state has an invalid row');
+    return await inspect(io, home, parsed.body, parsed.rows);
+}
+/** Atomic readiness + V4 row write under one state-file lock. No production caller in 1b-2a. */
+export async function transactMergeState(io, home, fn) {
+    let result;
+    await transactIo(io, schema4StatePath(home), async (current) => {
+        if (current === null)
+            throw new V4BlockedError(blocked('merge-state-v4-required', 'schema4 state is missing'));
+        let value;
+        try {
+            value = JSON.parse(current);
+        }
+        catch {
+            throw new V4BlockedError(blocked('merge-state-needs-repair', 'merge state is not JSON'));
+        }
+        if (!object(value))
+            throw new V4BlockedError(blocked('merge-state-needs-repair', 'merge state is not an object'));
+        if (typeof value.schemaVersion === 'number' && value.schemaVersion > 4)
+            throw new V4BlockedError(blocked('merge-state-forward-only', 'state schema ' + String(value.schemaVersion) + ' is newer than this build'));
+        if (value.schemaVersion === 3)
+            throw new V4BlockedError(blocked('merge-state-normalize-required', 'schema3 state requires v4 normalize'));
+        if (value.schemaVersion !== 4)
+            throw new V4BlockedError(blocked('merge-state-needs-repair', 'merge state is not schema4'));
+        const parsed = parse(current);
+        if (parsed === null)
+            throw new V4BlockedError(blocked('merge-state-needs-repair', 'schema4 state has an invalid row'));
+        const ready = await inspect(io, home, parsed.body, parsed.rows);
+        if (!ready.ok)
+            throw new V4BlockedError(ready);
+        let rows = parsed.rows;
+        const apply = (write) => {
+            const next = applyV4Write(rows, write, new Date().toISOString());
+            if (next.ok)
+                rows = next.rows;
+            return next;
+        };
+        const tx = {
+            rows: () => rows,
+            createVerify: row => apply({ kind: 'createVerify', row }),
+            createSkipped: row => apply({ kind: 'createSkipped', row }),
+            transition: (id, event, expectedVersion) => apply({ kind: 'transition', id, event, expectedVersion }),
+            remove: (id, terminal, unit, expectedVersion) => apply({ kind: 'remove', id, terminal, ...(unit === undefined ? {} : { unit }), expectedVersion }),
+        };
+        result = await fn(tx);
+        return JSON.stringify({ ...parsed.body, schemaVersion: 4, rows }, null, 2) + '\n';
+    });
+    if (result === undefined)
+        throw new V4BlockedError(blocked('merge-state-needs-repair', 'v4 transaction did not produce a result'));
+    return result;
+}
+/** Pure v3-to-v4 projection for fixtures; 1b-2b wires it to the production normalize. */
+export function normalizeV3State(state, pre1b) {
+    return { schemaVersion: 4, rows: state.rows.map(v3ToV4), ...(state.migration === undefined ? {} : { migration: state.migration }), pre1b };
+}
+export function parseV4State(raw) {
+    const parsed = parse(raw);
+    if (parsed === null)
+        return null;
+    return { schemaVersion: 4, rows: parsed.rows, ...(parsed.body.migration === undefined ? {} : { migration: parsed.body.migration }), ...(object(parsed.body.pre1b) && string(parsed.body.pre1b.backupRef) ? { pre1b: { backupRef: parsed.body.pre1b.backupRef, at: typeof parsed.body.pre1b.at === 'string' ? parsed.body.pre1b.at : '' } } : {}) };
+}
+//# sourceMappingURL=schema4.js.map

package/lib/types/domain/selection-policy.d.ts

@@ -0,0 +1,14 @@
+/** Batch 3 selection policy: filter managed/protected before writing skipped. */
+import type { MergeCandidate } from '../contracts.ts';
+export interface SelectionLike {
+    readonly candidates: readonly MergeCandidate[];
+    readonly skipped: readonly {
+        readonly pairKey: string;
+        readonly a: string;
+        readonly b: string;
+        readonly reason?: string;
+    }[];
+    readonly reportOnly: readonly unknown[];
+}
+export declare function filterSelection<T extends SelectionLike>(selection: T, isManaged: (name: string) => boolean, isProtected: (name: string) => boolean): T;
+//# sourceMappingURL=selection-policy.d.ts.map

package/lib/types/domain/selection-policy.js

@@ -0,0 +1,6 @@
+export function filterSelection(selection, isManaged, isProtected) {
+    const skipped = selection.skipped.filter(item => isManaged(item.a) && isManaged(item.b) && !isProtected(item.a) && !isProtected(item.b));
+    const candidates = selection.candidates.filter(item => isManaged(item.a) && isManaged(item.b) && !isProtected(item.a) && !isProtected(item.b));
+    return { ...selection, candidates, skipped };
+}
+//# sourceMappingURL=selection-policy.js.map

package/lib/types/domain/skipped-expiry.d.ts

@@ -0,0 +1,5 @@
+/** Pure skipped-TTL planning. Reconcile owns the durable write. */
+import type { V4Row } from './row-v4.ts';
+/** Row ids whose skipped TTL has elapsed at `now`; the caller applies one transition each. */
+export declare function planSkippedExpiry(rows: readonly V4Row[], ttlDays: number, now: number): readonly string[];
+//# sourceMappingURL=skipped-expiry.d.ts.map

package/lib/types/domain/skipped-expiry.js

@@ -0,0 +1,16 @@
+/** Row ids whose skipped TTL has elapsed at `now`; the caller applies one transition each. */
+export function planSkippedExpiry(rows, ttlDays, now) {
+    if (ttlDays <= 0)
+        return [];
+    const ids = [];
+    for (const row of rows) {
+        if (row.state !== 'skipped' || row.expiredAt !== undefined)
+            continue;
+        const created = Date.parse(row.createdAt);
+        if (!Number.isFinite(created) || now - created < ttlDays * 86_400_000)
+            continue;
+        ids.push(row.id);
+    }
+    return ids;
+}
+//# sourceMappingURL=skipped-expiry.js.map

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

@@ -6,6 +6,7 @@ export interface StagingEntry {
     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>;