agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/state/write/mutation.js

@@ -0,0 +1,234 @@
+import fs from "node:fs";
+import path from "node:path";
+import { publishImmutableFile, publishNumberedArchive, } from "../archivePublication.js";
+import { assertValidatedProjectRoot } from "../projectRoot.js";
+import { acquireWriterLock } from "./lock.js";
+export const MUTATION_FAILURE_BOUNDARIES = [
+    "staged-write",
+    "archive-directory-publication",
+    "archive-publication",
+    "backup-publication",
+    "revision-publication",
+    "projection-consistency",
+    "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;
+    }
+    /**
+     * Atomically stage, fsync, and rename a decision revision document. The
+     * revision document is keyed-by-stable-id immutable evidence: a publication
+     * renames a fully-staged replacement into place, then fsyncs the directory.
+     * `expectedBytes` (the bytes read before staging) guards against a concurrent
+     * change to the revision document between preparation and publication.
+     *
+     * Boundaries (in order): `staged-write`, `revision-publication`,
+     * `directory-sync`. A `projection-consistency` checkpoint follows in the
+     * amendment handler, after the immutable evidence is durable.
+     */
+    publishRevisionDocument(target, bytes, expectedBytes) {
+        const stage = this.stageProjection(target, bytes);
+        try {
+            this.syncStaged(stage);
+            if (expectedBytes !== undefined) {
+                const currentBytes = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+                if (currentBytes !== expectedBytes) {
+                    throw new Error(`revision document '${target}' changed before publication; existing bytes were preserved`);
+                }
+            }
+            fs.renameSync(stage, target);
+            this.stages.delete(stage);
+            this.failAfter("revision-publication");
+            fsyncDirectory(path.dirname(target));
+            this.failAfter("directory-sync");
+        }
+        finally {
+            this.removeStage(stage);
+        }
+    }
+    /**
+     * A read-only recovery checkpoint. The amendment handler verifies the
+     * decisions projection base still agrees with the published revision's
+     * `base_sha256`, then marks the checkpoint so a recovery test can inject a
+     * failure after verification but before the operation returns success.
+     */
+    revisionConsistencyCheckpoint() {
+        this.failAfter("projection-consistency");
+    }
+    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 = {}, validatedRoot) {
+    const lock = acquireWriterLock(projectRoot, options.lockTimeoutMs, validatedRoot);
+    const transaction = new StateMutationTransaction(projectRoot, options);
+    try {
+        if (validatedRoot)
+            assertValidatedProjectRoot(validatedRoot);
+        removeStaleStages(path.join(projectRoot, ".agentera"));
+        return operation(transaction);
+    }
+    finally {
+        transaction.cleanup();
+        lock.release();
+    }
+}

package/dist/state/write/operations.js

@@ -0,0 +1,169 @@
+import crypto from "node:crypto";
+import { canonicalJson, loadMutationGrammar, } from "./grammar.js";
+import { RUNTIME_WRITABLE_ARTIFACTS, RUNTIME_WRITE_VERBS, runtimeOperationSpec, runtimeOperationSpecs, } from "./runtimeOperations.js";
+import { structuredInputDescriptor, structuredInputSchemaProjection } from "./input.js";
+export const WRITABLE_ARTIFACTS = RUNTIME_WRITABLE_ARTIFACTS;
+export const WRITE_VERBS = RUNTIME_WRITE_VERBS;
+let runtimeCache;
+function codeOwnedSpecs() {
+    if (!runtimeCache)
+        runtimeCache = runtimeOperationSpecs();
+    return runtimeCache;
+}
+/**
+ * Runtime behavior is deliberately code-owned. The authority is loaded only
+ * to prove that its discovery projection still describes these executable
+ * operations; it never supplies parser fields or accepted verbs.
+ */
+export function assertMutationGrammarParity() {
+    loadMutationGrammar();
+}
+export function operationSpec(artifact, verb) {
+    const spec = runtimeOperationSpec(artifact, verb);
+    return spec ? { ...spec, fields: spec.fields.map((field) => ({ ...field })) } : null;
+}
+export function verbsForArtifact(artifact) {
+    if (!isWritableArtifact(artifact))
+        return [];
+    return [...codeOwnedSpecs().filter((spec) => spec.artifact === artifact).map((spec) => spec.verb), "explain"];
+}
+export function isWriteVerb(value) {
+    return Boolean(value && WRITE_VERBS.includes(value));
+}
+export function isWritableArtifact(value) {
+    return WRITABLE_ARTIFACTS.includes(value);
+}
+export function writerOwnedFields(artifact) {
+    return [...new Set(codeOwnedSpecs().filter((spec) => spec.artifact === artifact).flatMap((spec) => spec.ownedFields))];
+}
+function declarationFor(grammar, artifact, verb) {
+    const declaration = grammar.operations.find((operation) => operation.artifact === artifact && operation.verb === verb);
+    if (!declaration)
+        throw new Error(`mutation grammar is missing code-owned operation '${artifact}.${verb}'`);
+    return declaration;
+}
+function operationProjection(operation) {
+    const structured = structuredInputDescriptor(operation.artifact, operation.verb);
+    return {
+        verb: operation.verb,
+        class: operation.mutationClass,
+        selectors: operation.selectors,
+        preconditions: operation.preconditions,
+        owned_fields: operation.ownedFields,
+        input: {
+            mode: operation.input.mode,
+            ...(operation.input.root ? { root: operation.input.root } : {}),
+            sources: operation.input.sources,
+            structured_sources: operation.input.structuredSources ?? [],
+            cli_owned_fields: operation.input.cliOwnedFields,
+            ...(structured ? { schema: structuredInputSchemaProjection(structured) } : {}),
+        },
+        recovery: operation.recovery,
+        examples: operation.examples,
+        bounds: operation.bounds,
+        fields: operation.fields.map((field) => ({
+            flag: field.flag,
+            field: field.field,
+            kind: field.kind,
+            required: field.required === true,
+            ...(field.repeatable ? { repeatable: true } : {}),
+            ...(field.validValues ? { valid_values: field.validValues } : {}),
+            ...(field.validValuesSource ? { valid_values_source: field.validValuesSource } : {}),
+            ...(field.description ? { description: field.description } : {}),
+        })),
+        allow_force: operation.allowForce,
+        compacts: operation.compacts,
+    };
+}
+export function mutationParityMatrix(targets = WRITABLE_ARTIFACTS) {
+    const selected = new Set(targets);
+    const grammar = loadMutationGrammar();
+    const rows = codeOwnedSpecs()
+        .filter((spec) => selected.has(spec.artifact))
+        .map((spec) => {
+        const declaration = declarationFor(grammar, spec.artifact, spec.verb);
+        const operationDigest = cryptoDigest(canonicalJson(operationProjection(declaration)));
+        return {
+            artifact: spec.artifact,
+            verb: spec.verb,
+            class: declaration.mutationClass,
+            contract_digest: grammar.contractDigest,
+            operation_digest: operationDigest,
+            surfaces: {
+                authority: `references/artifacts/state-storage-authority.yaml#mutation_grammar.${spec.artifact}.${spec.verb}`,
+                runtime: `agentera state ${spec.artifact} ${spec.verb}`,
+                explain: `agentera state ${spec.artifact} explain --verb ${spec.verb} --format json`,
+                schema: "agentera schema --format json",
+                help: `agentera state ${spec.artifact} --help`,
+            },
+            success: { command: declaration.examples[0], expected: "pass", evidence: "class-level runtime regression" },
+            rejection: { command: `${declaration.examples[0]} --retired-content-flag`, expected: "fail", before_effects: true, evidence: "generic parser rejection regression" },
+            compare: ["authority", "runtime", "explain", "schema", "help"],
+        };
+    });
+    return {
+        schemaVersion: "agentera.stateMutationParity.v1",
+        contract_digest: grammar.contractDigest,
+        rows,
+        counts: {
+            operations: rows.length,
+            classes: Object.fromEntries(["record_payload", "simple_transition", "batch_transaction"].map((kind) => [kind, rows.filter((row) => row.class === kind).length])),
+        },
+    };
+}
+function cryptoDigest(value) {
+    // Kept local to make the parity projection independent from authority bytes.
+    return createSha256(value);
+}
+function createSha256(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}
+export function stateWriterArtifactContract(artifact, mode = "full") {
+    if (!isWritableArtifact(artifact))
+        return null;
+    const grammar = loadMutationGrammar();
+    const specs = codeOwnedSpecs().filter((spec) => spec.artifact === artifact);
+    const mutations = specs.map((spec) => spec.verb);
+    const result = {
+        artifact,
+        contract_digest: grammar.contractDigest,
+        mutations,
+        operation_count: specs.length,
+        explain_command: `agentera state ${artifact} explain --format json`,
+        explain_all_command: `agentera state ${artifact} explain --all --format json`,
+        explain_by_verb: Object.fromEntries(mutations.map((verb) => [verb, `agentera state ${artifact} explain --verb ${verb} --format json`])),
+        ...(writerOwnedFields(artifact).length ? { writer_owned_fields: writerOwnedFields(artifact) } : {}),
+    };
+    if (mode === "full") {
+        result.operations = specs.map((spec) => operationProjection(declarationFor(grammar, artifact, spec.verb)));
+        result.parity_matrix = mutationParityMatrix([artifact]);
+    }
+    return result;
+}
+export function stateWriterContract(targets = WRITABLE_ARTIFACTS, mode = "full") {
+    const uniqueTargets = [...new Set(targets)];
+    const artifacts = uniqueTargets.map((target) => stateWriterArtifactContract(target, mode)).filter((entry) => entry !== null);
+    const grammar = loadMutationGrammar();
+    const fullParity = mutationParityMatrix(uniqueTargets);
+    const parity = mode === "full"
+        ? fullParity
+        : {
+            schemaVersion: fullParity.schemaVersion,
+            contract_digest: fullParity.contract_digest,
+            counts: fullParity.counts,
+            row_count: fullParity.rows.length,
+            detail: "agentera state <artifact> explain --all --format json",
+        };
+    return {
+        schemaVersion: "agentera.stateWriterDiscovery.v1",
+        namespace: "agentera state",
+        authority: grammar.authority,
+        contract_digest: grammar.contractDigest,
+        policy: "Use the state writer for supported artifact mutations; do not hand-edit those artifacts during normal capability execution.",
+        discovery_command: "agentera schema --format json",
+        mutation_grammar: `agentera state <artifact> explain --all --format json`,
+        artifacts,
+        parity_matrix: parity,
+        unsupported_targets: uniqueTargets.filter((target) => stateWriterArtifactContract(target, mode) === null),
+    };
+}

package/dist/state/write/planEvaluation.js

@@ -0,0 +1,128 @@
+import { localTimestamp } from "./assign.js";
+import { reject } from "./errors.js";
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function mutatePlanTaskEvaluation(task, inputValue, taskLabel, allowCompletedReplacementRecovery = false) {
+    const input = mapping(inputValue);
+    const attemptId = String(input.attempt_id ?? "").trim();
+    const verdict = String(input.verdict ?? "");
+    const provenance = String(input.provenance ?? "").trim();
+    const failureEvidence = String(input.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(task.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 { replay: true, attemptCount: Number(prior.attempt_count ?? 0), failureCount: Number(prior.failure_count ?? 0) };
+    }
+    const completedReplacementRecovery = allowCompletedReplacementRecovery
+        && task.status === "complete"
+        && task.evaluation === undefined
+        && verdict === "pass";
+    if (["complete", "blocked", "superseded"].includes(String(task.status ?? "")) && !completedReplacementRecovery)
+        reject({ class: "conflict", message: `${taskLabel} is ${task.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: `${taskLabel} has malformed evaluation state` });
+    if (verdict === "fail" && failureCount >= 2)
+        reject({ class: "conflict", message: `${taskLabel} has exhausted its evaluation retry budget` });
+    const nextFailureCount = failureCount + (verdict === "fail" ? 1 : 0);
+    task.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)
+        task.status = "blocked";
+    return { replay: false, attemptCount: attemptCount + 1, failureCount: nextFailureCount };
+}
+export function planEvaluationMetadataViolations(value, prefix, taskStatus) {
+    if (value === undefined)
+        return [];
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return [`plan: '${prefix}' must be a mapping`];
+    const evaluation = value;
+    const violations = [];
+    const allowed = new Set(["attempt_count", "failure_count", "last_verdict", "last_failure_evidence", "provenance"]);
+    for (const field of Object.keys(evaluation))
+        if (!allowed.has(field))
+            violations.push(`plan: unsupported field '${prefix}.${field}'`);
+    const attemptCount = evaluation.attempt_count;
+    const failureCount = evaluation.failure_count;
+    if (!Number.isInteger(attemptCount) || Number(attemptCount) < 1)
+        violations.push(`plan: '${prefix}.attempt_count' must be a positive integer`);
+    if (!Number.isInteger(failureCount) || Number(failureCount) < 0)
+        violations.push(`plan: '${prefix}.failure_count' must be a non-negative integer`);
+    if (Number.isInteger(attemptCount) && Number.isInteger(failureCount) && Number(failureCount) > Number(attemptCount))
+        violations.push(`plan: '${prefix}.failure_count' cannot exceed attempt_count`);
+    const verdict = evaluation.last_verdict;
+    if (verdict !== "pass" && verdict !== "fail")
+        violations.push(`plan: '${prefix}.last_verdict' must be pass or fail`);
+    const evidence = evaluation.last_failure_evidence;
+    if (evidence !== null && typeof evidence !== "string")
+        violations.push(`plan: '${prefix}.last_failure_evidence' must be a string or null`);
+    if (verdict === "fail" && (typeof evidence !== "string" || !evidence.trim()))
+        violations.push(`plan: '${prefix}.last_failure_evidence' is required for a failed evaluation`);
+    const provenance = mapping(evaluation.provenance);
+    if (Object.keys(provenance).length === 0)
+        violations.push(`plan: '${prefix}.provenance' must be a mapping`);
+    else {
+        for (const field of ["attempt_id", "source", "recorded_at", "writer_command"])
+            if (typeof provenance[field] !== "string" || !String(provenance[field]).trim())
+                violations.push(`plan: '${prefix}.provenance.${field}' must be a non-empty string`);
+        if (provenance.writer_command !== "agentera state plan record-evaluation")
+            violations.push(`plan: '${prefix}.provenance.writer_command' must identify the evaluation writer`);
+    }
+    if (Number(failureCount) >= 2 && !["blocked", "superseded"].includes(String(taskStatus)))
+        violations.push(`plan: '${prefix}' with two failed evaluations requires task status blocked or superseded`);
+    return violations;
+}
+export function planTaskRecordViolations(task, prefix = "plan task") {
+    const violations = [];
+    if (typeof task.plan !== "string" || !/^[a-z]{10}$/.test(task.plan))
+        violations.push(`${prefix}: plan must be a bare ten-letter plan ID`);
+    if (typeof task.name !== "string" || !task.name.trim())
+        violations.push(`${prefix}: name must be a non-empty string`);
+    const status = String(task.status);
+    if (!["pending", "in_progress", "complete", "blocked", "superseded", "skipped"].includes(status))
+        violations.push(`${prefix}: status must be pending, in_progress, complete, blocked, superseded, or skipped`);
+    for (const field of ["depends_on", "acceptance"])
+        if (!Array.isArray(task[field]) || !task[field].every((value) => typeof value === "string"))
+            violations.push(`${prefix}: ${field} must be a string list`);
+    if (Array.isArray(task.depends_on) && task.depends_on.some((value) => typeof value !== "string" || !/^[a-z]{10}$/.test(value)))
+        violations.push(`${prefix}: depends_on must contain only bare ten-letter task IDs`);
+    const hasSupersession = task.superseded_by !== undefined || task.superseded_reason !== undefined;
+    if (status !== "superseded" && hasSupersession)
+        violations.push(`${prefix}: superseded_by and superseded_reason are only valid when status is superseded`);
+    if (status === "superseded") {
+        const replacements = task.superseded_by;
+        if (!Array.isArray(replacements) || replacements.length === 0 || !replacements.every((value) => typeof value === "string" && /^[a-z]{10}$/.test(value)))
+            violations.push(`${prefix}: superseded_by must be a non-empty list of bare task IDs`);
+        else if (new Set(replacements).size !== replacements.length)
+            violations.push(`${prefix}: superseded_by must not contain duplicate task IDs`);
+        const reason = task.superseded_reason;
+        if (typeof reason !== "string" || !reason.trim() || reason.length > 500)
+            violations.push(`${prefix}: superseded_reason must be a non-empty explanation of at most 500 characters`);
+    }
+    return [...violations, ...planEvaluationMetadataViolations(task.evaluation, `${prefix}.evaluation`, task.status)];
+}