@lmzhen/dsh-evolution-merge 0.30.16 → 0.30.18

package/lib/types/scan-run.js

@@ -2,10 +2,11 @@
  * The scan pair loop. Registry/report lifecycle stays in withMergeRun; this module owns
  * candidate → round1 → pending/fuse → commit transitions and returns the report draft.
  */
-import { pairKey, } from "./contracts.js";
-import { transition } from "./coordinator.js";
-import { dropRow, loadMergeState, upsertRow } from "./state.js";
+import { pairKey, rowIdOf, } from "./contracts.js";
+import { dropRowV3, loadMergeState, transactRows } from "./state.js";
 import { recordPair } from "./domain/pair-index-store.js";
+import { writeStagingIndex } from "./domain/staging-index.js";
+import { v3ToLegacy } from "./domain/row-v3-bridge.js";
 const isAborted = (signal) => signal.aborted;
 function at(now) {
     return new Date(now()).toISOString();
@@ -37,6 +38,8 @@ export async function runScan(options) {
     const stage = options.stage ?? (async () => { });
     const candidates = await options.ports.screening(options.signal);
     const before = await loadMergeState(options.io, options.home);
+    if (!before.ok)
+        throw new Error(before.note ?? 'merge-state-invalid');
     const queueBefore = { verify: 0, pending: 0, fuse: 0, skipped: 0 };
     for (const row of before.state.rows)
         queueBefore[row.queue] += 1;
@@ -61,28 +64,37 @@ export async function runScan(options) {
         await stage('decide', { done: index, total: candidates.length });
         let row;
         try {
-            const created = transition(undefined, { type: 'candidate', a: candidate.a, b: candidate.b, at: at(options.now) });
-            if (!created.ok || created.row === null)
-                throw new Error(created.ok ? 'candidate row missing' : created.message);
-            row = options.runId === undefined ? created.row : { ...created.row, runId: options.runId };
+            const key = pairKey(candidate.a, candidate.b);
+            const atNow = at(options.now);
+            row = { id: rowIdOf(key), pairKey: key, a: candidate.a, b: candidate.b, state: 'verify', queue: 'verify', createdAt: atNow, updatedAt: atNow, ...(options.runId === undefined ? {} : { runId: options.runId }) };
             const before = (await loadMergeState(options.io, options.home)).state.rows.find(item => item.pairKey === row.pairKey);
             if (before?.state === 'verify' && before.runId !== undefined && before.runId !== options.runId
                 && (await options.isOwnerActive?.(before.runId)) === true) {
                 continue;
             }
-            const placed = await upsertRow(options.io, options.home, options.now, row, 'verify', before?.updatedAt ?? null);
-            if (!placed.ok && before?.state === 'skipped') {
-                const restored = transition(before, { type: 'restore', at: at(options.now) });
-                if (!restored.ok || restored.row === null)
-                    throw new Error('cannot restore skipped pair');
-                const persisted = await upsertRow(options.io, options.home, options.now, restored.row, 'any', before.updatedAt);
-                if (!persisted.ok)
-                    throw new Error('pair changed while restoring skipped row');
-                row = restored.row;
-            }
-            else if (!placed.ok) {
-                throw new Error('pair already in ' + placed.current.state);
-            }
+            const status = await transactRows(options.io, options.home, tx => {
+                const current = tx.rows().find(item => item.pairKey === row.pairKey);
+                if (current !== undefined && current.state !== 'verify' && current.state !== 'skipped')
+                    return 'conflict:' + current.state;
+                if (current?.state === 'skipped') {
+                    const removed = tx.transition(current.id, { type: 'restored' }, current.version);
+                    if (!removed.ok)
+                        return 'restore-failed';
+                }
+                if (current?.state === 'verify')
+                    return 'existing';
+                const made = tx.createVerify({
+                    id: current?.id ?? rowIdOf(row.pairKey), pairKey: row.pairKey, a: row.a, b: row.b,
+                    version: 0, createdAt: at(options.now), updatedAt: at(options.now), origin: 'agent',
+                    state: 'verify', verifySubState: 'unverified', attempts: 0,
+                    ...(row.runId === undefined ? {} : { runId: row.runId }),
+                });
+                return made.ok ? 'created' : 'invalid:' + made.code;
+            });
+            if (status.startsWith('conflict:'))
+                throw new Error('pair already in ' + status.slice(9));
+            if (status === 'restore-failed' || status.startsWith('invalid:'))
+                throw new Error('cannot place verify row: ' + status);
         }
         catch (error) {
             totals.failed += 1;
@@ -105,22 +117,39 @@ export async function runScan(options) {
             break;
         }
         if (round1.kind === 'failed') {
-            const next = transition(row, { type: 'round1-fail', failure: round1.failure ?? failureOf('decide', 'round1 failed'), at: at(options.now) });
-            if (next.ok && next.row !== null) {
-                row = next.row;
-                await upsertRow(options.io, options.home, options.now, row);
+            const failure = round1.failure ?? failureOf('decide', 'round1 failed');
+            const projected = await transactRows(options.io, options.home, tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined)
+                    return null;
+                const moved = tx.transition(row.id, { type: 'failed', failure }, current.version);
+                return moved.ok && moved.row !== null ? v3ToLegacy(moved.row) : null;
+            });
+            if (projected === null) {
+                pairs.push(pairOf(row, candidate, 'failed', { failure: failureOf('decide', 'row changed before failure record') }));
+                totals.failed += 1;
+                continue;
             }
-            pairs.push(pairOf(row, candidate, 'failed', { failure: round1.failure ?? failureOf('decide', 'round1 failed') }));
+            row = projected;
+            pairs.push(pairOf(row, candidate, 'failed', { failure }));
             totals.failed += 1;
             continue;
         }
         if (round1.kind === 'keep') {
-            const next = transition(row, { type: 'round1-keep', at: at(options.now) });
-            if (next.ok && next.row !== null) {
-                row = next.row;
-                await upsertRow(options.io, options.home, options.now, row);
-                await recordPair(options.io, options.home, { pairKey: row.pairKey, runId: row.runId ?? 'merge', result: 'kept' });
+            const projected = await transactRows(options.io, options.home, tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined)
+                    return null;
+                const moved = tx.transition(row.id, { type: 'skipped', reason: 'kept' }, current.version);
+                return moved.ok && moved.row !== null ? v3ToLegacy(moved.row) : null;
+            });
+            if (projected === null) {
+                pairs.push(pairOf(row, candidate, 'failed', { failure: failureOf('decide', 'row changed before keep record') }));
+                totals.failed += 1;
+                continue;
             }
+            row = projected;
+            await recordPair(options.io, options.home, { pairKey: row.pairKey, runId: row.runId ?? 'merge', result: 'kept' });
             pairs.push(pairOf(row, candidate, 'kept', round1.decision === undefined ? {} : { decision: round1.decision }));
             totals.kept += 1;
             continue;
@@ -131,29 +160,54 @@ export async function runScan(options) {
             continue;
         }
         if (options.approval) {
-            const next = transition(row, { type: 'round1-merge', approval: 'on', decision: round1.decision, ...(round1.sourceRevision === undefined ? {} : { sourceRevision: round1.sourceRevision }), ...(round1.targetRevision === undefined ? {} : { targetRevision: round1.targetRevision }), at: at(options.now) });
-            if (next.ok && next.row !== null) {
-                row = next.row;
-                await upsertRow(options.io, options.home, options.now, row);
+            const event = { type: 'verify-passed', decision: round1.decision, target: round1.decision.target, ...(round1.sourceRevision === undefined ? {} : { sourceRevision: round1.sourceRevision }) };
+            const projected = await transactRows(options.io, options.home, tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined)
+                    return null;
+                const moved = tx.transition(row.id, event, current.version);
+                return moved.ok && moved.row !== null ? v3ToLegacy(moved.row) : null;
+            });
+            if (projected === null) {
+                pairs.push(pairOf(row, candidate, 'failed', { decision: round1.decision, failure: failureOf('decide', 'row changed before pending record') }));
+                totals.failed += 1;
+                continue;
             }
+            row = projected;
             pairs.push(pairOf(row, candidate, 'pending', { decision: round1.decision }));
             totals.pending += 1;
             continue;
         }
-        const fuse = transition(row, { type: 'round1-merge', approval: 'off', decision: round1.decision, ...(round1.stagingRef === undefined ? {} : { stagingRef: round1.stagingRef }), ...(round1.stagingExpiresAt === undefined ? {} : { stagingExpiresAt: round1.stagingExpiresAt }), at: at(options.now) });
-        if (!fuse.ok || fuse.row === null) {
-            pairs.push(pairOf(row, candidate, 'failed', { decision: round1.decision, failure: failureOf('decide', 'cannot enter fuse') }));
+        const staged = await transactRows(options.io, options.home, tx => {
+            const current = tx.rows().find(item => item.id === row.id);
+            if (current === undefined)
+                return null;
+            const approved = tx.transition(row.id, { type: 'auto-approved', decision: round1.decision, target: round1.decision.target, ...(row.runId === undefined ? {} : { runId: row.runId }) }, current.version);
+            if (!approved.ok || approved.row === null)
+                return null;
+            const moved = tx.transition(row.id, { type: 'staged', ...(round1.stagingRef === undefined ? {} : { ref: round1.stagingRef }), ...(round1.stagingExpiresAt === undefined ? {} : { expiresAt: round1.stagingExpiresAt }) }, approved.row.version);
+            return moved.ok && moved.row !== null ? v3ToLegacy(moved.row) : null;
+        });
+        if (staged === null) {
+            pairs.push(pairOf(row, candidate, 'failed', { decision: round1.decision, failure: failureOf('author', 'row changed before staging record') }));
             totals.failed += 1;
             continue;
         }
-        row = fuse.row;
-        await upsertRow(options.io, options.home, options.now, row);
+        row = staged;
+        if (round1.stagingRef !== undefined) {
+            const expiresAt = round1.stagingExpiresAt ?? options.now() + 7 * 86_400_000;
+            await writeStagingIndex(options.io, options.home, { rowId: row.id, pairKey: row.pairKey, ref: round1.stagingRef, expiresAt, ...(row.runId === undefined ? {} : { runId: row.runId }), createdAt: options.now() });
+        }
         if (isAborted(options.signal)) {
-            const cancelled = transition(row, { type: 'round2-cancel', at: at(options.now) });
-            if (cancelled.ok && cancelled.row !== null) {
-                row = cancelled.row;
-                await upsertRow(options.io, options.home, options.now, row);
-            }
+            const projected = await transactRows(options.io, options.home, tx => {
+                const current = tx.rows().find(item => item.id === row.id);
+                if (current === undefined)
+                    return null;
+                const moved = tx.transition(row.id, { type: 'skipped', reason: 'cancelled' }, current.version);
+                return moved.ok && moved.row !== null ? v3ToLegacy(moved.row) : null;
+            });
+            if (projected !== null)
+                row = projected;
             stopReason = 'cancelled';
             remaining.push(...candidates.slice(index).map(candidate => ({ pairKey: pairKey(candidate.a, candidate.b), queue: 'fuse' })));
             break;
@@ -167,9 +221,12 @@ export async function runScan(options) {
             round2 = { kind: 'failed', failure: failureOf('author', error) };
         }
         if (round2.kind === 'merged') {
-            const success = transition(row, { type: 'round2-success', at: at(options.now) });
-            if (success.ok)
-                await dropRow(options.io, options.home, options.now, row.id);
+            const dropped = await dropRowV3(options.io, options.home, row.id, 'committed', round2.unitId ?? 'unknown');
+            if (!dropped) {
+                pairs.push(pairOf(row, candidate, 'failed', { decision: round1.decision, failure: failureOf('commit', 'row changed before commit record') }));
+                totals.failed += 1;
+                continue;
+            }
             pairs.push(pairOf(row, candidate, 'merged', {
                 decision: round1.decision,
                 ...(round2.unitId === undefined ? {} : { unitId: round2.unitId }),
@@ -180,11 +237,19 @@ export async function runScan(options) {
             continue;
         }
         const failed = round2.failure ?? failureOf('author', 'round2 failed');
-        const next = transition(row, { type: 'round2-fail', failure: failed, at: at(options.now) });
-        if (next.ok && next.row !== null) {
-            row = next.row;
-            await upsertRow(options.io, options.home, options.now, row);
+        const projected = await transactRows(options.io, options.home, tx => {
+            const current = tx.rows().find(item => item.id === row.id);
+            if (current === undefined)
+                return null;
+            const moved = tx.transition(row.id, { type: 'failed', failure: failed }, current.version);
+            return moved.ok && moved.row !== null ? v3ToLegacy(moved.row) : null;
+        });
+        if (projected === null) {
+            pairs.push(pairOf(row, candidate, 'failed', { decision: round1.decision, failure: failureOf('author', 'row changed before failure record') }));
+            totals.failed += 1;
+            continue;
         }
+        row = projected;
         pairs.push(pairOf(row, candidate, 'failed', { decision: round1.decision, failure: failed }));
         totals.failed += 1;
     }

package/lib/types/screening-port.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The real screening port: lexical floor + optional C3 proposal + optional L0–L2 gate.
+ * Each stage is independently testable; this file only composes their frozen contracts.
+ */
+import { type MergeCandidate } from './contracts.ts';
+import { type SkillCard, type ScreeningOptions } from './screening.ts';
+import { type ModelPort } from './propose.ts';
+import type { GateCache, GateModelPort } from './ladder.ts';
+export interface ScreeningForRunOptions extends Omit<BuildScreeningOptions, 'signal'> {
+    readonly runSeed: string;
+}
+export interface BuildScreeningOptions {
+    readonly cards: readonly SkillCard[];
+    readonly signal: AbortSignal;
+    readonly lexical?: ScreeningOptions;
+    readonly propose?: {
+        readonly model: ModelPort;
+        readonly shardSize?: number;
+        readonly maxPairs?: number;
+    };
+    readonly gate?: {
+        readonly model: GateModelPort;
+        readonly modelName: string;
+        readonly runSeed: string;
+        readonly cache?: GateCache;
+        readonly auditRate?: number;
+    };
+}
+export interface ScreeningPortStats {
+    readonly lexical: number;
+    readonly proposed: number;
+    readonly candidates: number;
+    readonly kept: number;
+    readonly dropped: number;
+    readonly gateCalls: number;
+    readonly gateErrors: number;
+    readonly shards: number;
+}
+export interface ScreeningPortResult {
+    readonly candidates: readonly MergeCandidate[];
+    readonly stats: ScreeningPortStats;
+    readonly degraded: readonly string[];
+}
+export declare function buildScreeningCandidates(options: BuildScreeningOptions): Promise<ScreeningPortResult>;
+/** Build the run-scoped screening function; the run id seeds the 10% audit. */
+export declare function createScreeningForRun(options: ScreeningForRunOptions): (signal: AbortSignal) => Promise<readonly MergeCandidate[]>;
+//# sourceMappingURL=screening-port.d.ts.map

package/lib/types/screening-port.js

@@ -0,0 +1,93 @@
+/**
+ * The real screening port: lexical floor + optional C3 proposal + optional L0–L2 gate.
+ * Each stage is independently testable; this file only composes their frozen contracts.
+ */
+import { pairKey } from "./contracts.js";
+import { lexicalCandidates } from "./screening.js";
+import { proposePairs } from "./propose.js";
+import { filterCandidates } from "./gate-filter.js";
+export async function buildScreeningCandidates(options) {
+    const lexical = lexicalCandidates(options.cards, options.lexical);
+    const merged = new Map();
+    for (const candidate of lexical.candidates)
+        merged.set(pairKey(candidate.a, candidate.b), candidate);
+    const degraded = [];
+    let proposed = 0;
+    let shards = 0;
+    if (options.propose !== undefined) {
+        const proposal = await proposePairs(options.cards, options.propose.model, {
+            signal: options.signal,
+            ...(options.propose.shardSize === undefined ? {} : { shardSize: options.propose.shardSize }),
+            ...(options.propose.maxPairs === undefined ? {} : { maxPairs: options.propose.maxPairs }),
+        });
+        proposed = proposal.candidates.length;
+        shards = proposal.shards;
+        degraded.push(...proposal.degraded);
+        for (const candidate of proposal.candidates) {
+            const key = pairKey(candidate.a, candidate.b);
+            const existing = merged.get(key);
+            if (existing === undefined) {
+                merged.set(key, candidate);
+                continue;
+            }
+            const arms = [...new Set([...(existing.arms ?? []), ...(candidate.arms ?? [])])];
+            merged.set(key, {
+                ...existing,
+                ...(candidate.reason === undefined || existing.reason !== undefined ? {} : { reason: candidate.reason }),
+                ...(arms.length === 0 ? {} : { arms }),
+            });
+        }
+    }
+    let candidates = [...merged.values()].sort((left, right) => (right.score ?? 0) - (left.score ?? 0)
+        || left.a.localeCompare(right.a)
+        || left.b.localeCompare(right.b));
+    let kept = candidates.length;
+    let dropped = 0;
+    let gateCalls = 0;
+    let gateErrors = 0;
+    if (options.gate !== undefined) {
+        const facts = options.cards.map(card => ({ name: card.name, description: card.description, body: card.body }));
+        const filtered = await filterCandidates(candidates, {
+            facts,
+            model: options.gate.model,
+            modelName: options.gate.modelName,
+            signal: options.signal,
+            runSeed: options.gate.runSeed,
+            ...(options.gate.cache === undefined ? {} : { cache: options.gate.cache }),
+            ...(options.gate.auditRate === undefined ? {} : { auditRate: options.gate.auditRate }),
+        });
+        candidates = filtered.kept.map(decision => decision.candidate);
+        kept = filtered.kept.length;
+        dropped = filtered.dropped.length;
+        gateCalls = filtered.calls;
+        gateErrors = filtered.errors.length;
+        for (const error of filtered.errors)
+            degraded.push('gate error: ' + error.candidate.a + ' + ' + error.candidate.b + ': ' + error.message);
+    }
+    return {
+        candidates,
+        stats: {
+            lexical: lexical.candidates.length,
+            proposed,
+            candidates: merged.size,
+            kept,
+            dropped,
+            gateCalls,
+            gateErrors,
+            shards,
+        },
+        degraded,
+    };
+}
+/** Build the run-scoped screening function; the run id seeds the 10% audit. */
+export function createScreeningForRun(options) {
+    const gate = options.gate === undefined ? undefined : { ...options.gate, runSeed: options.runSeed };
+    return async (signal) => (await buildScreeningCandidates({
+        cards: options.cards,
+        signal,
+        ...(options.lexical === undefined ? {} : { lexical: options.lexical }),
+        ...(options.propose === undefined ? {} : { propose: options.propose }),
+        ...(gate === undefined ? {} : { gate }),
+    })).candidates;
+}
+//# sourceMappingURL=screening-port.js.map

package/lib/types/screening.d.ts

@@ -0,0 +1,30 @@
+import type { MergeCandidate } from './contracts.ts';
+export interface SkillCard {
+    readonly name: string;
+    readonly description: string;
+    readonly body: string;
+}
+export interface ScreeningOptions {
+    /** Body Jaccard at/above this is a candidate on its own. */
+    readonly bodyGate?: number;
+    /** Description Jaccard at/above this is a candidate when the body also clears minAffinity. */
+    readonly summaryGate?: number;
+    /** Minimum body affinity for a summary-led candidate. */
+    readonly minAffinity?: number;
+    /** Upper bound after sorting by score; absent = no cap. */
+    readonly maxCandidates?: number;
+}
+export interface ScreeningStats {
+    readonly skills: number;
+    readonly filtered: number;
+    readonly candidates: number;
+}
+export interface ScreeningResult {
+    readonly candidates: readonly MergeCandidate[];
+    readonly stats: ScreeningStats;
+}
+/** Shannon entropy over characters; a cheap prefilter signal, not a name-quality judge. */
+export declare function nameEntropy(name: string): number;
+export declare function prefilter(cards: readonly SkillCard[]): readonly SkillCard[];
+export declare function lexicalCandidates(cards: readonly SkillCard[], options?: ScreeningOptions): ScreeningResult;
+//# sourceMappingURL=screening.d.ts.map

package/lib/types/screening.js

@@ -0,0 +1,75 @@
+/**
+ * Deterministic candidate screening: name prefilter + lexical affinity.
+ *
+ * The semantic proposer (C3) is a separate port; this module is the zero-cost floor that
+ * must work without a model. It reuses core `vocabulary`/`affinity` so drift/dedup and
+ * merge screening share one tokenizer.
+ */
+import { affinity, vocabulary } from '@lmzhen/dsh-evolution-core';
+/** Shannon entropy over characters; a cheap prefilter signal, not a name-quality judge. */
+export function nameEntropy(name) {
+    if (name === '')
+        return 0;
+    const counts = new Map();
+    for (const char of name)
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const p = count / name.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+const MIN_NAME_ENTROPY = 1.5;
+const MIN_NAME_LENGTH = 6;
+export function prefilter(cards) {
+    return cards.filter((card) => {
+        const name = card.name.trim();
+        if (name.length < MIN_NAME_LENGTH)
+            return false;
+        if (nameEntropy(name) < MIN_NAME_ENTROPY)
+            return false;
+        return card.body.trim() !== '' || card.description.trim() !== '';
+    });
+}
+function sortedPair(a, b) {
+    return a < b ? [a, b] : [b, a];
+}
+export function lexicalCandidates(cards, options = {}) {
+    const bodyGate = options.bodyGate ?? 0.9;
+    const summaryGate = options.summaryGate ?? 0.5;
+    const minAffinity = options.minAffinity ?? 0.3;
+    const eligible = prefilter(cards);
+    const vectors = eligible.map(card => ({
+        card,
+        summary: vocabulary(card.description),
+        body: vocabulary(card.body),
+    }));
+    const candidates = [];
+    for (let i = 0; i < vectors.length; i += 1) {
+        for (let j = i + 1; j < vectors.length; j += 1) {
+            const left = vectors[i];
+            const right = vectors[j];
+            if (left === undefined || right === undefined)
+                continue;
+            const summary = affinity(left.summary, right.summary);
+            const body = affinity(left.body, right.body);
+            const arms = [];
+            if (body >= bodyGate)
+                arms.push('body');
+            if (summary >= summaryGate && body >= minAffinity)
+                arms.push('summary');
+            if (arms.length === 0)
+                continue;
+            const [a, b] = sortedPair(left.card.name, right.card.name);
+            candidates.push({ a, b, score: Math.max(body, summary), arms, source: 'lexical' });
+        }
+    }
+    candidates.sort((left, right) => (right.score ?? 0) - (left.score ?? 0) || left.a.localeCompare(right.a) || left.b.localeCompare(right.b));
+    const capped = options.maxCandidates === undefined ? candidates : candidates.slice(0, options.maxCandidates);
+    return {
+        candidates: capped,
+        stats: { skills: cards.length, filtered: cards.length - eligible.length, candidates: capped.length },
+    };
+}
+//# sourceMappingURL=screening.js.map

package/lib/types/state.d.ts

@@ -1,5 +1,7 @@
 import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
 import { type MergePairState, type MergeQueue, type MergeRow, type MergeState } from './contracts.ts';
+import { type RowWriteResult } from './domain/row-tx.ts';
+import { type SkippedRowV3, type V3Event, type V3Row, type VerifyRowV3 } from './domain/row-v3.ts';
 export declare function mergeStatePath(home: string): string;
 export interface LoadMergeStateResult {
     readonly ok: boolean;
@@ -8,6 +10,16 @@ export interface LoadMergeStateResult {
 }
 /** Pure read: never writes, never deletes a row. */
 export declare function loadMergeState(io: EvolutionIoLike, home: string): Promise<LoadMergeStateResult>;
+/** Schema probe for doctor; the only other reader of mergeStatePath. */
+export declare function loadStateSchema(io: EvolutionIoLike, home: string): Promise<number | null>;
+export interface RowTx {
+    rows(): readonly V3Row[];
+    createVerify(row: VerifyRowV3): RowWriteResult;
+    createSkipped(row: SkippedRowV3): RowWriteResult;
+    transition(id: string, event: V3Event, expectedVersion: number): RowWriteResult;
+}
+/** G3-5 runtime write API: only createVerify/createSkipped/transition. v2 writes are rejected. */
+export declare function transactRows<T>(io: EvolutionIoLike, home: string, fn: (tx: RowTx) => T): Promise<T>;
 /** The ONE write point. The callback returns the whole row set, not a delta. */
 export declare function mutateMergeState<T>(io: EvolutionIoLike, home: string, now: () => number, fn: (rows: readonly MergeRow[]) => {
     rows: readonly MergeRow[];
@@ -31,6 +43,8 @@ export type UpsertResult = {
 };
 export declare function upsertRow(io: EvolutionIoLike, home: string, now: () => number, row: MergeRow, expect?: UpsertExpect, cas?: string | null): Promise<UpsertResult>;
 export declare function moveRow(io: EvolutionIoLike, home: string, now: () => number, id: string, patch: MoveRowPatch): Promise<MergeRow | undefined>;
+/** G3-5 v3-aware drop: only terminal events. */
+export declare function dropRowV3(io: EvolutionIoLike, home: string, id: string, event: 'committed' | 'superseded' | 'restored', unitId?: string): Promise<boolean>;
 export declare function dropRow(io: EvolutionIoLike, home: string, now: () => number, id: string): Promise<boolean>;
 export declare function rowsOf(io: EvolutionIoLike, home: string, queue?: MergeQueue): Promise<readonly MergeRow[]>;
 //# sourceMappingURL=state.d.ts.map

package/lib/types/state.js

@@ -10,6 +10,10 @@ import { join } from 'node:path';
 import { transactIo } from '@lmzhen/dsh-evolution-core';
 import { MERGE_STATE_VERSION, queueOf, } from "./contracts.js";
 import { parseLedger } from "./domain/ledger.js";
+import { legacyToV3 } from "./domain/row-v3-bridge.js";
+import { applyRowWrite } from "./domain/row-tx.js";
+import { isV3Row } from "./domain/row-v3.js";
+import { deleteStagingIndex } from "./domain/staging-index.js";
 export function mergeStatePath(home) {
     return join(home, 'merge', 'merge-state.json');
 }
@@ -39,6 +43,55 @@ export async function loadMergeState(io, home) {
         ...(parsed.note === undefined ? {} : { note: parsed.note }),
     };
 }
+/** Schema probe for doctor; the only other reader of mergeStatePath. */
+export async function loadStateSchema(io, home) {
+    try {
+        const raw = await io.readText(mergeStatePath(home));
+        if (raw === null)
+            return null;
+        const parsed = JSON.parse(raw);
+        return typeof parsed.schemaVersion === 'number' ? parsed.schemaVersion : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** G3-5 runtime write API: only createVerify/createSkipped/transition. v2 writes are rejected. */
+export async function transactRows(io, home, fn) {
+    let result;
+    await transactIo(io, mergeStatePath(home), (current) => {
+        let rows = [];
+        if (current !== null) {
+            let parsed;
+            try {
+                parsed = JSON.parse(current);
+            }
+            catch {
+                throw new Error('merge-state-needs-repair');
+            }
+            const body = parsed;
+            if (body.schemaVersion !== 3 || !Array.isArray(body.rows) || !body.rows.every(isV3Row)) {
+                throw new Error(body.schemaVersion === 2 ? 'merge-state-migration-required' : 'merge-state-needs-repair');
+            }
+            rows = body.rows;
+        }
+        const apply = (write) => {
+            const next = applyRowWrite(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 }),
+        };
+        result = fn(tx);
+        return JSON.stringify({ schemaVersion: 3, rows }, null, 2);
+    });
+    return result;
+}
 /** The ONE write point. The callback returns the whole row set, not a delta. */
 export async function mutateMergeState(io, home, now, fn) {
     let result;
@@ -46,9 +99,14 @@ export async function mutateMergeState(io, home, now, fn) {
     await transactIo(io, mergeStatePath(home), (current) => {
         ran = true;
         const parsed = parseState(current);
+        if (!parsed.ok || parsed.note === 'merge-state-forward-only')
+            throw new Error(parsed.note ?? 'merge-state-invalid');
         const out = fn(parsed.rows);
         result = out.result;
-        return JSON.stringify({ schemaVersion: MERGE_STATE_VERSION, rows: out.rows }, null, 2);
+        const rows = out.rows.map(row => legacyToV3(row));
+        if (rows.some(row => row === null))
+            throw new Error('merge-state-v3-row-invalid');
+        return JSON.stringify({ schemaVersion: 3, rows }, null, 2);
     });
     // transactIo only returns after fn ran; a skipped write is not a state outcome.
     void ran;
@@ -100,6 +158,19 @@ export async function moveRow(io, home, now, id, patch) {
         return { rows: copy, result: next };
     });
 }
+/** G3-5 v3-aware drop: only terminal events. */
+export async function dropRowV3(io, home, id, event, unitId = 'unknown') {
+    const dropped = await transactRows(io, home, tx => {
+        const row = tx.rows().find(item => item.id === id);
+        if (row === undefined)
+            return false;
+        const moved = tx.transition(id, event === 'committed' ? { type: 'committed', unitId } : { type: event }, row.version);
+        return moved.ok;
+    });
+    if (dropped)
+        await deleteStagingIndex(io, home, id);
+    return dropped;
+}
 export async function dropRow(io, home, now, id) {
     return await mutateMergeState(io, home, now, (rows) => {
         const next = rows.filter(item => item.id !== id);

package/lib/types/status.d.ts

@@ -3,6 +3,7 @@
  * writes, no report reads. The UI and command parser share this vocabulary.
  */
 import type { MergeQueue, MergeRow } from './contracts.ts';
+import type { Facts, RunsView } from './wire.ts';
 export interface MergeCounts {
     readonly verify: number;
     readonly pending: number;
@@ -11,5 +12,7 @@ export interface MergeCounts {
 }
 export declare function countRows(rows: readonly MergeRow[]): MergeCounts;
 export declare function formatStatus(rows: readonly MergeRow[]): string;
+export declare function formatFacts(facts: Facts): string;
+export declare function formatRunsView(view: RunsView): string;
 export declare function formatQueue(rows: readonly MergeRow[], queue: MergeQueue): string;
 //# sourceMappingURL=status.d.ts.map