agentera 3.0.0-dev.4 → 3.0.0-dev.41

package/dist/state/changelog.js

@@ -0,0 +1,222 @@
+import path from "node:path";
+import { docsPathOverridesFromBytes, loadArtifactRecord, resolveArtifactPath, } from "../registries/artifactRegistry.js";
+import { ARTIFACT_PROTOCOL_PATHS } from "../registries/artifactProtocolIds.js";
+import { validateRealProjectRoot } from "./projectRoot.js";
+import { readProjectFileSnapshot } from "./safeProjectFile.js";
+export const CHANGELOG_QUERY_COMMAND = "agentera state query changelog --format json";
+export const CHANGELOG_SCANNER_ID = "agentera.changelogHeadingScanner.v1";
+export const CHANGELOG_MAX_READ_BYTES = 1_048_576;
+export const CHANGELOG_DOCS_MAX_READ_BYTES = 262_144;
+export const CHANGELOG_MAX_HEADING_BYTES = 256;
+export const CHANGELOG_MAX_SOURCE_PATH_BYTES = 512;
+export const CHANGELOG_MAX_OUTPUT_BYTES = 2_000;
+export const CHANGELOG_CLOSEOUT_RESERVE_BYTES = 400;
+const CHANGELOG_SHARED_MAX_OUTPUT_BYTES = CHANGELOG_MAX_OUTPUT_BYTES - CHANGELOG_CLOSEOUT_RESERVE_BYTES;
+const UNRELEASED_RE = /^## \[Unreleased\]\s*$/i;
+const RELEASE_RE = /^## \[((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?)\](?:\s+(?:-|·)\s+\d{4}-\d{2}-\d{2})?\s*$/;
+const RECOVERY = {
+    strategy: "repair_validate_retry_once",
+    repair: "Repair or restore the configured CHANGELOG artifact as a bounded regular project file with unambiguous Keep a Changelog release headings.",
+    validate: "Confirm there is at most one Unreleased heading, every release identity is unique, and no arbitrary release-level H2 headings remain.",
+    retry: CHANGELOG_QUERY_COMMAND,
+    retry_limit: 1,
+};
+/** Classify release-level headings without depending on paths, line endings, or project state. */
+export function scanChangelogHeadings(text) {
+    const h2 = text.split(/\r\n|\r|\n/).filter((line) => line.startsWith("## ")).map((line) => line.trim());
+    const boundedH2 = h2.filter((heading) => Buffer.byteLength(heading, "utf8") <= CHANGELOG_MAX_HEADING_BYTES);
+    const identityBoundExceeded = boundedH2.length !== h2.length;
+    const unreleased = boundedH2.filter((heading) => UNRELEASED_RE.test(heading));
+    const releases = [];
+    let malformedCount = identityBoundExceeded ? 1 : 0;
+    for (const heading of boundedH2) {
+        if (UNRELEASED_RE.test(heading))
+            continue;
+        const match = RELEASE_RE.exec(heading);
+        if (match)
+            releases.push({ heading, version: match[1] });
+        else
+            malformedCount += 1;
+    }
+    const releaseVersions = releases.map(({ version }) => version);
+    const duplicateRelease = new Set(releaseVersions).size !== releaseVersions.length;
+    const available = malformedCount === 0
+        && unreleased.length <= 1
+        && !duplicateRelease
+        && releases.length > 0;
+    const unreleasedHeading = unreleased.length === 1 ? unreleased[0] : null;
+    const latestReleaseHeading = releases[0]?.heading ?? null;
+    const boundary = available ? (unreleasedHeading ?? latestReleaseHeading) : null;
+    const recognizedHeadings = available
+        ? [unreleasedHeading, latestReleaseHeading].filter((heading) => heading !== null)
+        : [];
+    return {
+        status: available ? "available" : "incomplete",
+        recognizedHeadings,
+        recognizedReleaseVersions: releaseVersions,
+        recognizedReleaseCount: releases.length,
+        unreleasedHeading,
+        latestReleaseHeading,
+        boundary,
+        identityBoundExceeded,
+    };
+}
+function source(relativePath) {
+    return {
+        artifact: "changelog",
+        path: relativePath,
+        path_resolution: "artifact_registry",
+    };
+}
+function provenance() {
+    return {
+        source_family: "changelog",
+        command: CHANGELOG_QUERY_COMMAND,
+        field: "recognized_headings",
+        scanner: CHANGELOG_SCANNER_ID,
+    };
+}
+function serializedProjectionBytes(projection) {
+    return Buffer.byteLength(`${JSON.stringify(projection, null, 2)}\n`, "utf8");
+}
+function projectionResult(projection, recognizedReleaseVersions) {
+    if (serializedProjectionBytes(projection) <= CHANGELOG_SHARED_MAX_OUTPUT_BYTES) {
+        return { projection, recognizedReleaseVersions };
+    }
+    return fixedBoundFailure();
+}
+export function boundedChangelogUnavailable(caveat = "CHANGELOG state is unavailable because its bounded identity projection exceeds the supported output limit.") {
+    const projection = {
+        schemaVersion: "agentera.changelogRead.v1",
+        command: "changelog",
+        status: "unavailable",
+        recognized_headings: [],
+        recognized_release_count: 0,
+        unreleased_present: false,
+        latest_release_heading: null,
+        boundary_present: false,
+        boundary: null,
+        source: source(null),
+        source_provenance: provenance(),
+        caveats: [caveat],
+        recovery: RECOVERY,
+    };
+    if (serializedProjectionBytes(projection) > CHANGELOG_SHARED_MAX_OUTPUT_BYTES) {
+        throw new Error("fixed changelog unavailable projection exceeds its output limit");
+    }
+    return { projection, recognizedReleaseVersions: [] };
+}
+function fixedBoundFailure() {
+    return boundedChangelogUnavailable();
+}
+function unavailable(relativePath, caveat) {
+    if (relativePath !== null && Buffer.byteLength(relativePath, "utf8") > CHANGELOG_MAX_SOURCE_PATH_BYTES) {
+        return fixedBoundFailure();
+    }
+    return projectionResult({
+        schemaVersion: "agentera.changelogRead.v1",
+        command: "changelog",
+        status: "unavailable",
+        recognized_headings: [],
+        recognized_release_count: 0,
+        unreleased_present: false,
+        latest_release_heading: null,
+        boundary_present: false,
+        boundary: null,
+        source: source(relativePath),
+        source_provenance: provenance(),
+        caveats: [caveat],
+        recovery: RECOVERY,
+    }, []);
+}
+function relativeArtifactPath(projectRoot, absolute) {
+    const relative = path.relative(projectRoot, absolute);
+    if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        return null;
+    return relative.split(path.sep).join("/");
+}
+/** Resolve and safely read the registry-owned CHANGELOG singleton for one project. */
+export function readChangelog(projectRootInput) {
+    let projectRoot;
+    try {
+        projectRoot = validateRealProjectRoot(projectRootInput);
+    }
+    catch {
+        return unavailable("CHANGELOG.md", "CHANGELOG state is unavailable because the project root is unsafe or unreadable.");
+    }
+    let overrides = {};
+    const docsSnapshot = readProjectFileSnapshot(projectRoot, ARTIFACT_PROTOCOL_PATHS.docs, undefined, CHANGELOG_DOCS_MAX_READ_BYTES);
+    if (docsSnapshot.kind === "unsafe") {
+        return unavailable(null, "CHANGELOG state is unavailable because the configured docs path authority is unsafe, unreadable, or over its read limit.");
+    }
+    if (docsSnapshot.kind === "file") {
+        let docsText;
+        try {
+            docsText = new TextDecoder("utf-8", { fatal: true }).decode(docsSnapshot.bytes);
+        }
+        catch {
+            return unavailable(null, "CHANGELOG state is unavailable because the configured docs path authority is not valid UTF-8.");
+        }
+        try {
+            overrides = docsPathOverridesFromBytes(docsText, true);
+        }
+        catch {
+            return unavailable(null, "CHANGELOG state is unavailable because the configured docs path authority is malformed.");
+        }
+    }
+    let relativePath = "CHANGELOG.md";
+    try {
+        const record = loadArtifactRecord("changelog");
+        if (!record)
+            return unavailable(relativePath, "CHANGELOG state is unavailable because its artifact registry entry could not be resolved.");
+        const absolute = resolveArtifactPath(record, projectRoot.path, { docsPathOverrides: overrides, strictWrite: true });
+        const resolvedRelative = relativeArtifactPath(projectRoot.path, absolute);
+        if (resolvedRelative === null)
+            return unavailable(relativePath, "CHANGELOG state is unavailable because its configured path is unsafe.");
+        if (Buffer.byteLength(resolvedRelative, "utf8") > CHANGELOG_MAX_SOURCE_PATH_BYTES)
+            return fixedBoundFailure();
+        relativePath = resolvedRelative;
+    }
+    catch {
+        return unavailable(relativePath, "CHANGELOG state is unavailable because its configured path is unsafe.");
+    }
+    const snapshot = readProjectFileSnapshot(projectRoot, relativePath, undefined, CHANGELOG_MAX_READ_BYTES);
+    if (snapshot.kind === "missing") {
+        return unavailable(relativePath, "CHANGELOG state is unavailable because the configured artifact is missing.");
+    }
+    if (snapshot.kind === "unsafe") {
+        const caveat = snapshot.reason === "over_limit"
+            ? "CHANGELOG state is unavailable because the configured artifact exceeds the bounded read limit."
+            : "CHANGELOG state is unavailable because the configured artifact is not a safe readable regular file.";
+        return unavailable(relativePath, caveat);
+    }
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(snapshot.bytes);
+    }
+    catch {
+        return unavailable(relativePath, "CHANGELOG state is unavailable because the configured artifact is not valid UTF-8.");
+    }
+    const scan = scanChangelogHeadings(text);
+    if (scan.identityBoundExceeded)
+        return fixedBoundFailure();
+    const incomplete = scan.status === "incomplete";
+    return projectionResult({
+        schemaVersion: "agentera.changelogRead.v1",
+        command: "changelog",
+        status: scan.status,
+        recognized_headings: scan.recognizedHeadings,
+        recognized_release_count: scan.recognizedReleaseCount,
+        unreleased_present: scan.unreleasedHeading !== null,
+        latest_release_heading: scan.latestReleaseHeading,
+        boundary_present: scan.boundary !== null,
+        boundary: scan.boundary,
+        source: source(relativePath),
+        source_provenance: provenance(),
+        caveats: incomplete
+            ? ["CHANGELOG headings are incomplete or ambiguous; use one optional Unreleased heading and distinct Keep a Changelog release headings only."]
+            : [],
+        recovery: incomplete ? RECOVERY : null,
+    }, scan.recognizedReleaseVersions);
+}
+//# sourceMappingURL=changelog.js.map

package/dist/state/changelog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../../../../home/jgabor/git/agentera.release-publish-dev40/packages/cli/src/state/changelog.ts"],"names":[],"mappings":"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"}

package/dist/state/decisionEntities.js

@@ -0,0 +1,368 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { canonicalRecordJson, decisionOverlayContract } from "./archiveDiscovery.js";
+import { requestedSatisfaction, validateTransition } from "./decisionOverlay.js";
+import { decisionRevisionContract } from "./decisionRevision.js";
+import { decisionLegacyCoexistence, knownLegacyConfidenceCaveat } from "./decisionLegacyValidation.js";
+import { StateRetrievalFailure } from "./directRetrieval.js";
+import { allocateAndPublishEntity, allocateEntityId, assertEntityDiscoveryOrigin, discoverEntities, exactDiscoveredEntityBytes, publishEntity, replaceEntity, withEntityWriterLock } from "./entityStorage.js";
+import { localDate } from "./write/assign.js";
+import { detailMetadata, detailProvenance, isSummaryEntity } from "./summaryEntityRead.js";
+import { decodeListCursor, encodeListCursor, projectedListSnapshot } from "./listCursor.js";
+import { loadStateStorageAuthority } from "./stateStorageAuthority.js";
+import { entityListSelectorFlags, entityListSelectorKey, projectEntityList, resolveEntityListSelector } from "./entityListProjection.js";
+import { shellQuoteArgument } from "../core/shell.js";
+import { normalizeDecisionRecordInput } from "./write/input.js";
+import { detectStateModeBinding } from "./stateMode.js";
+const ARTIFACT = "decisions";
+const BASE = "decision";
+const SUMMARY = "decision_summary";
+const SATISFACTION = "decision_satisfaction";
+const REVISION = "decision_revision";
+const ORDER = "date_desc_then_id_asc";
+const ID_PATTERN = /^[a-z]{10}$/;
+function mapping(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function requiredText(value, field) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`decision entity requires ${field}`);
+    return value;
+}
+function contract(sourceRoot = resolveSourceRoot()) {
+    const { authorityPath, document: authority } = loadStateStorageAuthority(sourceRoot);
+    const target = mapping(authority.entity_target) ? authority.entity_target : {};
+    const storage = mapping(target.storage_boundary) && mapping(target.storage_boundary.shared_primitives) ? target.storage_boundary.shared_primitives : {};
+    const entities = Array.isArray(target.entities) ? target.entities : [];
+    const base = entities.find((value) => mapping(value) && value.boundary === BASE);
+    const retrieval = mapping(base) && mapping(base.retrieval) ? base.retrieval : {};
+    const number = (value, field) => {
+        const result = Number(value);
+        if (!Number.isSafeInteger(result) || result < 1)
+            throw new Error(`invalid decisions entity ${field} authority`);
+        return result;
+    };
+    return { authorityPath, entityRoot: requiredText(storage.canonical_root, "canonical_root"), defaultLimit: number(retrieval.default_limit, "default_limit"), maximumLimit: number(retrieval.maximum_limit, "maximum_limit"), maxUtf8Bytes: number(retrieval.max_utf8_bytes, "max_utf8_bytes") };
+}
+function failure(kind, message, recovery, id) {
+    return new StateRetrievalFailure({ schemaVersion: "agentera.stateFailure.v1", status: "fail", error: { class: kind, message, syntax: "agentera state decisions get --id ID --format json", example: `agentera state decisions get --id ${id ?? "qjtrmnpvka"} --format json`, recovery, artifact: ARTIFACT, ...(id ? { id } : {}) } }, kind === "invalid_request" ? 2 : 1);
+}
+function summaryMutationFailure(id, verb) {
+    const syntax = verb === "amend"
+        ? "agentera state decisions amend --id ID --base-sha256 SHA256 --input PATH --format json"
+        : "agentera state decisions update --id ID --satisfaction-state STATE --format json";
+    return new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: "unsupported_state",
+            message: `decision '${id}' is an immutable migrated summary: incomplete historical evidence is read-only`,
+            syntax,
+            example: `agentera state decisions get --id ${id} --format json`,
+            recovery: `Run agentera state decisions get --id ${id} --format json to inspect retained evidence and caveats. For new deliberation, run agentera state decisions append --input decision.yaml --format json.`,
+            artifact: ARTIFACT,
+            id,
+        },
+    }, 1);
+}
+function relative(root, file) { return path.relative(path.resolve(root), file).split(path.sep).join("/"); }
+function entityRecord(values) {
+    const alternatives = mapping(values.alternatives) ? values.alternatives : {};
+    const chosen = requiredText(alternatives.chosen, "alternatives.chosen");
+    const rejected = Array.isArray(alternatives.rejected) ? alternatives.rejected.map(String) : [];
+    const record = {
+        date: typeof values.date === "string" ? values.date : localDate(),
+        question: requiredText(values.question, "question"),
+        context: requiredText(values.context, "context"),
+        alternatives: [{ name: chosen, status: "chosen" }, ...rejected.map((name) => ({ name, status: "rejected" }))],
+        choice: requiredText(values.choice, "choice"), reasoning: requiredText(values.reasoning, "reasoning"), confidence: requiredText(values.confidence, "confidence"),
+    };
+    if (typeof values.feeds_into === "string")
+        record.feeds_into = values.feeds_into;
+    return record;
+}
+function envelope(command, published, record, dryRun = false) {
+    return { schemaVersion: "agentera.stateWrite.v1", command, status: "pass", path: published.path, id: published.id, artifact: published.artifact, record, operation: { verb: command.split(" ").at(-1), dry_run: dryRun, idempotent_replay: published.replay }, validation: { status: "pass", violations: [] } };
+}
+function publish(req, boundary, record, options) {
+    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    if (req.dryRun) {
+        const id = options.id ?? allocateEntityId(options.publicationContext?.pinnedPath() ?? req.projectRoot, options.candidate, sourceRoot);
+        return envelope(`state decisions ${req.spec.verb}`, { id, artifact: ARTIFACT, path: path.join(req.projectRoot, contract(sourceRoot).entityRoot, ARTIFACT, boundary, `${id}.yaml`), replay: false }, record, true);
+    }
+    const result = options.id
+        ? publishEntity({ projectRoot: req.projectRoot, sourceRoot, publicationContext: options.publicationContext, artifact: ARTIFACT, boundary, id: options.id, record })
+        : allocateAndPublishEntity({ projectRoot: req.projectRoot, sourceRoot, publicationContext: options.publicationContext, artifact: ARTIFACT, boundary, record }, options.candidate);
+    return envelope(`state decisions ${req.spec.verb}`, result, record);
+}
+function decisionLogicalReplay(root, sourceRoot, record) {
+    return discoverEntities(root, sourceRoot).entities.find((entity) => entity.artifact === ARTIFACT
+        && entity.boundary === BASE
+        && entity.classification === "valid"
+        && entity.record
+        && canonicalRecordJson(entity.record) === canonicalRecordJson(record));
+}
+function appendDecisionEntityUnderLock(req, options, record) {
+    if (!options.id) {
+        const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+        const replay = decisionLogicalReplay(options.publicationContext?.pinnedPath() ?? req.projectRoot, sourceRoot, record);
+        if (replay?.record) {
+            return envelope("state decisions append", { id: replay.id, artifact: ARTIFACT, path: replay.path, replay: true }, replay.record, req.dryRun);
+        }
+    }
+    return publish(req, BASE, record, options);
+}
+export function appendDecisionEntity(req, options = {}) {
+    const record = entityRecord(req.input ? normalizeDecisionRecordInput(req.input) : req.values);
+    if (options.id || options.publicationContext) {
+        if (!options.id && options.publicationContext)
+            return withEntityWriterLock(options.publicationContext, () => appendDecisionEntityUnderLock(req, options, record));
+        return publish(req, BASE, record, options);
+    }
+    if (req.dryRun)
+        return publish(req, BASE, record, options);
+    const binding = detectStateModeBinding(req.projectRoot, options.sourceRoot);
+    if (binding.mode !== "entities")
+        throw new Error("decision publication requires the durable entity-mode marker; legacy mode remains authoritative");
+    try {
+        return withEntityWriterLock(binding.publicationContext, () => appendDecisionEntityUnderLock(req, { ...options, publicationContext: binding.publicationContext }, record));
+    }
+    finally {
+        binding.publicationContext.close();
+    }
+}
+function decisionEntities(root, sourceRoot, supplied) {
+    if (supplied)
+        assertEntityDiscoveryOrigin(root, sourceRoot, supplied);
+    const discovery = supplied ?? discoverEntities(root, sourceRoot);
+    const relevant = discovery.entities.filter((entity) => entity.artifact === ARTIFACT || [BASE, SUMMARY, SATISFACTION, REVISION].includes(entity.boundary ?? ""));
+    const bad = relevant.find((entity) => entity.classification !== "valid" || !entity.id || !entity.record);
+    if (bad)
+        throw failure(bad.classification === "duplicate" ? "ambiguous" : "corrupt", `decision entity '${bad.relativePath}' is not canonical`, "Run agentera check validate state, preserve conflicting values, and repair the entity files.", bad.id ?? undefined);
+    return relevant;
+}
+function baseFor(root, id, sourceRoot, mutation) {
+    if (!ID_PATTERN.test(id))
+        throw failure("invalid_request", `decision ID '${id}' must be ten lowercase letters`, "Use an ID returned by decisions append or list.", id);
+    const all = decisionEntities(root, sourceRoot);
+    const summary = all.find((entity) => entity.id === id && entity.boundary === SUMMARY);
+    if (summary)
+        throw mutation ? summaryMutationFailure(id, mutation) : failure("unsupported_state", `decision '${id}' is an immutable migrated summary: incomplete historical evidence is read-only`, "Use agentera state decisions get --id " + id + " --format json to inspect its retained caveat and provenance.", id);
+    const matches = all.filter((entity) => entity.id === id && entity.boundary === BASE);
+    if (matches.length !== 1)
+        throw failure(matches.length ? "ambiguous" : "not_found", matches.length ? `decision ID '${id}' has multiple base entities` : `decision ID '${id}' was not found`, "Run agentera check validate state and resolve duplicate ownership, or use an ID returned by list.", id);
+    return { base: matches[0], all };
+}
+export function applyDecisionChanges(record, changes) {
+    const result = structuredClone(record);
+    for (const [field, value] of Object.entries(changes)) {
+        if (field === "alternatives") {
+            result.alternatives = structuredClone(value);
+        }
+        else if (field === "alternatives.chosen" || field === "alternatives.rejected") {
+            const alternatives = Array.isArray(result.alternatives) ? structuredClone(result.alternatives).filter(mapping) : [];
+            if (field.endsWith("chosen")) {
+                const chosen = alternatives.find((entry) => entry.status === "chosen");
+                if (chosen)
+                    chosen.name = structuredClone(value);
+                else
+                    alternatives.unshift({ name: structuredClone(value), status: "chosen" });
+            }
+            else {
+                const names = Array.isArray(value) ? value.map(String) : [String(value)];
+                for (const name of names)
+                    if (!alternatives.some((entry) => entry.status === "rejected" && entry.name === name))
+                        alternatives.push({ name, status: "rejected" });
+            }
+            result.alternatives = alternatives;
+        }
+        else
+            result[field] = structuredClone(value);
+    }
+    return result;
+}
+function compose(root, base, all, sourceRoot) {
+    let effective = structuredClone(base.record);
+    let hash = createHash("sha256").update(canonicalRecordJson(effective)).digest("hex");
+    let legacyConfidenceEvidence = base.migrationProvenance?.kind === "inherited_decision_confidence"
+        && base.migrationProvenance.confidence === effective.confidence;
+    const revisions = [];
+    const candidates = all.filter((entity) => entity.boundary === REVISION && entity.record?.decision === base.id);
+    const unused = new Set(candidates);
+    while (true) {
+        const next = [...unused].filter((entity) => entity.record?.base_sha256 === hash);
+        if (next.length > 1)
+            throw failure("ambiguous", `decision '${base.id}' has competing revisions for base ${hash}`, "Preserve both revision entities and resolve their ownership explicitly.", base.id);
+        if (next.length === 0)
+            break;
+        const revision = next[0];
+        unused.delete(revision);
+        if (!mapping(revision.record.changes))
+            throw failure("corrupt", `decision revision '${revision.id}' has invalid changes`, "Repair the canonical revision entity.", base.id);
+        if ("confidence" in revision.record.changes) {
+            legacyConfidenceEvidence = revision.migrationProvenance?.kind === "inherited_decision_revision_confidence"
+                && revision.migrationProvenance.confidence === revision.record.changes.confidence;
+        }
+        effective = applyDecisionChanges(effective, revision.record.changes);
+        hash = createHash("sha256").update(canonicalRecordJson(effective)).digest("hex");
+        revisions.push({ id: revision.id, artifact: ARTIFACT, base_sha256: revision.record.base_sha256, effective_sha256: hash, fields: Object.keys(revision.record.changes), path: relative(root, revision.path) });
+    }
+    if (unused.size)
+        throw failure("ambiguous", `decision '${base.id}' has stale or disconnected revision ownership`, "Preserve every revision and repair the revision chain explicitly.", base.id);
+    const satisfactions = all.filter((entity) => entity.boundary === SATISFACTION && entity.record?.decision === base.id);
+    if (satisfactions.length > 1)
+        throw failure("ambiguous", `decision '${base.id}' has competing satisfaction owners`, "Preserve both satisfaction entities and resolve ownership explicitly.", base.id);
+    let satisfactionProvenance = null;
+    if (satisfactions[0]) {
+        const { decision: _decision, ...satisfaction } = satisfactions[0].record;
+        effective.satisfaction = satisfaction;
+        satisfactionProvenance = { id: satisfactions[0].id, artifact: ARTIFACT, path: relative(root, satisfactions[0].path) };
+    }
+    const inherited = base.migrationProvenance;
+    const caveatSource = inherited?.source === "verified_archive" ? "archive" : "active";
+    const legacyCaveat = legacyConfidenceEvidence
+        ? knownLegacyConfidenceCaveat(effective, decisionLegacyCoexistence(sourceRoot), caveatSource)
+        : null;
+    return { id: base.id, artifact: ARTIFACT, ...detailMetadata(base), record: effective, effective_sha256: hash, provenance: { ...detailProvenance(relative(root, base.path), base), base: { id: base.id, artifact: ARTIFACT, path: relative(root, base.path), ...(inherited ? { migration_provenance: inherited } : {}) }, revisions, satisfaction: satisfactionProvenance }, ...(legacyCaveat ? { caveats: [legacyCaveat.caveat] } : {}), retrieval: { get: `agentera state decisions get --id ${base.id} --format json` } };
+}
+export function getDecisionEntity(root, id, sourceRoot = resolveSourceRoot()) {
+    if (!ID_PATTERN.test(id))
+        throw failure("invalid_request", `decision ID '${id}' must be ten lowercase letters`, "Use an ID returned by decisions append or list.", id);
+    const all = decisionEntities(root, sourceRoot);
+    const summary = all.filter((entity) => entity.id === id && entity.boundary === SUMMARY);
+    const bases = all.filter((entity) => entity.id === id && entity.boundary === BASE);
+    if (summary.length || bases.length > 1) {
+        if (summary.length !== 1 || bases.length)
+            throw failure("ambiguous", `decision ID '${id}' has multiple base entities`, "Run agentera check validate state and resolve duplicate ownership.", id);
+        const entity = summary[0];
+        return { schemaVersion: "agentera.stateRetrieval.v1", command: "state decisions get", status: "degraded", entry: { id, artifact: ARTIFACT, ...detailMetadata(entity), record: entity.record, provenance: detailProvenance(relative(root, entity.path), entity), retrieval: { get: `agentera state decisions get --id ${id} --format json` } }, source: { artifact: ARTIFACT, authority: "canonical_entity_files" }, source_contract: { authority: "references/artifacts/state-storage-authority.yaml", detail: "summary" } };
+    }
+    if (bases.length !== 1)
+        throw failure("not_found", `decision ID '${id}' was not found`, "Run agentera state decisions list --format json and retry with a returned ID.", id);
+    return { schemaVersion: "agentera.stateRetrieval.v1", command: "state decisions get", status: "ok", entry: compose(root, bases[0], all, sourceRoot), source: { artifact: ARTIFACT, authority: "canonical_entity_files" }, source_contract: { authority: "references/artifacts/state-storage-authority.yaml", detail: "full" } };
+}
+export function updateDecisionSatisfactionEntity(req, options = {}) {
+    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    const id = requiredText(req.values.id, "id");
+    const { all } = baseFor(req.projectRoot, id, sourceRoot, "update");
+    const owners = all.filter((entity) => entity.boundary === SATISFACTION && entity.record?.decision === id);
+    if (owners.length > 1)
+        throw failure("ambiguous", `decision '${id}' has competing satisfaction owners`, "Preserve both entities and resolve ownership explicitly.", id);
+    const requested = requestedSatisfaction(mapping(req.values.satisfaction) ? req.values.satisfaction : {}, decisionOverlayContract(sourceRoot));
+    const current = owners[0];
+    const historical = current ? { ...current.record } : undefined;
+    if (mapping(historical))
+        delete historical.decision;
+    validateTransition(requested, historical ? { satisfaction: historical } : undefined, undefined, decisionOverlayContract(sourceRoot));
+    const record = { decision: id, ...requested };
+    if (!current)
+        return publish(req, SATISFACTION, record, options);
+    if (req.dryRun)
+        return envelope("state decisions update", { id: current.id, artifact: ARTIFACT, path: current.path, replay: canonicalRecordJson(current.record) === canonicalRecordJson(record) }, record, true);
+    const result = replaceEntity({ projectRoot: req.projectRoot, sourceRoot, publicationContext: options.publicationContext, artifact: ARTIFACT, boundary: SATISFACTION, id: current.id, expectedRecord: current.record, expectedBytes: exactDiscoveredEntityBytes(current), migrationProvenance: current.migrationProvenance, record });
+    return envelope("state decisions update", result, record);
+}
+export function amendDecisionEntity(req, options = {}) {
+    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    const id = requiredText(req.values.id, "id");
+    const expected = requiredText(req.values.base_sha256, "base_sha256");
+    const allowed = new Set(decisionRevisionContract(sourceRoot).amendablePaths);
+    const content = req.input ? normalizeDecisionRecordInput(req.input) : req.values;
+    const changes = {};
+    for (const [field, value] of Object.entries(content))
+        if (!["id", "base_sha256"].includes(field)) {
+            if (field === "alternatives" && mapping(value)) {
+                for (const [name, alternative] of Object.entries(value)) {
+                    const target = `alternatives.${name}`;
+                    if (!allowed.has(target))
+                        throw failure("invalid_request", `'${target}' is not amendable decision content`, "Use only authority-declared content fields.", id);
+                    changes[target] = structuredClone(alternative);
+                }
+            }
+            else {
+                if (!allowed.has(field) || field === "satisfaction")
+                    throw failure("invalid_request", `'${field}' is not amendable decision content`, "Use only authority-declared content fields; update satisfaction separately.", id);
+                changes[field] = structuredClone(value);
+            }
+        }
+    if (!Object.keys(changes).length)
+        throw failure("invalid_request", "decision amendment requires at least one content field", "Supply one amendable content field.", id);
+    const { all } = baseFor(req.projectRoot, id, sourceRoot, "amend");
+    const existingClaims = all.filter((entity) => entity.boundary === REVISION && entity.record?.decision === id && entity.record?.base_sha256 === expected);
+    const replay = existingClaims.find((entity) => canonicalRecordJson(entity.record?.changes) === canonicalRecordJson(changes));
+    if (replay)
+        return envelope("state decisions amend", { id: replay.id, artifact: ARTIFACT, path: replay.path, replay: true }, replay.record, req.dryRun);
+    if (existingClaims.length)
+        throw failure("immutable_conflict", `decision '${id}' already has a divergent revision for requested base ${expected}`, "Preserve both requested values and resolve the same-base amendment explicitly.", id);
+    const current = getDecisionEntity(req.projectRoot, id, sourceRoot).entry;
+    if (current.effective_sha256 !== expected)
+        throw failure("immutable_conflict", `decision '${id}' changed from requested base ${expected}`, "Get the decision again, review the effective provenance, and retry with its current effective_sha256.", id);
+    const effective = current.record;
+    const projected = applyDecisionChanges(effective, changes);
+    if (canonicalRecordJson(projected) === canonicalRecordJson(effective))
+        return { schemaVersion: "agentera.stateWrite.v1", command: "state decisions amend", status: "pass", path: String(current.provenance.base.path), id, artifact: ARTIFACT, record: changes, operation: { verb: "amend", dry_run: req.dryRun, idempotent_replay: true }, validation: { status: "pass", violations: [] } };
+    return publish(req, REVISION, { decision: id, date: localDate(), provenance: "historical_revision", base_sha256: expected, changes }, options);
+}
+function key(entity) { return `${String(entity.record.date ?? "")}\0${entity.id}`; }
+function listEntry(root, entity, all, sourceRoot) {
+    return entity.boundary === SUMMARY
+        ? { id: entity.id, artifact: ARTIFACT, ...detailMetadata(entity), record: entity.record, provenance: detailProvenance(relative(root, entity.path), entity), retrieval: { get: `agentera state decisions get --id ${entity.id} --format json` } }
+        : compose(root, entity, all, sourceRoot);
+}
+function snapshot(root, bases, all, sourceRoot, topic, entityRoot) {
+    return projectedListSnapshot({
+        schemaVersion: "agentera.stateList.v1",
+        command: "state decisions list",
+        order: ORDER,
+        filters: { topic: topic ?? null },
+        source: { artifact: ARTIFACT, authority: "canonical_entity_files", root: entityRoot },
+        source_contract: { authority: "references/artifacts/state-storage-authority.yaml", detail: bases.some(isSummaryEntity) ? "mixed" : "full", cursor: "opaque_snapshot_cursor" },
+        entries: bases.map((entity) => listEntry(root, entity, all, sourceRoot)),
+    });
+}
+function encode(payload, root, authorityPath) { return encodeListCursor(payload, root, authorityPath); }
+function decode(token, root, authorityPath) {
+    try {
+        return decodeListCursor(token, root, authorityPath);
+    }
+    catch {
+        throw failure("cursor_invalid", "decisions cursor is malformed or belongs to another project", "Copy next_cursor exactly, or omit --cursor to restart.");
+    }
+}
+export function listDecisionEntities(root, limit, topic, cursor, options = {}) {
+    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    const declared = contract(sourceRoot);
+    const effectiveLimit = limit ?? declared.defaultLimit;
+    if (!Number.isSafeInteger(effectiveLimit) || effectiveLimit < 1 || effectiveLimit > declared.maximumLimit)
+        throw failure("invalid_request", `decisions list limit must be 1..${declared.maximumLimit}`, "Use a limit in the declared range.");
+    const all = decisionEntities(root, sourceRoot, options.discovery);
+    let bases = all.filter((entity) => [BASE, SUMMARY].includes(entity.boundary ?? "")).sort((a, b) => String(b.record.date ?? "").localeCompare(String(a.record.date ?? "")) || a.id.localeCompare(b.id));
+    if (topic) {
+        const needle = topic.toLowerCase();
+        bases = bases.filter((entity) => canonicalRecordJson(entity.record).toLowerCase().includes(needle));
+    }
+    const format = options.format ?? "json";
+    const projectionOptions = { family: "decisions", artifact: ARTIFACT, boundary: BASE, format, maxUtf8Bytes: declared.maxUtf8Bytes, selector: options.selector };
+    const selector = resolveEntityListSelector(options.selector, bases.map((entity) => listEntry(root, entity, all, sourceRoot)), projectionOptions);
+    const selectorKey = entityListSelectorKey(selector);
+    const snap = snapshot(root, bases, all, sourceRoot, topic, declared.entityRoot);
+    let start = 0;
+    if (cursor) {
+        const value = decode(cursor, root, declared.authorityPath);
+        if (value.selector !== selectorKey)
+            throw failure("cursor_invalid", "decisions cursor selectors do not match this request", "Repeat the original selector, or omit --cursor to restart from the current snapshot.");
+        if (value.version !== 1 || value.artifact !== ARTIFACT || value.order !== ORDER || value.snapshot_id !== snap || value.topic !== (topic ?? null))
+            throw failure("cursor_snapshot_unavailable", "decisions state or filters changed after this cursor snapshot", "Repeat the original filters, or omit --cursor to restart from the current snapshot.");
+        const found = bases.findIndex((entity) => key(entity) === value.after_key);
+        if (found < 0)
+            throw failure("cursor_snapshot_unavailable", "decisions cursor continuation is unavailable", "Omit --cursor to restart.");
+        start = found + 1;
+    }
+    const selected = bases.slice(start, start + effectiveLimit);
+    const remaining = bases.length - start - selected.length;
+    const next = remaining && selected.length ? encode({ version: 1, artifact: ARTIFACT, order: ORDER, snapshot_id: snap, selector: selectorKey, topic: topic ?? null, after_key: key(selected.at(-1)) }, root, declared.authorityPath) : undefined;
+    const selectorFlags = entityListSelectorFlags(selector);
+    const filterFlags = topic ? ` --topic ${shellQuoteArgument(topic)}` : "";
+    const response = { schemaVersion: "agentera.stateList.v1", command: "state decisions list", status: remaining || bases.some(isSummaryEntity) ? "degraded" : "ok", entries: selected.map((entity) => listEntry(root, entity, all, sourceRoot)), counts: { total: bases.length, returned: selected.length, remaining }, filters: { topic: topic ?? null }, snapshot: { id: snap, first_page: !cursor, order: ORDER, has_more: Boolean(remaining), candidate_count: bases.length }, source: { artifact: ARTIFACT, authority: "canonical_entity_files", root: declared.entityRoot }, source_contract: { authority: "references/artifacts/state-storage-authority.yaml", detail: bases.some(isSummaryEntity) ? "mixed" : "full", cursor: "opaque_snapshot_cursor" }, retrieval: { ...(next ? { continue: `agentera state decisions list${filterFlags}${selectorFlags} --limit ${effectiveLimit} --cursor ${next} --format json` } : {}) }, ...(remaining ? { omitted: true, omitted_count: remaining, omission_reason: "page_limit", next_cursor: next } : {}) };
+    return projectEntityList(response, selector, projectionOptions);
+}
+//# sourceMappingURL=decisionEntities.js.map