agentera 3.0.0-dev.20 → 3.0.0-dev.21

package/dist/state/write/transaction.js

@@ -1,17 +1,24 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { splitLinesKeepEnds, unifiedDiff } from "../../core/difflib.js";
 import { dumpYamlMapping, loadYamlMapping } from "../../core/yaml.js";
-import { lintFullArtifactPayload } from "../../cli/commands/lint.js";
 import { compactYamlFile, decisionProtectedOverflowCount, } from "../../hooks/compaction/index.js";
 import { assertRealpathBoundary, loadArtifactRegistry, resolveArtifactPath, } from "../../registries/artifactRegistry.js";
-import { acquireWriterLock } from "./lock.js";
+import { withStateMutation, } from "./mutation.js";
 import { localDate, localTimestamp, nextEntryNumber, nextTaskNumber } from "./assign.js";
 import { reject } from "./errors.js";
+import { findByNumber, schemaViolation } from "./helpers.js";
 import { validateArtifactBytes } from "./validate.js";
+import { planEvaluationViolations, validatePlanCreateInput, validatePlanPublicationCandidate, } from "./planPublication.js";
 import { dependencyReadyTasks } from "../../cli/capabilityContext/planState.js";
+import { publishImmutableFile, } from "../archivePublication.js";
+import { findArchivedReplay, isExactArchiveReplay, recoverArchivedEntry, } from "../archiveReplay.js";
+import { discoverNumberedArchives } from "../archiveDiscovery.js";
+import { hydrateDecisionRecords, updateDecisionOverlay, } from "../decisionOverlay.js";
+import { repairHealthDuplicates, repairHealthProjectionBytes } from "../healthRepair.js";
+import { executeExperimentPublication } from "./experimentPublication.js";
 function mapping(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -22,25 +29,6 @@ function array(doc, key) {
         ? doc[key].filter((v) => Boolean(v && typeof v === "object" && !Array.isArray(v)))
         : [];
 }
-function setNested(target, field, value) {
-    const parts = field.split(".");
-    let cursor = target;
-    for (const part of parts.slice(0, -1)) {
-        if (!cursor[part] || typeof cursor[part] !== "object" || Array.isArray(cursor[part]))
-            cursor[part] = {};
-        cursor = cursor[part];
-    }
-    cursor[parts.at(-1)] = value;
-}
-function project(entry, payload) {
-    const result = {};
-    for (const [key, expected] of Object.entries(payload)) {
-        const actual = mappingPath(entry, key);
-        if (expected !== undefined)
-            setNested(result, key, actual);
-    }
-    return result;
-}
 function mappingPath(entry, field) {
     let value = entry;
     for (const part of field.split(".")) {
@@ -50,9 +38,6 @@ function mappingPath(entry, field) {
     }
     return value;
 }
-function exactReplay(entry, payload) {
-    return Boolean(entry && isDeepStrictEqual(project(entry, payload), payload));
-}
 function readExisting(target) {
     if (!fs.existsSync(target))
         return { doc: {}, bytes: "" };
@@ -116,41 +101,28 @@ function normalizedDecisionPayload(values) {
     ];
     return payload;
 }
-function schemaViolation(violations) {
-    reject({ class: "schema_violation", message: violations[0], violations });
-}
-function validatePlanPublicationCandidate(bytes) {
-    const lint = lintFullArtifactPayload("plan", bytes);
-    const lintViolations = lint.checks
-        .filter((check) => check.status === "fail")
-        .map((check) => `strict prose lint ${check.name}: ${check.detail}; action: ${check.action}`);
-    const schemaViolations = validateArtifactBytes("plan", bytes).map((violation) => `schema validation: ${violation}`);
-    const violations = [...lintViolations, ...schemaViolations];
-    if (violations.length === 0)
-        return;
-    reject({
-        class: "schema_violation",
-        message: "plan publication candidate failed strict prose lint or schema validation; correct the reported violations and retry",
-        violations,
-        syntax: "agentera state plan create --input plan.yaml --format json",
-        example: "agentera state plan create --input plan.yaml --format json",
-    });
-}
-function findByNumber(entries, number) {
-    return entries.find((entry) => Number(entry.number) === number);
-}
-function mutateCandidate(req, doc) {
+function mutateCandidate(req, doc, recovered) {
     const candidate = structuredClone(doc);
     if (req.artifact === "progress") {
         const payload = req.callerPayload;
         const entries = array(candidate, "cycles");
-        if (exactReplay(entries[0], payload))
+        const replay = entries.find((entry) => isExactArchiveReplay(entry, payload));
+        if (replay)
+            return {
+                candidate,
+                written: replay,
+                assigned: { number: replay.number, timestamp: replay.timestamp },
+                replay: true,
+            };
+        if (recovered) {
+            recoverArchivedEntry(candidate, "cycles", entries, recovered, true);
             return {
                 candidate,
-                written: entries[0],
-                assigned: { number: entries[0].number, timestamp: entries[0].timestamp },
+                written: recovered,
+                assigned: { number: recovered.number, timestamp: recovered.timestamp },
                 replay: true,
             };
+        }
         const entry = buildProgress(candidate, req.values);
         candidate.cycles = [entry, ...entries];
         return {
@@ -163,8 +135,9 @@ function mutateCandidate(req, doc) {
     if (req.artifact === "decisions" && req.spec.verb === "append") {
         const entries = array(candidate, "decisions");
         const payload = normalizedDecisionPayload(req.callerPayload);
-        if (exactReplay(entries.at(-1), payload)) {
-            const entry = entries.at(-1);
+        const replay = entries.find((entry) => isExactArchiveReplay(entry, payload));
+        if (replay) {
+            const entry = replay;
             return {
                 candidate,
                 written: entry,
@@ -172,14 +145,17 @@ function mutateCandidate(req, doc) {
                 replay: true,
             };
         }
+        if (recovered) {
+            recoverArchivedEntry(candidate, "decisions", entries, recovered, false);
+            return {
+                candidate,
+                written: recovered,
+                assigned: { number: recovered.number, date: recovered.date },
+                replay: true,
+            };
+        }
         const entry = buildDecision(candidate, req.values);
         candidate.decisions = [...entries, entry];
-        if (decisionProtectedOverflowCount(candidate.decisions, Array.isArray(candidate.archive) ? candidate.archive : []) > 0) {
-            reject({
-                class: "conflict",
-                message: "decision append would exceed protected review capacity; review decision satisfaction first",
-            });
-        }
         return {
             candidate,
             written: entry,
@@ -187,40 +163,17 @@ function mutateCandidate(req, doc) {
             replay: false,
         };
     }
-    if (req.artifact === "decisions") {
-        const entries = array(candidate, "decisions");
-        const archived = array(candidate, "archive");
-        const number = Number(req.values.number);
-        const entry = findByNumber(entries, number) ?? findByNumber(archived, number);
-        if (!entry)
-            reject({
-                class: "unsupported_target",
-                message: `no decision with number ${number}; highest is ${Math.max(0, ...entries.map((e) => Number(e.number) || 0), ...archived.map((e) => Number(e.number) || 0))}`,
-            });
-        const satisfaction = mapping(req.values.satisfaction);
-        if (satisfaction.state === "provisionally_satisfied" &&
-            !String(satisfaction.evidence ?? "").trim()) {
-            reject({
-                class: "schema_violation",
-                message: "provisionally_satisfied requires non-empty --satisfaction-evidence",
-            });
-        }
-        if (satisfaction.state === "user_confirmed_satisfied") {
-            const confirmation = mapping(satisfaction.user_confirmation);
-            if (!String(confirmation.confirmed_by ?? "").trim() ||
-                !String(confirmation.confirmed_at ?? "").trim()) {
-                reject({
-                    class: "schema_violation",
-                    message: "user_confirmed_satisfied requires --confirmed-by and --confirmed-at",
-                });
-            }
-        }
-        if (isDeepStrictEqual(entry.satisfaction, satisfaction))
-            return { candidate, written: entry, assigned: { number }, replay: true };
-        entry.satisfaction = satisfaction;
-        return { candidate, written: entry, assigned: { number }, replay: false };
-    }
     if (req.artifact === "health") {
+        if (req.spec.verb === "repair") {
+            if (!req.force)
+                reject({ class: "conflict", message: "health repair requires --force; use --dry-run to preview the edit" });
+            const number = Number(req.values.number);
+            const keep = req.values.keep === "last" ? "last" : "first";
+            const repaired = repairHealthDuplicates(candidate, number, keep);
+            if (repaired.removed === 0)
+                reject({ class: "unsupported_target", message: `health audit ${number} has no duplicate current-history rows to repair` });
+            return { candidate: repaired.candidate, written: { number, removed_rows: repaired.removed, retained: keep }, assigned: { number, removed_rows: repaired.removed }, replay: false };
+        }
         if (req.input && ("audits" in req.input || "archive" in req.input)) {
             reject({
                 class: "schema_violation",
@@ -230,8 +183,9 @@ function mutateCandidate(req, doc) {
         }
         const entries = array(candidate, "audits");
         const payload = req.callerPayload;
-        if (exactReplay(entries.at(-1), payload)) {
-            const entry = entries.at(-1);
+        const replay = entries.find((entry) => isExactArchiveReplay(entry, payload));
+        if (replay) {
+            const entry = replay;
             return {
                 candidate,
                 written: entry,
@@ -239,6 +193,15 @@ function mutateCandidate(req, doc) {
                 replay: true,
             };
         }
+        if (recovered) {
+            recoverArchivedEntry(candidate, "audits", entries, recovered, false);
+            return {
+                candidate,
+                written: recovered,
+                assigned: { number: recovered.number, date: recovered.date },
+                replay: true,
+            };
+        }
         const entry = {
             number: nextEntryNumber(candidate, "audits"),
             date: req.input?.date ?? localDate(),
@@ -257,7 +220,7 @@ function mutateCandidate(req, doc) {
         const sameName = tasks.find((task) => task.name === req.values.name);
         const payload = req.callerPayload;
         if (sameName) {
-            if (exactReplay(sameName, payload))
+            if (isExactArchiveReplay(sameName, payload))
                 return {
                     candidate,
                     written: sameName,
@@ -416,7 +379,9 @@ function activeKey(artifact) {
             ? "decisions"
             : artifact === "health"
                 ? "audits"
-                : "tasks";
+                : artifact === "experiments"
+                    ? "experiments"
+                    : "tasks";
 }
 function stateSlice(artifact, doc, archivePath) {
     if (artifact === "plan") {
@@ -435,6 +400,7 @@ function stateSlice(artifact, doc, archivePath) {
         active_count: active.length,
         archive_count: archive.length,
         next_number: nextEntryNumber(doc, activeKey(artifact)),
+        ...(archivePath ? { archive_path: archivePath } : {}),
     };
 }
 function diffText(before, after, target) {
@@ -468,6 +434,13 @@ function archivePathFor(projectRoot, target, doc, bytes) {
     assertWriterBoundary(projectRoot, archivePath, "plan archive");
     return archivePath;
 }
+function decisionRecordForUpdate(projectRoot, doc, number) {
+    const current = findByNumber(array(doc, "decisions"), number) ?? findByNumber(array(doc, "archive"), number);
+    if (current)
+        return current;
+    const archived = discoverNumberedArchives(projectRoot).entries.find((entry) => entry.artifactId === "decisions" && entry.entryNumber === number);
+    return archived?.record ?? null;
+}
 function latestArchivePath(archiveDirectory) {
     if (!fs.existsSync(archiveDirectory))
         return null;
@@ -478,26 +451,6 @@ function latestArchivePath(archiveDirectory) {
         .at(-1);
     return latest ? path.join(archiveDirectory, latest) : null;
 }
-function validatePlanCreateInput(input) {
-    const tasks = array(input, "tasks");
-    const numbers = tasks.map((task) => Number(task.number));
-    const expected = tasks.map((_, index) => index + 1);
-    if (!isDeepStrictEqual(numbers, expected)) {
-        reject({
-            class: "schema_violation",
-            message: "plan create task numbers must be unique and sequential starting from 1",
-            violations: ["PV1: task numbers must equal 1..N"],
-        });
-    }
-    if (mapping(input.header).status === "complete" &&
-        tasks.some((task) => task.status !== "complete")) {
-        reject({
-            class: "schema_violation",
-            message: "a complete plan cannot contain incomplete tasks",
-            violations: ["header.status complete requires every task complete"],
-        });
-    }
-}
 function canonicalPlanDocumentForWrite(doc) {
     const header = mapping(doc.header);
     const status = String(header.status ?? "");
@@ -525,48 +478,15 @@ function fsyncDirectory(directory) {
     }
 }
 function ensureArchive(archivePath, bytes) {
-    const directory = path.dirname(archivePath);
-    fs.mkdirSync(directory, { recursive: true });
-    const stage = path.join(directory, `.${path.basename(archivePath)}.writer.${process.pid}.${Date.now()}.tmp`);
-    let stageCreated = false;
-    let fd;
-    try {
-        fd = fs.openSync(stage, "wx");
-        stageCreated = true;
-        fs.writeFileSync(fd, bytes, "utf8");
-        fs.fsyncSync(fd);
-        fs.closeSync(fd);
-        fd = undefined;
-        try {
-            fs.linkSync(stage, archivePath);
-            fsyncDirectory(directory);
-            return true;
-        }
-        catch (error) {
-            if (error.code !== "EEXIST")
-                throw error;
-            if (fs.readFileSync(archivePath, "utf8") !== bytes) {
+    return publishImmutableFile(archivePath, bytes, {
+        onExisting: () => {
+            if (fs.readFileSync(archivePath, "utf8") !== bytes)
                 reject({
                     class: "conflict",
                     message: `archive path '${archivePath}' already exists with different content; historical archives are immutable`,
                 });
-            }
-            return false;
-        }
-    }
-    finally {
-        if (fd !== undefined)
-            fs.closeSync(fd);
-        if (stageCreated) {
-            try {
-                fs.unlinkSync(stage);
-                fsyncDirectory(directory);
-            }
-            catch {
-                // A published archive is authoritative; a leftover private stage is ignored on retry.
-            }
-        }
-    }
+        },
+    });
 }
 function publishStagedPlan(stage, target) {
     fs.renameSync(stage, target);
@@ -605,10 +525,13 @@ function planLifecycle(req, target, existing, legacyLifecycle = false) {
                 message: `active plan "${mapping(existing.doc.header).title ?? existing.doc.title ?? "untitled"}" has status ${status || "unknown"} or incomplete tasks; archiving would discard incomplete work`,
                 syntax: "agentera state plan archive --force",
             });
-        const archiveDoc = canonicalPlanDocumentForArchive(existing.doc);
-        const archiveBytes = dumpYamlMapping(archiveDoc);
+        const preserveExactBytes = req.force && !legacyLifecycle;
+        const archiveDoc = preserveExactBytes ? existing.doc : canonicalPlanDocumentForArchive(existing.doc);
+        const archiveBytes = preserveExactBytes ? existing.bytes : dumpYamlMapping(archiveDoc);
         const archivePath = archivePathFor(req.projectRoot, target, archiveDoc, archiveBytes);
-        validatePlanPublicationCandidate(archiveBytes);
+        const predecessorValidation = validatePlanPublicationCandidate(archiveBytes, {
+            allowHistoricalBudgetOverflow: req.force,
+        });
         if (!req.dryRun) {
             // Archive creation and current-plan removal cannot be one filesystem transaction.
             // The durable archive is published first; retries remove the current plan only after
@@ -621,6 +544,7 @@ function planLifecycle(req, target, existing, legacyLifecycle = false) {
             diff: diffText(existing.bytes, "", target),
             before: existing.doc,
             after: {},
+            validationDiagnostics: predecessorValidation.diagnostics,
         });
     }
     const input = structuredClone(req.input ?? {});
@@ -634,10 +558,23 @@ function planLifecycle(req, target, existing, legacyLifecycle = false) {
         const oldStatus = String(mapping(existing.doc.header).status ?? existing.doc.status ?? "");
         const existingWithoutLineage = structuredClone(existing.doc);
         delete existingWithoutLineage.previous_plan_archived;
+        const existingHeader = mapping(existingWithoutLineage.header);
+        delete existingHeader.id;
+        existingWithoutLineage.header = existingHeader;
         const sameWithoutLineage = isDeepStrictEqual(existingWithoutLineage, input);
         if (sameWithoutLineage && !legacyLifecycle) {
-            validatePlanPublicationCandidate(dumpYamlMapping(existing.doc));
-            return envelope(req, target, existing.doc, mapping(existing.doc.header), {}, true, null, req.dryRun ? { diff: "", before: existing.doc, after: existing.doc } : {});
+            const predecessorBytes = req.force ? existing.bytes : dumpYamlMapping(existing.doc);
+            const predecessorValidation = validatePlanPublicationCandidate(predecessorBytes, {
+                allowHistoricalBudgetOverflow: req.force,
+            });
+            return envelope(req, target, existing.doc, mapping(existing.doc.header), {}, true, null, req.dryRun
+                ? {
+                    diff: "",
+                    before: existing.doc,
+                    after: existing.doc,
+                    validationDiagnostics: predecessorValidation.diagnostics,
+                }
+                : { validationDiagnostics: predecessorValidation.diagnostics });
         }
         if (!sameWithoutLineage) {
             if (oldStatus !== "complete" && !req.force)
@@ -645,14 +582,16 @@ function planLifecycle(req, target, existing, legacyLifecycle = false) {
                     class: "conflict",
                     message: `active plan "${mapping(existing.doc.header).title ?? existing.doc.title ?? "untitled"}" has status ${oldStatus || "unknown"}; replacing it would discard incomplete work`,
                 });
-            predecessorBytes = dumpYamlMapping(existing.doc);
+            predecessorBytes = req.force && !legacyLifecycle ? existing.bytes : dumpYamlMapping(existing.doc);
             archivePath = archivePathFor(req.projectRoot, target, existing.doc, predecessorBytes);
             input.previous_plan_archived = path.relative(req.projectRoot, archivePath);
         }
     }
+    input.header = { ...mapping(input.header), id: `plan:${randomUUID()}` };
     const bytes = dumpYamlMapping(input);
-    if (predecessorBytes)
-        validatePlanPublicationCandidate(predecessorBytes);
+    const predecessorValidation = predecessorBytes
+        ? validatePlanPublicationCandidate(predecessorBytes, { allowHistoricalBudgetOverflow: req.force })
+        : { diagnostics: [] };
     validatePlanPublicationCandidate(bytes);
     const finalDoc = loadYamlMapping(bytes);
     if (!req.dryRun) {
@@ -679,6 +618,7 @@ function planLifecycle(req, target, existing, legacyLifecycle = false) {
         diff: diffText(existing.bytes, bytes, target),
         before: existing.doc,
         after: finalDoc,
+        validationDiagnostics: predecessorValidation.diagnostics,
     });
 }
 function envelope(req, target, finalDoc, written, assigned, replay, compaction, extra = {}) {
@@ -697,9 +637,15 @@ function envelope(req, target, finalDoc, written, assigned, replay, compaction,
         assigned,
         written,
         state: stateSlice(req.artifact, finalDoc, extra.archivePath),
-        validation: { status: "pass", violations: [] },
+        validation: {
+            status: "pass",
+            violations: [],
+            ...(extra.validationDiagnostics && extra.validationDiagnostics.length > 0
+                ? { diagnostics: extra.validationDiagnostics }
+                : {}),
+        },
         compaction: compaction && req.artifact === "decisions"
-            ? { ...compaction, protected_overflow_count: 0 }
+            ? { ...compaction, protected_overflow_count: extra.protectedOverflowCount ?? 0 }
             : compaction,
     };
     if (req.dryRun && extra.diff !== undefined) {
@@ -709,79 +655,146 @@ function envelope(req, target, finalDoc, written, assigned, replay, compaction,
     }
     return result;
 }
-export function executeStateWrite(req) {
+export function executeStateWrite(req, options = {}) {
     assertWriterBoundary(req.projectRoot, path.join(req.projectRoot, ".agentera"), "writer lock");
     const planPublication = req.artifact === "plan" && ["archive", "create"].includes(req.spec.verb);
-    const lock = req.dryRun && planPublication ? null : acquireWriterLock(req.projectRoot);
+    if (req.dryRun && planPublication)
+        return executeStateWriteUnlocked(req);
+    return withStateMutation(req.projectRoot, (transaction) => executeStateWriteUnlocked(req, transaction), options);
+}
+function executeStateWriteUnlocked(req, transaction) {
+    if (req.artifact === "experiments" && req.spec.verb === "publish")
+        return executeExperimentPublication(req, transaction);
+    const record = loadArtifactRegistry().get(req.artifact);
+    if (!record)
+        throw new Error(`artifact '${req.artifact}' is not registered`);
+    let target;
     try {
-        const record = loadArtifactRegistry().get(req.artifact);
-        if (!record)
-            throw new Error(`artifact '${req.artifact}' is not registered`);
-        let target;
-        try {
-            target = resolveArtifactPath(record, req.projectRoot, { strictWrite: true });
-        }
-        catch (error) {
-            const message = error.message;
-            if (message.startsWith("artifact '"))
-                reject({ class: "unsupported_target", message });
-            throw error;
+        target = resolveArtifactPath(record, req.projectRoot, { strictWrite: true });
+    }
+    catch (error) {
+        const message = error.message;
+        if (message.startsWith("artifact '"))
+            reject({ class: "unsupported_target", message });
+        throw error;
+    }
+    const existing = readExisting(target);
+    const legacyLifecycle = req.artifact === "plan" && ["active", "completed"].includes(String(mapping(existing.doc.header).status ?? ""));
+    if (legacyLifecycle)
+        existing.doc = canonicalPlanDocumentForWrite(existing.doc);
+    if (existing.bytes) {
+        const validationBytes = req.artifact === "plan" ? dumpYamlMapping(existing.doc) : existing.bytes;
+        const violations = validateArtifactBytes(req.artifact, validationBytes);
+        if (violations.length) {
+            throw new Error(`existing artifact '${target}' is schema-invalid: ${violations.join("; ")}; repair it before retrying`);
         }
-        const existing = readExisting(target);
-        const legacyLifecycle = req.artifact === "plan" && ["active", "completed"].includes(String(mapping(existing.doc.header).status ?? ""));
-        if (legacyLifecycle)
-            existing.doc = canonicalPlanDocumentForWrite(existing.doc);
-        if (existing.bytes) {
-            const validationBytes = req.artifact === "plan" ? dumpYamlMapping(existing.doc) : existing.bytes;
-            const violations = validateArtifactBytes(req.artifact, validationBytes);
-            if (violations.length) {
-                throw new Error(`existing artifact '${target}' is schema-invalid: ${violations.join("; ")}; repair it before retrying`);
-            }
+        if (req.artifact === "plan") {
+            const evaluationViolations = planEvaluationViolations(existing.doc);
+            if (evaluationViolations.length > 0)
+                throw new Error(`existing artifact '${target}' is schema-invalid: ${evaluationViolations.join("; ")}; repair it before retrying`);
         }
-        if (req.artifact === "plan" && ["archive", "create"].includes(req.spec.verb))
-            return planLifecycle(req, target, existing, legacyLifecycle);
-        if (!existing.bytes && req.artifact === "plan")
+    }
+    if (req.artifact === "decisions" && req.spec.verb === "update") {
+        const number = Number(req.values.number);
+        if (!Number.isSafeInteger(number) || number < 1)
+            reject({
+                class: "schema_violation",
+                message: "decision update requires a positive decision number",
+                syntax: "agentera state decisions update --number N --satisfaction-state STATE --format json",
+                example: "agentera state decisions update --number 53 --satisfaction-state open --format json",
+            });
+        const record = decisionRecordForUpdate(req.projectRoot, existing.doc, number);
+        if (!record)
             reject({
                 class: "unsupported_target",
-                message: "no active plan exists; create one before appending a task",
-                example: "agentera state plan create --input plan.yaml",
+                message: `no decision with number ${number}; numbered archive or current projection record is required`,
+                syntax: "agentera state decisions update --number N --satisfaction-state STATE --format json",
+                example: "agentera state decisions update --number 53 --satisfaction-state open --format json",
             });
-        const mutated = mutateCandidate(req, existing.doc);
-        if (mutated.replay)
-            return envelope(req, target, mutated.candidate, mutated.written, mutated.assigned, true, null, req.dryRun ? { diff: "", before: existing.doc, after: mutated.candidate } : {});
-        const candidateBytes = dumpYamlMapping(mutated.candidate);
-        const candidateViolations = validateArtifactBytes(req.artifact, candidateBytes);
-        if (candidateViolations.length)
-            schemaViolation(candidateViolations);
-        const stage = stagingPath(req, target);
-        let compaction = null;
-        try {
+        if (!transaction)
+            throw new Error("state mutation transaction is unavailable");
+        const update = updateDecisionOverlay(req.projectRoot, number, req.values.satisfaction, record.satisfaction, transaction, !req.dryRun);
+        const before = dumpYamlMapping(update.before);
+        const after = dumpYamlMapping(update.after);
+        return envelope(req, update.path, existing.doc, { satisfaction: update.satisfaction }, { number }, update.replay, null, { diff: diffText(before, after, update.path), before: update.before, after: update.after });
+    }
+    if (req.artifact === "plan" && ["archive", "create"].includes(req.spec.verb))
+        return planLifecycle(req, target, existing, legacyLifecycle);
+    if (!existing.bytes && req.artifact === "plan")
+        reject({
+            class: "unsupported_target",
+            message: "no active plan exists; create one before appending a task",
+            example: "agentera state plan create --input plan.yaml",
+        });
+    const numberedAppend = req.spec.verb === "append" && ["progress", "decisions", "health"].includes(req.artifact);
+    const replayPayload = req.artifact === "decisions"
+        ? normalizedDecisionPayload(req.callerPayload)
+        : req.callerPayload;
+    const mutated = mutateCandidate(req, existing.doc, numberedAppend ? findArchivedReplay(req.projectRoot, req.artifact, replayPayload) : undefined);
+    if (mutated.replay && isDeepStrictEqual(mutated.candidate, existing.doc)) {
+        let archive;
+        if (numberedAppend && !req.dryRun) {
+            if (!transaction)
+                throw new Error("state mutation transaction is unavailable");
+            archive = transaction.publishArchive(req.artifact, Number(mutated.written.number), mutated.written);
+        }
+        return envelope(req, target, mutated.candidate, mutated.written, mutated.assigned, true, null, {
+            ...(archive ? { archivePath: archive.path } : {}),
+            ...(req.dryRun ? { diff: "", before: existing.doc, after: mutated.candidate } : {}),
+        });
+    }
+    const repairedBytes = req.artifact === "health" && req.spec.verb === "repair"
+        ? repairHealthProjectionBytes(existing.bytes, Number(req.values.number), req.values.keep === "last" ? "last" : "first")
+        : null;
+    if (repairedBytes && repairedBytes.removed === 0)
+        reject({ class: "unsupported_target", message: `health audit ${Number(req.values.number)} has no duplicate current-history rows to repair` });
+    const candidateBytes = repairedBytes?.bytes ?? dumpYamlMapping(mutated.candidate);
+    const candidateViolations = validateArtifactBytes(req.artifact, candidateBytes);
+    if (candidateViolations.length)
+        schemaViolation(candidateViolations);
+    const stage = req.dryRun
+        ? stagingPath(req, target)
+        : transaction?.stageProjection(target, candidateBytes);
+    if (!stage)
+        throw new Error("state mutation transaction is unavailable");
+    let compaction = null;
+    const protectedOverflowCount = req.artifact === "decisions"
+        ? decisionProtectedOverflowCount(hydrateDecisionRecords(array(mutated.candidate, "decisions"), req.projectRoot), hydrateDecisionRecords(array(mutated.candidate, "archive"), req.projectRoot))
+        : 0;
+    try {
+        if (req.dryRun)
             fs.writeFileSync(stage, candidateBytes);
-            if (req.spec.compacts)
-                compaction = compactYamlFile(stage, req.artifact);
-            const finalBytes = fs.readFileSync(stage, "utf8");
-            const finalViolations = validateArtifactBytes(req.artifact, finalBytes);
-            if (finalViolations.length)
-                throw new Error(`writer/compactor invariant failure: ${finalViolations.join("; ")}`);
-            const finalDoc = loadYamlMapping(finalBytes);
-            const diff = diffText(existing.bytes, finalBytes, target);
-            if (req.dryRun) {
-                return envelope(req, target, finalDoc, mutated.written, mutated.assigned, false, compaction, { diff, before: existing.doc, after: finalDoc });
-            }
-            fs.renameSync(stage, target);
-            return envelope(req, target, finalDoc, mutated.written, mutated.assigned, false, compaction);
+        if (req.spec.compacts) {
+            compaction = compactYamlFile(stage, req.artifact, req.projectRoot);
         }
-        finally {
-            try {
-                fs.unlinkSync(stage);
-            }
-            catch {
-                /* stage published or absent */
-            }
+        const finalBytes = fs.readFileSync(stage, "utf8");
+        const finalViolations = validateArtifactBytes(req.artifact, finalBytes);
+        if (finalViolations.length)
+            throw new Error(`writer/compactor invariant failure: ${finalViolations.join("; ")}`);
+        if (!req.dryRun)
+            transaction?.syncStaged(stage);
+        const finalDoc = loadYamlMapping(finalBytes);
+        const diff = diffText(existing.bytes, finalBytes, target);
+        if (req.dryRun) {
+            return envelope(req, target, finalDoc, mutated.written, mutated.assigned, false, compaction, { diff, before: existing.doc, after: finalDoc, protectedOverflowCount });
         }
+        const archive = numberedAppend
+            ? transaction?.publishArchive(req.artifact, Number(mutated.written.number), mutated.written)
+            : undefined;
+        if (!req.dryRun)
+            transaction?.publishProjection(stage, target);
+        return envelope(req, target, finalDoc, mutated.written, mutated.assigned, mutated.replay, compaction, { ...(archive ? { archivePath: archive.path } : {}), protectedOverflowCount });
     }
     finally {
-        lock?.release();
+        try {
+            if (req.dryRun)
+                fs.unlinkSync(stage);
+            else
+                transaction?.removeStage(stage);
+        }
+        catch {
+            /* stage published or absent */
+        }
     }
 }
 //# sourceMappingURL=transaction.js.map