agentera 3.0.0-dev.7 → 3.0.0-dev.72

package/dist/state/decisionLegacyValidation.js

@@ -0,0 +1,215 @@
+/**
+ * Task 4: enforce legacy coexistence across decision mutations.
+ *
+ * The whole-artifact validation gate validates the entire decisions artifact
+ * bytes. An untouched inherited record carrying a legacy confidence label
+ * (e.g. `high`) is unsupported by the decisions schema, so the strict gate
+ * blocked append, satisfaction update, and amend even when the operation never
+ * touched the legacy record.
+ *
+ * The authority's `compatibility.legacy_label_coexistence` rule (read through
+ * `legacyLabelCoexistence`) classifies an unsupported inherited label on a
+ * record the caller did not touch as explicit legacy state: it is preserved
+ * byte- and value-semantically, reported as a caveat, never coerced to the
+ * current vocabulary, and never blocks an operation on a different target. A
+ * confidence label supplied by append or amend is new/amended content and
+ * remains strict — it must be current vocabulary or the operation rejects
+ * before side effects.
+ *
+ * This module partitions schema violations into `blocking` (which still fail
+ * the operation) and `legacy_caveats` (untouched inherited legacy confidence
+ * labels that are preserved and reported). It never coerces a value and never
+ * broadens tolerance beyond the authority-declared confidence dimension: a
+ * missing required field, a type error, an invalid satisfaction state, or any
+ * other non-confidence violation stays blocking. (Touched confidence violations
+ * — a new/amended record whose confidence is unsupported — also stay blocking:
+ * the target/new content path remains strict.)
+ */
+import { classifyConfidenceLabel, legacyLabelCoexistence, } from "./decisionRevision.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+function isMapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+// Matches: `decisions: invalid value 'high' for 'decisions[0].confidence' (expected one of: ...)`.
+const CONFIDENCE_VIOLATION = /^decisions: invalid value '(?<value>[^']*)' for '(?<list>decisions|archive)\[(?<idx>\d+)\]\.confidence' \(expected one of:/;
+function recordAt(doc, list, idx) {
+    const arr = doc[list];
+    if (!Array.isArray(arr))
+        return {};
+    const entry = arr[idx];
+    return isMapping(entry) ? entry : {};
+}
+/**
+ * Partition decisions schema violations. Each confidence-label violation maps
+ * to the record it names; when that record was not touched by the current
+ * operation, the unsupported label is explicit legacy state (tolerated,
+ * caveated). When the record WAS touched (new or amended content), the
+ * unsupported label is rejected — target/new content must be current
+ * vocabulary. Every other violation stays blocking, so tolerance never extends
+ * beyond the authority-declared confidence dimension.
+ *
+ * `touchedNumbers` carries the decision numbers the caller touched (new or
+ * amended targets). For whole-artifact prevalidation of the existing artifact
+ * nothing is touched yet, so callers pass an empty set.
+ */
+export function partitionDecisionViolations(violations, doc, coexistence, touchedNumbers = new Set()) {
+    const blocking = [];
+    const legacy_caveats = [];
+    for (const violation of violations) {
+        const match = CONFIDENCE_VIOLATION.exec(violation);
+        if (!match || !match.groups) {
+            blocking.push(violation);
+            continue;
+        }
+        const { value, list, idx } = match.groups;
+        const source = list === "archive" ? "archive" : "active";
+        const record = recordAt(doc, list, Number(idx));
+        const number = Number(record.number);
+        const classification = classifyConfidenceLabel(coexistence, value, touchedNumbers.has(number));
+        if (classification.classification === "explicit_legacy") {
+            legacy_caveats.push({ number, label: value, source, caveat: classification.caveat });
+        }
+        else {
+            // Touched unsupported (rejected) or current-but-flagged: keep strict.
+            blocking.push(violation);
+        }
+    }
+    return { blocking, legacy_caveats };
+}
+/**
+ * Classify one record's confidence for amendment/read composition. An
+ * untouched inherited unsupported label is explicit legacy state and surfaces
+ * as a single caveat (never coerced, never promoted). `touched=true` marks
+ * the confidence as new or amended content; such a value can only be current
+ * vocabulary (enforced elsewhere), so no caveat is produced. Returns `null`
+ * when the confidence is current vocabulary or absent.
+ */
+export function legacyConfidenceCaveat(record, coexistence, touched, source = "active") {
+    const confidence = record.confidence;
+    if (typeof confidence !== "string")
+        return null;
+    const classification = classifyConfidenceLabel(coexistence, confidence, touched);
+    if (classification.classification !== "explicit_legacy")
+        return null;
+    return {
+        number: Number(record.number),
+        label: confidence,
+        source,
+        caveat: classification.caveat,
+    };
+}
+/**
+ * Return a caveat only for a label declared as known v2 legacy state. Migration
+ * uses this narrower classifier so an arbitrary unsupported confidence value
+ * cannot become publishable merely because it occupies the confidence field.
+ */
+export function knownLegacyConfidenceCaveat(record, coexistence, source = "active") {
+    if (typeof record.confidence !== "string" || !coexistence.knownLegacyExamples.includes(record.confidence))
+        return null;
+    return legacyConfidenceCaveat(record, coexistence, false, source);
+}
+/**
+ * Classify a complete migration source record without interpreting validator
+ * error text. A known legacy confidence is inherited only when replacing that
+ * one field with an authority-declared current value makes the whole record
+ * valid. Projection and verified-archive migration both use this classifier.
+ */
+export function classifyCompleteDecisionConfidence(record, coexistence, validate, source) {
+    if (coexistence.dimensions.length !== 1 || coexistence.dimensions[0] !== "confidence") {
+        throw new Error("decision legacy coexistence must declare confidence as its sole compatibility dimension");
+    }
+    const violations = validate(record);
+    if (violations.length === 0)
+        return { status: "current", violations, caveat: null };
+    const caveat = knownLegacyConfidenceCaveat(record, coexistence, source);
+    if (!caveat || coexistence.currentVocabulary.length === 0)
+        return { status: "invalid", violations, caveat: null };
+    const strictCandidate = { ...record, confidence: coexistence.currentVocabulary[0] };
+    return validate(strictCandidate).length === 0
+        ? { status: "inherited", violations, caveat }
+        : { status: "invalid", violations, caveat: null };
+}
+/**
+ * Scan a parsed decisions artifact mapping for untouched inherited legacy
+ * confidence labels. Records whose number is in `touchedNumbers` are new or
+ * amended content and are excluded — they remain strict. Used to report
+ * truthful compatibility caveats that reflect the published bytes.
+ */
+export function collectDecisionLegacyCaveats(doc, coexistence, touchedNumbers = new Set()) {
+    const caveats = [];
+    for (const [list, source] of [
+        ["decisions", "active"],
+        ["archive", "archive"],
+    ]) {
+        const arr = doc[list];
+        if (!Array.isArray(arr))
+            continue;
+        for (const entry of arr) {
+            if (!isMapping(entry))
+                continue;
+            const caveat = legacyConfidenceCaveat(entry, coexistence, touchedNumbers.has(Number(entry.number)), source);
+            if (caveat)
+                caveats.push(caveat);
+        }
+    }
+    return caveats;
+}
+/** Load the legacy label coexistence authority section for a project. */
+export function decisionLegacyCoexistence(sourceRoot = resolveSourceRoot()) {
+    return legacyLabelCoexistence(sourceRoot);
+}
+/**
+ * Gate 1 — prevalidation of the existing artifact. When coexistence is null
+ * (non-decisions artifact), throws the standard schema-invalid error. When
+ * coexistence is active, partitions: tolerates untouched inherited legacy
+ * confidence labels only; every other violation stays blocking. Returns
+ * legacy caveats from the violations.
+ */
+export function gateExistingDecisions(violations, doc, coexistence, target) {
+    if (!coexistence)
+        throw new Error(`existing artifact '${target}' is schema-invalid: ${violations.join("; ")}; repair it before retrying`);
+    const partition = partitionDecisionViolations(violations, doc, coexistence, new Set());
+    if (partition.blocking.length)
+        throw new Error(`existing artifact '${target}' is schema-invalid: ${partition.blocking.join("; ")}; repair it before retrying`);
+    return partition.legacy_caveats;
+}
+/**
+ * Gate 2 — candidate validation. When coexistence is null (non-decisions),
+ * calls `reject` with the raw violations if any exist. When active, the
+ * new/amended record's number is touched, so unsupported confidence on it
+ * stays blocking (calls `reject`). Then re-derives caveats from the candidate
+ * doc so the envelope reflects the about-to-be-published bytes.
+ */
+export function gateCandidateDecisions(violations, candidate, coexistence, writtenNumber, reject) {
+    if (!coexistence) {
+        if (violations.length)
+            reject(violations);
+        return [];
+    }
+    const touched = new Set([writtenNumber]);
+    const partition = partitionDecisionViolations(violations, candidate, coexistence, touched);
+    if (partition.blocking.length)
+        reject(partition.blocking);
+    return collectDecisionLegacyCaveats(candidate, coexistence, touched);
+}
+/**
+ * Gate 3 — post-compaction invariant. When coexistence is null, throws the
+ * standard writer/compactor error if violations exist. When active, proves
+ * untouched inherited legacy labels survived compaction unchanged:
+ * partitions final violations (throws if blocking), then re-derives caveats
+ * from the published bytes.
+ */
+export function gateCompactedDecisions(violations, doc, coexistence, writtenNumber) {
+    if (!coexistence) {
+        if (violations.length)
+            throw new Error(`writer/compactor invariant failure: ${violations.join("; ")}`);
+        return [];
+    }
+    const touched = new Set([writtenNumber]);
+    if (violations.length) {
+        const partition = partitionDecisionViolations(violations, doc, coexistence, touched);
+        if (partition.blocking.length)
+            throw new Error(`writer/compactor invariant failure: ${partition.blocking.join("; ")}`);
+    }
+    return collectDecisionLegacyCaveats(doc, coexistence, touched);
+}

package/dist/state/decisionMigrationProvenance.js

@@ -0,0 +1,199 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { loadYamlMapping } from "../core/yaml.js";
+import { canonicalRecordJson, numberedArchiveContract, stateCurrentProjectionPath, validateNumberedArchiveBytes, validateStateRecord } from "./archiveDiscovery.js";
+import { canonicalMigrationRecord } from "./canonicalMigrationRecord.js";
+import { classifyCompleteDecisionConfidence } from "./decisionLegacyValidation.js";
+import { decisionRevisionContract, decisionRevisionViolations, legacyLabelCoexistence } from "./decisionRevision.js";
+import { readBoundMigrationSource } from "./migrationSourceBinding.js";
+import { entityMigrationId } from "./entityMigrationIdentity.js";
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Validate the sole authority-declared canonical migration metadata shape. */
+export function decisionMigrationProvenanceViolations(record, provenance, declared, forbiddenAliases, sourceRoot, binding) {
+    if (declared.additionalFields !== "forbidden" || !declared.kind || declared.requiredFields.length === 0 || declared.sources.length === 0) {
+        throw new Error("invalid migration provenance authority for 'decision'");
+    }
+    const coexistence = legacyLabelCoexistence(sourceRoot ?? resolveSourceRoot());
+    const confidence = record.confidence;
+    if (typeof confidence !== "string")
+        return ["confidence must be a string from the authority-declared vocabulary"];
+    if (coexistence.currentVocabulary.includes(confidence)) {
+        return provenance === null || provenance === undefined ? [] : ["migration_provenance is allowed only for an inherited unsupported confidence"];
+    }
+    if (!coexistence.knownLegacyExamples.includes(confidence))
+        return [`unsupported decision confidence '${confidence}'`];
+    if (!mapping(provenance))
+        return ["an inherited unsupported confidence requires mapping migration_provenance"];
+    const violations = [];
+    const declaredKeys = new Set(declared.requiredFields);
+    for (const field of declared.requiredFields)
+        if (!(field in provenance))
+            violations.push(`migration_provenance.${field} is required`);
+    for (const field of Object.keys(provenance))
+        if (!declaredKeys.has(field))
+            violations.push(`migration_provenance.${field} is not allowed`);
+    if (provenance.kind !== declared.kind)
+        violations.push(`migration_provenance.kind must be '${declared.kind}'`);
+    if (typeof provenance.source !== "string" || !declared.sources.includes(provenance.source))
+        violations.push(`migration_provenance.source must be one of: ${declared.sources.join(", ")}`);
+    if (typeof provenance.source_path !== "string" || provenance.source_path.length === 0 || path.isAbsolute(provenance.source_path) || provenance.source_path.split(/[\\/]/).includes(".."))
+        violations.push("migration_provenance.source_path must be a safe project-relative path");
+    if (typeof provenance.source_record_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(provenance.source_record_sha256))
+        violations.push("migration_provenance.source_record_sha256 must be a lowercase SHA-256 digest");
+    if (provenance.confidence !== confidence)
+        violations.push("migration_provenance.confidence must match record.confidence");
+    if (violations.length)
+        return violations;
+    if (binding === undefined)
+        return ["an inherited unsupported confidence requires a source binding context"];
+    violations.push(...sourceBindingViolations(record, provenance, binding, sourceRoot ?? resolveSourceRoot(), forbiddenAliases));
+    return violations;
+}
+export function decisionRevisionMigrationProvenanceViolations(record, provenance, declared, sourceRoot = resolveSourceRoot(), binding) {
+    const changes = mapping(record.changes) ? record.changes : {};
+    const confidence = changes.confidence;
+    const coexistence = legacyLabelCoexistence(sourceRoot);
+    if (confidence === undefined || coexistence.currentVocabulary.includes(String(confidence))) {
+        return provenance === null || provenance === undefined ? [] : ["migration_provenance is allowed only for an inherited unsupported revision confidence"];
+    }
+    if (typeof confidence !== "string" || !coexistence.knownLegacyExamples.includes(confidence))
+        return [`unsupported decision revision confidence '${String(confidence)}'`];
+    if (!mapping(provenance))
+        return ["an inherited unsupported revision confidence requires mapping migration_provenance"];
+    const violations = [];
+    const declaredKeys = new Set(declared.requiredFields);
+    for (const field of declared.requiredFields)
+        if (!(field in provenance))
+            violations.push(`migration_provenance.${field} is required`);
+    for (const field of Object.keys(provenance))
+        if (!declaredKeys.has(field))
+            violations.push(`migration_provenance.${field} is not allowed`);
+    if (provenance.kind !== declared.kind)
+        violations.push(`migration_provenance.kind must be '${declared.kind}'`);
+    if (typeof provenance.source !== "string" || !declared.sources.includes(provenance.source))
+        violations.push(`migration_provenance.source must be one of: ${declared.sources.join(", ")}`);
+    const contract = decisionRevisionContract(sourceRoot);
+    if (provenance.source_path !== contract.location)
+        violations.push(`migration_provenance.source_path must be '${contract.location}'`);
+    if (typeof provenance.source_identity !== "string" || !/^decision_revision:decisions:[1-9][0-9]*:[0-9]+$/.test(provenance.source_identity))
+        violations.push("migration_provenance.source_identity must identify one ordered legacy decision revision");
+    if (typeof provenance.source_fingerprint !== "string" || !/^[a-f0-9]{64}$/.test(provenance.source_fingerprint))
+        violations.push("migration_provenance.source_fingerprint must be a lowercase SHA-256 digest");
+    if (typeof provenance.source_record_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(provenance.source_record_sha256))
+        violations.push("migration_provenance.source_record_sha256 must be a lowercase SHA-256 digest");
+    if (provenance.confidence !== confidence)
+        violations.push("migration_provenance.confidence must match record.changes.confidence");
+    if (violations.length)
+        return violations;
+    if (binding === undefined)
+        return ["an inherited unsupported revision confidence requires a source binding context"];
+    const match = /^decision_revision:(decisions:[1-9][0-9]*):([0-9]+)$/.exec(String(provenance.source_identity));
+    if (!match || entityMigrationId(String(provenance.source_fingerprint), match[1]) !== record.decision)
+        return ["migration_provenance source identity does not bind the canonical decision ID"];
+    if (binding.kind !== "migration_preview") {
+        const markerFile = readBoundMigrationSource(binding, ".agentera/state-mode.yaml");
+        if (markerFile.kind !== "file")
+            return ["migration_provenance requires the durable entity cutover marker"];
+        let marker;
+        try {
+            marker = loadYamlMapping(markerFile.bytes);
+        }
+        catch (error) {
+            return [`entity cutover marker is invalid YAML: ${error.message}`];
+        }
+        if (marker.schemaVersion !== "agentera.stateMode.v1" || marker.mode !== "entities" || marker.source_fingerprint !== provenance.source_fingerprint)
+            return ["migration_provenance source_fingerprint does not match the durable entity cutover marker"];
+    }
+    const sourceFile = readBoundMigrationSource(binding, contract.location);
+    if (sourceFile.kind !== "file")
+        return [`migration_provenance source '${contract.location}' is ${sourceFile.kind === "missing" ? "missing" : `unsafe (${sourceFile.reason})`}`];
+    let document;
+    try {
+        document = loadYamlMapping(sourceFile.bytes);
+    }
+    catch (error) {
+        return [`migration_provenance source '${contract.location}' is invalid YAML: ${error.message}`];
+    }
+    const candidate = match && Array.isArray(document[match[1]]) ? mapping(document[match[1]][Number(match[2])]) ? document[match[1]][Number(match[2])] : null : null;
+    if (!match || !candidate)
+        return ["migration_provenance source_identity does not resolve to one legacy decision revision"];
+    if (sourceHash(candidate) !== provenance.source_record_sha256)
+        return ["migration_provenance source_record_sha256 does not match the legacy decision revision"];
+    const sourceViolations = decisionRevisionViolations({ [match[1]]: [candidate] }, contract);
+    if (sourceViolations.length)
+        return [`migration_provenance source revision is invalid: ${sourceViolations.join("; ")}`];
+    const candidateChanges = Object.fromEntries(Object.entries(candidate).filter(([field]) => !["date", "provenance", "base_sha256"].includes(field)));
+    if (canonicalRecordJson(candidateChanges) !== canonicalRecordJson(changes))
+        return ["migration_provenance source revision changes do not match the canonical revision"];
+    if ((candidate.date ?? undefined) !== (record.date ?? undefined))
+        return ["migration_provenance source revision date does not match the canonical revision"];
+    if ((candidate.provenance ?? "historical_revision") !== record.provenance)
+        return ["migration_provenance source revision provenance does not match the canonical revision"];
+    return [];
+}
+function sourceAssessment(record, sourceRoot, source) {
+    return classifyCompleteDecisionConfidence(record, legacyLabelCoexistence(sourceRoot), (candidate) => validateStateRecord(sourceRoot, "decisions", candidate), source);
+}
+function sourceMatchesCanonical(source, canonical, forbiddenAliases) {
+    return canonicalRecordJson(canonicalMigrationRecord("decision", source, forbiddenAliases)) === canonicalRecordJson(canonical);
+}
+function sourceHash(record) {
+    return createHash("sha256").update(canonicalRecordJson(record)).digest("hex");
+}
+function sourceBindingViolations(record, provenance, binding, sourceRoot, forbiddenAliases) {
+    const sourcePath = String(provenance.source_path);
+    const digest = String(provenance.source_record_sha256);
+    const confidence = String(provenance.confidence);
+    if (provenance.source === "current_projection") {
+        const declaredPath = path.relative("/", stateCurrentProjectionPath("/", "decisions", sourceRoot)).split(path.sep).join("/");
+        if (sourcePath !== declaredPath)
+            return [`migration_provenance.source_path must be the authority-declared current projection '${declaredPath}'`];
+        const sourceFile = readBoundMigrationSource(binding, declaredPath);
+        if (sourceFile.kind !== "file")
+            return [`migration_provenance source '${declaredPath}' is ${sourceFile.kind === "missing" ? "missing" : `unsafe (${sourceFile.reason})`}`];
+        let document;
+        try {
+            document = loadYamlMapping(sourceFile.bytes);
+        }
+        catch (error) {
+            return [`migration_provenance source '${declaredPath}' is invalid YAML: ${error.message}`];
+        }
+        const candidates = [document.decisions, document.archive].flatMap((value) => Array.isArray(value) ? value.filter(mapping) : []);
+        const candidate = candidates.find((source) => sourceHash(source) === digest && source.confidence === confidence && sourceMatchesCanonical(source, record, forbiddenAliases));
+        if (!candidate)
+            return ["migration_provenance does not match any complete decision in the preserved current projection"];
+        const assessment = sourceAssessment(candidate, sourceRoot, "active");
+        return assessment.status === "inherited" ? [] : ["migration_provenance current-projection source is not a complete inherited-confidence decision"];
+    }
+    const contract = numberedArchiveContract("decisions", sourceRoot);
+    const archivePrefix = path.posix.join(contract.archiveRoot, "decisions");
+    const escapedExtension = contract.archiveExtension.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = new RegExp(`^${archivePrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/([1-9][0-9]*)${escapedExtension}$`).exec(sourcePath);
+    if (!match)
+        return [`migration_provenance.source_path must be an authority-valid numbered decision archive path under '${archivePrefix}'`];
+    const entryNumber = Number(match[1]);
+    const sourceFile = readBoundMigrationSource(binding, sourcePath);
+    if (sourceFile.kind !== "file")
+        return [`migration_provenance archive source is ${sourceFile.kind === "missing" ? "missing" : `unsafe (${sourceFile.reason})`}: ${sourcePath}`];
+    const lookup = validateNumberedArchiveBytes("decisions", entryNumber, sourceFile.bytes, {
+        sourceRoot,
+        sourcePath,
+        recordValidator: (source) => {
+            const assessment = sourceAssessment(source, sourceRoot, "archive");
+            return assessment.status === "inherited" ? [] : assessment.violations.length ? assessment.violations : ["archive decision is not inherited legacy confidence"];
+        },
+    });
+    if (!lookup.entry?.record)
+        return [`migration_provenance archive source is missing or invalid: ${lookup.rejection?.message ?? sourcePath}`];
+    const source = lookup.entry.record;
+    if (lookup.entry.recordSha256 !== digest || sourceHash(source) !== digest)
+        return ["migration_provenance source_record_sha256 does not match the authority-valid archive record"];
+    if (source.confidence !== confidence)
+        return ["migration_provenance confidence does not match the archive record"];
+    if (!sourceMatchesCanonical(source, record, forbiddenAliases))
+        return ["migration_provenance archive record does not correspond to the canonical decision content"];
+    return [];
+}

package/dist/state/decisionOverlay.js

@@ -0,0 +1,254 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { dumpYamlMapping, loadYamlMapping } from "../core/yaml.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { assertRealpathBoundary } from "../registries/artifactRegistry.js";
+import { decisionOverlayContract, } from "./archiveDiscovery.js";
+import { reject } from "./write/errors.js";
+function isMapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function mapping(value) {
+    return isMapping(value) ? value : {};
+}
+function valueAt(value, field) {
+    let current = value;
+    for (const part of field.split(".")) {
+        if (!isMapping(current))
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function setAt(target, field, value) {
+    const parts = field.split(".");
+    let current = target;
+    for (const part of parts.slice(0, -1)) {
+        const next = current[part];
+        if (!isMapping(next))
+            current[part] = {};
+        current = current[part];
+    }
+    current[parts.at(-1)] = structuredClone(value);
+}
+function pathAllowed(field, contract) {
+    return contract.mutablePaths.some((mutable) => mutable === field || mutable.startsWith(`${field}.`));
+}
+function validateValueTypes(field, value, contract, violations) {
+    if (field.endsWith(".state")) {
+        if (typeof value !== "string" || !contract.stateValues.includes(value)) {
+            violations.push(`${field} must be one of: ${contract.stateValues.join(", ")}`);
+        }
+        return;
+    }
+    if (field.endsWith(".evidence") || field.endsWith(".confirmed_by") || field.endsWith(".confirmed_at")) {
+        if (typeof value !== "string")
+            violations.push(`${field} must be a string`);
+    }
+}
+function validateOverlayValue(value, contract, prefix = "", violations = []) {
+    if (!isMapping(value)) {
+        violations.push(`${prefix || "overlay entry"} must be a mapping`);
+        return violations;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        const field = prefix ? `${prefix}.${key}` : key;
+        if (!pathAllowed(field, contract)) {
+            violations.push(`${field} is not an authority-declared mutable overlay field`);
+            continue;
+        }
+        if (isMapping(child))
+            validateOverlayValue(child, contract, field, violations);
+        else
+            validateValueTypes(field, child, contract, violations);
+    }
+    return violations;
+}
+function decisionNumberFromId(id, contract) {
+    const prefix = `${contract.identityPrefix}:`;
+    if (!id.startsWith(prefix))
+        return null;
+    const number = id.slice(prefix.length);
+    if (!/^[1-9][0-9]*$/.test(number))
+        return null;
+    const parsed = Number(number);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+export function decisionOverlayPath(projectRoot, sourceRoot = resolveSourceRoot()) {
+    const contract = decisionOverlayContract(sourceRoot);
+    const target = path.resolve(projectRoot, contract.location);
+    assertRealpathBoundary(projectRoot, target, "decision overlay");
+    return target;
+}
+export function decisionOverlayViolations(document, contract = decisionOverlayContract()) {
+    if (!isMapping(document))
+        return ["decision overlay root must be a mapping keyed by stable decision ID"];
+    const violations = [];
+    for (const [stableId, value] of Object.entries(document)) {
+        if (decisionNumberFromId(stableId, contract) === null) {
+            violations.push(`${stableId} is not a valid ${contract.identityKey} key`);
+            continue;
+        }
+        validateOverlayValue(value, contract, "", violations);
+    }
+    return violations;
+}
+function readOverlayDocument(projectRoot, sourceRoot = resolveSourceRoot()) {
+    const contract = decisionOverlayContract(sourceRoot);
+    const target = decisionOverlayPath(projectRoot, sourceRoot);
+    if (!fs.existsSync(target))
+        return { path: target, document: {}, contract };
+    const bytes = fs.readFileSync(target, "utf8");
+    let document;
+    try {
+        document = loadYamlMapping(bytes);
+    }
+    catch (error) {
+        throw new Error(`cannot parse decision overlay '${target}': ${error.message}`);
+    }
+    const violations = decisionOverlayViolations(document, contract);
+    if (violations.length > 0)
+        throw new Error(`decision overlay '${target}' is invalid: ${violations.join("; ")}`);
+    return { path: target, document: document, contract };
+}
+export function loadDecisionOverlay(projectRoot = process.cwd(), sourceRoot = resolveSourceRoot()) {
+    return readOverlayDocument(projectRoot, sourceRoot).document;
+}
+export function hydrateDecisionRecords(entries, source = process.cwd()) {
+    const overlay = typeof source === "string" ? loadDecisionOverlay(source) : source;
+    const contract = decisionOverlayContract();
+    return entries.map((entry) => {
+        const number = entry.number;
+        const stableId = typeof number === "number" || typeof number === "string" ? `decisions:${number}` : null;
+        return composeDecisionOverlay(entry, stableId ? overlay[stableId] : undefined, contract);
+    });
+}
+export function composeDecisionOverlay(entry, overlay, contract = decisionOverlayContract()) {
+    if (!overlay)
+        return structuredClone(entry);
+    const hydrated = structuredClone(entry);
+    const historicalSatisfaction = mapping(hydrated.satisfaction);
+    const overlaySatisfaction = mapping(overlay.satisfaction);
+    const composedSatisfaction = { ...historicalSatisfaction };
+    for (const field of contract.mutablePaths) {
+        const relative = field.startsWith("satisfaction.") ? field.slice("satisfaction.".length) : field;
+        const value = valueAt(overlaySatisfaction, relative);
+        if (value !== undefined)
+            setAt(composedSatisfaction, relative, value);
+    }
+    hydrated.satisfaction = composedSatisfaction;
+    return hydrated;
+}
+export function requestedSatisfaction(requested, contract) {
+    const violations = validateOverlayValue({ satisfaction: requested }, contract);
+    if (violations.length > 0) {
+        reject({
+            class: "schema_violation",
+            message: "decision satisfaction update contains invalid overlay fields",
+            violations,
+            syntax: "agentera state decisions update --id ID --satisfaction-state STATE --format json",
+            example: "agentera state decisions update --id qjtrmnpvka --satisfaction-state provisionally_satisfied --satisfaction-evidence 'verified' --format json",
+        });
+    }
+    const result = {};
+    for (const field of contract.mutablePaths) {
+        const relative = field.startsWith("satisfaction.") ? field.slice("satisfaction.".length) : field;
+        const value = valueAt(requested, relative);
+        if (value !== undefined)
+            setAt(result, relative, value);
+    }
+    return result;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function statePath(contract) {
+    return contract.mutablePaths.find((field) => field.endsWith(".state"))?.slice("satisfaction.".length) ?? "state";
+}
+function evidencePath(contract) {
+    return contract.mutablePaths.find((field) => field.endsWith(".evidence"))?.slice("satisfaction.".length) ?? "evidence";
+}
+function confirmationPaths(contract) {
+    return contract.mutablePaths
+        .filter((field) => field.includes("user_confirmation."))
+        .map((field) => field.slice("satisfaction.".length));
+}
+function effectiveState(overlay, historicalSatisfaction) {
+    return valueAt(overlay?.satisfaction, "state") ?? valueAt(historicalSatisfaction, "state");
+}
+export function validateTransition(requested, currentOverlay, historicalSatisfaction, contract) {
+    const nextState = valueAt(requested, statePath(contract));
+    const evidence = valueAt(requested, evidencePath(contract));
+    const confirmation = mapping(requested.user_confirmation);
+    if (nextState === "provisionally_satisfied" && !nonEmptyString(evidence)) {
+        reject({
+            class: "schema_violation",
+            message: "provisionally_satisfied requires non-empty --satisfaction-evidence",
+            syntax: "agentera state decisions update --id ID --satisfaction-state STATE --satisfaction-evidence TEXT --format json",
+            example: "agentera state decisions update --id qjtrmnpvka --satisfaction-state provisionally_satisfied --satisfaction-evidence 'verified' --format json",
+        });
+    }
+    if (nextState === "user_confirmed_satisfied") {
+        const paths = confirmationPaths(contract);
+        if (paths.some((field) => !nonEmptyString(valueAt(confirmation, field.split(".").at(-1))))) {
+            reject({
+                class: "schema_violation",
+                message: "user_confirmed_satisfied requires explicit current user confirmation metadata",
+                syntax: "agentera state decisions update --id ID --satisfaction-state user_confirmed_satisfied --confirmed-by USER --confirmed-at TIME --format json",
+                example: "agentera state decisions update --id qjtrmnpvka --satisfaction-state user_confirmed_satisfied --confirmed-by user --confirmed-at 2026-07-13T12:00:00Z --format json",
+            });
+        }
+    }
+    const currentState = effectiveState(currentOverlay, historicalSatisfaction);
+    if (typeof currentState === "string" && contract.stateValues.includes(currentState)) {
+        if (!contract.allowedNext[currentState]?.includes(String(nextState))) {
+            const downgradeConfirmation = confirmationPaths(contract).every((field) => nonEmptyString(valueAt(confirmation, field.split(".").at(-1))));
+            if (!(currentState === "user_confirmed_satisfied" && downgradeConfirmation)) {
+                reject({
+                    class: "conflict",
+                    message: `decision satisfaction cannot transition from ${currentState} to ${String(nextState)} without explicit current user confirmation`,
+                    syntax: "agentera state decisions update --id ID --satisfaction-state STATE --format json",
+                    example: "agentera state decisions update --id qjtrmnpvka --satisfaction-state user_confirmed_satisfied --confirmed-by user --confirmed-at 2026-07-13T12:00:00Z --format json",
+                });
+            }
+        }
+    }
+}
+export function updateDecisionOverlay(projectRoot, decisionNumber, requested, historicalSatisfaction, transaction, publish = true, sourceRoot = resolveSourceRoot()) {
+    const current = readOverlayDocument(projectRoot, sourceRoot);
+    const stableId = `${current.contract.identityPrefix}:${decisionNumber}`;
+    const currentEntry = current.document[stableId];
+    const satisfaction = requestedSatisfaction(requested, current.contract);
+    validateTransition(satisfaction, currentEntry, historicalSatisfaction, current.contract);
+    const nextDocument = structuredClone(current.document);
+    const replay = Boolean(currentEntry && isDeepStrictEqual(currentEntry.satisfaction, satisfaction));
+    if (!replay)
+        nextDocument[stableId] = { satisfaction };
+    if (!replay && publish) {
+        const bytes = dumpYamlMapping(nextDocument);
+        const violations = decisionOverlayViolations(nextDocument, current.contract);
+        if (violations.length > 0) {
+            reject({
+                class: "schema_violation",
+                message: "decision overlay publication failed validation",
+                violations,
+            });
+        }
+        const stage = transaction.stageProjection(current.path, bytes);
+        try {
+            transaction.syncStaged(stage);
+            transaction.publishProjection(stage, current.path);
+        }
+        finally {
+            transaction.removeStage(stage);
+        }
+    }
+    return {
+        path: current.path,
+        satisfaction,
+        replay,
+        before: current.document,
+        after: nextDocument,
+    };
+}