agentera 3.0.0-dev.2 → 3.0.0-dev.20

package/dist/state/write/transaction.js

@@ -0,0 +1,787 @@
+import { createHash } 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 { localDate, localTimestamp, nextEntryNumber, nextTaskNumber } from "./assign.js";
+import { reject } from "./errors.js";
+import { validateArtifactBytes } from "./validate.js";
+import { dependencyReadyTasks } from "../../cli/capabilityContext/planState.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 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(".")) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return undefined;
+        value = value[part];
+    }
+    return value;
+}
+function exactReplay(entry, payload) {
+    return Boolean(entry && isDeepStrictEqual(project(entry, payload), payload));
+}
+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 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) {
+    const candidate = structuredClone(doc);
+    if (req.artifact === "progress") {
+        const payload = req.callerPayload;
+        const entries = array(candidate, "cycles");
+        if (exactReplay(entries[0], payload))
+            return {
+                candidate,
+                written: entries[0],
+                assigned: { number: entries[0].number, timestamp: entries[0].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);
+        if (exactReplay(entries.at(-1), payload)) {
+            const entry = entries.at(-1);
+            return {
+                candidate,
+                written: entry,
+                assigned: { number: entry.number, date: entry.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,
+            assigned: { number: entry.number, date: entry.date },
+            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.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;
+        if (exactReplay(entries.at(-1), payload)) {
+            const entry = entries.at(-1);
+            return {
+                candidate,
+                written: entry,
+                assigned: { number: entry.number, date: entry.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 (exactReplay(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"
+                : "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)),
+    };
+}
+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 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 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 ?? "");
+    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) {
+    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) {
+                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);
+    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 archiveDoc = canonicalPlanDocumentForArchive(existing.doc);
+        const archiveBytes = dumpYamlMapping(archiveDoc);
+        const archivePath = archivePathFor(req.projectRoot, target, archiveDoc, archiveBytes);
+        validatePlanPublicationCandidate(archiveBytes);
+        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: {},
+        });
+    }
+    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 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 } : {});
+        }
+        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 = dumpYamlMapping(existing.doc);
+            archivePath = archivePathFor(req.projectRoot, target, existing.doc, predecessorBytes);
+            input.previous_plan_archived = path.relative(req.projectRoot, archivePath);
+        }
+    }
+    const bytes = dumpYamlMapping(input);
+    if (predecessorBytes)
+        validatePlanPublicationCandidate(predecessorBytes);
+    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,
+    });
+}
+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: [] },
+        compaction: compaction && req.artifact === "decisions"
+            ? { ...compaction, protected_overflow_count: 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) {
+    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);
+    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;
+        }
+        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" && ["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 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 {
+            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);
+        }
+        finally {
+            try {
+                fs.unlinkSync(stage);
+            }
+            catch {
+                /* stage published or absent */
+            }
+        }
+    }
+    finally {
+        lock?.release();
+    }
+}
+//# sourceMappingURL=transaction.js.map