@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.19

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

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

package/lib/types/domain/reconcile.js

@@ -0,0 +1,178 @@
+import { readTextOrNull } from "./read-probe.js";
+/**
+ * Explicit merge reconciliation: the ONE writer of row-state convergence.
+ *
+ * Reconcile owns the durable corrections that used to be scattered across startup
+ * (skipped TTL expiry, approved+reserved continuation) and reports them in
+ * `<home>/merge/reconcile.json`. Snapshots and all four GET routes stay read-only:
+ * they may DERIVE a fact (an expired stage, a source that disappeared) but never
+ * persist it; only this module and the command lifecycle write rows.
+ */
+import { join } from 'node:path';
+import { transactIo } from '@lmzhen/dsh-evolution-core';
+import { readV4Readiness } from "./schema4.js";
+import { pairLedger } from "./pair-ledger.js";
+import { planSkippedExpiry } from "./skipped-expiry.js";
+import { presentStage, readAllStages, readStageTree, writeStageIndex } from "./stage-aggregate.js";
+import { pendingExpiry } from "./live-facts.js";
+export const RECONCILE_REPORT_VERSION = 1;
+export function reconcileReportPath(home) {
+    return join(home, 'merge', 'reconcile.json');
+}
+/** Read the last reconcile report; a malformed report is absent, never a throw. */
+export async function readReconcileReport(io, home) {
+    const raw = await readTextOrNull(io, reconcileReportPath(home));
+    if (raw === null)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== RECONCILE_REPORT_VERSION || (parsed.state !== 'ok' && parsed.state !== 'blocked'))
+            return null;
+        if (typeof parsed.at !== 'number' || !Array.isArray(parsed.actions))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function blockedReport(now, code, message) {
+    return { version: RECONCILE_REPORT_VERSION, at: now, state: 'blocked', code, message, actions: [], notes: ['reconcile wrote nothing: the merge state is not readable'] };
+}
+/** One stage's tree can still serve the round-2 author. */
+async function stageUsable(io, home, entry, now) {
+    if (entry.state !== 'reserved' && entry.state !== 'present')
+        return false;
+    if (entry.expiresAt <= now)
+        return false;
+    return (await readStageTree(io, home, entry.ref).catch(() => ({ kind: 'absent' }))).kind === 'present';
+}
+/**
+ * Converge the row layer once, atomically, then persist the report.
+ * A blocked state writes no rows and no report; every other run is idempotent.
+ */
+export async function reconcileMergeState(options) {
+    const now = options.now();
+    const ttlDays = options.ttlDays ?? 0;
+    const ready = await readV4Readiness(options.io, options.home);
+    if (!ready.ok)
+        return blockedReport(now, ready.code, ready.message);
+    const stages = await readAllStages(options.io, options.home);
+    const byRow = new Map(stages.map(entry => [entry.rowId, entry]));
+    const usable = new Map();
+    const expiredStages = [];
+    for (const entry of stages) {
+        if (entry.state !== 'reserved' && entry.state !== 'present')
+            continue;
+        if (entry.expiresAt <= now) {
+            expiredStages.push(entry);
+            continue;
+        }
+        usable.set(entry.rowId, await stageUsable(options.io, options.home, entry, now));
+    }
+    const actions = [];
+    const promote = [];
+    await pairLedger(options.io, options.home).transact(tx => {
+        for (const row of [...tx.rows()]) {
+            if (row.state === 'skipped' && ttlDays > 0 && planSkippedExpiry([row], ttlDays, now).length === 1) {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current !== undefined && tx.transition(row.id, { type: 'mark-skipped-expired', at: now }, current.version).ok) {
+                    actions.push({ kind: 'skipped-expired', rowId: row.id, from: 'skipped', to: 'skipped', code: 'skipped-ttl' });
+                }
+                continue;
+            }
+            if (row.state === 'pending' && row.expired === undefined && options.live !== undefined) {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined || current.state !== 'pending' || current.expired !== undefined)
+                    continue;
+                const kind = pendingExpiry(current, options.live);
+                if (kind === null)
+                    continue;
+                if (kind === 'source-gone') {
+                    const removed = tx.remove(row.id, 'superseded', undefined, current.version);
+                    if (removed.ok)
+                        actions.push({ kind: 'source-gone', rowId: row.id, from: 'pending', to: 'removed', code: 'source-gone', detail: [row.a, row.b].filter(name => !options.live?.managed(name)).join(', ') });
+                    continue;
+                }
+                const moved = tx.transition(row.id, { type: 'expired', kind }, current.version);
+                if (moved.ok)
+                    actions.push({ kind: 'pending-expired', rowId: row.id, from: 'pending', to: 'pending', code: kind });
+                continue;
+            }
+            if (row.state !== 'approved')
+                continue;
+            const current = tx.rows().find(item => item.id === row.id);
+            if (current === undefined || current.state !== 'approved')
+                continue;
+            const entry = byRow.get(row.id);
+            if (usable.get(row.id) === true) {
+                const moved = tx.transition(row.id, { type: 'staged' }, current.version);
+                if (moved.ok) {
+                    actions.push({ kind: 'approved-fused', rowId: row.id, from: 'approved', to: 'fuse', code: 'stage-present' });
+                    if (entry !== undefined && entry.state === 'reserved')
+                        promote.push(entry);
+                }
+                continue;
+            }
+            const failure = { stage: 'author', code: 'stage-lost', message: 'stage tree is missing, expired, or lost before round2', retryable: true, retryFrom: 'agent2' };
+            const moved = tx.transition(row.id, { type: 'failed', failure }, current.version);
+            if (moved.ok)
+                actions.push({ kind: 'approved-fused', rowId: row.id, from: 'approved', to: 'fuse', code: 'stage-lost' });
+        }
+        if (options.managed !== undefined) {
+            for (const row of [...tx.rows()]) {
+                if (row.state === 'skipped')
+                    continue;
+                if (options.managed.has(row.a) && options.managed.has(row.b))
+                    continue;
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined)
+                    continue;
+                const removed = tx.remove(row.id, 'superseded', undefined, current.version);
+                if (removed.ok)
+                    actions.push({ kind: 'source-gone', rowId: row.id, from: current.state, to: 'removed', code: 'source-gone', detail: [row.a, row.b].filter(name => !options.managed?.has(name)).join(', ') });
+            }
+        }
+        return actions.length;
+    });
+    for (const entry of promote) {
+        try {
+            await presentStage(options.io, options.home, entry);
+        }
+        catch { /* the stage index stays reserved; the report still names the row */ }
+    }
+    // NFR-06: the index (the record the read face and the resume path consult) must agree
+    // with the read-side derivation that an expired stage is no longer present.
+    for (const entry of expiredStages) {
+        try {
+            await writeStageIndex(options.io, options.home, { ...entry, state: 'expired' });
+        }
+        catch { /* report keeps the read-side verdict */ }
+    }
+    const notes = [];
+    if (expiredStages.length > 0)
+        notes.push(String(expiredStages.length) + ' expired stage(s) marked in the index');
+    if (options.managed === undefined)
+        notes.push('source-gone convergence skipped: no live library was supplied');
+    if (ttlDays <= 0)
+        notes.push('skipped TTL disabled (mergeSkippedTtlDays=0)');
+    const report = { version: RECONCILE_REPORT_VERSION, at: now, state: 'ok', actions, notes };
+    await transactIo(options.io, reconcileReportPath(options.home), () => JSON.stringify(report, null, 2) + '\n');
+    return report;
+}
+/** One-line text face for the CLI/doctor consumers. */
+export function formatReconcileReport(report) {
+    if (report.state === 'blocked')
+        return 'merge reconcile: blocked ' + (report.code ?? 'merge-state-blocked') + ' — ' + (report.message ?? 'state is not readable');
+    const counts = new Map();
+    for (const action of report.actions)
+        counts.set(action.kind, (counts.get(action.kind) ?? 0) + 1);
+    const summary = counts.size === 0 ? 'no actions' : [...counts].map(([kind, count]) => kind + ' ' + String(count)).join(', ');
+    const lines = ['merge reconcile: ' + summary + ' (at ' + new Date(report.at).toISOString() + ')'];
+    for (const action of report.actions)
+        lines.push('- ' + action.rowId + ': ' + action.from + ' → ' + action.to + ' [' + action.code + ']' + (action.detail === undefined ? '' : ' ' + action.detail));
+    for (const note of report.notes)
+        lines.push('note: ' + note);
+    return lines.join('\n');
+}
+//# sourceMappingURL=reconcile.js.map

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

@@ -1,11 +1,4 @@
-/** Pure pairKey lookup over run records. No IO. */
+/** Pure pair-index lookup. No run-record merge fields. */
 import type { PairIndexEntryV2 } from './indexes.ts';
-import type { PairRecord } from './run-record.ts';
-export interface PairRunLike {
-    readonly id: string;
-    readonly pairKey?: string;
-    readonly pairs: readonly PairRecord[];
-    readonly resultRef?: string;
-}
-export declare function findPairRun(runs: readonly PairRunLike[], pairKey: string): PairIndexEntryV2 | undefined;
+export declare function findPairRun(pairs: readonly PairIndexEntryV2[], pairKey: string): PairIndexEntryV2 | undefined;
 //# sourceMappingURL=resolve-pair.d.ts.map

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

@@ -1,17 +1,4 @@
-export function findPairRun(runs, pairKey) {
-    for (const run of runs) {
-        if (run.pairKey === pairKey) {
-            return { pairKey, runId: run.id, result: 'merged', ...(run.resultRef === undefined ? {} : { reportRef: run.resultRef }) };
-        }
-        const pair = run.pairs.find(item => item.pairKey === pairKey);
-        if (pair !== undefined) {
-            return {
-                pairKey, runId: run.id, result: pair.result === 'undone' ? 'undone' : pair.result === 'kept' ? 'kept' : pair.result === 'failed' ? 'failed' : pair.result === 'cancelled' ? 'cancelled' : 'merged',
-                ...(pair.target?.actual === undefined ? {} : { target: pair.target.actual }),
-                ...(run.resultRef === undefined ? {} : { reportRef: run.resultRef }),
-            };
-        }
-    }
-    return undefined;
+export function findPairRun(pairs, pairKey) {
+    return pairs.find(entry => entry.pairKey === pairKey);
 }
 //# sourceMappingURL=resolve-pair.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