@lmzhen/dsh-evolution-core 0.30.17 → 0.30.19

package/lib/types/unit-transaction.js

@@ -0,0 +1,487 @@
+/** G2 opaque UnitTransaction. Core owns prepare/commit/verify/rollback lifecycle. */
+import { createHash } from "node:crypto";
+import { acquireTreeWriteLock } from "./tree-lock.js";
+import { readUnitEvidence, readUnitReceipt, readUnitSnapshot, unitStorageKey, writeUnitEvidence, writeUnitReceipt, writeUnitSnapshot, } from "./unit-storage.js";
+import { readUnitJournal, writeUnitJournal } from "./unit-journal.js";
+function canonical(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return "[" + value.map(canonical).join(",") + "]";
+    const object = value;
+    return ("{" +
+        Object.keys(object)
+            .sort()
+            .map((key) => JSON.stringify(key) + ":" + canonical(object[key]))
+            .join(",") +
+        "}");
+}
+function digest(plan) {
+    return createHash("sha256").update(canonical(plan)).digest("hex");
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonicalJson).join(',') + ']';
+    const object = value;
+    return '{' + Object.keys(object).sort().map(key => JSON.stringify(key) + ':' + canonicalJson(object[key])).join(',') + '}';
+}
+export function unitEvidenceDigest(evidence) {
+    return createHash("sha256").update(canonicalJson({ ...evidence, at: 0, mutations: 0 })).digest("hex");
+}
+function evidenceDigest(evidence) {
+    return createHash("sha256").update(JSON.stringify({ ...evidence, at: 0, mutations: 0 }, null, 2) + "\n").digest("hex");
+}
+export class UnitTransactions {
+    options;
+    prepared = new Map();
+    commits = new Map();
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => Date.now());
+    }
+    unitId(plan) {
+        return plan.runId + ":" + createHash("sha256").update(plan.pairKey).digest("hex").slice(0, 16);
+    }
+    async snapshot(plan, unitId, planDigest) {
+        const targetBefore = await this.options.backend.readSkill(plan.target);
+        const supportBefore = await Promise.all(plan.supportFiles.map(async (file) => ({
+            path: file.path,
+            content: await this.options.backend.readSupportFile(plan.target, file.path),
+        })));
+        const sourceBefore = await Promise.all(plan.sources
+            .filter((source) => source !== plan.target)
+            .map(async (name) => ({ name, body: (await this.options.backend.readSkill(name)) ?? "" })));
+        return {
+            schemaVersion: 1,
+            unitId,
+            planDigest,
+            runId: plan.runId,
+            target: plan.target,
+            targetExists: plan.targetExists,
+            targetBefore,
+            targetAfter: plan.body,
+            supportBefore,
+            supportAfter: plan.supportFiles,
+            sourceBefore,
+            origin: plan.origin,
+            summary: plan.summary,
+            ...(plan.validationPlan === undefined ? {} : { validationPlan: plan.validationPlan }),
+            createdAt: this.now(),
+        };
+    }
+    async prepare(plan) {
+        const unitId = this.unitId(plan);
+        const planDigest = digest(plan);
+        const existing = this.prepared.get(unitId);
+        if (existing !== undefined)
+            return existing.digest === planDigest
+                ? { ok: true, prepared: { unitId, planDigest } }
+                : { ok: false, code: "unit-conflict", message: "unitId already prepared with a different plan" };
+        const snapshot = await this.snapshot(plan, unitId, planDigest);
+        const path = await writeUnitSnapshot(this.options.io, this.options.home, snapshot);
+        const journal = {
+            schemaVersion: 1,
+            unitId,
+            runId: plan.runId,
+            planDigest,
+            target: plan.target,
+            sources: plan.sources,
+            phase: "prepared",
+            storageKey: unitStorageKey(unitId),
+            snapshotSha256: createHash("sha256")
+                .update(JSON.stringify(snapshot, null, 2) + "\n")
+                .digest("hex"),
+            updatedAt: this.now(),
+        };
+        await writeUnitJournal(this.options.io, this.options.home, journal);
+        await this.options.onPhase?.("prepared");
+        this.prepared.set(unitId, {
+            plan,
+            digest: planDigest,
+            at: this.now(),
+            snapshotSha256: createHash("sha256")
+                .update(JSON.stringify(snapshot, null, 2) + "\n")
+                .digest("hex"),
+        });
+        void path;
+        return { ok: true, prepared: { unitId, planDigest } };
+    }
+    async commit(prepared, options) {
+        const running = this.commits.get(prepared.unitId);
+        if (running !== undefined)
+            return await running;
+        const task = this.commitOnce(prepared, options);
+        this.commits.set(prepared.unitId, task);
+        try {
+            return await task;
+        }
+        finally {
+            this.commits.delete(prepared.unitId);
+        }
+    }
+    async commitOnce(prepared, options) {
+        const existing = await readUnitEvidence(this.options.io, this.options.home, prepared.unitId);
+        if (existing !== null)
+            return existing.planDigest === prepared.planDigest
+                ? { ok: true, evidence: existing }
+                : { ok: false, code: "unit-conflict", message: "unit already committed with a different digest" };
+        const stored = this.prepared.get(prepared.unitId);
+        if (stored === undefined || stored.digest !== prepared.planDigest)
+            return {
+                ok: false,
+                code: "unit-plan-missing",
+                message: "prepared plan is not in this process; manual recovery required",
+            };
+        if (options?.signal?.aborted === true)
+            return { ok: false, code: "unit-commit-failed", message: "cancelled before commit" };
+        const journalBase = {
+            schemaVersion: 1,
+            unitId: prepared.unitId,
+            runId: stored.plan.runId,
+            planDigest: stored.digest,
+            target: stored.plan.target,
+            sources: stored.plan.sources,
+            storageKey: unitStorageKey(prepared.unitId),
+            snapshotSha256: stored.snapshotSha256,
+            updatedAt: this.now(),
+        };
+        let lock;
+        let claim;
+        const checkpoints = [];
+        const writePhase = async (phase, checkpointsNext = checkpoints) => {
+            if (lock !== undefined && !(await lock.assertHeld()))
+                throw new Error("unit-fence-lost");
+            await writeUnitJournal(this.options.io, this.options.home, {
+                ...journalBase,
+                phase,
+                checkpoints: checkpointsNext,
+            });
+            await this.options.onPhase?.(phase);
+        };
+        try {
+            const acquired = await acquireTreeWriteLock({ io: this.options.io, home: this.options.home, waitMs: this.options.waitMs ?? 5000 });
+            if (!acquired.ok)
+                return { ok: false, code: "unit-fence-failed", message: acquired.message ?? acquired.reason };
+            lock = acquired.lock;
+            if (!(await lock.assertHeld()))
+                return { ok: false, code: "unit-fence-failed", message: "tree fence lost" };
+            this.options.onLock?.("tree");
+            claim = await this.options.claim.acquire(stored.plan.target, stored.plan.runId);
+            this.options.onLock?.("claim");
+            await writeUnitJournal(this.options.io, this.options.home, { ...journalBase, phase: "target-pending" });
+            const result = await this.options.backend.commit({ ...stored.plan, unitId: prepared.unitId }, async (phase, detail) => {
+                if (phase === "support-pending") {
+                    await writePhase("support-pending");
+                    await this.options.onPhase?.("support-pending");
+                    return;
+                }
+                if (phase === "target-applied") {
+                    await this.options.onPhase?.("target-applied");
+                    return;
+                }
+                if (phase === "unit-written") {
+                    if (lock !== undefined && !(await lock.assertHeld()))
+                        throw new Error("unit-fence-lost");
+                    await writeUnitReceipt(this.options.io, this.options.home, {
+                        schemaVersion: 1,
+                        unitId: prepared.unitId,
+                        runId: stored.plan.runId,
+                        planDigest: stored.digest,
+                        target: stored.plan.target,
+                        archived: stored.plan.sources.filter((source) => source !== stored.plan.target),
+                        at: this.now(),
+                    });
+                    await writePhase("unit-written");
+                    return;
+                }
+                if (phase === "source-archiving" && detail?.source !== undefined) {
+                    checkpoints.push({
+                        source: detail.source,
+                        phase: "archived",
+                        hash: createHash("sha256")
+                            .update(stored.plan.expectedSourceBodies.find((item) => item.name === detail.source)?.body ?? "")
+                            .digest("hex"),
+                        at: this.now(),
+                    });
+                }
+                await writePhase(phase, checkpoints);
+            }, options?.signal, async () => lock !== undefined && (await lock.assertHeld()));
+            if (!result.ok) {
+                await writePhase("failed");
+                return { ok: false, code: result.code ?? "unit-commit-failed", message: result.message };
+            }
+            const targetAfter = (await this.options.backend.readSkill(stored.plan.target)) ?? "";
+            const evidence = {
+                schemaVersion: 1,
+                unitId: prepared.unitId,
+                runId: stored.plan.runId,
+                planDigest: stored.digest,
+                state: "complete",
+                target: {
+                    before: stored.plan.expectedTargetBody,
+                    after: targetAfter,
+                    supportDigest: createHash("sha256").update(JSON.stringify(stored.plan.supportFiles)).digest("hex"),
+                    created: !stored.plan.targetExists,
+                },
+                sources: stored.plan.sources
+                    .filter((source) => source !== stored.plan.target)
+                    .map((name) => ({
+                    name,
+                    before: stored.plan.expectedSourceBodies.find((item) => item.name === name)?.body ?? "",
+                    after: null,
+                    archived: (result.archived ?? []).includes(name),
+                    absorbedInto: stored.plan.target,
+                })),
+                mutations: result.mutations ?? 0,
+                ...(stored.plan.validationPlan === undefined ? {} : { validationPlan: stored.plan.validationPlan }),
+                at: this.now(),
+            };
+            if (!(await lock.assertHeld()))
+                throw new Error("unit-fence-lost");
+            const evidenceSha256 = evidenceDigest(evidence);
+            await writeUnitEvidence(this.options.io, this.options.home, evidence);
+            await writeUnitReceipt(this.options.io, this.options.home, {
+                schemaVersion: 1, unitId: prepared.unitId, runId: stored.plan.runId, planDigest: stored.digest,
+                target: stored.plan.target, archived: stored.plan.sources.filter((source) => source !== stored.plan.target), at: this.now(), evidenceSha256,
+            });
+            await writePhase("committed", checkpoints);
+            this.prepared.delete(prepared.unitId);
+            return { ok: true, evidence };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                ok: false,
+                code: message === "unit-fence-lost" ? "unit-fence-failed" : "unit-claim-failed",
+                message,
+            };
+        }
+        finally {
+            await claim?.release();
+            await lock?.release();
+        }
+    }
+    async verify(ref) {
+        if ("unitId" in ref)
+            return await readUnitEvidence(this.options.io, this.options.home, ref.unitId);
+        const all = await Promise.all([...this.prepared.keys()].map(async (id) => readUnitEvidence(this.options.io, this.options.home, id)));
+        const found = all.filter((item) => item !== null && item.runId === ref.runId);
+        const only = found[0];
+        return found.length === 0 ? null : found.length === 1 ? (only ?? null) : found;
+    }
+    async finalize(unitId) {
+        const existing = await readUnitEvidence(this.options.io, this.options.home, unitId);
+        if (existing !== null)
+            return { ok: true, evidence: existing };
+        const snapshot = await readUnitSnapshot(this.options.io, this.options.home, unitId);
+        const journal = await readUnitJournal(this.options.io, this.options.home, unitId);
+        const receipt = await readUnitReceipt(this.options.io, this.options.home, unitId);
+        if (snapshot === null || journal === null || (journal.phase !== "committed" && receipt === null))
+            return { ok: false, code: "unit-rollback-blocked", message: "unit is not committed; manual recovery required" };
+        if (receipt !== null &&
+            (receipt.unitId !== unitId ||
+                receipt.runId !== snapshot.runId ||
+                receipt.planDigest !== snapshot.planDigest ||
+                receipt.target !== snapshot.target))
+            return {
+                ok: false,
+                code: "unit-rollback-blocked",
+                message: "unit receipt does not match snapshot; manual recovery required",
+            };
+        const checkpoints = journal.checkpoints ?? [];
+        const missing = snapshot.sourceBefore.filter((source) => !checkpoints.some((item) => item.source === source.name));
+        if (missing.length > 0)
+            return {
+                ok: false,
+                code: "unit-rollback-blocked",
+                message: "source checkpoint missing: " + missing.map((item) => item.name).join(","),
+            };
+        const liveTarget = await this.options.backend.readSkill(snapshot.target);
+        if (liveTarget === null || liveTarget !== (snapshot.targetAfter ?? null))
+            return { ok: false, code: "unit-rollback-blocked", message: "target live hash does not match the prepared target; manual recovery required" };
+        const liveSources = await Promise.all(snapshot.sourceBefore.map(async (source) => ({ name: source.name, body: await this.options.backend.readSkill(source.name) })));
+        const liveSource = liveSources.find(source => source.body !== null);
+        if (liveSource !== undefined)
+            return { ok: false, code: "unit-rollback-blocked", message: "source is still live: " + liveSource.name };
+        const liveSupport = await Promise.all(snapshot.supportAfter.map(async (file) => ({ path: file.path, content: await this.options.backend.readSupportFile(snapshot.target, file.path) })));
+        if (liveSupport.some(file => file.content !== (snapshot.supportAfter.find(item => item.path === file.path)?.content ?? null)))
+            return { ok: false, code: "unit-rollback-blocked", message: "support file live hash does not match the prepared support; manual recovery required" };
+        const evidence = {
+            schemaVersion: 1,
+            unitId,
+            runId: snapshot.runId,
+            planDigest: snapshot.planDigest,
+            state: "complete",
+            target: {
+                before: snapshot.targetBefore,
+                after: (await this.options.backend.readSkill(snapshot.target)) ?? "",
+                supportDigest: createHash("sha256").update(JSON.stringify(snapshot.supportAfter)).digest("hex"),
+                created: !snapshot.targetExists,
+            },
+            sources: snapshot.sourceBefore.map((source) => ({
+                name: source.name,
+                before: source.body,
+                after: null,
+                archived: checkpoints.some((item) => item.source === source.name),
+                absorbedInto: snapshot.target,
+            })),
+            mutations: 0,
+            ...(snapshot.validationPlan === undefined ? {} : { validationPlan: snapshot.validationPlan }),
+            at: this.now(),
+        };
+        if (receipt?.evidenceSha256 !== undefined && evidenceDigest(evidence) !== receipt.evidenceSha256)
+            return { ok: false, code: "unit-rollback-blocked", message: "receipt evidence hash does not match rebuilt evidence" };
+        await writeUnitEvidence(this.options.io, this.options.home, evidence);
+        if (journal.phase !== "committed")
+            await writeUnitJournal(this.options.io, this.options.home, { ...journal, phase: "committed", checkpoints, updatedAt: this.now() });
+        return { ok: true, evidence };
+    }
+    async rollForward(unitId) {
+        const existing = await readUnitEvidence(this.options.io, this.options.home, unitId);
+        if (existing !== null)
+            return { ok: true, evidence: existing };
+        const snapshot = await readUnitSnapshot(this.options.io, this.options.home, unitId);
+        const journal = await readUnitJournal(this.options.io, this.options.home, unitId);
+        if (snapshot === null || journal === null || !["target-written", "support-pending", "source-archiving", "sources-archived", "unit-written"].includes(journal.phase))
+            return {
+                ok: false,
+                code: "unit-rollback-blocked",
+                message: "unit is not roll-forwardable; manual recovery required",
+            };
+        const checkpoints = journal.checkpoints ?? [];
+        const missing = snapshot.sourceBefore.filter((source) => !checkpoints.some((item) => item.source === source.name));
+        if (missing.length > 0)
+            return {
+                ok: false,
+                code: "unit-rollback-blocked",
+                message: "source checkpoint missing: " + missing.map((item) => item.name).join(","),
+            };
+        const targetAfter = await this.options.backend.readSkill(snapshot.target);
+        if (targetAfter === null || targetAfter !== (snapshot.targetAfter ?? null))
+            return { ok: false, code: "unit-rollback-blocked", message: "target missing or drifted; manual recovery required" };
+        const liveSources = await Promise.all(snapshot.sourceBefore.map(async (source) => ({ name: source.name, body: await this.options.backend.readSkill(source.name) })));
+        const liveSource = liveSources.find(source => source.body !== null);
+        if (liveSource !== undefined)
+            return { ok: false, code: "unit-rollback-blocked", message: "source is still live: " + liveSource.name };
+        const liveSupport = await Promise.all(snapshot.supportAfter.map(async (file) => ({ path: file.path, content: await this.options.backend.readSupportFile(snapshot.target, file.path) })));
+        if (liveSupport.some(file => file.content !== (snapshot.supportAfter.find(item => item.path === file.path)?.content ?? null)))
+            return { ok: false, code: "unit-rollback-blocked", message: "support file live hash does not match the prepared support; manual recovery required" };
+        const evidence = {
+            schemaVersion: 1,
+            unitId,
+            runId: snapshot.runId,
+            planDigest: snapshot.planDigest,
+            state: "complete",
+            target: {
+                before: snapshot.targetBefore,
+                after: targetAfter,
+                supportDigest: createHash("sha256").update(JSON.stringify(snapshot.supportAfter)).digest("hex"),
+                created: !snapshot.targetExists,
+            },
+            sources: snapshot.sourceBefore.map((source) => ({
+                name: source.name,
+                before: source.body,
+                after: null,
+                archived: checkpoints.some((item) => item.source === source.name),
+                absorbedInto: snapshot.target,
+            })),
+            mutations: 0,
+            ...(snapshot.validationPlan === undefined ? {} : { validationPlan: snapshot.validationPlan }),
+            at: this.now(),
+        };
+        await writeUnitEvidence(this.options.io, this.options.home, evidence);
+        await writeUnitJournal(this.options.io, this.options.home, { ...journal, phase: "committed", checkpoints, updatedAt: this.now() });
+        return { ok: true, evidence };
+    }
+    async rollback(ref) {
+        const evidence = await readUnitEvidence(this.options.io, this.options.home, ref.unitId);
+        const receipt = await readUnitReceipt(this.options.io, this.options.home, ref.unitId);
+        if (evidence !== null || receipt !== null)
+            return { ok: false, code: "unit-committed", message: "committed unit cannot roll back" };
+        const snapshot = await readUnitSnapshot(this.options.io, this.options.home, ref.unitId);
+        if (snapshot === null)
+            return { ok: false, code: "unit-rollback-blocked", message: "snapshot missing" };
+        const journal = await readUnitJournal(this.options.io, this.options.home, ref.unitId);
+        const acquired = await acquireTreeWriteLock({ io: this.options.io, home: this.options.home, waitMs: this.options.waitMs ?? 5000 });
+        if (!acquired.ok)
+            return { ok: false, code: "unit-fence-failed", message: acquired.message ?? acquired.reason };
+        let claim;
+        try {
+            if (!(await acquired.lock.assertHeld()))
+                return { ok: false, code: "unit-fence-failed", message: "tree fence lost" };
+            this.options.onLock?.("tree");
+            claim = await this.options.claim.acquire(snapshot.target, snapshot.runId);
+            this.options.onLock?.("claim");
+            const currentTarget = await this.options.backend.readSkill(snapshot.target);
+            if (currentTarget !== snapshot.targetBefore && currentTarget !== (snapshot.targetAfter ?? null))
+                return {
+                    ok: false,
+                    code: "unit-rollback-blocked",
+                    message: "target drifted since snapshot; manual recovery required",
+                };
+            for (const source of snapshot.sourceBefore) {
+                const current = await this.options.backend.readSkill(source.name);
+                if (current !== null && current !== source.body)
+                    return { ok: false, code: "unit-rollback-blocked", message: "source drifted since snapshot: " + source.name };
+            }
+            if (!(await acquired.lock.assertHeld()))
+                return { ok: false, code: "unit-fence-failed", message: "tree fence lost before target restore" };
+            await this.options.backend.restoreTarget(snapshot.target, snapshot.targetBefore);
+            for (const file of snapshot.supportBefore) {
+                if (!(await acquired.lock.assertHeld()))
+                    return { ok: false, code: "unit-fence-failed", message: "tree fence lost before support restore" };
+                await this.options.backend.restoreSupportFile?.(snapshot.target, file.path, file.content);
+            }
+            for (const source of snapshot.sourceBefore) {
+                if (!(await acquired.lock.assertHeld()))
+                    return { ok: false, code: "unit-fence-failed", message: "tree fence lost before source restore" };
+                await this.options.backend.restoreSource(source.name, source.body);
+            }
+            if (journal !== null)
+                await writeUnitJournal(this.options.io, this.options.home, { ...journal, phase: "rolled-back", updatedAt: this.now() });
+            const evidenceRecord = {
+                schemaVersion: 1,
+                unitId: ref.unitId,
+                runId: snapshot.runId,
+                planDigest: snapshot.planDigest,
+                state: "target-only",
+                target: { before: snapshot.targetBefore, after: snapshot.targetBefore ?? "", supportDigest: "", created: false },
+                sources: snapshot.sourceBefore.map((source) => ({
+                    name: source.name,
+                    before: source.body,
+                    after: null,
+                    archived: false,
+                    absorbedInto: snapshot.target,
+                })),
+                mutations: 0,
+                at: this.now(),
+            };
+            return { ok: true, evidence: evidenceRecord };
+        }
+        finally {
+            await claim?.release();
+            await acquired.lock.release();
+        }
+    }
+    async cancel(unitId, reason) {
+        const journal = await readUnitJournal(this.options.io, this.options.home, unitId);
+        if (journal === null)
+            return { ok: false, phase: "none" };
+        if (journal.phase === "prepared" && this.prepared.has(unitId)) {
+            this.prepared.delete(unitId);
+            return { ok: true, phase: "prepared" };
+        }
+        if (journal.phase === "target-pending" ||
+            journal.phase === "target-written" ||
+            journal.phase === "source-archiving" ||
+            journal.phase === "sources-archived") {
+            const rolled = await this.rollback({ unitId, reason });
+            return { ok: rolled.ok, phase: journal.phase };
+        }
+        return { ok: false, phase: journal.phase };
+    }
+}
+//# sourceMappingURL=unit-transaction.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.30.17",
+  "version": "0.30.19",
   "publishConfig": {
     "access": "public"
   },

package/persisted-write-inventory.json

@@ -175,7 +175,7 @@
     {
       "id": "merge-state",
       "path": "<evolutionHome>/merge/merge-state.json",
-      "writer": "evolution-merge/src/state.ts",
+      "writer": "evolution-merge/src/domain/pair-ledger.ts",
       "serializedBy": "transact",
       "marker": "transactIo(io, mergeStatePath(home)",
       "state": [],
@@ -190,6 +190,96 @@
       "state": [],
       "note": "The L0-L2 gate cache. A cache is still a durable write and goes through the same transaction seam."
     },
+    {
+      "id": "reports-retention-lock",
+      "path": "<evolutionHome>/reports/.retention",
+      "writer": "evolution-merge/src/index.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, reportsSweepLockTarget()",
+      "state": [],
+      "note": "The report sweep retention lock; startup sweeps merge-* reports under this one transaction."
+    },
+    {
+      "id": "merge-reconcile-report",
+      "path": "<evolutionHome>/merge/reconcile.json",
+      "writer": "evolution-merge/src/domain/reconcile.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(options.io, reconcileReportPath(options.home)",
+      "state": [],
+      "note": "The reconcile report snapshot, written once per reconcile action set."
+    },
+    {
+      "id": "merge-run-meta",
+      "path": "<evolutionHome>/merge/run-meta/<runId>.json",
+      "writer": "evolution-merge/src/domain/run-coordinator.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, runMetaPath(home, meta.runId)",
+      "state": [],
+      "note": "One merge run metadata record; phase and approval transitions go through the same transaction."
+    },
+    {
+      "id": "merge-state-schema4",
+      "path": "<evolutionHome>/merge/merge-state.json",
+      "writer": "evolution-merge/src/domain/schema4.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, schema4StatePath(home)",
+      "state": [],
+      "note": "The schema4 state writer; the same file as merge-state, guarded by the readiness gate."
+    },
+    {
+      "id": "merge-migration-report",
+      "path": "<evolutionHome>/merge/merge-state.migration.report.json",
+      "writer": "evolution-merge/src/domain/state-bootstrap.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, migrationReportPath(home)",
+      "state": [],
+      "note": "Migration report for the v3 to v4 bootstrap."
+    },
+    {
+      "id": "merge-state-bootstrap",
+      "path": "<evolutionHome>/merge/merge-state.json",
+      "writer": "evolution-merge/src/domain/state-bootstrap.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, mergeStatePath(home), async (current)",
+      "state": [],
+      "note": "The bootstrap migration write of the state file."
+    },
+    {
+      "id": "merge-v2-backup",
+      "path": "<evolutionHome>/merge/merge-state.v2.bak.json",
+      "writer": "evolution-merge/src/domain/state-bootstrap.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, backup,",
+      "state": [],
+      "note": "The v2 backup is written through the transaction once before migration."
+    },
+    {
+      "id": "merge-migration-journal",
+      "path": "<evolutionHome>/merge/merge-state.migration.json",
+      "writer": "evolution-merge/src/domain/state-bootstrap.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, migrationJournalPath(home)",
+      "state": [],
+      "note": "The migration journal; a resumable record of the v3 to v4 move."
+    },
+    {
+      "id": "merge-quarantine",
+      "path": "<evolutionHome>/merge/merge-state.quarantine.json",
+      "writer": "evolution-merge/src/domain/state-bootstrap.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, quarantinePath(home)",
+      "state": [],
+      "note": "Rows the migration could not map, preserved for manual repair."
+    },
+    {
+      "id": "merge-undo-journal",
+      "path": "<evolutionHome>/merge/undo-journal/<runId>.json",
+      "writer": "evolution-merge/src/domain/undo-journal.ts",
+      "serializedBy": "transact",
+      "marker": "transactIo(io, undoJournalPath(home, journal.runId)",
+      "state": [],
+      "note": "Per-run undo progress; recovery reads it to finish a partial undo."
+    },
     {
       "id": "merge-tree-lock-acquire",
       "path": "<evolutionHome>/merge/.tree-lock",

package/lib/{ensure-MEYMj9jn.js → ensure-BuWsjPGD.js}

@@ -1,6 +1,6 @@
 import { n as errorText } from "./errors-Br2-uUSK.js";
-import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import * as yaml from "js-yaml";
 //#region lib/types/package-identity.js