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

package/dist/state/write/experimentPublication.js

@@ -0,0 +1,193 @@
+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 } from "../../hooks/compaction/index.js";
+import { assertRealpathBoundary } from "../../registries/artifactRegistry.js";
+import { assertExperimentArchiveReplay, prepareExperimentArchive, } from "../experimentArchive.js";
+import { ExperimentIdentityError, discoverObjectiveArtifacts, inspectExperimentIdentities, validateExperimentPublicationIdentity, } from "../experimentIdentity.js";
+import { reject } from "./errors.js";
+import { schemaViolation } from "./helpers.js";
+import { validateArtifactBytes } from "./validate.js";
+function array(doc, key) {
+    return Array.isArray(doc[key])
+        ? doc[key].filter((value) => Boolean(value && typeof value === "object" && !Array.isArray(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 diffText(before, after, target) {
+    return unifiedDiff(splitLinesKeepEnds(before), splitLinesKeepEnds(after), target, target).join("");
+}
+function rejectIdentity(error) {
+    reject({
+        class: error.className === "invalid_request"
+            ? "invalid_request"
+            : error.className === "not_found"
+                ? "unsupported_target"
+                : "conflict",
+        message: error.message,
+        syntax: "agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml --format json",
+        example: "agentera state experiments publish --objective objective:123e4567-e89b-42d3-a456-426614174000 --number 0 --input experiment.yaml --format json",
+        recovery: "Correct the objective or experiment identity and retry; no state was changed.",
+    });
+}
+function envelope(req, target, doc, written, assigned, replay, compaction, archive, preview) {
+    return {
+        schemaVersion: "agentera.stateWrite.v1",
+        command: "state experiments publish",
+        status: "pass",
+        artifact: "experiments",
+        path: target,
+        operation: { verb: "publish", dry_run: req.dryRun, idempotent_replay: replay, forced: false },
+        assigned,
+        written,
+        state: {
+            active_count: array(doc, "experiments").length,
+            archive_count: array(doc, "archive").length,
+        },
+        validation: { status: "pass", violations: [] },
+        compaction,
+        ...(archive ? {
+            archive: {
+                path: archive.target,
+                stable_id: archive.stableId,
+                record_sha256: archive.recordSha256,
+                provenance: archive.provenance,
+                idempotent_replay: archive.replay,
+            },
+        } : {}),
+        ...(preview ?? {}),
+    };
+}
+export function executeExperimentPublication(req, transaction) {
+    const objectiveId = String(req.values.objective ?? "");
+    const number = Number(req.values.number);
+    const input = structuredClone(req.input ?? {});
+    if ("number" in input)
+        reject({
+            class: "schema_violation",
+            message: "experiments publish assigns number; remove 'number' from the input document",
+            violations: ["CLI-owned field: number"],
+        });
+    const discovery = discoverObjectiveArtifacts(req.projectRoot);
+    const objective = discovery.objectives.find((candidate) => candidate.stableId === objectiveId);
+    try {
+        validateExperimentPublicationIdentity(discovery, { objectiveId, entries: [], caveats: [] }, objectiveId, number);
+    }
+    catch (error) {
+        if (error instanceof ExperimentIdentityError)
+            rejectIdentity(error);
+        throw error;
+    }
+    const canonicalPaths = objective?.paths.filter((candidate) => candidate.includes(`${path.sep}.agentera${path.sep}optimize${path.sep}`)) ?? [];
+    const objectivePath = objective?.paths.length === 1
+        ? objective.paths[0]
+        : canonicalPaths.length === 1
+            ? canonicalPaths[0]
+            : null;
+    if (!objectivePath)
+        reject({
+            class: "conflict",
+            message: `objective identity ${objectiveId} does not resolve to one publication target; no effects are allowed`,
+            recovery: `Resolve the objective path collision (${(objective?.paths ?? []).join(", ") || "no candidates"}) and retry; no state was changed.`,
+        });
+    const target = path.join(path.dirname(objectivePath), "experiments.yaml");
+    assertRealpathBoundary(req.projectRoot, target, "experiments");
+    const existing = readExisting(target);
+    if (existing.bytes) {
+        const violations = validateArtifactBytes("experiments", existing.bytes);
+        if (violations.length)
+            throw new Error(`existing artifact '${target}' is schema-invalid: ${violations.join("; ")}; repair it before retrying`);
+    }
+    const projection = inspectExperimentIdentities(objectiveId, existing.doc);
+    const written = { number, ...input };
+    const stableId = `${objectiveId}/experiment:${number}`;
+    const assigned = { objective: objectiveId, number, stable_id: stableId };
+    const retained = projection.entries.filter((entry) => entry.stableId === stableId);
+    if (retained.length === 1 && retained[0].addressable && isDeepStrictEqual(retained[0].data, written)) {
+        const archive = prepareExperimentArchive(req.projectRoot, objectivePath, objectiveId, number, written);
+        const archiveExists = fs.existsSync(archive.target);
+        let archiveReplay = archiveExists;
+        if (archiveExists) {
+            assertExperimentArchiveReplay(archive);
+        }
+        else if (!req.dryRun) {
+            const published = transaction?.publishExperimentArchive(archive, () => assertExperimentArchiveReplay(archive));
+            if (published === undefined)
+                throw new Error("state mutation transaction is unavailable");
+            archiveReplay = !published;
+        }
+        const preview = req.dryRun ? { diff: "", before: existing.doc, after: existing.doc } : undefined;
+        return envelope(req, target, existing.doc, written, assigned, true, null, { ...archive, replay: archiveReplay }, preview);
+    }
+    try {
+        validateExperimentPublicationIdentity(discovery, projection, objectiveId, number);
+    }
+    catch (error) {
+        if (error instanceof ExperimentIdentityError)
+            rejectIdentity(error);
+        throw error;
+    }
+    const inputViolations = validateArtifactBytes("experiments", dumpYamlMapping({ experiments: [written] }));
+    if (inputViolations.length)
+        schemaViolation(inputViolations);
+    const candidate = structuredClone(existing.doc);
+    candidate.experiments = [...array(candidate, "experiments"), written];
+    const candidateBytes = dumpYamlMapping(candidate);
+    const candidateViolations = validateArtifactBytes("experiments", candidateBytes);
+    if (candidateViolations.length)
+        schemaViolation(candidateViolations);
+    const archive = prepareExperimentArchive(req.projectRoot, objectivePath, objectiveId, number, written);
+    const stage = req.dryRun
+        ? path.join(path.dirname(target), `.${path.basename(target)}.writer.${process.pid}.${Date.now()}.tmp`)
+        : transaction?.stageProjection(target, candidateBytes);
+    if (!stage)
+        throw new Error("state mutation transaction is unavailable");
+    let compaction = null;
+    try {
+        if (req.dryRun)
+            fs.writeFileSync(stage, candidateBytes);
+        if (req.spec.compacts)
+            compaction = compactYamlFile(stage, "experiments", req.projectRoot);
+        const finalBytes = fs.readFileSync(stage, "utf8");
+        const finalViolations = validateArtifactBytes("experiments", finalBytes);
+        if (finalViolations.length)
+            throw new Error(`writer/compactor invariant failure: ${finalViolations.join("; ")}`);
+        const finalDoc = loadYamlMapping(finalBytes);
+        const preview = req.dryRun
+            ? { diff: diffText(existing.bytes, finalBytes, target), before: existing.doc, after: finalDoc }
+            : undefined;
+        if (!req.dryRun) {
+            transaction?.syncStaged(stage);
+            const published = transaction?.publishExperimentArchive(archive, () => assertExperimentArchiveReplay(archive));
+            if (published === undefined)
+                throw new Error("state mutation transaction is unavailable");
+            transaction?.publishProjection(stage, target, existing.bytes);
+            return envelope(req, target, finalDoc, written, assigned, false, compaction, { ...archive, replay: !published }, preview);
+        }
+        return envelope(req, target, finalDoc, written, assigned, false, compaction, { ...archive, replay: false }, preview);
+    }
+    finally {
+        try {
+            if (req.dryRun)
+                fs.unlinkSync(stage);
+            else
+                transaction?.removeStage(stage);
+        }
+        catch {
+            /* stage published or absent */
+        }
+    }
+}
+//# sourceMappingURL=experimentPublication.js.map

package/dist/state/write/experimentPublication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experimentPublication.js","sourceRoot":"","sources":["../../../src/state/write/experimentPublication.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,eAAe,EAAsB,MAAM,iCAAiC,CAAC;AACtF,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,GAEzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC3B,qCAAqC,GACtC,MAAM,0BAA0B,CAAC;AAIlC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,SAAS,KAAK,CAAC,GAA4B,EAAE,GAAW;IACtD,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC,CAAE,GAAG,CAAC,GAAG,CAAe,CAAC,MAAM,CAAC,CAAC,KAAK,EAAoC,EAAE,CACzE,OAAO,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QACzE,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAED,SAAS,YAAY,CAAC,MAAc;IAClC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAC1D,MAAM,KAAK,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,IAAI,CAAC;QACH,OAAO,EAAE,GAAG,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;IAChD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,mCAAmC,MAAM,MAAO,KAAe,CAAC,OAAO,wDAAwD,CAChI,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,MAAc,EAAE,KAAa,EAAE,MAAc;IAC7D,OAAO,WAAW,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACrG,CAAC;AAED,SAAS,cAAc,CAAC,KAA8B;IACpD,MAAM,CAAC;QACL,KAAK,EAAE,KAAK,CAAC,SAAS,KAAK,iBAAiB;YAC1C,CAAC,CAAC,iBAAiB;YACnB,CAAC,CAAC,KAAK,CAAC,SAAS,KAAK,WAAW;gBAC/B,CAAC,CAAC,oBAAoB;gBACtB,CAAC,CAAC,UAAU;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM,EAAE,8GAA8G;QACtH,OAAO,EAAE,gJAAgJ;QACzJ,QAAQ,EAAE,+EAA+E;KAC1F,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CACf,GAAsB,EACtB,MAAc,EACd,GAA4B,EAC5B,OAAgC,EAChC,QAAiC,EACjC,MAAe,EACf,UAAgC,EAChC,OAA4D,EAC5D,OAA2F;IAE3F,OAAO;QACL,aAAa,EAAE,wBAAwB;QACvC,OAAO,EAAE,2BAA2B;QACpC,MAAM,EAAE,MAAM;QACd,QAAQ,EAAE,aAAa;QACvB,IAAI,EAAE,MAAM;QACZ,SAAS,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE;QAC7F,QAAQ;QACR,OAAO;QACP,KAAK,EAAE;YACL,YAAY,EAAE,KAAK,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,MAAM;YAC9C,aAAa,EAAE,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,MAAM;SAC5C;QACD,UAAU,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE;QAC9C,UAAU;QACV,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YACZ,OAAO,EAAE;gBACP,IAAI,EAAE,OAAO,CAAC,MAAM;gBACpB,SAAS,EAAE,OAAO,CAAC,QAAQ;gBAC3B,aAAa,EAAE,OAAO,CAAC,YAAY;gBACnC,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,iBAAiB,EAAE,OAAO,CAAC,MAAM;aAClC;SACF,CAAC,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;KACnB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC1C,GAAsB,EACtB,WAAsC;IAEtC,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC/C,IAAI,QAAQ,IAAI,KAAK;QACnB,MAAM,CAAC;YACL,KAAK,EAAE,kBAAkB;YACzB,OAAO,EAAE,6EAA6E;YACtF,UAAU,EAAE,CAAC,yBAAyB,CAAC;SACxC,CAAC,CAAC;IAEL,MAAM,SAAS,GAAG,0BAA0B,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,KAAK,WAAW,CAAC,CAAC;IAC/F,IAAI,CAAC;QACH,qCAAqC,CAAC,SAAS,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IACnH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,uBAAuB;YAAE,cAAc,CAAC,KAAK,CAAC,CAAC;QACpE,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,cAAc,GAAG,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAC3D,SAAS,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,GAAG,YAAY,IAAI,CAAC,GAAG,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAClF,MAAM,aAAa,GAAG,SAAS,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC;QACjD,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACpB,CAAC,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC;YAC3B,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC;YACnB,CAAC,CAAC,IAAI,CAAC;IACX,IAAI,CAAC,aAAa;QAChB,MAAM,CAAC;YACL,KAAK,EAAE,UAAU;YACjB,OAAO,EAAE,sBAAsB,WAAW,qEAAqE;YAC/G,QAAQ,EAAE,yCAAyC,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,eAAe,oCAAoC;SAC9I,CAAC,CAAC;IACL,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,kBAAkB,CAAC,CAAC;IAC1E,sBAAsB,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,UAAU,GAAG,qBAAqB,CAAC,aAAa,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;QACxE,IAAI,UAAU,CAAC,MAAM;YACnB,MAAM,IAAI,KAAK,CAAC,sBAAsB,MAAM,wBAAwB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;IAC5H,CAAC;IAED,MAAM,UAAU,GAAG,2BAA2B,CAAC,WAAW,EAAE,QAAQ,CAAC,GAAiB,CAAC,CAAC;IACxF,MAAM,OAAO,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAG,GAAG,WAAW,eAAe,MAAM,EAAE,CAAC;IACvD,MAAM,QAAQ,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;IACzE,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;IACnF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,WAAW,IAAI,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;QACrG,MAAM,OAAO,GAAG,wBAAwB,CACtC,GAAG,CAAC,WAAW,EACf,aAAa,EACb,WAAW,EACX,MAAM,EACN,OAAqB,CACtB,CAAC;QACF,MAAM,aAAa,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACpD,IAAI,aAAa,GAAG,aAAa,CAAC;QAClC,IAAI,aAAa,EAAE,CAAC;YAClB,6BAA6B,CAAC,OAAO,CAAC,CAAC;QACzC,CAAC;aAAM,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;YACvB,MAAM,SAAS,GAAG,WAAW,EAAE,wBAAwB,CACrD,OAAO,EACP,GAAG,EAAE,CAAC,6BAA6B,CAAC,OAAO,CAAC,CAC7C,CAAC;YACF,IAAI,SAAS,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;YAC1F,aAAa,GAAG,CAAC,SAAS,CAAC;QAC7B,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACjG,OAAO,QAAQ,CACb,GAAG,EACH,MAAM,EACN,QAAQ,CAAC,GAAG,EACZ,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,EACrC,OAAO,CACR,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,qCAAqC,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IACpF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,uBAAuB;YAAE,cAAc,CAAC,KAAK,CAAC,CAAC;QACpE,MAAM,KAAK,CAAC;IACd,CAAC;IAED,MAAM,eAAe,GAAG,qBAAqB,CAAC,aAAa,EAAE,eAAe,CAAC,EAAE,WAAW,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1G,IAAI,eAAe,CAAC,MAAM;QAAE,eAAe,CAAC,eAAe,CAAC,CAAC;IAC7D,MAAM,SAAS,GAAG,eAAe,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAChD,SAAS,CAAC,WAAW,GAAG,CAAC,GAAG,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC,EAAE,OAAO,CAAC,CAAC;IACtE,MAAM,cAAc,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IAClD,MAAM,mBAAmB,GAAG,qBAAqB,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IACjF,IAAI,mBAAmB,CAAC,MAAM;QAAE,eAAe,CAAC,mBAAmB,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,wBAAwB,CACtC,GAAG,CAAC,WAAW,EACf,aAAa,EACb,WAAW,EACX,MAAM,EACN,OAAqB,CACtB,CAAC;IAEF,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM;QACtB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC;QACtG,CAAC,CAAC,WAAW,EAAE,eAAe,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACzD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IACzE,IAAI,UAAU,GAAyB,IAAI,CAAC;IAC5C,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,MAAM;YAAE,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;QACxD,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ;YAAE,UAAU,GAAG,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;QAC3F,MAAM,UAAU,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAClD,MAAM,eAAe,GAAG,qBAAqB,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;QACzE,IAAI,eAAe,CAAC,MAAM;YACxB,MAAM,IAAI,KAAK,CAAC,uCAAuC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvF,MAAM,QAAQ,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM;YACxB,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE;YAC/F,CAAC,CAAC,SAAS,CAAC;QACd,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;YAChB,WAAW,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;YAC/B,MAAM,SAAS,GAAG,WAAW,EAAE,wBAAwB,CACrD,OAAO,EACP,GAAG,EAAE,CAAC,6BAA6B,CAAC,OAAO,CAAC,CAC7C,CAAC;YACF,IAAI,SAAS,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;YAC1F,WAAW,EAAE,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC9D,OAAO,QAAQ,CACb,GAAG,EACH,MAAM,EACN,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,KAAK,EACL,UAAU,EACV,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,CAAC,SAAS,EAAE,EAClC,OAAO,CACR,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CACb,GAAG,EACH,MAAM,EACN,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,KAAK,EACL,UAAU,EACV,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,EAC7B,OAAO,CACR,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,MAAM;gBAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;;gBAChC,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;QACjC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/state/write/explain.js

@@ -13,7 +13,7 @@ function liveDoc(p) {
     return loadYamlMapping(fs.readFileSync(p, "utf8"));
 }
 function defaultVerb(artifact) {
-    return artifact === "plan" ? "append" : "append";
+    return artifact === "experiments" ? "publish" : "append";
 }
 export function buildExplain(artifact, projectRoot, requestedVerb) {
     const verb = (requestedVerb ?? defaultVerb(artifact));
@@ -28,13 +28,17 @@ export function buildExplain(artifact, projectRoot, requestedVerb) {
     const record = loadArtifactRegistry().get(artifact);
     if (!record)
         reject({ class: "unsupported_target", message: `artifact "${artifact}" is not registered` });
-    const resolved = resolveArtifactPath(record, projectRoot, { strictWrite: true });
-    const doc = liveDoc(resolved);
-    const next = artifact === "plan"
-        ? { task_number: nextTaskNumber(doc) }
-        : {
-            number: nextEntryNumber(doc, artifact === "progress" ? "cycles" : artifact === "decisions" ? "decisions" : "audits"),
-        };
+    const resolved = artifact === "experiments"
+        ? path.join(projectRoot, ".agentera", "optimize", "<objective>", "experiments.yaml")
+        : resolveArtifactPath(record, projectRoot, { strictWrite: true });
+    const doc = artifact === "experiments" ? {} : liveDoc(resolved);
+    const next = artifact === "experiments"
+        ? {}
+        : artifact === "plan"
+            ? { task_number: nextTaskNumber(doc) }
+            : {
+                number: nextEntryNumber(doc, artifact === "progress" ? "cycles" : artifact === "decisions" ? "decisions" : "audits"),
+            };
     const validator = new ArtifactSchemaValidator();
     const fields = projectedFields(spec, validator).map((field) => ({
         flag: field.flag,
@@ -61,11 +65,11 @@ export function buildExplain(artifact, projectRoot, requestedVerb) {
         fields,
     };
     if (spec.compacts) {
-        result.compaction =
-            "uniform_10_40_50 (10 full, 40 archive, drop beyond 50); runs automatically on append";
+        result.compaction = artifact === "experiments"
+            ? "uniform_10_40_50 (10 active full-detail and 40 one-line archive entries); runs automatically on publication; durable archival is deferred"
+            : "uniform_10_40_50 (bounded active/archive projections: 10 active full-detail and 40 archive entries; verified numbered archives remain authoritative; no destructive deletion; recovery refuses to omit entries when archive evidence is missing); runs automatically on append";
     }
     if (spec.inputRoot) {
-        result.fields = [];
         result.input_schema = {
             flag: "--input",
             sources: ["file path", "- (stdin)"],
@@ -76,7 +80,9 @@ export function buildExplain(artifact, projectRoot, requestedVerb) {
             defaulted_fields: artifact === "health" ? { date: "today" } : {},
             groups: artifact === "health"
                 ? ["AUDIT", "DIMENSION", "FINDING", "TRENDS"]
-                : ["HEADER", "PLAN", "SCOPE", "TASK"],
+                : artifact === "experiments"
+                    ? ["EXPERIMENT"]
+                    : ["HEADER", "PLAN", "SCOPE", "TASK"],
         };
     }
     result.guidance = [
@@ -84,7 +90,11 @@ export function buildExplain(artifact, projectRoot, requestedVerb) {
             ? "supply sequential task numbers and valid dependencies; previous_plan_archived is assigned by the CLI"
             : artifact === "plan"
                 ? "task numbers are assigned by the CLI for append"
-                : "number is assigned by the CLI; do not pass --number",
+                : artifact === "health" && verb === "repair"
+                    ? "repair is a destructive projection edit; select an existing duplicate audit and pass --force"
+                    : artifact === "experiments"
+                        ? "pass the intended non-negative --number; the CLI validates and assigns it to the entry"
+                        : "number is assigned by the CLI; do not pass --number",
         "do not embed commit hashes; evidence belongs in the commit message (Decision 66)",
         "fold the artifact write into the implementation commit per AGENTS.md",
     ];
@@ -98,6 +108,8 @@ export function exampleFor(artifact, verb) {
         return 'agentera state decisions update --number 1 --satisfaction-state provisionally_satisfied --satisfaction-evidence "..."';
     if (artifact === "decisions")
         return 'agentera state decisions append --question "..." --context "..." --alternative-chosen "..." --choice "..." --reasoning "..." --confidence firm';
+    if (artifact === "health" && verb === "repair")
+        return "agentera state health repair --number 14 --keep first --force --format json";
     if (artifact === "health")
         return "agentera state health append --input audit.yaml --format json";
     if (verb === "create")
@@ -112,6 +124,8 @@ export function exampleFor(artifact, verb) {
         return "agentera state plan set-plan-status --status complete --format json";
     if (verb === "record-evaluation")
         return 'agentera state plan record-evaluation --task 1 --attempt-id audit-1 --verdict pass --provenance "audit report" --format json';
+    if (verb === "publish")
+        return "agentera state experiments publish --objective OBJECTIVE_ID --number 0 --input experiment.yaml --format json";
     return `agentera state plan ${verb} --name "..."`;
 }
 export function renderExplainText(explain) {
@@ -141,7 +155,7 @@ export function renderExplainText(explain) {
             }
         }
     }
-    else if (explain.input_schema) {
+    if (explain.input_schema) {
         lines.push("", "Required:", "  --input PATH             YAML/JSON document; use - for stdin");
     }
     if (explain.compaction)

package/dist/state/write/explain.js.map

@@ -1 +1 @@
-{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/state/write/explain.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,aAAa,EACb,gBAAgB,GAGjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,SAAS,OAAO,CAAC,CAAS;IACxB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,OAAO,eAAe,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,WAAW,CAAC,QAA0B;IAC7C,OAAO,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,QAA0B,EAC1B,WAAmB,EACnB,aAA6B;IAE7B,MAAM,IAAI,GAAG,CAAC,aAAa,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAkC,CAAC;IACvF,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,CAAC;YACL,KAAK,EAAE,gBAAgB;YACvB,OAAO,EAAE,SAAS,IAAI,uBAAuB,QAAQ,EAAE;YACvD,YAAY,EAAE,gBAAgB,CAAC,QAAQ,CAAC;SACzC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,MAAM,GAAG,oBAAoB,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM;QACT,MAAM,CAAC,EAAE,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,aAAa,QAAQ,qBAAqB,EAAE,CAAC,CAAC;IAC/F,MAAM,QAAQ,GAAG,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;IACjF,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9B,MAAM,IAAI,GACR,QAAQ,KAAK,MAAM;QACjB,CAAC,CAAC,EAAE,WAAW,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE;QACtC,CAAC,CAAC;YACE,MAAM,EAAE,eAAe,CACrB,GAAG,EACH,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CACvF;SACF,CAAC;IACR,MAAM,SAAS,GAAG,IAAI,uBAAuB,EAAE,CAAC;IAChD,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC9D,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;QACjC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzD,CAAC,CAAC,CAAC;IACJ,MAAM,MAAM,GAA4B;QACtC,aAAa,EAAE,+BAA+B;QAC9C,OAAO,EAAE,SAAS,QAAQ,UAAU;QACpC,cAAc,EAAE,IAAI;QACpB,QAAQ;QACR,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,QAAQ;QACtD,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC;QACjC,IAAI;QACJ,MAAM,EAAE,YAAY,CAAC,QAAQ,EAAE,SAAS,CAAC;QACzC,MAAM;KACP,CAAC;IACF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,MAAM,CAAC,UAAU;YACf,sFAAsF,CAAC;IAC3F,CAAC;IACD,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC;QACnB,MAAM,CAAC,YAAY,GAAG;YACpB,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC;YACnC,MAAM,EAAE,MAAM;YACd,YAAY,EAAE,IAAI;YAClB,IAAI,EAAE,IAAI,CAAC,SAAS;YACpB,gBAAgB,EAAE,IAAI,CAAC,cAAc,IAAI,EAAE;YAC3C,gBAAgB,EAAE,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE;YAChE,MAAM,EACJ,QAAQ,KAAK,QAAQ;gBACnB,CAAC,CAAC,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC;gBAC7C,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC;SAC1C,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,QAAQ,GAAG;QAChB,QAAQ,KAAK,MAAM,IAAI,IAAI,KAAK,QAAQ;YACtC,CAAC,CAAC,sGAAsG;YACxG,CAAC,CAAC,QAAQ,KAAK,MAAM;gBACnB,CAAC,CAAC,iDAAiD;gBACnD,CAAC,CAAC,qDAAqD;QAC3D,kFAAkF;QAClF,sEAAsE;KACvE,CAAC;IACF,MAAM,CAAC,OAAO,GAAG,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC5C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,QAA0B,EAAE,IAAY;IACjE,IAAI,QAAQ,KAAK,UAAU;QACzB,OAAO,mGAAmG,CAAC;IAC7G,IAAI,QAAQ,KAAK,WAAW,IAAI,IAAI,KAAK,QAAQ;QAC/C,OAAO,uHAAuH,CAAC;IACjI,IAAI,QAAQ,KAAK,WAAW;QAC1B,OAAO,gJAAgJ,CAAC;IAC1J,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,+DAA+D,CAAC;IAClG,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,4DAA4D,CAAC;IAC3F,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,uCAAuC,CAAC;IACvE,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,gEAAgE,CAAC;IAC/F,IAAI,IAAI,KAAK,YAAY;QACvB,OAAO,yEAAyE,CAAC;IACnF,IAAI,IAAI,KAAK,iBAAiB;QAC5B,OAAO,qEAAqE,CAAC;IAC/E,IAAI,IAAI,KAAK,mBAAmB;QAC9B,OAAO,8HAA8H,CAAC;IACxI,OAAO,uBAAuB,IAAI,eAAe,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAgC;IAChE,MAAM,KAAK,GAAG;QACZ,yBAAyB,OAAO,CAAC,QAAQ,IAAK,OAAuC,CAAC,cAAc,IAAI,QAAQ,UAAU;QAC1H,EAAE;QACF,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,IAAI,GAAG;KACxC,CAAC;IACF,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC;QAC1C,CAAC,CAAE,OAAO,CAAC,MAAyC;QACpD,CAAC,CAAC,EAAE,CAAC;IACP,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC1D,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC3D,KAAK,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI;YAC/B,CAAC,UAAU,EAAE,QAAQ,CAAC;YACtB,CAAC,UAAU,EAAE,QAAQ,CAAC;SACd,EAAE,CAAC;YACX,IAAI,CAAC,OAAO,CAAC,MAAM;gBAAE,SAAS;YAC9B,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,OAAO,GAAG,CAAC,CAAC;YAC9B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC;oBAC9C,CAAC,CAAC,YAAa,KAAK,CAAC,YAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;oBAC3D,CAAC,CAAC,EAAE,CAAC;gBACP,KAAK,CAAC,IAAI,CACR,KAAK,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,KAAK,CAAC,EAAE,CAC1F,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;SAAM,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,EAAE,gEAAgE,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,OAAO,CAAC,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,eAAe,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC5E,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;IAC5B,KAAK,MAAM,QAAQ,IAAI,OAAO,CAAC,QAAoB;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC;IACjF,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACnD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACjC,CAAC"}
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/state/write/explain.ts"],"names":[],"mappings":"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"}

package/dist/state/write/helpers.js

@@ -0,0 +1,8 @@
+import { reject } from "./errors.js";
+export function schemaViolation(violations) {
+    reject({ class: "schema_violation", message: violations[0], violations });
+}
+export function findByNumber(entries, number) {
+    return entries.find((entry) => Number(entry.number) === number);
+}
+//# sourceMappingURL=helpers.js.map

package/dist/state/write/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/state/write/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,UAAU,eAAe,CAAC,UAAoB;IAClD,MAAM,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,OAAkC,EAClC,MAAc;IAEd,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,CAAC;AAClE,CAAC"}

package/dist/state/write/index.js

@@ -4,6 +4,7 @@ export * from "./input.js";
 export * from "./assign.js";
 export * from "./explain.js";
 export * from "./lock.js";
+export * from "./mutation.js";
 export * from "./transaction.js";
 export * from "./validate.js";
 export * from "./serialize.js";

package/dist/state/write/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/state/write/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/state/write/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/state/write/lock.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { assertRealpathBoundary } from "../../registries/artifactRegistry.js";
+import { reject } from "./errors.js";
 const sleepArray = new Int32Array(new SharedArrayBuffer(4));
 const INITIALIZATION_GRACE_MS = 250;
 function malformedLockIsStale(lockPath) {
@@ -30,6 +31,15 @@ function ownerIsDead(lockPath) {
         return malformedLockIsStale(lockPath);
     }
 }
+function syncDirectory(directory) {
+    const fd = fs.openSync(directory, "r");
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 export function acquireWriterLock(projectRoot, timeoutMs = 2000) {
     const dir = path.join(projectRoot, ".agentera");
     assertRealpathBoundary(projectRoot, dir, "writer lock");
@@ -44,8 +54,10 @@ export function acquireWriterLock(projectRoot, timeoutMs = 2000) {
             fd = fs.openSync(lockPath, "wx");
             createdLock = true;
             fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() }) + "\n");
+            fs.fsyncSync(fd);
             fs.closeSync(fd);
             fd = undefined;
+            syncDirectory(dir);
             let released = false;
             return {
                 path: lockPath,
@@ -59,6 +71,12 @@ export function acquireWriterLock(projectRoot, timeoutMs = 2000) {
                     catch {
                         /* already released */
                     }
+                    try {
+                        syncDirectory(dir);
+                    }
+                    catch {
+                        /* lock removal is already visible to this process */
+                    }
                     if (createdDir) {
                         try {
                             fs.rmdirSync(dir);
@@ -99,7 +117,12 @@ export function acquireWriterLock(projectRoot, timeoutMs = 2000) {
                 continue;
             }
             if (Date.now() >= deadline) {
-                throw new Error(`writer lock timeout at '${lockPath}'; retry the command after the active writer finishes`);
+                reject({
+                    class: "conflict",
+                    message: `writer lock timeout at '${lockPath}'; retry the command after the active writer finishes`,
+                    syntax: "agentera state <artifact-id> <verb> ... --format json",
+                    example: "retry the same command after the active writer finishes",
+                });
             }
             Atomics.wait(sleepArray, 0, 0, 25);
         }

package/dist/state/write/lock.js.map

@@ -1 +1 @@
-{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../../src/state/write/lock.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../../src/state/write/lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5D,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC,SAAS,oBAAoB,CAAC,QAAgB;IAC5C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,IAAI,uBAAuB,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,QAAgB;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAqB,CAAC;QACjF,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC;YAAE,OAAO,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QACzE,IAAI,MAAM,CAAC,GAAG,KAAK,OAAO,CAAC,GAAG;YAAE,OAAO,KAAK,CAAC;QAC7C,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAa,EAAE,CAAC,CAAC,CAAC;YACtC,OAAO,KAAK,CAAC;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAQ,KAA+B,CAAC,IAAI,KAAK,OAAO,CAAC;QAC3D,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,SAAiB;IACtC,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAOD,MAAM,UAAU,iBAAiB,CAAC,WAAmB,EAAE,SAAS,GAAG,IAAI;IACrE,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IAChD,sBAAsB,CAAC,WAAW,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC;IACxD,MAAM,UAAU,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACvC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,EAAsB,CAAC;QAC3B,IAAI,WAAW,GAAG,KAAK,CAAC;QACxB,IAAI,CAAC;YACH,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACjC,WAAW,GAAG,IAAI,CAAC;YACnB,EAAE,CAAC,aAAa,CACd,EAAE,EACF,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,GAAG,IAAI,CAClF,CAAC;YACF,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACjB,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACjB,EAAE,GAAG,SAAS,CAAC;YACf,aAAa,CAAC,GAAG,CAAC,CAAC;YACnB,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,GAAG,EAAE;oBACZ,IAAI,QAAQ;wBAAE,OAAO;oBACrB,QAAQ,GAAG,IAAI,CAAC;oBAChB,IAAI,CAAC;wBACH,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;oBAC1B,CAAC;oBAAC,MAAM,CAAC;wBACP,sBAAsB;oBACxB,CAAC;oBACD,IAAI,CAAC;wBACH,aAAa,CAAC,GAAG,CAAC,CAAC;oBACrB,CAAC;oBAAC,MAAM,CAAC;wBACP,qDAAqD;oBACvD,CAAC;oBACD,IAAI,UAAU,EAAE,CAAC;wBACf,IAAI,CAAC;4BACH,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;wBACpB,CAAC;wBAAC,MAAM,CAAC;4BACP,yDAAyD;wBAC3D,CAAC;oBACH,CAAC;gBACH,CAAC;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;gBACrB,IAAI,CAAC;oBACH,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;gBACnB,CAAC;gBAAC,MAAM,CAAC;oBACP,gCAAgC;gBAClC,CAAC;YACH,CAAC;YACD,IAAI,WAAW,EAAE,CAAC;gBAChB,IAAI,CAAC;oBACH,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;gBAC1B,CAAC;gBAAC,MAAM,CAAC;oBACP,gCAAgC;gBAClC,CAAC;YACH,CAAC;YACD,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,KAAK,CAAC;YACpE,IAAI,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC1B,IAAI,CAAC;oBACH,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;gBAC1B,CAAC;gBAAC,MAAM,CAAC;oBACP,+BAA+B;gBACjC,CAAC;gBACD,SAAS;YACX,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC3B,MAAM,CAAC;oBACL,KAAK,EAAE,UAAU;oBACjB,OAAO,EAAE,2BAA2B,QAAQ,uDAAuD;oBACnG,MAAM,EAAE,uDAAuD;oBAC/D,OAAO,EAAE,yDAAyD;iBACnE,CAAC,CAAC;YACL,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/state/write/mutation.js

@@ -0,0 +1,190 @@
+import fs from "node:fs";
+import path from "node:path";
+import { publishImmutableFile, publishNumberedArchive, } from "../archivePublication.js";
+import { acquireWriterLock } from "./lock.js";
+export const MUTATION_FAILURE_BOUNDARIES = [
+    "staged-write",
+    "archive-directory-publication",
+    "archive-publication",
+    "backup-publication",
+    "projection-publication",
+    "directory-sync",
+];
+export class InjectedMutationFailure extends Error {
+    boundary;
+    constructor(boundary) {
+        super(`injected state mutation failure after ${boundary}`);
+        this.name = "InjectedMutationFailure";
+        this.boundary = boundary;
+    }
+}
+let stageSequence = 0;
+function fsyncDirectory(directory) {
+    const fd = fs.openSync(directory, "r");
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function stagePath(target) {
+    stageSequence += 1;
+    return path.join(path.dirname(target), `.${path.basename(target)}.writer.${process.pid}.${stageSequence}.tmp`);
+}
+function isMutationStage(name) {
+    return /\.writer\.\d+\.\d+\.tmp$/.test(name);
+}
+function removeStaleStages(directory) {
+    if (!fs.existsSync(directory))
+        return;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const candidate = path.join(directory, entry.name);
+        if (entry.isDirectory() && !entry.isSymbolicLink()) {
+            removeStaleStages(candidate);
+            continue;
+        }
+        if (!entry.isFile() || !isMutationStage(entry.name))
+            continue;
+        try {
+            fs.unlinkSync(candidate);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+export class StateMutationTransaction {
+    projectRoot;
+    options;
+    stages = new Set();
+    failureInjected = false;
+    constructor(projectRoot, options = {}) {
+        this.projectRoot = projectRoot;
+        this.options = options;
+    }
+    stageProjection(target, bytes) {
+        const directory = path.dirname(target);
+        fs.mkdirSync(directory, { recursive: true });
+        removeStaleStages(directory);
+        const stage = stagePath(target);
+        let fd;
+        try {
+            fd = fs.openSync(stage, "wx");
+            fs.writeFileSync(fd, bytes, "utf8");
+            fs.fsyncSync(fd);
+            fs.closeSync(fd);
+            fd = undefined;
+            this.stages.add(stage);
+            return stage;
+        }
+        finally {
+            if (fd !== undefined)
+                fs.closeSync(fd);
+            if (!this.stages.has(stage)) {
+                try {
+                    fs.unlinkSync(stage);
+                }
+                catch {
+                    /* stage was never created or cleanup is already complete */
+                }
+            }
+        }
+    }
+    syncStaged(stage) {
+        const fd = fs.openSync(stage, "r");
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        this.failAfter("staged-write");
+    }
+    publishArchive(artifact, entryNumber, record) {
+        const archive = publishNumberedArchive(this.projectRoot, artifact, entryNumber, record, {
+            afterDirectorySync: () => this.failAfter("directory-sync"),
+        });
+        this.failAfter("archive-publication");
+        return archive;
+    }
+    publishExperimentArchive(publication, onExisting) {
+        const published = publishImmutableFile(publication.target, publication.bytes, {
+            directoryDurabilityRoot: publication.directoryDurabilityRoot,
+            onExisting,
+            afterDirectoryEntrySync: () => this.failAfter("archive-directory-publication"),
+            afterDirectorySync: () => this.failAfter("directory-sync"),
+        });
+        this.failAfter("archive-publication");
+        return published;
+    }
+    publishBackup(target, bytes, onExisting) {
+        const published = publishImmutableFile(target, bytes, {
+            onExisting,
+            afterDirectorySync: () => this.failAfter("directory-sync"),
+        });
+        this.failAfter("backup-publication");
+        return published;
+    }
+    publishProjection(stage, target, expectedBytes) {
+        if (expectedBytes !== undefined) {
+            const currentBytes = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+            if (currentBytes !== expectedBytes) {
+                throw new Error(`projection target '${target}' changed before publication; existing bytes were preserved`);
+            }
+        }
+        fs.renameSync(stage, target);
+        this.stages.delete(stage);
+        this.failAfter("projection-publication");
+        fsyncDirectory(path.dirname(target));
+        this.failAfter("directory-sync");
+    }
+    mutateProjection(target, mutation) {
+        const stage = this.stageProjection(target, fs.readFileSync(target, "utf8"));
+        try {
+            const result = mutation(stage);
+            if (result.changed) {
+                this.syncStaged(stage);
+                this.publishProjection(stage, target);
+            }
+            return result;
+        }
+        finally {
+            this.removeStage(stage);
+        }
+    }
+    removeStage(stage) {
+        this.stages.delete(stage);
+        try {
+            fs.unlinkSync(stage);
+        }
+        catch {
+            /* published or already removed */
+        }
+    }
+    cleanup() {
+        for (const stage of this.stages)
+            this.removeStage(stage);
+        this.stages.clear();
+    }
+    failAfter(boundary) {
+        if (this.failureInjected || this.options.failAfter !== boundary)
+            return;
+        this.failureInjected = true;
+        throw new InjectedMutationFailure(boundary);
+    }
+}
+export function withStateMutation(projectRoot, operation, options = {}) {
+    const lock = acquireWriterLock(projectRoot, options.lockTimeoutMs);
+    const transaction = new StateMutationTransaction(projectRoot, options);
+    try {
+        removeStaleStages(path.join(projectRoot, ".agentera"));
+        return operation(transaction);
+    }
+    finally {
+        transaction.cleanup();
+        lock.release();
+    }
+}
+//# sourceMappingURL=mutation.js.map