agentera 3.0.0-dev.32 → 3.0.0-dev.39

package/dist/state/decisionRevision.js

@@ -1,31 +1,6 @@
-import { createHash } from "node:crypto";
-import fs from "node:fs";
 import path from "node:path";
-import { loadYamlMapping } from "../core/yaml.js";
 import { resolveSourceRoot } from "../core/sourceRoot.js";
-import { assertRealpathBoundary } from "../registries/artifactRegistry.js";
-import { canonicalRecordJson, readNumberedArchiveEntry, stateCurrentProjectionPath, validateStateRecord, } from "./archiveDiscovery.js";
-import { legacyEntryNumber } from "./legacyIdentity.js";
-import { reject } from "./write/errors.js";
-// partitionDecisionViolations lives in decisionLegacyValidation.js, which in
-// turn imports the coexistence primitives declared below. Both modules
-// reference each other only inside functions, so the circular binding is
-// resolved by the time either is called (same pattern as the
-// decisionRevisionPublication.js re-export at the end of this file).
-import { partitionDecisionViolations } from "./decisionLegacyValidation.js";
-/**
- * Focused accessor for the decision-content amendment contract declared in
- * references/artifacts/state-storage-authority.yaml (`revisions:` and
- * `compatibility.legacy_label_coexistence:`). It reads the same single
- * authority file as the other focused accessors (e.g. gitBackfillAuthority) and
- * projects only the amendment-relevant sections.
- *
- * The overlay (satisfaction) and revision (content) authorities share an
- * identity prefix but never overlap fields. This module owns the revision
- * contract, the revision document loader, base→revisions composition, and
- * amendment preparation. Amendment publication with recovery is plan task 3.
- */
-const AUTHORITY_RELATIVE_PATH = "references/artifacts/state-storage-authority.yaml";
+import { loadStateStorageAuthority } from "./stateStorageAuthority.js";
 const EXPECTED_AUTHORITY_SCHEMA = "agentera.stateStorageAuthority.v1";
 function mapping(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
@@ -39,13 +14,14 @@ function requiredString(value, field) {
     return value;
 }
 function requiredList(value, field) {
-    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.length === 0)) {
+    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 = loadYamlMapping(fs.readFileSync(path.join(sourceRoot, AUTHORITY_RELATIVE_PATH), "utf8"));
+    const authority = loadStateStorageAuthority(sourceRoot).document;
     if (authority.schema_version !== EXPECTED_AUTHORITY_SCHEMA) {
         throw new Error("state storage authority schema_version is unsupported");
     }
@@ -54,11 +30,6 @@ function readAuthority(sourceRoot) {
     }
     return authority;
 }
-/**
- * Cross-validation inputs extracted from the same authority: the decision
- * overlay identity prefix and mutable paths. Revisions must share the overlay
- * identity and never overlap an overlay mutable path.
- */
 function overlayCrossCheck(authority) {
     const overlays = mapping(authority.overlays);
     const identityKey = requiredString(overlays.identity_key, "overlays.identity_key");
@@ -91,23 +62,32 @@ export function decisionRevisionContract(sourceRoot = resolveSourceRoot()) {
         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 amendable of amendablePaths) {
-        if (reserved.has(amendable)) {
-            throw new Error(`state storage authority revisions.amendable_paths 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.amendable_paths must not overlap overlay mutable path '${amendable}'`);
+    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"),
@@ -138,14 +118,6 @@ export function legacyLabelCoexistence(sourceRoot = resolveSourceRoot()) {
         noSilentNormalization: requiredString(coexistence.no_silent_normalization, "compatibility.legacy_label_coexistence.no_silent_normalization"),
     };
 }
-/**
- * Evaluate the legacy-label coexistence rule for one confidence value.
- * `touched=true` marks the value as new or amended content supplied by append
- * or amend; `touched=false` marks an untouched inherited value on an existing
- * record. The current vocabulary always passes. An untouched unsupported
- * value is explicit legacy state (preserved, caveated, allowed). A touched
- * unsupported value is rejected and requires the current vocabulary.
- */
 export function classifyConfidenceLabel(contract, value, touched) {
     const vocabulary = contract.currentVocabulary.join(", ");
     if (contract.currentVocabulary.includes(value)) {
@@ -164,12 +136,6 @@ export function classifyConfidenceLabel(contract, value, touched) {
         caveat: `confidence label '${value}' requires current vocabulary (${vocabulary}) for new or amended content`,
     };
 }
-/**
- * Revision provenance vocabulary (state-storage-authority `revisions.provenance`).
- * A revision carries revision provenance only and is never labeled as
- * historical archive provenance. A revision whose base was bootstrapped from a
- * complete legacy projection may carry degraded_projection provenance.
- */
 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";
@@ -186,28 +152,12 @@ function decisionNumberFromId(id, contract) {
     const parsed = Number(number);
     return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
 }
-/**
- * Resolve the revision document path for a project. Mirrors
- * {@link decisionOverlayPath}: project-relative, realpath-bounded.
- */
-export function decisionRevisionPath(projectRoot, sourceRoot = resolveSourceRoot()) {
-    const contract = decisionRevisionContract(sourceRoot);
-    const target = path.resolve(projectRoot, contract.location);
-    assertRealpathBoundary(projectRoot, target, "decision revision");
-    return target;
-}
-/**
- * Validate a revision document against the amendment contract. Returns a list of
- * human-readable violations (empty when valid). The document must be a mapping
- * keyed by stable decision ID; each value is an ordered list of revision
- * records carrying only amendment-meta keys and amendable content paths.
- */
 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.amendablePaths);
-    const allowed = new Set([...REVISION_META_KEYS, ...contract.amendablePaths]);
+    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) {
@@ -219,12 +169,12 @@ export function decisionRevisionViolations(document, contract = decisionRevision
             continue;
         }
         value.forEach((revision, index) => {
-            violations.push(...decisionRevisionRecordViolations(revision, `${stableId}[${index}]`, contract, allowed, amendable));
+            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]), amendable = new Set(contract.amendablePaths)) {
+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 = [];
@@ -232,30 +182,67 @@ function decisionRevisionRecordViolations(revision, label, contract, allowed = n
         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))
+        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)))
+    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))
+    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 (${contract.amendablePaths.join(", ")})`);
+    }
+    if (!Object.keys(revision).some((key) => amendable.has(key))) {
+        violations.push(`${label} must amend at least one content field (${amendablePaths.join(", ")})`);
+    }
     return violations;
 }
-/** Validate one canonical entity revision through the same revision contract as legacy revisions. */
-export function decisionRevisionEntityViolations(record, contract = decisionRevisionContract()) {
+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);
+    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`);
@@ -264,369 +251,7 @@ export function decisionRevisionEntityViolations(record, contract = decisionRevi
         date: record.date,
         provenance: record.provenance,
         base_sha256: record.base_sha256,
-    }, "decision revision", contract));
+    }, "decision revision", contract, undefined, undefined, undefined, false, allowLegacyConfidence));
     return violations;
 }
-export function loadDecisionRevision(projectRoot = process.cwd(), sourceRoot = resolveSourceRoot()) {
-    const target = decisionRevisionPath(projectRoot, sourceRoot);
-    if (!fs.existsSync(target))
-        return {};
-    const bytes = fs.readFileSync(target, "utf8");
-    let document;
-    try {
-        document = loadYamlMapping(bytes);
-    }
-    catch (error) {
-        throw new Error(`cannot parse decision revision document '${target}': ${error.message}`);
-    }
-    const violations = decisionRevisionViolations(document, decisionRevisionContract(sourceRoot));
-    if (violations.length > 0) {
-        throw new Error(`decision revision document '${target}' is invalid: ${violations.join("; ")}`);
-    }
-    return document;
-}
-/**
- * Compose ordered revisions over an immutable base record. Each revision
- * applies only its authority-declared amendable content paths, in declared
- * order; no revision overwrites, reorders, or deletes a prior revision. The
- * overlay (satisfaction) authority composes its own evidence separately and is
- * not touched here.
- *
- * When `baseSha256` is supplied, the first revision that carries a
- * `base_sha256` is checked against it; a mismatch marks `broken_hash` so the
- * caller degrades rather than reconstructing inconsistent detail.
- */
-export function composeDecisionRevision(entry, revisions, options = {}) {
-    const contract = options.contract ?? decisionRevisionContract();
-    if (!revisions || revisions.length === 0) {
-        return { record: structuredClone(entry), applied: false, fields: [], revisions: [], broken_hash: false };
-    }
-    const effective = structuredClone(entry);
-    const touched = new Set();
-    const provenance = [];
-    let brokenHash = false;
-    const expectedBase = options.baseSha256;
-    for (let index = 0; index < revisions.length; index++) {
-        const revision = revisions[index];
-        const fields = [];
-        for (const amendablePath of contract.amendablePaths) {
-            if (amendablePath in revision && revision[amendablePath] !== undefined) {
-                effective[amendablePath] = structuredClone(revision[amendablePath]);
-                touched.add(amendablePath);
-                fields.push(amendablePath);
-            }
-        }
-        // The first revision establishes the base lineage; a base_sha256 mismatch
-        // there means the immutable base drifted after the revision was published.
-        if (index === 0 && expectedBase !== undefined && typeof revision.base_sha256 === "string" && revision.base_sha256 !== expectedBase) {
-            brokenHash = true;
-        }
-        provenance.push({
-            index,
-            ...(typeof revision.date === "string" ? { date: revision.date } : {}),
-            provenance: (typeof revision.provenance === "string" ? revision.provenance : "historical_revision"),
-            fields,
-            ...(typeof revision.base_sha256 === "string" ? { base_sha256: revision.base_sha256 } : {}),
-        });
-    }
-    return {
-        record: effective,
-        applied: touched.size > 0,
-        fields: [...touched],
-        revisions: provenance,
-        broken_hash: brokenHash,
-    };
-}
-/**
- * Load the revision snapshot once for a project. Returns `null` when no
- * revision document exists. Throws a plain `Error` (with a descriptive
- * message) when the document is unreadable or violates the contract, so
- * callers can wrap the failure in their own retrieval envelope.
- */
-export function loadDecisionRevisionSnapshot(projectRoot, sourceRoot = resolveSourceRoot()) {
-    const contract = decisionRevisionContract(sourceRoot);
-    const revisionPath = decisionRevisionPath(projectRoot, sourceRoot);
-    let document;
-    try {
-        document = loadDecisionRevision(projectRoot, sourceRoot);
-        // loadDecisionRevision returns {} when the document is absent; normalize to null
-        // so callers short-circuit the snapshot path entirely.
-        document = Object.keys(document).length > 0 ? document : {};
-    }
-    catch (error) {
-        throw new Error(`cannot read decision revision document: ${error.message}`);
-    }
-    if (Object.keys(document).length === 0)
-        return null;
-    return { path: revisionPath, document, amendablePaths: contract.amendablePaths, contract };
-}
-/**
- * Bounded composition metadata for one stable ID in a list snapshot. Does not
- * hash-verify lineage (that is the exact/get path's responsibility); it reports
- * whether any amendable content field is amended and which, for truthful list
- * provenance without reconstructing full detail.
- */
-export function decisionRevisionFields(snapshot, stableId) {
-    if (!snapshot || !stableId || !snapshot.document[stableId]) {
-        return { applied: false, fields: [], count: 0 };
-    }
-    const revisions = snapshot.document[stableId];
-    const fields = new Set();
-    for (const entry of revisions) {
-        for (const amendable of snapshot.amendablePaths) {
-            if (amendable in entry && entry[amendable] !== undefined)
-                fields.add(amendable);
-        }
-    }
-    return { applied: fields.size > 0, fields: [...fields], count: revisions.length };
-}
-/**
- * Compose a bounded list summary's effective record from the base and any
- * revisions for the stable ID. Returns the base (cloned) when no revisions
- * apply, so list summaries never reconstruct missing detail.
- */
-export function composedRevisionRecord(snapshot, stableId, base) {
-    if (!snapshot || !stableId || !snapshot.document[stableId])
-        return structuredClone(base);
-    return composeDecisionRevision(base, snapshot.document[stableId], { contract: snapshot.contract }).record;
-}
-/**
- * Locate a complete base record for amendment preparation. A verified numbered
- * archive seeds a `historical_archive` base. When the decision has no numbered
- * archive but is represented by a complete legacy full projection record, the
- * exact projection values seed a hash-verified `degraded_projection` base
- * (never historical_archive). Summary-only, conflicting, ambiguous,
- * broken-hash, and incomplete targets are refused with a working correction
- * rather than reconstructed.
- */
-export function prepareDecisionAmendment(projectRoot, decisionNumber, requested, options = {}) {
-    if (!Number.isSafeInteger(decisionNumber) || decisionNumber <= 0) {
-        reject({
-            class: "invalid_request",
-            message: `decision number must be a positive integer; received ${decisionNumber}`,
-            syntax: "agentera state decisions amend --number N [--question ... --choice ... --reasoning ... --confidence firm ...] [--dry-run] --format json",
-            example: 'agentera state decisions amend --number 53 --choice "..." --reasoning "..." --confidence firm --dry-run --format json',
-            recovery: "Supply an existing numbered decision and retry; no files were changed.",
-        });
-    }
-    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
-    const contract = options.contract ?? decisionRevisionContract(sourceRoot);
-    const amendableSet = new Set(contract.amendablePaths);
-    const requestedFields = Object.keys(requested).filter((key) => amendableSet.has(key) && requested[key] !== undefined);
-    if (requestedFields.length === 0) {
-        reject({
-            class: "missing_argument",
-            message: "amend requires at least one amendable content field",
-            syntax: "agentera state decisions amend --number N [--question ... --choice ... --reasoning ... --confidence firm ...] [--dry-run] --format json",
-            example: 'agentera state decisions amend --number 53 --choice "..." --reasoning "..." --confidence firm --dry-run --format json',
-            recovery: `Supply at least one of ${contract.amendablePaths.join(", ")}; no files were changed.`,
-        });
-    }
-    // New/amended confidence must be current vocabulary; legacy labels are never normalized.
-    if (requestedFields.includes("confidence")) {
-        const value = requested.confidence;
-        const coexistence = legacyLabelCoexistence(sourceRoot);
-        const classification = classifyConfidenceLabel(coexistence, String(value), true);
-        if (!classification.allowed) {
-            reject({
-                class: "invalid_choice",
-                message: classification.caveat,
-                valid_values: coexistence.currentVocabulary,
-                syntax: "agentera state decisions amend --number N --confidence firm --format json",
-                example: "agentera state decisions amend --number 53 --confidence firm --dry-run --format json",
-                recovery: "Use a current-vocabulary confidence label for new or amended content; no files were changed.",
-            });
-        }
-    }
-    const lookup = readNumberedArchiveEntry(projectRoot, "decisions", decisionNumber, { sourceRoot });
-    if (lookup.rejection) {
-        const reason = lookup.rejection.reason;
-        const brokenHash = reason === "invalid_envelope" || reason === "read_failure" || reason === "unsafe_path";
-        reject({
-            class: "conflict",
-            message: `decision ${decisionNumber} amendment target has a broken numbered archive (${reason}: ${lookup.rejection.message})`,
-            syntax: "agentera state decisions amend --number N [--question ... --confidence firm ...] [--dry-run] --format json",
-            example: 'agentera state decisions amend --number 53 --choice "..." --reasoning "..." --confidence firm --dry-run --format json',
-            recovery: brokenHash
-                ? "Preserve the affected archive bytes for diagnostics, repair the numbered record, then retry the amend."
-                : "Restore or publish the validated numbered archive for this ID before retrying; missing fields are not reconstructed.",
-        });
-    }
-    const projectionPath = stateCurrentProjectionPath(projectRoot, "decisions", sourceRoot);
-    let base;
-    let currentRepresentation;
-    if (lookup.entry) {
-        // A verified numbered archive seeds an immutable historical_archive base.
-        if (!lookup.entry.record) {
-            reject({
-                class: "conflict",
-                message: `decision ${decisionNumber} amendment target has a numbered archive without a complete record`,
-                syntax: "agentera state decisions amend --number N [--question ... --confidence firm ...] [--dry-run] --format json",
-                example: 'agentera state decisions amend --number 53 --choice "..." --reasoning "..." --confidence firm --dry-run --format json',
-                recovery: "Preserve the numbered archive for diagnostics, repair or republish its complete record, then retry the amend.",
-            });
-        }
-        base = {
-            record: lookup.entry.record,
-            sha256: lookup.entry.recordSha256,
-            provenance: "historical_archive",
-            source: "archive",
-        };
-        currentRepresentation = "full";
-    }
-    else {
-        // No numbered archive: bootstrap a hash-verified base from a complete legacy
-        // full projection record. Summary-only targets are refused; missing fields
-        // are never reconstructed.
-        const projection = legacyFullProjectionFor(projectRoot, decisionNumber, projectionPath, sourceRoot);
-        if (projection.kind === "missing" || projection.kind === "absent") {
-            reject({
-                class: "unsupported_target",
-                message: `decision ${decisionNumber} has no numbered archive and is not present in the current projection`,
-                syntax: "agentera state decisions amend --number N [--question ... --confidence firm ...] [--dry-run] --format json",
-                example: 'agentera state decisions amend --number 53 --choice "..." --reasoning "..." --confidence firm --dry-run --format json',
-                recovery: "Append or restore the decision with a complete record (and its numbered archive) before amending; missing fields are not reconstructed.",
-            });
-        }
-        else if (projection.kind === "ambiguous") {
-            reject({
-                class: "conflict",
-                message: `decision ${decisionNumber} is represented by multiple conflicting current projection entries`,
-                syntax: "agentera state decisions amend --number N [--question ... --confidence firm ...] [--dry-run] --format json",
-                example: 'agentera state decisions amend --number 53 --choice "..." --reasoning "..." --confidence firm --dry-run --format json',
-                recovery: "Remove the duplicate identity conflict according to the artifact schema, then retry the amend.",
-            });
-        }
-        else if (projection.kind === "summary") {
-            reject({
-                class: "unsupported_target",
-                message: `decision ${decisionNumber} is represented only by an irrecoverable legacy summary; a base cannot be hash-verified`,
-                syntax: "agentera state decisions amend --number N [--question ... --confidence firm ...] [--dry-run] --format json",
-                example: 'agentera state decisions amend --number 53 --choice "..." --reasoning "..." --confidence firm --dry-run --format json',
-                recovery: "Restore or publish the validated numbered archive for this ID before retrying; missing fields are not reconstructed.",
-            });
-        }
-        else {
-            // degraded_projection base: hash-verified from exact legacy projection values, never historical_archive.
-            base = {
-                record: projection.record,
-                sha256: sha256(projection.record),
-                provenance: "degraded_projection",
-                source: "legacy_full",
-            };
-            currentRepresentation = "full";
-        }
-    }
-    const revisionPath = decisionRevisionPath(projectRoot, sourceRoot);
-    let revisions = [];
-    try {
-        const document = loadDecisionRevision(projectRoot, sourceRoot);
-        revisions = document[`decisions:${decisionNumber}`] ?? [];
-    }
-    catch (error) {
-        reject({
-            class: "conflict",
-            message: `decision ${decisionNumber} amendment target has a broken revision document: ${error.message}`,
-            syntax: "agentera state decisions amend --number N [--question ... --confidence firm ...] [--dry-run] --format json",
-            example: 'agentera state decisions amend --number 53 --choice "..." --reasoning "..." --confidence firm --dry-run --format json',
-            recovery: "Preserve the revision document for diagnostics, repair its YAML and amendable content paths, then retry the amend.",
-        });
-    }
-    const composed = composeDecisionRevision(base.record, revisions, { contract, baseSha256: base.sha256 });
-    if (composed.broken_hash) {
-        reject({
-            class: "conflict",
-            message: `decision ${decisionNumber} base hash no longer matches the recorded revision base_sha256; the immutable base drifted after the revision was published`,
-            syntax: "agentera state decisions amend --number N [--question ... --confidence firm ...] [--dry-run] --format json",
-            example: 'agentera state decisions amend --number 53 --choice "..." --reasoning "..." --confidence firm --dry-run --format json',
-            recovery: "Preserve the immutable archive and existing revisions, reconcile the base drift, then retry the amend.",
-        });
-    }
-    const effective = structuredClone(composed.record);
-    for (const field of requestedFields) {
-        effective[field] = structuredClone(requested[field]);
-    }
-    const replay = composed.applied &&
-        requestedFields.every((field) => canonicalRecordJson(effective[field]) === canonicalRecordJson(composed.record[field] ?? effective[field])) &&
-        requestedFields.length === composed.fields.length &&
-        composed.fields.every((field) => requestedFields.includes(field));
-    return {
-        number: decisionNumber,
-        base,
-        revisions,
-        requested: { ...requested },
-        effective,
-        replay,
-        provenance: {
-            base: base.provenance,
-            archive: {
-                path: lookup.path,
-                available: Boolean(lookup.entry),
-                verified: Boolean(lookup.entry),
-                ...(lookup.entry ? { record_sha256: lookup.entry.recordSha256 } : {}),
-            },
-            current_projection: { path: projectionPath, representation: currentRepresentation },
-            revision_path: revisionPath,
-            existing_revisions: revisions.length,
-            amended_fields: requestedFields,
-        },
-    };
-}
-export function legacyFullProjectionFor(projectRoot, decisionNumber, projectionPath, sourceRoot) {
-    if (!fs.existsSync(projectionPath))
-        return { kind: "missing" };
-    let bytes;
-    try {
-        bytes = fs.readFileSync(projectionPath, "utf8");
-    }
-    catch {
-        return { kind: "missing" };
-    }
-    let document;
-    try {
-        document = loadYamlMapping(bytes);
-    }
-    catch {
-        return { kind: "missing" };
-    }
-    const active = document.decisions;
-    if (!Array.isArray(active))
-        return { kind: "absent" };
-    let match;
-    for (const candidate of active) {
-        if (!isRecord(candidate))
-            continue;
-        if (legacyEntryNumber(candidate, "decisions", "number") !== decisionNumber)
-            continue;
-        if (match)
-            return { kind: "ambiguous" };
-        match = candidate;
-    }
-    if (!match) {
-        return { kind: "absent" };
-    }
-    // A complete legacy projection record validates against the decision schema;
-    // otherwise the entry is summary-only and must not be reconstructed. An
-    // untouched inherited legacy confidence label is explicit legacy state under
-    // the authority's coexistence rule: it does not degrade a complete record to
-    // summary, so the base remains hash-verifiable and amend proceeds (the label
-    // is reported as a compatibility caveat by the amendment path). Tolerance is
-    // confidence-only — every other violation still degrades to summary.
-    try {
-        const violations = validateStateRecord(sourceRoot, "decisions", match);
-        if (violations.length === 0)
-            return { kind: "full", record: match };
-        const partition = partitionDecisionViolations(violations, { decisions: [match] }, legacyLabelCoexistence(sourceRoot), new Set());
-        return partition.blocking.length === 0 ? { kind: "full", record: match } : { kind: "summary" };
-    }
-    catch {
-        return { kind: "summary" };
-    }
-}
-export function sha256(value) {
-    return createHash("sha256").update(canonicalRecordJson(value), "utf8").digest("hex");
-}
-// Re-export the publication primitives for backward-compatible imports.
-// The implementation lives in decisionRevisionPublication.ts.
-export { buildPublishedRevisionRecord, dispatchDecisionAmendment, findConflictingRevision, findPublishedRevision, projectRevisionOverride, publishDecisionAmendment, } from "./decisionRevisionPublication.js";
 //# sourceMappingURL=decisionRevision.js.map