@lmzhen/dsh-evolution-merge 0.30.16 → 0.30.18

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

@@ -0,0 +1,68 @@
+function blocked(message) { return { ok: false, code: 'state-migration-blocked', message }; }
+function text(value) { return typeof value === 'string' && value.length > 0; }
+function decisionOf(value) { return value !== null && typeof value === 'object' ? value : undefined; }
+function failureOf(value) { return value !== null && typeof value === 'object' ? value : undefined; }
+function originOf(value) { return value === 'agent' || value === 'human' || value === 'system' ? value : 'system'; }
+export function migrateV2ToV3(raw) {
+    const state = raw;
+    if (state === null || typeof state !== 'object' || !Array.isArray(state.rows))
+        return blocked('v2 state is not {rows[]}');
+    if (state.schemaVersion !== 2 && state.schemaVersion !== undefined)
+        return blocked('v2 state schemaVersion is ' + String(state.schemaVersion));
+    const rows = [];
+    const quarantine = [];
+    for (const value of state.rows) {
+        if (!text(value.id) || !text(value.pairKey) || !text(value.a) || !text(value.b)) {
+            quarantine.push({ reason: 'v2 row identity is incomplete', raw: value });
+            continue;
+        }
+        if (!text(value.state) || !text(value.createdAt) || !text(value.updatedAt)) {
+            quarantine.push({ reason: 'v2 row state/timestamps are incomplete', raw: value });
+            continue;
+        }
+        const base = { id: value.id, pairKey: value.pairKey, a: value.a, b: value.b, version: 0, createdAt: value.createdAt, updatedAt: value.updatedAt, origin: originOf(value.origin), ...(failureOf(value.failure) === undefined ? {} : { failure: failureOf(value.failure) }) };
+        if (value.state === 'verify') {
+            const row = { ...base, state: 'verify', verifySubState: 'unverified', attempts: typeof value.attempts === 'number' ? value.attempts : 0, ...(text(value.sourceRevision) ? { sourceRevision: value.sourceRevision } : {}) };
+            rows.push(row);
+            continue;
+        }
+        if (value.state === 'skipped') {
+            if (!text(value.reason)) {
+                quarantine.push({ reason: 'skipped row lacks reason', raw: value });
+                continue;
+            }
+            const row = { ...base, state: 'skipped', reason: value.reason, attempts: typeof value.attempts === 'number' ? value.attempts : 0, ...(value.reason === 'expired' && text(value.updatedAt) ? { expiredAt: Date.parse(value.updatedAt) } : {}) };
+            rows.push(row);
+            continue;
+        }
+        const decision = decisionOf(value.decision);
+        if (decision === undefined) {
+            quarantine.push({ reason: 'row lacks decision', raw: value });
+            continue;
+        }
+        const targetName = text(value.target?.requested) ? value.target.requested : text(decision.target) ? decision.target : undefined;
+        if (targetName === undefined) {
+            quarantine.push({ reason: 'row lacks target', raw: value });
+            continue;
+        }
+        if (value.state === 'pending') {
+            const row = { ...base, state: 'pending', target: targetName, decision, attempts: typeof value.attempts === 'number' ? value.attempts : 0, ...(text(value.targetRevision) ? { targetRevision: value.targetRevision } : {}), ...(text(value.sourceRevision) ? { sourceRevision: value.sourceRevision } : {}), ...(value.expired === 'target-taken' || value.expired === 'source-changed' ? { expired: value.expired } : {}) };
+            rows.push(row);
+            continue;
+        }
+        if (value.state === 'approved') {
+            rows.push({ ...base, state: 'approved', target: targetName, decision, attempts: typeof value.attempts === 'number' ? value.attempts : 0, ...(text(value.sourceRevision) ? { sourceRevision: value.sourceRevision } : {}), ...(text(value.runId) ? { runId: value.runId } : {}) });
+            continue;
+        }
+        if (value.state === 'fuse') {
+            const staging = text(value.stagingRef)
+                ? typeof value.stagingExpiresAt === 'number' ? { kind: 'present', ref: value.stagingRef, expiresAt: value.stagingExpiresAt } : { kind: 'expired', expiresAt: 0, ref: value.stagingRef }
+                : { kind: 'absent' };
+            rows.push({ ...base, state: 'fuse', target: targetName, decision, attempts: typeof value.attempts === 'number' ? value.attempts : 0, ...(text(value.sourceRevision) ? { sourceRevision: value.sourceRevision } : {}), ...(text(value.runId) ? { runId: value.runId } : {}), staging });
+            continue;
+        }
+        quarantine.push({ reason: 'unknown v2 state: ' + value.state, raw: value });
+    }
+    return { ok: true, state: { schemaVersion: 3, rows }, quarantine };
+}
+//# sourceMappingURL=migrate-v3.js.map

package/lib/types/domain/row-tx.d.ts

@@ -0,0 +1,27 @@
+/** G3-5 RowTx pure write API: only createVerify/createSkipped/transition. */
+import { type SkippedRowV3, type V3Event, type V3Row, type VerifyRowV3 } from './row-v3.ts';
+export type RowWrite = {
+    readonly kind: 'createVerify';
+    readonly row: VerifyRowV3;
+} | {
+    readonly kind: 'createSkipped';
+    readonly row: SkippedRowV3;
+} | {
+    readonly kind: 'transition';
+    readonly id: string;
+    readonly event: V3Event;
+    readonly expectedVersion: number;
+};
+type RowWriteErrorCode = 'row-invalid' | 'row-duplicate' | 'row-not-found' | 'version-conflict' | 'illegal-transition';
+export type RowWriteResult = {
+    readonly ok: true;
+    readonly rows: readonly V3Row[];
+    readonly row: V3Row | null;
+} | {
+    readonly ok: false;
+    readonly code: RowWriteErrorCode;
+    readonly message: string;
+};
+export declare function applyRowWrite(rows: readonly V3Row[], write: RowWrite, at: string): RowWriteResult;
+export {};
+//# sourceMappingURL=row-tx.d.ts.map

package/lib/types/domain/row-tx.js

@@ -0,0 +1,31 @@
+/** G3-5 RowTx pure write API: only createVerify/createSkipped/transition. */
+import { isV3Row, transitionV3 } from "./row-v3.js";
+function bad(code, message) { return { ok: false, code, message }; }
+export function applyRowWrite(rows, write, at) {
+    if (write.kind === 'transition') {
+        const index = rows.findIndex(row => row.id === write.id);
+        if (index < 0)
+            return bad('row-not-found', 'row not found: ' + write.id);
+        const current = rows[index];
+        const moved = transitionV3(current, write.event, write.expectedVersion, at);
+        if (!moved.ok)
+            return bad(moved.code, moved.message);
+        if (moved.row === null)
+            return { ok: true, rows: rows.filter((_, atIndex) => atIndex !== index), row: null };
+        const next = [...rows];
+        next[index] = moved.row;
+        return { ok: true, rows: next, row: moved.row };
+    }
+    if (write.row.version !== 0)
+        return bad('row-invalid', 'create requires version 0');
+    if (write.kind === 'createVerify' && (write.row.state !== 'verify' || write.row.verifySubState !== 'unverified'))
+        return bad('row-invalid', 'createVerify requires verify/unverified');
+    if (write.kind === 'createSkipped' && write.row.state !== 'skipped')
+        return bad('row-invalid', 'createSkipped requires skipped');
+    if (!isV3Row(write.row))
+        return bad('row-invalid', 'created row is invalid');
+    if (rows.some(row => row.id === write.row.id))
+        return bad('row-duplicate', 'duplicate row id: ' + write.row.id);
+    return { ok: true, rows: [...rows, write.row], row: write.row };
+}
+//# sourceMappingURL=row-tx.js.map

package/lib/types/domain/row-v3-bridge.d.ts

@@ -0,0 +1,6 @@
+/** Temporary v3 <-> legacy projection while commands still consume the flat row. */
+import type { MergeRowV2 } from './row.ts';
+import type { V3Row } from './row-v3.ts';
+export declare function v3ToLegacy(row: V3Row): MergeRowV2;
+export declare function legacyToV3(row: MergeRowV2): V3Row | null;
+//# sourceMappingURL=row-v3-bridge.d.ts.map

package/lib/types/domain/row-v3-bridge.js

@@ -0,0 +1,47 @@
+export function v3ToLegacy(row) {
+    const common = {
+        id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, state: row.state,
+        queue: row.state === 'verify' ? 'verify' : row.state === 'pending' ? 'pending' : row.state === 'skipped' ? 'skipped' : 'fuse',
+        version: row.version, origin: row.origin, ...(row.runId === undefined ? {} : { runId: row.runId }),
+        ...(row.failure === undefined ? {} : { failure: row.failure }),
+        createdAt: row.createdAt, updatedAt: row.updatedAt,
+    };
+    if (row.state === 'verify')
+        return { ...common, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), attempts: row.attempts };
+    if (row.state === 'skipped')
+        return { ...common, reason: row.reason, queue: 'skipped', ...(row.expiredAt === undefined ? {} : { expired: 'target-taken' }), attempts: row.attempts };
+    const target = { requested: row.target, ...(row.state === 'fuse' ? { actual: row.target } : {}) };
+    if (row.state === 'fuse') {
+        return {
+            ...common, target, decision: row.decision, attempts: row.attempts,
+            ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }),
+            ...(row.runId === undefined ? {} : { runId: row.runId }),
+            ...(row.staging.kind === 'present' ? { stagingRef: row.staging.ref, stagingExpiresAt: row.staging.expiresAt } : row.staging.kind === 'expired' ? { stagingExpiresAt: row.staging.expiresAt, ...(row.staging.ref === undefined ? {} : { stagingRef: row.staging.ref }) } : {}),
+        };
+    }
+    return {
+        ...common, target, decision: row.decision, attempts: row.attempts,
+        ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }),
+        ...(row.state === 'pending' && row.targetRevision !== undefined ? { targetRevision: row.targetRevision } : {}),
+        ...(row.state === 'pending' && row.expired !== undefined ? { expired: row.expired } : {}),
+        ...(row.state === 'approved' && row.runId !== undefined ? { runId: row.runId } : {}),
+    };
+}
+export function legacyToV3(row) {
+    const base = { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, version: row.version ?? 0, createdAt: row.createdAt, updatedAt: row.updatedAt, origin: row.origin ?? 'system', ...(row.runId === undefined ? {} : { runId: row.runId }), ...(row.failure === undefined ? {} : { failure: row.failure }) };
+    if (row.state === 'verify')
+        return { ...base, state: 'verify', verifySubState: 'unverified', attempts: row.attempts ?? 0, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }) };
+    if (row.state === 'skipped')
+        return { ...base, state: 'skipped', reason: row.reason ?? 'skipped', attempts: row.attempts ?? 0 };
+    const targetName = row.target?.requested ?? row.a;
+    const decision = row.decision ?? { shouldMerge: false, mode: 'keep', target: targetName, sources: [row.b], rationale: 'legacy row without decision' };
+    if (row.state === 'pending')
+        return { ...base, state: 'pending', target: targetName, decision, attempts: row.attempts ?? 0, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), ...(row.targetRevision === undefined ? {} : { targetRevision: row.targetRevision }), ...(row.expired === undefined ? {} : { expired: row.expired }) };
+    if (row.state === 'approved')
+        return { ...base, state: 'approved', target: targetName, decision, attempts: row.attempts ?? 0, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), ...(row.runId === undefined ? {} : { runId: row.runId }) };
+    const staging = row.stagingRef !== undefined
+        ? row.stagingExpiresAt !== undefined ? { kind: 'present', ref: row.stagingRef, expiresAt: row.stagingExpiresAt } : { kind: 'expired', expiresAt: 0 }
+        : { kind: 'absent' };
+    return { ...base, state: 'fuse', target: targetName, decision, attempts: row.attempts ?? 0, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), ...(row.runId === undefined ? {} : { runId: row.runId }), staging };
+}
+//# sourceMappingURL=row-v3-bridge.js.map

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

@@ -0,0 +1,113 @@
+/** G3 v3 row machine (parallel to the v2 row until the schema-3 cutover). */
+import type { MergeDecision, MergeFailure } from '../contracts.ts';
+export type RowOriginV3 = 'agent' | 'human' | 'system';
+export type VerifySubStateV3 = 'candidate' | 'screened' | 'unverified';
+export interface RowBaseV3 {
+    readonly id: string;
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly version: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly origin: RowOriginV3;
+    readonly failure?: MergeFailure;
+    readonly runId?: string;
+}
+export interface VerifyRowV3 extends RowBaseV3 {
+    readonly state: 'verify';
+    readonly verifySubState: VerifySubStateV3;
+    readonly sourceRevision?: string;
+    readonly attempts: number;
+}
+export interface PendingRowV3 extends RowBaseV3 {
+    readonly state: 'pending';
+    readonly target: string;
+    readonly decision: MergeDecision;
+    readonly targetRevision?: string;
+    readonly sourceRevision?: string;
+    readonly expired?: 'target-taken' | 'source-changed';
+    readonly attempts: number;
+}
+export interface ApprovedRowV3 extends RowBaseV3 {
+    readonly state: 'approved';
+    readonly target: string;
+    readonly decision: MergeDecision;
+    readonly sourceRevision?: string;
+    readonly runId?: string;
+    readonly attempts: number;
+}
+export interface FuseRowV3 extends RowBaseV3 {
+    readonly state: 'fuse';
+    readonly target: string;
+    readonly decision: MergeDecision;
+    readonly sourceRevision?: string;
+    readonly staging: {
+        readonly kind: 'present';
+        readonly ref: string;
+        readonly expiresAt: number;
+    } | {
+        readonly kind: 'absent';
+    } | {
+        readonly kind: 'expired';
+        readonly expiresAt: number;
+        readonly ref?: string;
+    };
+    readonly runId?: string;
+    readonly attempts: number;
+}
+export interface SkippedRowV3 extends RowBaseV3 {
+    readonly state: 'skipped';
+    readonly reason: string;
+    readonly expiredAt?: number;
+    readonly attempts: number;
+}
+export type V3Row = VerifyRowV3 | PendingRowV3 | ApprovedRowV3 | FuseRowV3 | SkippedRowV3;
+export type V3Event = {
+    readonly type: 'verify-passed';
+    readonly decision: MergeDecision;
+    readonly target: string;
+    readonly sourceRevision?: string;
+} | {
+    readonly type: 'approved';
+    readonly runId: string;
+} | {
+    readonly type: 'auto-approved';
+    readonly decision: MergeDecision;
+    readonly target: string;
+    readonly runId?: string;
+} | {
+    readonly type: 'staged';
+    readonly ref?: string;
+    readonly expiresAt?: number;
+} | {
+    readonly type: 'committed';
+    readonly unitId: string;
+} | {
+    readonly type: 'skipped';
+    readonly reason: string;
+    readonly origin?: 'agent' | 'human' | 'system';
+} | {
+    readonly type: 'expired';
+    readonly kind: 'target-taken' | 'source-changed';
+} | {
+    readonly type: 'failed';
+    readonly failure: MergeFailure;
+} | {
+    readonly type: 'restored';
+} | {
+    readonly type: 'superseded';
+};
+export type V3Transition = {
+    readonly ok: true;
+    readonly row: V3Row | null;
+    readonly version: number;
+} | {
+    readonly ok: false;
+    readonly code: 'version-conflict' | 'illegal-transition';
+    readonly message: string;
+};
+export declare function transitionV3(row: V3Row, event: V3Event, expectedVersion: number, at?: string): V3Transition;
+/** Runtime validation for a persisted v3 row. */
+export declare function isV3Row(value: unknown): value is V3Row;
+//# sourceMappingURL=row-v3.d.ts.map

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

@@ -0,0 +1,107 @@
+function bad(code, message) { return { ok: false, code, message }; }
+function advance(row, at, patch) { return { ...row, ...patch, version: row.version + 1, updatedAt: at }; }
+export function transitionV3(row, event, expectedVersion, at = new Date().toISOString()) {
+    if (row.version !== expectedVersion)
+        return bad('version-conflict', 'expected ' + String(expectedVersion) + ', got ' + String(row.version));
+    switch (row.state) {
+        case 'verify':
+            if (event.type === 'verify-passed')
+                return { ok: true, row: advance(row, at, { state: 'pending', target: event.target, decision: event.decision, sourceRevision: event.sourceRevision, attempts: 0 }), version: expectedVersion + 1 };
+            if (event.type === 'auto-approved')
+                return { ok: true, row: advance(row, at, { state: 'approved', target: event.target, decision: event.decision, attempts: 0, ...(event.runId === undefined ? {} : { runId: event.runId }) }), version: expectedVersion + 1 };
+            if (event.type === 'failed')
+                return { ok: true, row: advance(row, at, { failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 };
+            if (event.type === 'skipped')
+                return { ok: true, row: advance(row, at, { state: 'skipped', reason: event.reason, attempts: row.attempts }), version: expectedVersion + 1 };
+            if (event.type === 'superseded')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            return bad('illegal-transition', 'verify/' + event.type);
+        case 'pending':
+            if (event.type === 'approved')
+                return { ok: true, row: advance(row, at, { state: 'approved', runId: event.runId }), version: expectedVersion + 1 };
+            if (event.type === 'auto-approved')
+                return { ok: true, row: advance(row, at, { state: 'approved', ...(event.runId === undefined ? {} : { runId: event.runId }) }), version: expectedVersion + 1 };
+            if (event.type === 'staged')
+                return { ok: true, row: advance(row, at, { state: 'fuse', staging: event.ref === undefined ? { kind: 'absent' } : { kind: 'present', ref: event.ref, expiresAt: event.expiresAt ?? Date.now() + 7 * 86_400_000 } }), version: expectedVersion + 1 };
+            if (event.type === 'skipped')
+                return { ok: true, row: advance(row, at, { state: 'skipped', reason: event.reason, ...(event.origin === undefined ? {} : { origin: event.origin }) }), version: expectedVersion + 1 };
+            if (event.type === 'expired')
+                return { ok: true, row: advance(row, at, { expired: event.kind }), version: expectedVersion + 1 };
+            if (event.type === 'failed')
+                return { ok: true, row: advance(row, at, { failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 };
+            if (event.type === 'superseded')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            return bad('illegal-transition', 'pending/' + event.type);
+        case 'approved':
+            if (event.type === 'staged')
+                return { ok: true, row: advance(row, at, { state: 'fuse', staging: event.ref === undefined ? { kind: 'absent' } : { kind: 'present', ref: event.ref, expiresAt: event.expiresAt ?? Date.now() + 7 * 86_400_000 } }), version: expectedVersion + 1 };
+            if (event.type === 'committed')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            if (event.type === 'skipped')
+                return { ok: true, row: advance(row, at, { state: 'skipped', reason: event.reason }), version: expectedVersion + 1 };
+            if (event.type === 'failed')
+                return event.failure.retryable
+                    ? { ok: true, row: advance(row, at, { state: 'pending', failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 }
+                    : { ok: true, row: advance(row, at, { state: 'skipped', reason: event.failure.code, failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 };
+            if (event.type === 'superseded')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            return bad('illegal-transition', 'approved/' + event.type);
+        case 'fuse':
+            if (event.type === 'staged')
+                return { ok: true, row: advance(row, at, { staging: event.ref === undefined ? { kind: 'absent' } : { kind: 'present', ref: event.ref, expiresAt: event.expiresAt ?? Date.now() + 7 * 86_400_000 } }), version: expectedVersion + 1 };
+            if (event.type === 'committed')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            if (event.type === 'skipped')
+                return { ok: true, row: advance(row, at, { state: 'skipped', reason: event.reason }), version: expectedVersion + 1 };
+            if (event.type === 'failed')
+                return event.failure.retryable
+                    ? { ok: true, row: advance(row, at, { state: 'pending', failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 }
+                    : { ok: true, row: advance(row, at, { state: 'skipped', reason: event.failure.code, failure: event.failure, attempts: row.attempts + 1 }), version: expectedVersion + 1 };
+            if (event.type === 'superseded')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            return bad('illegal-transition', 'fuse/' + event.type);
+        case 'skipped':
+            if (event.type === 'restored' || event.type === 'superseded')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            return bad('illegal-transition', 'skipped is terminal');
+    }
+}
+function object(value) { return value !== null && typeof value === 'object'; }
+function string(value) { return typeof value === 'string' && value.length > 0; }
+function number(value) { return typeof value === 'number' && Number.isFinite(value); }
+/** Runtime validation for a persisted v3 row. */
+export function isV3Row(value) {
+    if (!object(value))
+        return false;
+    if (!string(value.id) || !string(value.pairKey) || !string(value.a) || !string(value.b) || !number(value.version))
+        return false;
+    if (!string(value.createdAt) || !string(value.updatedAt))
+        return false;
+    if (value.origin !== 'agent' && value.origin !== 'human' && value.origin !== 'system')
+        return false;
+    if (value.failure !== undefined && !object(value.failure))
+        return false;
+    if (!number(value.attempts))
+        return false;
+    switch (value.state) {
+        case 'verify':
+            return value.verifySubState === 'candidate' || value.verifySubState === 'screened' || value.verifySubState === 'unverified';
+        case 'pending':
+            return string(value.target) && object(value.decision);
+        case 'approved':
+            return string(value.target) && object(value.decision);
+        case 'fuse':
+            if (!string(value.target) || !object(value.decision) || !object(value.staging))
+                return false;
+            if (value.staging.kind === 'present')
+                return string(value.staging.ref) && number(value.staging.expiresAt);
+            if (value.staging.kind === 'expired')
+                return number(value.staging.expiresAt);
+            return value.staging.kind === 'absent';
+        case 'skipped':
+            return string(value.reason);
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=row-v3.js.map

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

@@ -15,6 +15,7 @@ export interface MergeRowV2 {
     readonly unitId?: string;
     readonly origin?: 'agent' | 'human' | 'system';
     readonly attempts?: number;
+    readonly version?: number;
     readonly stagingRef?: string;
     readonly stagingExpiresAt?: number;
     readonly target?: {

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

@@ -0,0 +1,14 @@
+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;
+}
+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-v3.d.ts

@@ -0,0 +1,15 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type QuarantinedRow, type V3State } from './migrate-v3.ts';
+export declare function v2BackupPath(home: string): string;
+export type StateMigration = {
+    readonly ok: true;
+    readonly migrated: boolean;
+    readonly state: V3State;
+    readonly quarantine: readonly QuarantinedRow[];
+} | {
+    readonly ok: false;
+    readonly code: 'state-migration-blocked';
+    readonly message: string;
+};
+export declare function loadOrMigrateStateV3(io: EvolutionIoLike, home: string): Promise<StateMigration>;
+//# sourceMappingURL=state-v3.d.ts.map

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

@@ -0,0 +1,80 @@
+/** G3 schema-3 state IO: backup v2, map, atomic v3 write. */
+import { chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { migrateV2ToV3 } from "./migrate-v3.js";
+import { isV3Row } from "./row-v3.js";
+import { writeStagingIndex } from "./staging-index.js";
+export function v2BackupPath(home) { return join(home, 'merge', 'merge-state.v2.bak.json'); }
+function blocked(message) { return { ok: false, code: 'state-migration-blocked', message }; }
+async function readOnly(path) { try {
+    await chmod(path, 0o444);
+}
+catch { /* io seam without chmod; v2 bytes still preserved */ } }
+export async function loadOrMigrateStateV3(io, home) {
+    const path = join(home, 'merge', 'merge-state.json');
+    const raw = await io.readText(path);
+    if (raw === null)
+        return { ok: true, migrated: false, state: { schemaVersion: 3, rows: [] }, quarantine: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return blocked('v2 state is not JSON');
+    }
+    if (parsed !== null && typeof parsed === 'object' && parsed.schemaVersion === 3) {
+        const rows = parsed.rows;
+        if (!Array.isArray(rows) || !rows.every(isV3Row))
+            return blocked('v3 state has an invalid row');
+        return { ok: true, migrated: false, state: { schemaVersion: 3, rows }, quarantine: [] };
+    }
+    const mapped = migrateV2ToV3(parsed);
+    if (!mapped.ok)
+        return blocked(mapped.message);
+    const backup = v2BackupPath(home);
+    const existing = await io.readText(backup);
+    if (existing !== null && existing !== raw)
+        return blocked('v2 backup exists with different bytes');
+    if (existing === null) {
+        try {
+            if (io.transact !== undefined)
+                await io.transact(backup, () => raw);
+            else
+                await io.writeText(backup, raw);
+        }
+        catch {
+            return blocked('v2 backup write failed');
+        }
+    }
+    await readOnly(backup);
+    const rawRows = parsed.rows;
+    if (Array.isArray(rawRows)) {
+        for (const row of rawRows) {
+            if (typeof row.id !== 'string' || typeof row.pairKey !== 'string' || typeof row.stagingRef !== 'string')
+                continue;
+            if (row.state !== 'pending' && row.state !== 'approved')
+                continue;
+            await writeStagingIndex(io, home, { 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() });
+        }
+    }
+    if (mapped.quarantine.length > 0) {
+        try {
+            await io.writeText(join(home, 'merge', 'merge-state.quarantine.json'), JSON.stringify(mapped.quarantine, null, 2) + '\n');
+        }
+        catch {
+            return blocked('quarantine write failed; v3 not written');
+        }
+    }
+    const text = JSON.stringify(mapped.state, null, 2) + '\n';
+    try {
+        if (io.transact !== undefined)
+            await io.transact(path, () => text);
+        else
+            await io.writeText(path, text);
+    }
+    catch {
+        return blocked('v3 state write failed; v2 backup + quarantine retained');
+    }
+    return { ok: true, migrated: true, state: mapped.state, quarantine: mapped.quarantine };
+}
+//# sourceMappingURL=state-v3.js.map

package/lib/types/facts.d.ts

@@ -0,0 +1,24 @@
+/** 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';
+export declare function countsOf(rows: readonly MergeRow[]): MergeCounts;
+export declare function toRunView(record: RunRecord, readAt: number): RunView;
+export interface FactsInput {
+    readonly rows: readonly MergeRow[];
+    readonly runs: readonly RunRecord[];
+    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