@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.19

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

@@ -0,0 +1,148 @@
+/** Batch 1b-2a additive schema4 row types and pure write helpers. */
+import type { MergeDecision, MergeFailure, MergeRow } from '../contracts.ts';
+import type { V3Row } from './row-v3.ts';
+export type RowOriginV4 = 'agent' | 'human' | 'system';
+export type VerifySubStateV4 = 'candidate' | 'screened' | 'unverified';
+export interface RowBaseV4 {
+    readonly id: string;
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly version: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly origin: RowOriginV4;
+    readonly failure?: MergeFailure;
+    readonly runId?: string;
+}
+export interface VerifyRowV4 extends RowBaseV4 {
+    readonly state: 'verify';
+    readonly verifySubState: VerifySubStateV4;
+    readonly sourceRevision?: string;
+    readonly attempts: number;
+}
+export interface PendingRowV4 extends RowBaseV4 {
+    readonly state: 'pending';
+    readonly target: string;
+    readonly decision: MergeDecision;
+    readonly targetRevision?: string;
+    readonly sourceRevision?: string;
+    readonly promptVersion?: string;
+    readonly promptHash?: string;
+    readonly expired?: 'target-taken' | 'source-changed';
+    readonly expiredAt?: number;
+    readonly attempts: number;
+}
+export interface ApprovedRowV4 extends RowBaseV4 {
+    readonly state: 'approved';
+    readonly target: string;
+    readonly decision: MergeDecision;
+    readonly sourceRevision?: string;
+    readonly targetRevision?: string;
+    readonly runId?: string;
+    readonly attempts: number;
+}
+export interface FuseRowV4 extends RowBaseV4 {
+    readonly state: 'fuse';
+    readonly target: string;
+    readonly decision: MergeDecision;
+    readonly sourceRevision?: string;
+    readonly targetRevision?: string;
+    readonly runId?: string;
+    readonly attempts: number;
+}
+export interface SkippedRowV4 extends RowBaseV4 {
+    readonly state: 'skipped';
+    readonly reason: string;
+    readonly skipSource?: string;
+    readonly expiredAt?: number;
+    readonly attempts: number;
+}
+export type V4Row = VerifyRowV4 | PendingRowV4 | ApprovedRowV4 | FuseRowV4 | SkippedRowV4;
+export type V4Event = {
+    readonly type: 'verify-passed';
+    readonly decision: MergeDecision;
+    readonly target: string;
+    readonly sourceRevision?: string;
+    readonly promptVersion?: string;
+    readonly promptHash?: string;
+} | {
+    readonly type: 'approved';
+    readonly runId: string;
+} | {
+    readonly type: 'auto-approved';
+    readonly decision: MergeDecision;
+    readonly target: string;
+    readonly runId?: string;
+} | {
+    readonly type: 'staged';
+} | {
+    readonly type: 'committed';
+    readonly unitId: CommitUnitRef;
+} | {
+    readonly type: 'skipped';
+    readonly reason: string;
+    readonly origin?: RowOriginV4;
+    readonly skipSource?: string;
+} | {
+    readonly type: 'mark-skipped-expired';
+    readonly at: number;
+} | {
+    readonly type: 'expired';
+    readonly kind: 'target-taken' | 'source-changed';
+} | {
+    readonly type: 'failed';
+    readonly failure: MergeFailure;
+} | {
+    readonly type: 'restored';
+} | {
+    readonly type: 'superseded';
+};
+export interface CommitUnitRef {
+    readonly unitId: string;
+    readonly evidenceSha256: string;
+}
+export type V4Transition = {
+    readonly ok: true;
+    readonly row: V4Row | null;
+    readonly version: number;
+} | {
+    readonly ok: false;
+    readonly code: 'version-conflict' | 'illegal-transition';
+    readonly message: string;
+};
+export type V4Terminal = 'committed' | 'superseded' | 'restored';
+export type V4Write = {
+    readonly kind: 'createVerify';
+    readonly row: VerifyRowV4;
+} | {
+    readonly kind: 'createSkipped';
+    readonly row: SkippedRowV4;
+} | {
+    readonly kind: 'transition';
+    readonly id: string;
+    readonly event: V4Event;
+    readonly expectedVersion: number;
+} | {
+    readonly kind: 'remove';
+    readonly id: string;
+    readonly terminal: V4Terminal;
+    readonly unit?: CommitUnitRef;
+    readonly expectedVersion: number;
+};
+export type V4WriteError = 'row-invalid' | 'row-duplicate' | 'row-not-found' | 'version-conflict' | 'illegal-transition';
+export type V4WriteResult = {
+    readonly ok: true;
+    readonly rows: readonly V4Row[];
+    readonly row: V4Row | null;
+} | {
+    readonly ok: false;
+    readonly code: V4WriteError;
+    readonly message: string;
+};
+export declare function transitionV4(row: V4Row, event: V4Event, expectedVersion: number, at?: string): V4Transition;
+export declare function isV4Row(value: unknown): value is V4Row;
+export declare function v3ToV4(row: V3Row): V4Row;
+export declare function applyV4Write(rows: readonly V4Row[], write: V4Write, at: string): V4WriteResult;
+export declare function v4ToLegacy(row: V4Row): MergeRow;
+//# sourceMappingURL=row-v4.d.ts.map

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

@@ -0,0 +1,159 @@
+function bad(code, message) { return { ok: false, code, message }; }
+function conflict(message) { return { ok: false, code: 'version-conflict', message }; }
+function illegal(message) { return { ok: false, code: 'illegal-transition', message }; }
+function advance(row, at, patch) { return { ...row, ...patch, version: row.version + 1, updatedAt: at }; }
+export function transitionV4(row, event, expectedVersion, at = new Date().toISOString()) {
+    if (row.version !== expectedVersion)
+        return 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, ...(event.sourceRevision === undefined ? {} : { sourceRevision: event.sourceRevision }), ...(event.promptVersion === undefined ? {} : { promptVersion: event.promptVersion }), ...(event.promptHash === undefined ? {} : { promptHash: event.promptHash }), 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, ...(event.skipSource === undefined ? {} : { skipSource: event.skipSource }) }), version: expectedVersion + 1 };
+            if (event.type === 'superseded')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            return illegal('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' }), 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 }), ...(event.skipSource === undefined ? {} : { skipSource: event.skipSource }) }), 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 illegal('pending/' + event.type);
+        case 'approved':
+            if (event.type === 'staged')
+                return { ok: true, row: advance(row, at, { state: 'fuse' }), 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, ...(event.skipSource === undefined ? {} : { skipSource: event.skipSource }) }), version: expectedVersion + 1 };
+            if (event.type === 'failed')
+                return event.failure.retryable
+                    ? { ok: true, row: advance(row, at, { state: 'fuse', 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 illegal('approved/' + event.type);
+        case 'fuse':
+            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, ...(event.skipSource === undefined ? {} : { skipSource: event.skipSource }) }), version: expectedVersion + 1 };
+            if (event.type === 'failed')
+                return event.failure.retryable
+                    ? { ok: true, row: advance(row, at, { state: 'fuse', 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 illegal('fuse/' + event.type);
+        case 'skipped':
+            if (event.type === 'restored' || event.type === 'superseded')
+                return { ok: true, row: null, version: expectedVersion + 1 };
+            if (event.type === 'mark-skipped-expired')
+                return row.expiredAt !== undefined ? { ok: true, row, version: expectedVersion } : { ok: true, row: { ...row, expiredAt: event.at }, version: expectedVersion + 1 };
+            return illegal('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); }
+export function isV4Row(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) || (value.origin !== 'agent' && value.origin !== 'human' && value.origin !== 'system'))
+        return false;
+    if (typeof value.attempts !== 'number')
+        return false;
+    if (value.state === 'verify')
+        return value.verifySubState === 'candidate' || value.verifySubState === 'screened' || value.verifySubState === 'unverified';
+    if (value.state === 'pending' || value.state === 'approved' || value.state === 'fuse')
+        return string(value.target) && object(value.decision);
+    if (value.state === 'skipped')
+        return string(value.reason);
+    return false;
+}
+export function v3ToV4(row) {
+    const base = { id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, version: row.version, createdAt: row.createdAt, updatedAt: row.updatedAt, origin: row.origin, attempts: row.attempts, ...(row.failure === undefined ? {} : { failure: row.failure }), ...(row.runId === undefined ? {} : { runId: row.runId }) };
+    if (row.state === 'verify')
+        return { ...base, state: 'verify', verifySubState: row.verifySubState, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }) };
+    if (row.state === 'pending')
+        return { ...base, state: 'pending', target: row.target, decision: row.decision, ...(row.targetRevision === undefined ? {} : { targetRevision: row.targetRevision }), ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), ...(row.expired === undefined ? {} : { expired: row.expired }) };
+    if (row.state === 'approved')
+        return { ...base, state: 'approved', target: row.target, decision: row.decision, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), ...(row.runId === undefined ? {} : { runId: row.runId }) };
+    if (row.state === 'fuse')
+        return { ...base, state: 'fuse', target: row.target, decision: row.decision, ...(row.sourceRevision === undefined ? {} : { sourceRevision: row.sourceRevision }), ...(row.runId === undefined ? {} : { runId: row.runId }) };
+    return { ...base, state: 'skipped', reason: row.reason, ...(row.expiredAt === undefined ? {} : { expiredAt: row.expiredAt }) };
+}
+export function applyV4Write(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 moved = transitionV4(rows[index], 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.kind === 'remove') {
+        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];
+        if (write.terminal === 'committed' && (write.unit === undefined || write.unit.unitId.length === 0 || write.unit.evidenceSha256.length === 0))
+            return bad('row-invalid', 'committed remove requires commit evidence');
+        const event = write.terminal === 'committed' ? { type: 'committed', unitId: write.unit } : { type: write.terminal };
+        const moved = transitionV4(current, event, write.expectedVersion, at);
+        if (!moved.ok)
+            return bad(moved.code, moved.message);
+        return moved.row === null ? { ok: true, rows: rows.filter((_, atIndex) => atIndex !== index), row: null } : { ok: true, rows: rows.map((row, atIndex) => atIndex === index ? moved.row : row), 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 (!isV4Row(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 };
+}
+export function v4ToLegacy(row) {
+    const queue = row.state === 'verify' ? 'verify' : row.state === 'pending' ? 'pending' : row.state === 'skipped' ? 'skipped' : 'fuse';
+    const target = row.state === 'pending' || row.state === 'approved' || row.state === 'fuse' ? { requested: row.target } : undefined;
+    return {
+        id: row.id, pairKey: row.pairKey, a: row.a, b: row.b, state: row.state, queue,
+        ...(row.state === 'skipped' ? { reason: row.reason } : {}),
+        ...(target === undefined ? {} : { target }),
+        ...(row.failure === undefined ? {} : { failure: row.failure }),
+        ...(row.state === 'pending' || row.state === 'approved' || row.state === 'fuse' ? { decision: row.decision } : {}),
+        ...((row.state === 'pending' || row.state === 'approved' || row.state === 'fuse') && row.sourceRevision !== undefined ? { sourceRevision: row.sourceRevision } : {}),
+        ...((row.state === 'pending' || row.state === 'approved' || row.state === 'fuse') && row.targetRevision !== undefined ? { targetRevision: row.targetRevision } : {}),
+        ...(row.runId === undefined ? {} : { runId: row.runId }),
+        ...(row.origin === undefined ? {} : { origin: row.origin }),
+        ...(row.attempts === undefined ? {} : { attempts: row.attempts }),
+        createdAt: row.createdAt, updatedAt: row.updatedAt,
+    };
+}
+//# sourceMappingURL=row-v4.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/run-coordinator.d.ts

@@ -0,0 +1,51 @@
+import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+export type MergeRunPhase = 'begin' | 'running' | 'awaiting-approval' | 'settled' | 'cancelled' | 'undone';
+export interface MergeRunMeta {
+    readonly version: 1;
+    readonly runId: string;
+    readonly pairCount?: number;
+    /** The pair a single-pair command (pair/approve/resume) is working on; absent for scan. */
+    readonly pairKey?: string;
+    readonly parentRunId?: string;
+    readonly phase: MergeRunPhase;
+    readonly stopReason?: string;
+    readonly approval?: 'pending' | 'approved' | 'rejected';
+    readonly reportRef?: string;
+    readonly undonePairs?: readonly string[];
+    readonly undoneAt?: string;
+    readonly degraded?: boolean;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface PairIndexEntry {
+    readonly version: 1;
+    readonly runId: string;
+    readonly pairKey: string;
+    readonly a: string;
+    readonly b: string;
+    readonly target: string;
+    readonly targetRevision?: string;
+    readonly sourceRevisions?: Readonly<Record<string, string>>;
+    readonly state: 'pending' | 'approved' | 'fused' | 'skipped';
+    readonly updatedAt: string;
+}
+export interface RunCoordinatorRead {
+    readonly runId: string;
+    readonly meta: MergeRunMeta | null;
+    readonly pairs: readonly PairIndexEntry[];
+    readonly consistency: 'eventual';
+}
+export interface RunCoordinator {
+    begin(meta: MergeRunMeta): Promise<void>;
+    recordPair(entry: PairIndexEntry): Promise<void>;
+    read(runId: string): Promise<RunCoordinatorRead>;
+}
+export declare function runMetaPath(home: string, runId: string): string;
+export declare function writeRunMeta(io: EvolutionIoLike, home: string, meta: MergeRunMeta): Promise<void>;
+export declare function readRunMeta(io: EvolutionIoLike, home: string, runId: string): Promise<MergeRunMeta | null>;
+/** Every run-meta record on disk (the in-flight index for pair/target serialisation). */
+export declare function readRunMetas(io: EvolutionIoLike, home: string): Promise<readonly MergeRunMeta[]>;
+/** The run currently working on this pair, if any (pairKey is written at run begin). */
+export declare function inFlightPairRun(metas: readonly MergeRunMeta[], pairKeyValue: string): MergeRunMeta | undefined;
+export { recordPair } from './pair-index-store.ts';
+//# sourceMappingURL=run-coordinator.d.ts.map

package/lib/types/domain/run-coordinator.js

@@ -0,0 +1,45 @@
+import { readTextOrNull, listOrEmpty } from "./read-probe.js";
+/** 1b-1 additive types for the merge run lifecycle; no writer is active in this phase. */
+import { join } from 'node:path';
+import { transactIo } from '@lmzhen/dsh-evolution-core';
+export function runMetaPath(home, runId) { return join(home, 'merge', 'run-meta', encodeURIComponent(runId) + '.json'); }
+export async function writeRunMeta(io, home, meta) {
+    await transactIo(io, runMetaPath(home, meta.runId), () => JSON.stringify(meta, null, 2) + '\n');
+}
+export async function readRunMeta(io, home, runId) {
+    const raw = await readTextOrNull(io, runMetaPath(home, runId));
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Every run-meta record on disk (the in-flight index for pair/target serialisation). */
+export async function readRunMetas(io, home) {
+    const root = join(home, 'merge', 'run-meta');
+    const names = await io.exists(root) ? await listOrEmpty(io, root) : [];
+    const metas = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const raw = await readTextOrNull(io, join(root, name));
+        if (raw === null)
+            continue;
+        try {
+            const meta = JSON.parse(raw);
+            if (typeof meta.runId === 'string' && typeof meta.phase === 'string')
+                metas.push(meta);
+        }
+        catch { /* malformed meta is not an in-flight claim */ }
+    }
+    return metas;
+}
+/** The run currently working on this pair, if any (pairKey is written at run begin). */
+export function inFlightPairRun(metas, pairKeyValue) {
+    return metas.find(meta => meta.phase === 'running' && meta.pairKey === pairKeyValue);
+}
+export { recordPair } from "./pair-index-store.js";
+//# sourceMappingURL=run-coordinator.js.map

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