agentera 3.0.0-dev.2 → 3.0.0-dev.21

package/dist/state/write/transaction.js

@@ -0,0 +1,800 @@
+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 { compactYamlFile, decisionProtectedOverflowCount, } from "../../hooks/compaction/index.js";
+import { assertRealpathBoundary, loadArtifactRegistry, resolveArtifactPath, } from "../../registries/artifactRegistry.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
+        : {};
+}
+function array(doc, key) {
+    return Array.isArray(doc[key])
+        ? doc[key].filter((v) => Boolean(v && typeof v === "object" && !Array.isArray(v)))
+        : [];
+}
+function mappingPath(entry, field) {
+    let value = entry;
+    for (const part of field.split(".")) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return undefined;
+        value = value[part];
+    }
+    return value;
+}
+function readExisting(target) {
+    if (!fs.existsSync(target))
+        return { doc: {}, bytes: "" };
+    const bytes = fs.readFileSync(target, "utf8");
+    try {
+        return { doc: loadYamlMapping(bytes), bytes };
+    }
+    catch (error) {
+        throw new Error(`cannot parse existing artifact '${target}': ${error.message}; run agentera check validate artifact before retrying`);
+    }
+}
+function buildProgress(doc, values) {
+    const entry = {
+        number: nextEntryNumber(doc, "cycles"),
+        timestamp: values.timestamp ?? localTimestamp(),
+        type: values.type,
+        phase: values.phase,
+        what: values.what,
+    };
+    for (const field of ["inspiration", "discovered", "verified", "next"])
+        if (values[field] !== undefined)
+            entry[field] = values[field];
+    const context = { intent: mappingPath(values, "context.intent") };
+    for (const field of ["constraints", "unknowns", "scope"]) {
+        const value = mappingPath(values, `context.${field}`);
+        if (value !== undefined)
+            context[field] = value;
+    }
+    entry.context = context;
+    return entry;
+}
+function buildDecision(doc, values) {
+    const alternatives = mapping(values.alternatives);
+    const rejected = Array.isArray(alternatives.rejected) ? alternatives.rejected : [];
+    const entry = {
+        number: nextEntryNumber(doc, "decisions"),
+        date: values.date ?? localDate(),
+        question: values.question,
+        context: values.context,
+        alternatives: [
+            { name: alternatives.chosen, status: "chosen" },
+            ...rejected.map((name) => ({ name, status: "rejected" })),
+        ],
+        choice: values.choice,
+        reasoning: values.reasoning,
+        confidence: values.confidence,
+    };
+    if (values.feeds_into !== undefined)
+        entry.feeds_into = values.feeds_into;
+    return entry;
+}
+function normalizedDecisionPayload(values) {
+    const payload = { ...values };
+    const alternatives = mapping(values.alternatives);
+    payload.alternatives = [
+        { name: alternatives.chosen, status: "chosen" },
+        ...(Array.isArray(alternatives.rejected) ? alternatives.rejected : []).map((name) => ({
+            name,
+            status: "rejected",
+        })),
+    ];
+    return payload;
+}
+function mutateCandidate(req, doc, recovered) {
+    const candidate = structuredClone(doc);
+    if (req.artifact === "progress") {
+        const payload = req.callerPayload;
+        const entries = array(candidate, "cycles");
+        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: recovered,
+                assigned: { number: recovered.number, timestamp: recovered.timestamp },
+                replay: true,
+            };
+        }
+        const entry = buildProgress(candidate, req.values);
+        candidate.cycles = [entry, ...entries];
+        return {
+            candidate,
+            written: entry,
+            assigned: { number: entry.number, timestamp: entry.timestamp },
+            replay: false,
+        };
+    }
+    if (req.artifact === "decisions" && req.spec.verb === "append") {
+        const entries = array(candidate, "decisions");
+        const payload = normalizedDecisionPayload(req.callerPayload);
+        const replay = entries.find((entry) => isExactArchiveReplay(entry, payload));
+        if (replay) {
+            const entry = replay;
+            return {
+                candidate,
+                written: entry,
+                assigned: { number: entry.number, date: entry.date },
+                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];
+        return {
+            candidate,
+            written: entry,
+            assigned: { number: entry.number, date: entry.date },
+            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",
+                message: "health append input must be one audit entry, not a whole health artifact",
+                violations: ["remove audits/archive wrapper fields"],
+            });
+        }
+        const entries = array(candidate, "audits");
+        const payload = req.callerPayload;
+        const replay = entries.find((entry) => isExactArchiveReplay(entry, payload));
+        if (replay) {
+            const entry = replay;
+            return {
+                candidate,
+                written: entry,
+                assigned: { number: entry.number, date: entry.date },
+                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(),
+            ...req.input,
+        };
+        candidate.audits = [...entries, entry];
+        return {
+            candidate,
+            written: entry,
+            assigned: { number: entry.number, date: entry.date },
+            replay: false,
+        };
+    }
+    const tasks = array(candidate, "tasks");
+    if (req.spec.verb === "append") {
+        const sameName = tasks.find((task) => task.name === req.values.name);
+        const payload = req.callerPayload;
+        if (sameName) {
+            if (isExactArchiveReplay(sameName, payload))
+                return {
+                    candidate,
+                    written: sameName,
+                    assigned: { number: sameName.number },
+                    replay: true,
+                };
+            reject({
+                class: "conflict",
+                message: `plan task "${req.values.name}" exists with different fields; use 'state plan update --task ${sameName.number}' to modify it`,
+            });
+        }
+        const entry = {
+            number: nextTaskNumber(candidate),
+            name: req.values.name,
+            status: req.values.status ?? "pending",
+        };
+        for (const field of ["depends_on", "acceptance"])
+            if (req.values[field] !== undefined)
+                entry[field] = req.values[field];
+        candidate.tasks = [...tasks, entry];
+        return { candidate, written: entry, assigned: { number: entry.number }, replay: false };
+    }
+    if (req.spec.verb === "update") {
+        const number = Number(req.values.task);
+        const entry = findByNumber(tasks, number);
+        if (!entry)
+            reject({ class: "unsupported_target", message: `no plan task with number ${number}` });
+        let changed = false;
+        for (const field of [
+            "name",
+            "depends_on",
+            "acceptance",
+            "status",
+            "evidence",
+            "blocked_reason",
+        ]) {
+            if (req.values[field] !== undefined && !isDeepStrictEqual(entry[field], req.values[field])) {
+                entry[field] = req.values[field];
+                changed = true;
+            }
+        }
+        if (req.values.surprise !== undefined) {
+            const current = String(candidate.surprises ?? "").trim();
+            const surprise = String(req.values.surprise);
+            if (!current.split("\n").includes(surprise)) {
+                candidate.surprises = current ? `${current}\n${surprise}` : surprise;
+                changed = true;
+            }
+        }
+        return { candidate, written: entry, assigned: { number }, replay: !changed };
+    }
+    if (req.spec.verb === "set-plan-status") {
+        const status = String(req.values.status);
+        if (status === "complete" && tasks.some((task) => task.status !== "complete")) {
+            reject({
+                class: "conflict",
+                message: "plan cannot be marked complete while incomplete tasks remain",
+            });
+        }
+        const header = mapping(candidate.header);
+        const replay = header.status === status;
+        header.status = status;
+        candidate.header = header;
+        return { candidate, written: header, assigned: {}, replay };
+    }
+    if (req.spec.verb === "set-status") {
+        const taskNumber = Number(req.values.task);
+        const status = String(req.values.status);
+        if (!["complete", "in_progress", "pending", "blocked"].includes(status))
+            reject({
+                class: "invalid_choice",
+                message: `argument --status: invalid choice: '${status}'`,
+                valid_values: ["complete", "in_progress", "pending", "blocked"],
+            });
+        const entry = findByNumber(tasks, taskNumber);
+        if (!entry)
+            reject({ class: "unsupported_target", message: `no plan task with number ${taskNumber}` });
+        const replay = entry.status === status;
+        entry.status = status;
+        return { candidate, written: entry, assigned: { number: taskNumber }, replay };
+    }
+    if (req.spec.verb === "record-evaluation") {
+        const taskNumber = Number(req.values.task);
+        const entry = findByNumber(tasks, taskNumber);
+        if (!entry)
+            reject({ class: "unsupported_target", message: `no plan task with number ${taskNumber}` });
+        const evaluationInput = mapping(req.values.evaluation);
+        const attemptId = String(evaluationInput.attempt_id ?? "").trim();
+        const verdict = String(evaluationInput.verdict ?? "");
+        const provenance = String(evaluationInput.provenance ?? "").trim();
+        const failureEvidence = String(evaluationInput.failure_evidence ?? "").trim();
+        if (!attemptId || !provenance)
+            reject({ class: "schema_violation", message: "evaluation requires non-empty --attempt-id and --provenance" });
+        if (verdict === "fail" && !failureEvidence)
+            reject({ class: "schema_violation", message: "a failed evaluation requires non-empty --failure-evidence" });
+        if (verdict === "pass" && failureEvidence)
+            reject({ class: "schema_violation", message: "--failure-evidence applies only to a failed evaluation" });
+        const prior = mapping(entry.evaluation);
+        const priorProvenance = mapping(prior.provenance);
+        if (priorProvenance.attempt_id === attemptId) {
+            const replay = prior.last_verdict === verdict &&
+                priorProvenance.source === provenance &&
+                (verdict !== "fail" || prior.last_failure_evidence === failureEvidence);
+            if (!replay)
+                reject({
+                    class: "conflict",
+                    message: `evaluation attempt '${attemptId}' already exists with different result data`,
+                });
+            return {
+                candidate,
+                written: entry,
+                assigned: { number: taskNumber, attempt_count: prior.attempt_count ?? 0 },
+                replay: true,
+            };
+        }
+        if (["complete", "blocked"].includes(String(entry.status ?? "")))
+            reject({ class: "conflict", message: `plan task ${taskNumber} is ${entry.status} and cannot accept another evaluation` });
+        const attemptCount = Number(prior.attempt_count ?? 0);
+        const failureCount = Number(prior.failure_count ?? 0);
+        if (!Number.isInteger(attemptCount) || attemptCount < 0 || !Number.isInteger(failureCount) || failureCount < 0)
+            reject({ class: "schema_violation", message: `plan task ${taskNumber} has malformed evaluation state` });
+        if (verdict === "fail" && failureCount >= 2)
+            reject({ class: "conflict", message: `plan task ${taskNumber} has exhausted its evaluation retry budget` });
+        const nextFailureCount = failureCount + (verdict === "fail" ? 1 : 0);
+        entry.evaluation = {
+            attempt_count: attemptCount + 1,
+            failure_count: nextFailureCount,
+            last_verdict: verdict,
+            last_failure_evidence: verdict === "fail" ? failureEvidence : prior.last_failure_evidence ?? null,
+            provenance: {
+                attempt_id: attemptId,
+                source: provenance,
+                recorded_at: localTimestamp(),
+                writer_command: "agentera state plan record-evaluation",
+            },
+        };
+        if (nextFailureCount >= 2)
+            entry.status = "blocked";
+        return {
+            candidate,
+            written: entry,
+            assigned: {
+                number: taskNumber,
+                attempt_count: attemptCount + 1,
+                failure_count: nextFailureCount,
+            },
+            replay: false,
+        };
+    }
+    throw new Error(`unsupported transaction ${req.artifact} ${req.spec.verb}`);
+}
+function activeKey(artifact) {
+    return artifact === "progress"
+        ? "cycles"
+        : artifact === "decisions"
+            ? "decisions"
+            : artifact === "health"
+                ? "audits"
+                : artifact === "experiments"
+                    ? "experiments"
+                    : "tasks";
+}
+function stateSlice(artifact, doc, archivePath) {
+    if (artifact === "plan") {
+        const tasks = array(doc, "tasks");
+        return {
+            title: mapping(doc.header).title ?? doc.title ?? null,
+            status: mapping(doc.header).status ?? doc.status ?? null,
+            task_count: tasks.length,
+            next_pending_task: dependencyReadyTasks(tasks).find((task) => task.status === "pending") ?? null,
+            ...(archivePath ? { archive_path: archivePath } : {}),
+        };
+    }
+    const active = array(doc, activeKey(artifact));
+    const archive = Array.isArray(doc.archive) ? doc.archive : [];
+    return {
+        active_count: active.length,
+        archive_count: archive.length,
+        next_number: nextEntryNumber(doc, activeKey(artifact)),
+        ...(archivePath ? { archive_path: archivePath } : {}),
+    };
+}
+function diffText(before, after, target) {
+    return unifiedDiff(splitLinesKeepEnds(before), splitLinesKeepEnds(after), target, target).join("");
+}
+function slug(value) {
+    return (String(value ?? "plan")
+        .replace(/^Plan:\s*/i, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "") || "plan");
+}
+function assertWriterBoundary(projectRoot, candidate, artifactId) {
+    try {
+        assertRealpathBoundary(projectRoot, candidate, artifactId);
+    }
+    catch (error) {
+        const message = error.message;
+        if (message.startsWith("artifact '"))
+            reject({ class: "unsupported_target", message });
+        throw error;
+    }
+}
+function archivePathFor(projectRoot, target, doc, bytes) {
+    const header = mapping(doc.header);
+    const created = String(header.created ?? "undated").replace(/[^0-9-]/g, "") || "undated";
+    const title = header.title ?? doc.title;
+    // Archive identity must survive a retry that crosses a calendar boundary.
+    const identity = createHash("sha256").update(bytes).digest("hex").slice(0, 16);
+    const archivePath = path.join(path.dirname(target), "archive", `PLAN-${created}-${slug(title)}-${identity}.yaml`);
+    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;
+    const latest = fs
+        .readdirSync(archiveDirectory)
+        .filter((name) => name.startsWith("PLAN-") && name.endsWith(".yaml"))
+        .sort()
+        .at(-1);
+    return latest ? path.join(archiveDirectory, latest) : null;
+}
+function canonicalPlanDocumentForWrite(doc) {
+    const header = mapping(doc.header);
+    const status = String(header.status ?? "");
+    if (status !== "active" && status !== "completed")
+        return doc;
+    const canonicalStatus = status === "active" || array(doc, "tasks").some((task) => task.status !== "complete")
+        ? "open"
+        : "complete";
+    return { ...doc, header: { ...header, status: canonicalStatus } };
+}
+function canonicalPlanDocumentForArchive(doc) {
+    const candidate = structuredClone(doc);
+    const tasks = array(candidate, "tasks");
+    const complete = tasks.length > 0 && tasks.every((task) => task.status === "complete");
+    candidate.header = { ...mapping(candidate.header), status: complete ? "complete" : "open" };
+    return candidate;
+}
+function fsyncDirectory(directory) {
+    const fd = fs.openSync(directory, "r");
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function ensureArchive(archivePath, 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`,
+                });
+        },
+    });
+}
+function publishStagedPlan(stage, target) {
+    fs.renameSync(stage, target);
+    fsyncDirectory(path.dirname(target));
+}
+function removeCurrentPlan(target) {
+    fs.unlinkSync(target);
+    fsyncDirectory(path.dirname(target));
+}
+function stagingPath(req, target) {
+    const dir = req.dryRun ? path.join(req.projectRoot, ".agentera") : path.dirname(target);
+    if (!req.dryRun)
+        fs.mkdirSync(dir, { recursive: true });
+    return path.join(dir, `.${path.basename(target)}.writer.${process.pid}.${Date.now()}.tmp`);
+}
+function planLifecycle(req, target, existing, legacyLifecycle = false) {
+    if (req.spec.verb === "archive") {
+        const archiveDir = path.join(path.dirname(target), "archive");
+        assertWriterBoundary(req.projectRoot, archiveDir, "plan archive");
+        if (!existing.bytes) {
+            const archivePath = latestArchivePath(archiveDir);
+            if (!archivePath)
+                reject({ class: "unsupported_target", message: "no active plan exists to archive" });
+            const archived = readExisting(archivePath);
+            return envelope(req, target, {}, mapping(archived.doc.header), {}, true, null, {
+                archivePath,
+                ...(req.dryRun ? { diff: "", before: {}, after: {} } : {}),
+            });
+        }
+        const status = String(mapping(existing.doc.header).status ?? existing.doc.status ?? "");
+        const incomplete = status !== "complete" ||
+            array(existing.doc, "tasks").some((task) => task.status !== "complete");
+        if (incomplete && !req.force)
+            reject({
+                class: "conflict",
+                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 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);
+        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
+            // they observe that exact immutable archive.
+            ensureArchive(archivePath, archiveBytes);
+            removeCurrentPlan(target);
+        }
+        return envelope(req, target, {}, mapping(archiveDoc.header), {}, false, null, {
+            archivePath,
+            diff: diffText(existing.bytes, "", target),
+            before: existing.doc,
+            after: {},
+            validationDiagnostics: predecessorValidation.diagnostics,
+        });
+    }
+    const input = structuredClone(req.input ?? {});
+    validatePlanCreateInput(input);
+    const candidateStatus = String(mapping(input.header).status ?? input.status ?? "");
+    if (!candidateStatus)
+        reject({ class: "schema_violation", message: "plan create input requires header.status" });
+    let archivePath;
+    let predecessorBytes = null;
+    if (existing.bytes) {
+        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) {
+            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)
+                reject({
+                    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 = 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);
+    const predecessorValidation = predecessorBytes
+        ? validatePlanPublicationCandidate(predecessorBytes, { allowHistoricalBudgetOverflow: req.force })
+        : { diagnostics: [] };
+    validatePlanPublicationCandidate(bytes);
+    const finalDoc = loadYamlMapping(bytes);
+    if (!req.dryRun) {
+        const stage = stagingPath(req, target);
+        try {
+            fs.writeFileSync(stage, bytes);
+            // Archive and current replacement are deliberately two durable operations. If the
+            // process stops between them, retry sees the exact archive and converges on this plan.
+            if (predecessorBytes && archivePath)
+                ensureArchive(archivePath, predecessorBytes);
+            publishStagedPlan(stage, target);
+        }
+        finally {
+            try {
+                fs.unlinkSync(stage);
+            }
+            catch {
+                /* published or already removed */
+            }
+        }
+    }
+    return envelope(req, target, finalDoc, mapping(finalDoc.header), {}, false, null, {
+        archivePath,
+        diff: diffText(existing.bytes, bytes, target),
+        before: existing.doc,
+        after: finalDoc,
+        validationDiagnostics: predecessorValidation.diagnostics,
+    });
+}
+function envelope(req, target, finalDoc, written, assigned, replay, compaction, extra = {}) {
+    const result = {
+        schemaVersion: "agentera.stateWrite.v1",
+        command: `state ${req.artifact} ${req.spec.verb}`,
+        status: "pass",
+        artifact: req.artifact,
+        path: target,
+        operation: {
+            verb: req.spec.verb,
+            dry_run: req.dryRun,
+            idempotent_replay: replay,
+            forced: req.force,
+        },
+        assigned,
+        written,
+        state: stateSlice(req.artifact, finalDoc, extra.archivePath),
+        validation: {
+            status: "pass",
+            violations: [],
+            ...(extra.validationDiagnostics && extra.validationDiagnostics.length > 0
+                ? { diagnostics: extra.validationDiagnostics }
+                : {}),
+        },
+        compaction: compaction && req.artifact === "decisions"
+            ? { ...compaction, protected_overflow_count: extra.protectedOverflowCount ?? 0 }
+            : compaction,
+    };
+    if (req.dryRun && extra.diff !== undefined) {
+        result.diff = extra.diff;
+        result.before = extra.before ?? {};
+        result.after = extra.after ?? finalDoc;
+    }
+    return result;
+}
+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);
+    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 {
+        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`);
+        }
+        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 === "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 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",
+            });
+        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, req.projectRoot);
+        }
+        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 {
+        try {
+            if (req.dryRun)
+                fs.unlinkSync(stage);
+            else
+                transaction?.removeStage(stage);
+        }
+        catch {
+            /* stage published or absent */
+        }
+    }
+}
+//# sourceMappingURL=transaction.js.map