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

package/dist/state/decisionRevision.js

@@ -0,0 +1,256 @@
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { loadStateStorageAuthority } from "./stateStorageAuthority.js";
+const EXPECTED_AUTHORITY_SCHEMA = "agentera.stateStorageAuthority.v1";
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function requiredString(value, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`state storage authority field '${field}' must be a non-empty string`);
+    }
+    return value;
+}
+function requiredList(value, field) {
+    if (!Array.isArray(value) ||
+        value.some((item) => typeof item !== "string" || item.length === 0)) {
+        throw new Error(`state storage authority field '${field}' must be a list of non-empty strings`);
+    }
+    return value;
+}
+function readAuthority(sourceRoot) {
+    const authority = loadStateStorageAuthority(sourceRoot).document;
+    if (authority.schema_version !== EXPECTED_AUTHORITY_SCHEMA) {
+        throw new Error("state storage authority schema_version is unsupported");
+    }
+    if (authority.status !== "active_authority") {
+        throw new Error("state storage authority must be active_authority");
+    }
+    return authority;
+}
+function overlayCrossCheck(authority) {
+    const overlays = mapping(authority.overlays);
+    const identityKey = requiredString(overlays.identity_key, "overlays.identity_key");
+    const identityPrefix = identityKey.split(":")[0];
+    if (!identityPrefix || identityKey !== `${identityPrefix}:<decision-number>`) {
+        throw new Error("state storage authority overlays.identity_key is unsupported");
+    }
+    return {
+        identityPrefix,
+        mutablePaths: requiredList(overlays.mutable_paths, "overlays.mutable_paths"),
+    };
+}
+export function decisionRevisionContract(sourceRoot = resolveSourceRoot()) {
+    const authority = readAuthority(sourceRoot);
+    const revisions = mapping(authority.revisions);
+    if (Object.keys(revisions).length === 0) {
+        throw new Error("state storage authority revisions section is required");
+    }
+    const location = requiredString(revisions.location, "revisions.location");
+    if (path.isAbsolute(location) || location.split(/[\\/]/).some((part) => part === "..")) {
+        throw new Error("state storage authority revisions location must be project-relative");
+    }
+    const identityKey = requiredString(revisions.identity_key, "revisions.identity_key");
+    const identityPrefix = identityKey.split(":")[0];
+    if (!identityPrefix || identityKey !== `${identityPrefix}:<decision-number>`) {
+        throw new Error("state storage authority revisions identity_key is unsupported");
+    }
+    const overlay = overlayCrossCheck(authority);
+    if (identityPrefix !== overlay.identityPrefix) {
+        throw new Error("state storage authority revisions identity_key prefix must match the overlay identity");
+    }
+    const amendablePaths = requiredList(revisions.amendable_paths, "revisions.amendable_paths");
+    const legacyAmendablePaths = requiredList(revisions.legacy_amendable_paths, "revisions.legacy_amendable_paths");
+    const migrationAmendablePaths = requiredList(revisions.migration_amendable_paths, "revisions.migration_amendable_paths");
+    const identityPaths = requiredList(revisions.identity_paths, "revisions.identity_paths");
+    const temporalPaths = requiredList(revisions.temporal_paths, "revisions.temporal_paths");
+    const reserved = new Set([...identityPaths, ...temporalPaths]);
+    for (const [field, paths] of [["amendable_paths", amendablePaths], ["legacy_amendable_paths", legacyAmendablePaths], ["migration_amendable_paths", migrationAmendablePaths]]) {
+        for (const amendable of paths) {
+            if (reserved.has(amendable)) {
+                throw new Error(`state storage authority revisions.${field} must not include identity or temporal path '${amendable}'`);
+            }
+            if (overlay.mutablePaths.some((mutable) => amendable === mutable || amendable.startsWith(`${mutable}.`))) {
+                throw new Error(`state storage authority revisions.${field} must not overlap overlay mutable path '${amendable}'`);
+            }
+        }
+    }
+    return {
+        location,
+        legacySourceState: requiredString(revisions.legacy_source_state, "revisions.legacy_source_state"),
+        schemaVersion: requiredString(revisions.schema_version, "revisions.schema_version"),
+        identityKey,
+        identityPrefix,
+        amendablePaths,
+        legacyAmendablePaths,
+        migrationAmendablePaths,
+        currentConfidenceVocabulary: requiredList(mapping(mapping(authority.compatibility).legacy_label_coexistence).current_vocabulary, "compatibility.legacy_label_coexistence.current_vocabulary"),
+        knownLegacyConfidenceValues: requiredList(mapping(mapping(authority.compatibility).legacy_label_coexistence).known_legacy_examples, "compatibility.legacy_label_coexistence.known_legacy_examples"),
+        identityPaths,
+        temporalPaths,
+        separationFromOverlay: requiredString(revisions.separation_from_overlay, "revisions.separation_from_overlay"),
+        immutability: requiredString(revisions.immutability, "revisions.immutability"),
+        provenance: requiredString(revisions.provenance, "revisions.provenance"),
+        publicationOrder: requiredList(revisions.publication_order, "revisions.publication_order"),
+        applyState: requiredString(revisions.apply_state, "revisions.apply_state"),
+        applyStateNote: requiredString(revisions.apply_state_note, "revisions.apply_state_note"),
+    };
+}
+export function legacyLabelCoexistence(sourceRoot = resolveSourceRoot()) {
+    const authority = readAuthority(sourceRoot);
+    const compatibility = mapping(authority.compatibility);
+    const coexistence = mapping(compatibility.legacy_label_coexistence);
+    if (Object.keys(coexistence).length === 0) {
+        throw new Error("state storage authority compatibility.legacy_label_coexistence section is required");
+    }
+    const currentVocabulary = requiredList(coexistence.current_vocabulary, "compatibility.legacy_label_coexistence.current_vocabulary");
+    if (currentVocabulary.length === 0) {
+        throw new Error("state storage authority legacy_label_coexistence.current_vocabulary must be non-empty");
+    }
+    return {
+        dimensions: requiredList(coexistence.dimensions, "compatibility.legacy_label_coexistence.dimensions"),
+        currentVocabulary,
+        currentVocabularyRef: requiredString(coexistence.current_vocabulary_ref, "compatibility.legacy_label_coexistence.current_vocabulary_ref"),
+        knownLegacyExamples: requiredList(coexistence.known_legacy_examples, "compatibility.legacy_label_coexistence.known_legacy_examples"),
+        classificationRule: requiredString(coexistence.classification_rule, "compatibility.legacy_label_coexistence.classification_rule"),
+        noSilentNormalization: requiredString(coexistence.no_silent_normalization, "compatibility.legacy_label_coexistence.no_silent_normalization"),
+    };
+}
+export function classifyConfidenceLabel(contract, value, touched) {
+    const vocabulary = contract.currentVocabulary.join(", ");
+    if (contract.currentVocabulary.includes(value)) {
+        return { classification: "current", allowed: true, caveat: "" };
+    }
+    if (!touched) {
+        return {
+            classification: "explicit_legacy",
+            allowed: true,
+            caveat: `inherited unsupported confidence label '${value}' is explicit legacy state; current vocabulary is ${vocabulary}`,
+        };
+    }
+    return {
+        classification: "rejected",
+        allowed: false,
+        caveat: `confidence label '${value}' requires current vocabulary (${vocabulary}) for new or amended content`,
+    };
+}
+export const REVISION_PROVENANCE_VALUES = ["historical_revision", "degraded_projection"];
+const REVISION_META_KEYS = new Set(["date", "provenance", "base_sha256"]);
+const FORBIDDEN_REVISION_PROVENANCE = "historical_archive";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+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 decisionRevisionViolations(document, contract = decisionRevisionContract()) {
+    if (!isRecord(document)) {
+        return ["decision revision root must be a mapping keyed by stable decision ID"];
+    }
+    const amendable = new Set(contract.legacyAmendablePaths);
+    const allowed = new Set([...REVISION_META_KEYS, ...contract.legacyAmendablePaths]);
+    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;
+        }
+        if (!Array.isArray(value)) {
+            violations.push(`${stableId} must be an ordered list of revision records`);
+            continue;
+        }
+        value.forEach((revision, index) => {
+            violations.push(...decisionRevisionRecordViolations(revision, `${stableId}[${index}]`, contract, allowed, amendable, contract.legacyAmendablePaths, true));
+        });
+    }
+    return violations;
+}
+function decisionRevisionRecordViolations(revision, label, contract, allowed = new Set([...REVISION_META_KEYS, ...contract.amendablePaths, ...contract.migrationAmendablePaths]), amendable = new Set([...contract.amendablePaths, ...contract.migrationAmendablePaths]), amendablePaths = [...contract.amendablePaths, ...contract.migrationAmendablePaths], legacy = false, allowLegacyConfidence = false) {
+    if (!isRecord(revision))
+        return [`${label} must be a mapping of amendable fields and revision provenance`];
+    const violations = [];
+    for (const key of Object.keys(revision)) {
+        if (!allowed.has(key))
+            violations.push(`${label} carries '${key}' which is not an amendable content path or revision meta key`);
+    }
+    if ("alternatives" in revision && ("alternatives.chosen" in revision || "alternatives.rejected" in revision)) {
+        violations.push(`${label} must not mix migration-only alternatives replacement with granular alternative changes`);
+    }
+    for (const key of amendable) {
+        if (!(key in revision))
+            continue;
+        const value = revision[key];
+        if (key === "alternatives") {
+            const alternatives = Array.isArray(value) ? value : [];
+            const malformed = !Array.isArray(value)
+                || alternatives.length === 0
+                || alternatives.some((entry) => {
+                    const candidate = isRecord(entry) ? entry : {};
+                    return typeof candidate.name !== "string"
+                        || candidate.name.length === 0
+                        || !["chosen", "rejected"].includes(String(candidate.status));
+                })
+                || alternatives.filter((entry) => isRecord(entry) && entry.status === "chosen").length !== 1;
+            if (malformed) {
+                violations.push(`${label}.alternatives must be a non-empty list with exactly one named chosen alternative and zero or more named rejected alternatives`);
+            }
+        }
+        else if (key === "alternatives.rejected") {
+            if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.length === 0)) {
+                violations.push(`${label}.alternatives.rejected must be a list of non-empty strings`);
+            }
+        }
+        else if (typeof value !== "string" || value.length === 0) {
+            violations.push(`${label}.${key} must be a non-empty string`);
+        }
+        else if (key === "confidence" && !legacy && !contract.currentConfidenceVocabulary.includes(value) && !(allowLegacyConfidence && contract.knownLegacyConfidenceValues.includes(value))) {
+            violations.push(`${label}.confidence '${value}' is not one of: ${contract.currentConfidenceVocabulary.join(", ")}`);
+        }
+    }
+    const provenance = revision.provenance;
+    if (provenance !== undefined) {
+        if (typeof provenance !== "string")
+            violations.push(`${label}.provenance must be a string`);
+        else if (provenance === FORBIDDEN_REVISION_PROVENANCE)
+            violations.push(`${label}.provenance must never claim historical_archive provenance`);
+        else if (!REVISION_PROVENANCE_VALUES.includes(provenance)) {
+            violations.push(`${label}.provenance '${provenance}' is not one of: ${REVISION_PROVENANCE_VALUES.join(", ")}`);
+        }
+    }
+    const baseSha = revision.base_sha256;
+    if (baseSha !== undefined && (typeof baseSha !== "string" || !/^[0-9a-f]{64}$/.test(baseSha))) {
+        violations.push(`${label}.base_sha256 must be a 64-character sha256 hex digest`);
+    }
+    const date = revision.date;
+    if (date !== undefined && (typeof date !== "string" || date.length === 0)) {
+        violations.push(`${label}.date must be a non-empty string`);
+    }
+    if (!Object.keys(revision).some((key) => amendable.has(key))) {
+        violations.push(`${label} must amend at least one content field (${amendablePaths.join(", ")})`);
+    }
+    return violations;
+}
+export function decisionRevisionEntityViolations(record, contract = decisionRevisionContract(), allowLegacyConfidence = false) {
+    if (!isRecord(record.changes))
+        return ["decision revision changes must be a mapping of amendable fields"];
+    const amendable = new Set([...contract.amendablePaths, ...contract.migrationAmendablePaths]);
+    const violations = Object.keys(record.changes)
+        .filter((key) => !amendable.has(key))
+        .map((key) => `decision revision changes carries '${key}' which is not an amendable content path`);
+    violations.push(...decisionRevisionRecordViolations({
+        ...record.changes,
+        date: record.date,
+        provenance: record.provenance,
+        base_sha256: record.base_sha256,
+    }, "decision revision", contract, undefined, undefined, undefined, false, allowLegacyConfidence));
+    return violations;
+}

package/dist/state/decisionRevisionMigration.js

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { canonicalRecordJson, validateStateRecord } from "./archiveDiscovery.js";
+import { canonicalMigrationRecord } from "./canonicalMigrationRecord.js";
+import { applyDecisionChanges } from "./decisionEntities.js";
+import { classifyCompleteDecisionConfidence, decisionLegacyCoexistence } from "./decisionLegacyValidation.js";
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function hash(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function refuse(entry, recovery) {
+    entry.classification = "corrupt";
+    entry.detail_availability = "unavailable";
+    entry.compatibility = "degraded";
+    entry.proposed_target = null;
+    entry.target_sha256 = null;
+    entry.recovery = recovery;
+}
+function changesFrom(source) {
+    const changes = mapping(source.changes);
+    return structuredClone(changes ?? Object.fromEntries(Object.entries(source).filter(([field]) => !["decision", "date", "provenance", "base_sha256"].includes(field))));
+}
+export function migrateDecisionRevisionEntries(entries, decisions, legacyDecisions, sourceRoot, forbiddenAliases, sourceFingerprint) {
+    const coexistence = decisionLegacyCoexistence(sourceRoot);
+    const grouped = new Map();
+    for (const entry of entries.filter(({ boundary }) => boundary === "decision_revision")) {
+        const decision = entry.relationships.find(({ field }) => field === "decision")?.target_id ?? "";
+        grouped.set(decision, [...(grouped.get(decision) ?? []), entry]);
+    }
+    for (const [decision, revisions] of grouped) {
+        let effective = structuredClone(decisions.get(decision) ?? {});
+        const legacyBase = legacyDecisions.get(decision);
+        let legacyEffective = structuredClone(legacyBase ?? {});
+        const legacyBaseSha256 = legacyBase ? hash(canonicalRecordJson(legacyBase)) : null;
+        let chainValid = decisions.has(decision) && legacyBaseSha256 !== null;
+        for (const entry of revisions.sort((left, right) => left.source_identity.localeCompare(right.source_identity, undefined, { numeric: true }))) {
+            if (!entry.proposed_target) {
+                chainValid = false;
+                continue;
+            }
+            const source = entry.record;
+            const changes = changesFrom(source);
+            const expectedBase = hash(canonicalRecordJson(effective));
+            const claimedBase = typeof source.base_sha256 === "string" ? source.base_sha256 : null;
+            if (!chainValid || (claimedBase !== null && claimedBase !== legacyBaseSha256)) {
+                refuse(entry, claimedBase !== null && claimedBase !== legacyBaseSha256
+                    ? `Legacy revision '${entry.source_identity}' claims base ${claimedBase}, but the immutable legacy base is ${legacyBaseSha256}; preserve the source and reconcile the stale hash before migration.`
+                    : `Legacy revision '${entry.source_identity}' follows an invalid or unavailable revision base; preserve the source and repair the ordered chain before migration.`);
+                chainValid = false;
+                continue;
+            }
+            const legacyProjected = { ...legacyEffective, ...structuredClone(changes) };
+            const assessment = classifyCompleteDecisionConfidence(legacyProjected, coexistence, (candidate) => validateStateRecord(sourceRoot, "decisions", candidate), "active");
+            if (assessment.status === "invalid") {
+                refuse(entry, `Legacy revision '${entry.source_identity}' produces an invalid effective decision (${assessment.violations.join("; ")}); preserve the source and repair the revision before migration.`);
+                chainValid = false;
+                continue;
+            }
+            const projected = applyDecisionChanges(effective, changes);
+            const expectedProjection = canonicalMigrationRecord("decision", legacyProjected, forbiddenAliases);
+            if (canonicalRecordJson(projected) !== canonicalRecordJson(expectedProjection)) {
+                refuse(entry, `Legacy revision '${entry.source_identity}' cannot be represented by canonical decision changes without altering its effective value; preserve the source and repair the revision before migration.`);
+                chainValid = false;
+                continue;
+            }
+            entry.record = {
+                decision,
+                ...(typeof source.date === "string" ? { date: source.date } : {}),
+                provenance: typeof source.provenance === "string" ? source.provenance : "historical_revision",
+                base_sha256: expectedBase,
+                changes,
+            };
+            if (typeof changes.confidence === "string" && coexistence.knownLegacyExamples.includes(changes.confidence)) {
+                entry.canonical_migration_provenance = {
+                    kind: "inherited_decision_revision_confidence",
+                    source: "revision_document",
+                    source_path: entry.source_paths[0],
+                    source_identity: entry.source_identity,
+                    source_fingerprint: sourceFingerprint,
+                    source_record_sha256: entry.content_sha256 ?? hash(canonicalRecordJson(source)),
+                    confidence: changes.confidence,
+                };
+            }
+            effective = projected;
+            legacyEffective = legacyProjected;
+        }
+    }
+}

package/dist/state/directRetrieval.js

@@ -0,0 +1,323 @@
+import fs from "node:fs";
+import { loadYamlMapping } from "../core/yaml.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { canonicalRecordJson, decisionOverlayContract, numberedArchiveArtifacts, numberedArchiveContract, readNumberedArchiveEntry, stateCurrentProjectionPath, validateStateRecord, } from "./archiveDiscovery.js";
+import { composeDecisionOverlay, decisionOverlayPath, loadDecisionOverlay } from "./decisionOverlay.js";
+import { decisionContextEntry } from "../cli/commands/state/decisions.js";
+import { assertRealpathBoundary } from "../registries/artifactRegistry.js";
+import { legacyEntryNumber, legacyIdentity } from "./legacyIdentity.js";
+export class StateRetrievalFailure extends Error {
+    body;
+    exitCode;
+    constructor(body, exitCode) {
+        super(body.error.message);
+        this.body = body;
+        this.exitCode = exitCode;
+    }
+}
+function isMapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stateSyntax(artifactId = "<artifact-id>") {
+    return `agentera state ${artifactId} get --number N --format json`;
+}
+function stateExample(artifactId, entryNumber = null) {
+    return `agentera state ${artifactId} get --number ${entryNumber ?? 1} --format json`;
+}
+function failure(exitCode, className, message, options) {
+    const artifactId = options.artifactId;
+    const entryNumber = options.entryNumber;
+    const stableId = artifactId && entryNumber ? `${artifactId}:${entryNumber}` : undefined;
+    return new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: className,
+            message,
+            syntax: stateSyntax(artifactId),
+            example: artifactId ? stateExample(artifactId, entryNumber ?? null) : stateExample("progress"),
+            recovery: options.recovery,
+            ...(artifactId ? { artifact_id: artifactId } : {}),
+            ...(entryNumber ? { entry_number: entryNumber } : {}),
+            ...(stableId ? { stable_id: stableId } : {}),
+            ...(options.validValues ? { valid_values: options.validValues } : {}),
+            ...(options.details ? { details: options.details } : {}),
+        },
+    }, exitCode);
+}
+function inspectCurrentProjection(projectRoot, artifactId, entryNumber, contract, sourceRoot) {
+    const projectionPath = stateCurrentProjectionPath(projectRoot, artifactId, sourceRoot);
+    try {
+        assertRealpathBoundary(projectRoot, projectionPath, `${artifactId} projection`);
+    }
+    catch (error) {
+        throw failure(1, "corrupt", `current ${artifactId} projection path is unsafe`, {
+            artifactId,
+            entryNumber,
+            recovery: "Preserve the project state, repair the unsafe projection path, then retry the direct get command.",
+            details: { path: projectionPath, reason: error.message },
+        });
+    }
+    let projectionStat;
+    try {
+        projectionStat = fs.lstatSync(projectionPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { path: projectionPath, state: "missing" };
+        throw failure(1, "corrupt", `cannot read current ${artifactId} projection`, {
+            artifactId,
+            entryNumber,
+            recovery: "Preserve the current projection for diagnostics, repair its file permissions or path, then retry the direct get command.",
+            details: { path: projectionPath, reason: error.message },
+        });
+    }
+    if (projectionStat.isSymbolicLink() || !projectionStat.isFile()) {
+        throw failure(1, "corrupt", `current ${artifactId} projection is not a regular file`, {
+            artifactId,
+            entryNumber,
+            recovery: "Restore the declared current projection as a regular project-local file, then retry the direct get command.",
+            details: { path: projectionPath },
+        });
+    }
+    let document;
+    try {
+        document = loadYamlMapping(fs.readFileSync(projectionPath, "utf8"));
+    }
+    catch (error) {
+        throw failure(1, "corrupt", `cannot parse current ${artifactId} projection: ${error.message}`, {
+            artifactId,
+            entryNumber,
+            recovery: "Preserve the current projection for diagnostics, repair its YAML, then retry the direct get command.",
+            details: { path: projectionPath },
+        });
+    }
+    const active = document[contract.entryCollection];
+    if (!Array.isArray(active)) {
+        throw failure(1, "corrupt", `current ${artifactId} projection is missing its '${contract.entryCollection}' collection`, {
+            artifactId,
+            entryNumber,
+            recovery: "Restore a valid current projection with its declared entry collection, then retry the direct get command.",
+            details: { path: projectionPath, collection: contract.entryCollection },
+        });
+    }
+    let matchingActive;
+    for (const candidate of active) {
+        if (!isMapping(candidate))
+            continue;
+        if (legacyEntryNumber(candidate, artifactId, contract.entryNumberField) !== entryNumber)
+            continue;
+        if (matchingActive) {
+            throw failure(1, "ambiguous", `current ${artifactId} projection contains duplicate identity ${artifactId}:${entryNumber}`, {
+                artifactId,
+                entryNumber,
+                recovery: "Preserve the duplicate current entries, remove the identity conflict according to the artifact schema, then retry.",
+                details: { path: projectionPath, collection: contract.entryCollection },
+            });
+        }
+        matchingActive = candidate;
+    }
+    if (matchingActive) {
+        try {
+            const violations = validateStateRecord(sourceRoot, artifactId, matchingActive);
+            return {
+                path: projectionPath,
+                state: violations.length === 0 ? "full" : "summary",
+                identity: legacyIdentity(matchingActive, artifactId, contract.entryNumberField).kind,
+                record: matchingActive,
+            };
+        }
+        catch (error) {
+            throw failure(1, "unsupported_state", `current ${artifactId} projection could not be validated: ${error.message}`, {
+                artifactId,
+                entryNumber,
+                recovery: "Use a state schema supported by the storage authority, repair the current projection, then retry.",
+                details: { path: projectionPath },
+            });
+        }
+    }
+    const archive = document.archive;
+    if (Array.isArray(archive)) {
+        for (const candidate of archive) {
+            if (legacyEntryNumber(candidate, artifactId, contract.entryNumberField) !== entryNumber)
+                continue;
+            return {
+                path: projectionPath,
+                state: "summary",
+                identity: legacyIdentity(candidate, artifactId, contract.entryNumberField).kind,
+                record: isMapping(candidate) ? candidate : { summary: candidate },
+            };
+        }
+    }
+    return { path: projectionPath, state: "absent" };
+}
+function overlayFor(projectRoot, sourceRoot, artifactId, entryNumber, record) {
+    if (artifactId !== "decisions")
+        return { record, applied: false, fields: [], path: "" };
+    const contract = decisionOverlayContract(sourceRoot);
+    const overlayPath = decisionOverlayPath(projectRoot, sourceRoot);
+    let overlay;
+    try {
+        overlay = loadDecisionOverlay(projectRoot, sourceRoot);
+    }
+    catch (error) {
+        throw failure(1, "corrupt", `cannot read decision overlay: ${error.message}`, {
+            artifactId,
+            entryNumber,
+            recovery: "Preserve the decision overlay for diagnostics, repair its YAML and whitelisted fields, then retry.",
+            details: { path: overlayPath },
+        });
+    }
+    const stableId = `decisions:${entryNumber}`;
+    const selected = overlay[stableId];
+    const fields = selected
+        ? contract.mutablePaths.filter((field) => {
+            let value = selected;
+            for (const part of field.split(".")) {
+                if (!isMapping(value))
+                    return false;
+                value = value[part];
+            }
+            return value !== undefined;
+        })
+        : [];
+    const composed = composeDecisionOverlay(record, selected, contract);
+    return {
+        record: decisionContextEntry(composed, { inferOutcome: false }),
+        applied: fields.length > 0,
+        fields,
+        path: overlayPath,
+    };
+}
+function compose(projectRoot, sourceRoot, artifactId, entryNumber, current, archivePath, archiveRecord, archiveHash) {
+    const record = archiveRecord ?? current.record;
+    if (!record) {
+        throw failure(1, "incomplete", `state ${artifactId}:${entryNumber} has no complete record available`, {
+            artifactId,
+            entryNumber,
+            recovery: "Restore or publish the validated numbered archive for this ID before retrying; missing fields are not reconstructed.",
+            details: { current_projection_path: current.path, archive_path: archivePath, current_representation: current.state },
+        });
+    }
+    if (!archiveRecord && current.state === "summary" && current.identity !== "explicit_decision_shorthand") {
+        throw failure(1, "incomplete", `state ${artifactId}:${entryNumber} is represented only by an irrecoverable legacy summary`, {
+            artifactId,
+            entryNumber,
+            recovery: "Restore or publish the validated numbered archive for this ID before retrying; missing fields are not reconstructed.",
+            details: { current_projection_path: current.path, archive_path: archivePath, current_representation: current.state },
+        });
+    }
+    const complete = archiveRecord !== undefined || current.state === "full";
+    const overlay = complete ? overlayFor(projectRoot, sourceRoot, artifactId, entryNumber, record) : { record, applied: false, fields: [], path: "" };
+    const source = archiveRecord ? "archive" : current.state === "summary" ? "legacy_summary" : "legacy_full";
+    const compatibility = archiveRecord ? "complete" : "degraded";
+    return {
+        stable_id: `${artifactId}:${entryNumber}`,
+        artifact_id: artifactId,
+        entry_number: entryNumber,
+        record: overlay.record,
+        source,
+        detail_availability: complete ? "full" : "summary",
+        compatibility,
+        provenance: {
+            archive: {
+                path: archivePath,
+                available: archiveRecord !== undefined,
+                verified: archiveRecord !== undefined,
+                ...(archiveHash ? { record_sha256: archiveHash } : {}),
+            },
+            current_projection: {
+                path: current.path,
+                present: current.state !== "missing" && current.state !== "absent",
+                representation: current.state,
+            },
+            ...(artifactId === "decisions" && complete
+                ? {
+                    overlay: { path: overlay.path, applied: overlay.applied, fields: overlay.fields },
+                }
+                : {}),
+        },
+    };
+}
+export function retrieveStateEntry(projectRoot, artifactId, entryNumber, options = {}) {
+    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    const artifacts = numberedArchiveArtifacts(sourceRoot);
+    if (!artifacts.includes(artifactId)) {
+        throw failure(2, "unsupported_artifact", `unsupported state artifact '${artifactId}'`, {
+            recovery: "Use a supported numbered state artifact and retry the direct get command.",
+            validValues: artifacts,
+        });
+    }
+    const contract = numberedArchiveContract(artifactId, sourceRoot);
+    let current;
+    try {
+        current = inspectCurrentProjection(projectRoot, artifactId, entryNumber, contract, sourceRoot);
+    }
+    catch (error) {
+        if (error instanceof StateRetrievalFailure)
+            throw error;
+        throw failure(1, "unsupported_state", `state authority could not read ${artifactId}:${entryNumber}: ${error.message}`, {
+            artifactId,
+            entryNumber,
+            recovery: "Use a state format supported by the storage authority, then retry the direct get command.",
+        });
+    }
+    const lookup = readNumberedArchiveEntry(projectRoot, artifactId, entryNumber, { sourceRoot });
+    if (lookup.rejection) {
+        const unsupported = lookup.rejection.class === "unsupported_artifact" ||
+            lookup.rejection.reason === "unsupported_artifact" ||
+            (lookup.rejection.reason === "invalid_envelope" && lookup.rejection.message.startsWith("schemaVersion must be"));
+        throw failure(1, unsupported ? "unsupported_state" : "corrupt", lookup.rejection.message, {
+            artifactId,
+            entryNumber,
+            recovery: unsupported
+                ? "Use a numbered archive schema supported by the storage authority, then retry the direct get command."
+                : "Preserve the affected archive bytes for diagnostics, repair the numbered record, then retry the direct get command.",
+            details: { archive_path: lookup.path, rejection: lookup.rejection.reason },
+        });
+    }
+    const archiveRecord = lookup.entry?.record;
+    if (!archiveRecord && current.state === "missing") {
+        throw failure(1, "not_found", `state ${artifactId}:${entryNumber} was not found in the current projection or numbered archive`, {
+            artifactId,
+            entryNumber,
+            recovery: "Use an existing stable ID or restore/publish this numbered record before retrying.",
+            details: { current_projection_path: current.path, archive_path: lookup.path },
+        });
+    }
+    if (!archiveRecord && current.state === "absent") {
+        throw failure(1, "not_found", `state ${artifactId}:${entryNumber} was not found in the current projection or numbered archive`, {
+            artifactId,
+            entryNumber,
+            recovery: "Use an existing stable ID or restore/publish this numbered record before retrying.",
+            details: { current_projection_path: current.path, archive_path: lookup.path },
+        });
+    }
+    if (archiveRecord && current.record && current.state === "full") {
+        try {
+            if (canonicalRecordJson(archiveRecord) !== canonicalRecordJson(current.record)) {
+                throw failure(1, "immutable_conflict", `state ${artifactId}:${entryNumber} differs between archive and current projection`, {
+                    artifactId,
+                    entryNumber,
+                    recovery: "Preserve the immutable archive bytes and reconcile the conflicting current record before retrying.",
+                    details: { current_projection_path: current.path, archive_path: lookup.path },
+                });
+            }
+        }
+        catch (error) {
+            if (error instanceof StateRetrievalFailure)
+                throw error;
+            throw failure(1, "corrupt", `state ${artifactId}:${entryNumber} could not be compared safely`, {
+                artifactId,
+                entryNumber,
+                recovery: "Preserve both records for diagnostics, repair their serialized state, then retry.",
+                details: { current_projection_path: current.path, archive_path: lookup.path },
+            });
+        }
+    }
+    return {
+        command: `state ${artifactId} get`,
+        status: "ok",
+        entry: compose(projectRoot, sourceRoot, artifactId, entryNumber, current, lookup.path, archiveRecord, lookup.entry?.recordSha256),
+    };
+}