agentera 3.0.0-dev.26 → 3.0.0-dev.28

package/dist/state/entityMigrationCausality.js

@@ -0,0 +1,99 @@
+/**
+ * Source validation identifies root corruption. Relationship validation then
+ * reports its downstream effects without relabelling valid source records as
+ * corrupt. A deterministic member roots an otherwise-valid cycle because the
+ * cycle itself is malformed source state and has no recovery interpretation.
+ */
+export function applyCausalBlockers(entries, project, recoveryFor, rootReasons = new Map()) {
+    const byIdentity = new Map(entries.map((entry) => [entry.source_identity, entry]));
+    const quote = project.replaceAll("'", "'\\''");
+    for (const entry of entries) {
+        const unresolved = entry.relationships.find((relationship) => relationship.status === "unresolved");
+        if (unresolved) {
+            const target = unresolved.target_source_identity ?? "missing structured reference";
+            rootReasons.set(entry.source_identity, `source relationship '${unresolved.field}' references unresolved target '${target}'`);
+            entry.classification = "corrupt";
+            entry.proposed_target = null;
+            entry.target_sha256 = null;
+            entry.recovery = `Repair relationship '${unresolved.field}' on '${entry.source_identity}' to reference an inventoried source identity instead of '${target}', then run agentera state migrate entities --project '${quote}' --dry-run --format json.`;
+        }
+        if (["duplicate", "conflict", "corrupt", "unsupported"].includes(entry.classification) && !rootReasons.has(entry.source_identity))
+            rootReasons.set(entry.source_identity, `${entry.classification} source requires explicit recovery`);
+    }
+    const adjacency = new Map(entries.map((entry) => [entry.source_identity, entry.relationships
+            .filter((relationship) => relationship.status === "resolved" && relationship.target_source_identity && byIdentity.has(relationship.target_source_identity))
+            .map((relationship) => relationship.target_source_identity)
+            .sort()]));
+    const index = new Map();
+    const lowlink = new Map();
+    const stack = [];
+    const onStack = new Set();
+    let nextIndex = 0;
+    const visit = (sourceIdentity) => {
+        index.set(sourceIdentity, nextIndex);
+        lowlink.set(sourceIdentity, nextIndex++);
+        stack.push(sourceIdentity);
+        onStack.add(sourceIdentity);
+        for (const target of adjacency.get(sourceIdentity) ?? []) {
+            if (!index.has(target)) {
+                visit(target);
+                lowlink.set(sourceIdentity, Math.min(lowlink.get(sourceIdentity), lowlink.get(target)));
+            }
+            else if (onStack.has(target))
+                lowlink.set(sourceIdentity, Math.min(lowlink.get(sourceIdentity), index.get(target)));
+        }
+        if (lowlink.get(sourceIdentity) !== index.get(sourceIdentity))
+            return;
+        const component = [];
+        while (true) {
+            const member = stack.pop();
+            onStack.delete(member);
+            component.push(member);
+            if (member === sourceIdentity)
+                break;
+        }
+        const cyclic = component.length > 1 || (adjacency.get(sourceIdentity) ?? []).includes(sourceIdentity);
+        if (cyclic && !component.some((member) => rootReasons.has(member))) {
+            const root = component.sort()[0];
+            const entry = byIdentity.get(root);
+            rootReasons.set(root, `source relationship graph contains a cycle rooted at '${root}'`);
+            entry.classification = "corrupt";
+            entry.proposed_target = null;
+            entry.target_sha256 = null;
+            entry.recovery = `Break the relationship cycle containing '${root}', then run agentera state migrate entities --project '${quote}' --dry-run --format json.`;
+        }
+    };
+    for (const sourceIdentity of [...byIdentity.keys()].sort())
+        if (!index.has(sourceIdentity))
+            visit(sourceIdentity);
+    const roots = new Set(rootReasons.keys());
+    const memo = new Map();
+    const resolving = new Set();
+    const resolveRoots = (sourceIdentity) => {
+        if (roots.has(sourceIdentity))
+            return [sourceIdentity];
+        const existing = memo.get(sourceIdentity);
+        if (existing)
+            return existing;
+        // Every cycle has a root after the SCC pass. This guard keeps malformed
+        // graph handling fail-closed if that invariant is ever changed.
+        if (resolving.has(sourceIdentity))
+            return [];
+        resolving.add(sourceIdentity);
+        const resolved = [...new Set((adjacency.get(sourceIdentity) ?? []).flatMap(resolveRoots))].sort();
+        resolving.delete(sourceIdentity);
+        memo.set(sourceIdentity, resolved);
+        return resolved;
+    };
+    for (const entry of entries) {
+        if (roots.has(entry.source_identity))
+            continue;
+        if (resolveRoots(entry.source_identity).length > 0) {
+            entry.proposed_target = null;
+            entry.target_sha256 = null;
+            entry.recovery = recoveryFor(entry.source_paths[0]);
+        }
+    }
+    return { rootReasons, rootsFor: resolveRoots };
+}
+//# sourceMappingURL=entityMigrationCausality.js.map

package/dist/state/entityMigrationCausality.js.map

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

package/dist/state/entityMigrationPreview.js

@@ -8,16 +8,20 @@ import { discoverPlanArtifacts, planDocumentParts } from "../cli/planArtifacts.j
 import { parseTodoMarkdownListItem } from "../cli/todoMarkdown.js";
 import { assertRealpathBoundary, docsPathOverridesFromBytes, loadArtifactRecord, resolveArtifactPath } from "../registries/artifactRegistry.js";
 import { canonicalRecordJson, validateStateRecord } from "./archiveDiscovery.js";
-import { canonicalEntityEnvelopeBytes, validateCanonicalEntityTargets } from "./entityStorage.js";
+import { canonicalEntityEnvelopeBytes, entityForbiddenCanonicalAliases, entityPreservedAggregateCollections, validateCanonicalEntityTargets } from "./entityStorage.js";
 import { discoverObjectiveArtifacts, inspectExperimentIdentities } from "./experimentIdentity.js";
 import { decisionRevisionContract, decisionRevisionViolations } from "./decisionRevision.js";
+import { classifyCompleteDecisionConfidence, decisionLegacyCoexistence } from "./decisionLegacyValidation.js";
 import { assertValidatedProjectRoot, validateRealProjectRoot } from "./projectRoot.js";
 import { todoDocsRecordViolations } from "./todoDocsEntityValidation.js";
 import { yamlArchiveEntry } from "../hooks/compaction/retention.js";
 import { truncateWords } from "../hooks/compaction/dryRun.js";
 import { legacyIdentity } from "./legacyIdentity.js";
+import { canonicalMigrationRecord } from "./canonicalMigrationRecord.js";
+import { legacySummaryRecord } from "./legacySummaryRecord.js";
+import { applyCausalBlockers } from "./entityMigrationCausality.js";
 import { projectPathIsStable as migrationPathIsStable, readProjectFileSnapshot, resolveProjectDescriptorPath, snapshotProjectPath as snapshotMigrationPath, } from "./safeProjectFile.js";
-const MAX_OUTPUT_BYTES = 32_768;
+export const ENTITY_MIGRATION_PREVIEW_MAX_OUTPUT_BYTES = 32_768;
 const DEFAULT_LIMIT = 100;
 const MAX_LIMIT = 1000;
 const NUMBERED = {
@@ -25,7 +29,8 @@ const NUMBERED = {
     decisions: { file: ".agentera/decisions.yaml", collection: "decisions", boundary: "decision" },
     health: { file: ".agentera/health.yaml", collection: "audits", boundary: "health_audit" },
 };
-const BLOCKING = new Set(["irrecoverable_summary_only", "duplicate", "conflict", "corrupt", "unsupported"]);
+const COMPACTED_SUMMARY_ARTIFACTS = new Set(["progress", "decisions", "health"]);
+const BLOCKING = new Set(["duplicate", "conflict", "corrupt", "unsupported"]);
 const INVENTORY_ORDER = "artifact_then_boundary_then_source_identity_then_source_path";
 const INVENTORY_FILTER = "complete_declared_inventory";
 const AUTHORITY_PATH = "references/artifacts/state-storage-authority.yaml";
@@ -36,6 +41,24 @@ function mapping(value) {
 function hash(value) {
     return createHash("sha256").update(value).digest("hex");
 }
+function completeRecordAssessment(sourceRoot, artifact, record, source, sourcePath) {
+    if (artifact !== "decisions") {
+        const violations = validateStateRecord(sourceRoot, artifact, record);
+        return { valid: violations.length === 0, violations };
+    }
+    const assessment = classifyCompleteDecisionConfidence(record, decisionLegacyCoexistence(sourceRoot), (candidate) => validateStateRecord(sourceRoot, artifact, candidate), source);
+    return {
+        valid: assessment.status !== "invalid",
+        violations: assessment.violations,
+        ...(assessment.status === "inherited" ? { inheritedConfidenceProvenance: {
+                kind: "inherited_decision_confidence",
+                source: source === "active" ? "current_projection" : "verified_archive",
+                source_path: sourcePath,
+                source_record_sha256: hash(canonicalRecordJson(record)),
+                confidence: record.confidence,
+            } } : {}),
+    };
+}
 function relative(root, target) {
     return path.relative(root, target).replaceAll(path.sep, "/");
 }
@@ -172,7 +195,7 @@ function inventoryFailureObservations(files, observations) {
         });
     }
 }
-function numberedObservations(root, sourceRoot, files, observations) {
+function numberedObservations(root, sourceRoot, files, observations, aggregateCollections) {
     const correlationSource = files.find((source) => source.relative === ".agentera/archive/recovery/projection-correlation.yaml");
     let correlationManifest = null;
     if (correlationSource?.kind === "file") {
@@ -197,6 +220,10 @@ function numberedObservations(root, sourceRoot, files, observations) {
         if (current?.kind === "file") {
             try {
                 const document = parseYaml(current);
+                const allowedCollections = new Set(aggregateCollections[declaration.file] ?? []);
+                for (const field of Object.keys(document).filter((field) => Array.isArray(document[field]) && !allowedCollections.has(field)).sort()) {
+                    observations.push({ key: `${artifact}:undeclared_collection:${field}`, artifact, boundary: "migration_inventory", path: declaration.file, provenance: "source_inventory", record: null, detail: "corrupt", relationships: [], message: `aggregate collection '${field}' is not declared for '${declaration.file}' by the state storage authority` });
+                }
                 const currentValues = document[declaration.collection];
                 if (!Array.isArray(currentValues))
                     throw new Error(`field '${declaration.collection}' must be a list`);
@@ -204,17 +231,20 @@ function numberedObservations(root, sourceRoot, files, observations) {
                 if (Array.isArray(document.archive))
                     collections.push(["archive", document.archive]);
                 collections.flatMap(([collection, values]) => values.map((value, index) => ({ collection, value, index }))).forEach(({ collection, value, index }) => {
-                    const record = mapping(value) ?? (typeof value === "string" ? { summary: value } : null);
+                    const record = legacySummaryRecord(value);
                     const identity = legacyIdentity(record, artifact, "number");
                     const number = identity.number;
                     const key = number ? `${artifact}:${number}` : `${artifact}:${collection}[${index}]`;
-                    const valid = record && typeof record.number === "number" ? validateStateRecord(sourceRoot, artifact, record).length === 0 : false;
+                    const assessment = record && typeof record.number === "number"
+                        ? completeRecordAssessment(sourceRoot, artifact, record, "active", declaration.file)
+                        : { valid: false, violations: ["record number is required"] };
+                    const valid = assessment.valid;
                     const summary = Boolean(record && (typeof record.summary === "string" || record.detail_availability === "summary_only"));
                     const text = typeof record?.summary === "string" ? record.summary : "";
                     const decisionRefs = artifact === "decisions" ? [...text.matchAll(/\bD([1-9][0-9]*)\b/g)] : [];
                     const residue = artifact === "decisions" && decisionRefs.length > 1 && !number;
-                    observations.push({ key: residue ? `historical_projection_residue:${declaration.file}:${collection}[${index}]` : key, artifact, boundary: residue ? "historical_projection_residue" : declaration.boundary, path: declaration.file, provenance: residue ? "historical_projection_residue" : "current_projection", record, detail: valid ? "full" : summary ? "summary" : "corrupt", relationships: [], message: valid || summary ? undefined : "projection record does not satisfy the declared full-detail schema", ...(residue ? { migrationProvenance: { classification: "historical_projection_residue", path: declaration.file, collection, index, content_sha256: hash(canonicalRecordJson(record)), text, inbound_structured_references: 0 } } : {}) });
-                    if (artifact === "decisions" && mapping(record?.satisfaction)) {
+                    observations.push({ key: residue ? `historical_projection_residue:${declaration.file}:${collection}[${index}]` : key, artifact, boundary: residue ? "historical_projection_residue" : declaration.boundary, path: declaration.file, provenance: residue ? "historical_projection_residue" : "current_projection", record, detail: valid ? "full" : summary ? "summary" : "corrupt", relationships: [], sourceRecordSha256: hash(canonicalRecordJson(value)), message: valid || summary ? undefined : "projection record does not satisfy the declared full-detail schema", ...(assessment.inheritedConfidenceProvenance ? { inheritedConfidenceProvenance: assessment.inheritedConfidenceProvenance } : {}), ...(residue ? { migrationProvenance: { classification: "historical_projection_residue", path: declaration.file, collection, index, content_sha256: hash(canonicalRecordJson(record)), text, inbound_structured_references: 0 } } : {}) });
+                    if (artifact === "decisions" && valid && mapping(record?.satisfaction)) {
                         observations.push({ key: `decision_satisfaction:${key}`, artifact: "decisions", boundary: "decision_satisfaction", path: declaration.file, provenance: "current_projection", record: mapping(record?.satisfaction), detail: "full", relationships: [{ field: "decision", target: key }] });
                     }
                 });
@@ -249,10 +279,10 @@ function numberedObservations(root, sourceRoot, files, observations) {
                         || mapping(correlation.overlay)?.final_record_sha256 !== expected)
                         throw new Error("recovered archive does not match its immutable projection correlation manifest entry");
                 }
-                const violations = validateStateRecord(sourceRoot, artifact, record);
-                if (violations.length > 0)
-                    throw new Error(`archive record is invalid: ${violations.join("; ")}`);
-                observations.push({ key, artifact, boundary: declaration.boundary, path: source.relative, provenance: "verified_archive", record, detail: "full", relationships: [], ...(mapping(envelope.recovery_provenance) ? { migrationProvenance: mapping(envelope.recovery_provenance) } : {}) });
+                const assessment = completeRecordAssessment(sourceRoot, artifact, record, "archive", source.relative);
+                if (!assessment.valid)
+                    throw new Error(`archive record is invalid: ${assessment.violations.join("; ")}`);
+                observations.push({ key, artifact, boundary: declaration.boundary, path: source.relative, provenance: "verified_archive", record, detail: "full", relationships: [], ...(assessment.inheritedConfidenceProvenance ? { inheritedConfidenceProvenance: assessment.inheritedConfidenceProvenance } : {}), ...(mapping(envelope.recovery_provenance) ? { migrationProvenance: mapping(envelope.recovery_provenance) } : {}) });
                 if (artifact === "decisions" && mapping(record.satisfaction)) {
                     observations.push({
                         key: `decision_satisfaction:${key}`,
@@ -506,15 +536,26 @@ function previewId(fingerprint, key) {
     const bytes = createHash("sha256").update(`agentera.entity-preview.v1\0${fingerprint}\0${key}`, "utf8").digest();
     return Array.from(bytes.subarray(0, 10), (byte) => String.fromCharCode(97 + byte % 26)).join("");
 }
-function classify(group) {
+function summaryBoundary(artifact, fallback) {
+    return { progress: "progress_summary", decisions: "decision_summary", health: "health_summary" }[artifact] ?? fallback;
+}
+function canonicalSummaryBodies(group, forbiddenAliases) {
+    return new Set(group.flatMap((item) => item.record
+        ? [canonicalRecordJson(canonicalMigrationRecord(summaryBoundary(item.artifact, item.boundary), item.record, forbiddenAliases))]
+        : []));
+}
+function classify(group, forbiddenAliases) {
     if (group.some((item) => item.provenance === "historical_projection_residue"))
         return "historical_projection_residue";
     if (group.some((item) => item.key.startsWith("unsupported:")))
         return "unsupported";
     if (group.some((item) => item.detail === "corrupt"))
         return "corrupt";
-    if (group.every((item) => item.detail === "summary"))
-        return "irrecoverable_summary_only";
+    if (group.every((item) => item.detail === "summary")) {
+        if (!COMPACTED_SUMMARY_ARTIFACTS.has(group[0]?.artifact ?? ""))
+            return "corrupt";
+        return canonicalSummaryBodies(group, forbiddenAliases).size === 1 ? "valid_compacted_summary" : "conflict";
+    }
     const full = group.filter((item) => item.detail === "full" && item.record);
     const bodies = new Set(full.map((item) => canonicalRecordJson(item.record)));
     if (bodies.size > 1)
@@ -522,11 +563,12 @@ function classify(group) {
     const projections = full.filter((item) => item.provenance === "current_projection");
     const archive = group.find((item) => item.provenance === "verified_archive" && item.record);
     const summaries = group.filter((item) => item.detail === "summary" && item.record);
-    if (archive && summaries.length) {
-        const recovery = archive.migrationProvenance;
+    if (full.length && summaries.length) {
+        const selected = archive ?? full[0];
+        const recovery = selected.migrationProvenance;
         const recorded = mapping(recovery?.current_projection)?.record_sha256;
-        const proven = summaries.every((item) => exactProjectionMirror(item.artifact, archive.record, item.record, recorded));
-        return proven ? "verified_full" : "conflict";
+        if (!summaries.every((item) => exactProjectionMirror(item.artifact, selected.record, item.record, recorded)))
+            return "conflict";
     }
     if (archive || group.some((item) => item.provenance === "verified_plan_archive"))
         return "verified_full";
@@ -538,52 +580,26 @@ function exactProjectionMirror(artifact, full, summary, recorded) {
     if (recorded === hash(canonicalRecordJson(summary)))
         return true;
     if (artifact === "health" && typeof summary.summary === "string" && typeof full.number === "number" && typeof full.date === "string" && typeof full.trajectory === "string") {
-        return summary.summary === `Audit ${full.number} · ${full.date} (${truncateWords(full.trajectory, 10)})`;
+        if (summary.summary === `Audit ${full.number} · ${full.date} (${truncateWords(full.trajectory, 10)})`)
+            return true;
     }
     if (artifact !== "progress" && artifact !== "decisions" && artifact !== "health")
         return false;
     return canonicalRecordJson(yamlArchiveEntry(artifact, full)) === canonicalRecordJson(summary);
 }
-function canonicalMigrationRecord(boundary, source, relationships) {
-    const record = structuredClone(source);
-    for (const field of ["id", "artifact", "number", "stable_id", "artifact_id", "entry_number", "task_number", "plan_id", "objective_id", "experiment_number"])
-        delete record[field];
-    if (boundary === "decision")
-        delete record.satisfaction;
-    if (boundary === "plan" || boundary === "objective") {
-        const header = record.header;
-        if (mapping(header))
-            delete header.id;
-    }
-    if (boundary === "plan") {
-        delete record.tasks;
-        delete record.previous_plan_archived;
-        const header = record.header;
-        if (mapping(header)) {
-            const planHeader = header;
-            if (planHeader.status === "active")
-                planHeader.status = "open";
-            if (planHeader.status === "completed")
-                planHeader.status = "complete";
-        }
-    }
-    for (const relationship of relationships) {
-        if (relationship.field === "depends_on") {
-            record.depends_on = relationships.filter(({ field }) => field === "depends_on").map(({ target_id }) => target_id);
-        }
-        else {
-            record[relationship.field] = relationship.target_id;
-        }
-    }
-    return record;
-}
-function buildEntries(project, fingerprint, observations) {
+function buildEntries(project, fingerprint, observations, forbiddenAliases) {
     const groups = new Map();
     for (const observation of observations)
         groups.set(observation.key, [...(groups.get(observation.key) ?? []), observation]);
     const ids = new Map();
-    for (const key of [...groups.keys()].sort())
-        ids.set(key, previewId(fingerprint, key));
+    for (const key of [...groups.keys()].sort()) {
+        const group = groups.get(key);
+        const canonicalSummaries = group.every((item) => item.detail === "summary") && COMPACTED_SUMMARY_ARTIFACTS.has(group[0]?.artifact ?? "")
+            ? [...canonicalSummaryBodies(group, forbiddenAliases)].sort()
+            : [];
+        const identityBinding = canonicalSummaries.length === 1 ? hash(canonicalRecordJson(canonicalSummaries)) : fingerprint;
+        ids.set(key, previewId(identityBinding, key));
+    }
     const collisions = new Set();
     const idOwners = new Map();
     for (const [key, id] of ids) {
@@ -595,12 +611,16 @@ function buildEntries(project, fingerprint, observations) {
         else
             idOwners.set(id, key);
     }
-    const entries = [...groups.entries()].map(([key, group]) => {
-        let classification = classify(group);
+    const entries = [...groups.entries()].map(([key, unsortedGroup]) => {
+        const group = [...unsortedGroup].sort((left, right) => `${left.path}\0${left.provenance}\0${canonicalRecordJson(left.record)}\0${left.sourceRecordSha256 ?? ""}`.localeCompare(`${right.path}\0${right.provenance}\0${canonicalRecordJson(right.record)}\0${right.sourceRecordSha256 ?? ""}`));
+        let classification = classify(group, forbiddenAliases);
         if (collisions.has(key))
             classification = "conflict";
         const primary = group[0];
-        const content = group.find((item) => item.provenance === "verified_archive" && item.record)?.record ?? group.find((item) => item.record)?.record ?? null;
+        const contentObservation = group.find((item) => item.provenance === "verified_archive" && item.detail === "full" && item.record)
+            ?? group.find((item) => item.detail === "full" && item.record)
+            ?? group.find((item) => item.detail === "summary" && item.record);
+        const content = contentObservation?.record ?? null;
         const contentSha256s = [...new Set(group.flatMap((item) => item.record ? [hash(canonicalRecordJson(item.record))] : []))].sort();
         const mirrored = contentSha256s.length === 1 && group.filter((item) => item.record).length > 1;
         const id = ids.get(key);
@@ -611,25 +631,35 @@ function buildEntries(project, fingerprint, observations) {
             target_id: relationship.target ? ids.get(relationship.target) ?? null : null,
             status: relationship.target && groups.has(relationship.target) ? "resolved" : "unresolved",
         }));
-        const record = content ? canonicalMigrationRecord(primary.boundary, content, relationships) : {};
+        const summary = classification === "valid_compacted_summary";
+        const boundary = summary ? summaryBoundary(primary.artifact, primary.boundary) : contentObservation?.boundary ?? primary.boundary;
+        const record = content ? canonicalMigrationRecord(boundary, content, forbiddenAliases, summary ? [] : relationships) : {};
+        if (summary && contentObservation && content) {
+            record.migration_provenance = {
+                source_path: contentObservation.path,
+                source_record_sha256: contentObservation.sourceRecordSha256 ?? hash(canonicalRecordJson(content)),
+            };
+        }
         const residue = classification === "historical_projection_residue";
         const blocked = BLOCKING.has(classification) || relationships.some((relationship) => relationship.status === "unresolved");
         return {
             source_identity: key,
             source_paths: [...new Set(group.map((item) => item.path))].sort(),
             artifact: primary.artifact,
-            boundary: primary.boundary,
+            boundary,
             classification,
-            detail_availability: classification === "irrecoverable_summary_only" ? "summary_only" : content ? "full" : "unavailable",
+            detail_availability: summary ? "summary" : content ? "full" : "unavailable",
+            compatibility: summary ? "degraded" : "current",
             provenance: [...new Set([...group.map((item) => item.provenance), ...(mirrored ? ["mirrored"] : [])])].sort(),
             content_sha256: contentSha256s.length === 1 ? contentSha256s[0] : null,
             content_sha256s: contentSha256s,
             physical_record_count: group.length,
-            proposed_target: blocked || residue ? null : { id, path: `.agentera/entities/${primary.artifact}/${primary.boundary}/${id}.yaml` },
+            proposed_target: blocked || residue ? null : { id, path: `.agentera/entities/${primary.artifact}/${boundary}/${id}.yaml` },
             target_sha256: null,
             relationships,
             record,
             recovery: blocked ? recovery(project, primary.path) : "none",
+            ...(contentObservation?.inheritedConfidenceProvenance ? { canonical_migration_provenance: contentObservation.inheritedConfidenceProvenance } : {}),
             ...(group.some((item) => item.migrationProvenance) ? { migration_provenance: group.flatMap((item) => item.migrationProvenance ? [item.migrationProvenance] : []) } : {}),
         };
     }).sort((a, b) => `${a.artifact}\0${a.boundary}\0${a.source_identity}\0${a.source_paths[0]}`.localeCompare(`${b.artifact}\0${b.boundary}\0${b.source_identity}\0${b.source_paths[0]}`));
@@ -651,12 +681,12 @@ function buildEntries(project, fingerprint, observations) {
     return entries;
 }
 export function validateEntityMigrationTargets(project, entries, sourceRoot) {
-    const targets = entries.flatMap((entry) => entry.proposed_target && entry.artifact && entry.boundary ? [{ sourceIdentity: entry.source_identity, path: entry.proposed_target.path, id: entry.proposed_target.id, artifact: entry.artifact, boundary: entry.boundary, record: entry.record }] : []);
+    const targets = entries.flatMap((entry) => entry.proposed_target && entry.artifact && entry.boundary ? [{ sourceIdentity: entry.source_identity, path: entry.proposed_target.path, id: entry.proposed_target.id, artifact: entry.artifact, boundary: entry.boundary, record: entry.record, migrationProvenance: entry.canonical_migration_provenance }] : []);
     const diagnostics = validateCanonicalEntityTargets(project, targets, sourceRoot);
     for (const entry of entries) {
         if (!entry.proposed_target || !entry.artifact)
             continue;
-        const actual = hash(canonicalEntityEnvelopeBytes({ id: entry.proposed_target.id, artifact: entry.artifact, record: entry.record }));
+        const actual = hash(canonicalEntityEnvelopeBytes({ id: entry.proposed_target.id, artifact: entry.artifact, record: entry.record, migrationProvenance: entry.canonical_migration_provenance }));
         if (entry.target_sha256 !== actual)
             diagnostics.push({ sourceIdentity: entry.source_identity, path: entry.proposed_target.path, message: `canonical target bytes have SHA-256 '${actual}', not manifest binding '${entry.target_sha256 ?? "missing"}'` });
     }
@@ -679,19 +709,20 @@ function migrationInventory(projectRoot, sourceRoot, resolveDescriptorPath) {
     const fingerprint = sourceFingerprint(files);
     const observations = [];
     inventoryFailureObservations(files, observations);
-    numberedObservations(project, sourceRoot, files, observations);
+    numberedObservations(project, sourceRoot, files, observations, entityPreservedAggregateCollections(sourceRoot));
     decisionEvidence(sourceRoot, files, observations);
     planObservations(project, files, observations);
     objectiveObservations(project, files, observations);
     todoAndDocs(project, todoPath, files, observations);
     const preserved = preservedSingletons(files);
-    const completeInventory = buildEntries(project, fingerprint, observations);
+    const completeInventory = buildEntries(project, fingerprint, observations, entityForbiddenCanonicalAliases(sourceRoot));
     const preservedResidues = completeInventory.filter((entry) => entry.classification === "historical_projection_residue");
     const completeEntries = completeInventory.filter((entry) => entry.classification !== "historical_projection_residue");
     for (const entry of completeEntries) {
         if (entry.proposed_target && entry.artifact)
-            entry.target_sha256 = hash(canonicalEntityEnvelopeBytes({ id: entry.proposed_target.id, artifact: entry.artifact, record: entry.record }));
+            entry.target_sha256 = hash(canonicalEntityEnvelopeBytes({ id: entry.proposed_target.id, artifact: entry.artifact, record: entry.record, migrationProvenance: entry.canonical_migration_provenance }));
     }
+    let causal = applyCausalBlockers(completeEntries, project, (sourcePath) => recovery(project, sourcePath));
     const targetDiagnostics = validateEntityMigrationTargets(project, completeEntries, sourceRoot);
     for (const diagnostic of targetDiagnostics) {
         const entry = completeEntries.find((candidate) => candidate.source_identity === diagnostic.sourceIdentity);
@@ -701,8 +732,10 @@ function migrationInventory(projectRoot, sourceRoot, resolveDescriptorPath) {
         entry.proposed_target = null;
         entry.target_sha256 = null;
         entry.recovery = recovery(project, entry.source_paths[0]);
+        causal.rootReasons.set(entry.source_identity, `target_invalid: ${diagnostic.message}`);
     }
-    const classes = ["verified_full", "recoverable_degraded_full_projection", "irrecoverable_summary_only", "duplicate", "conflict", "corrupt", "unsupported", "historical_projection_residue"];
+    causal = applyCausalBlockers(completeEntries, project, (sourcePath) => recovery(project, sourcePath), causal.rootReasons);
+    const classes = ["verified_full", "recoverable_degraded_full_projection", "valid_compacted_summary", "duplicate", "conflict", "corrupt", "unsupported", "historical_projection_residue"];
     const counts = Object.fromEntries(classes.map((classification) => [classification, completeInventory.filter((entry) => entry.classification === classification).length]));
     counts.total = completeInventory.length;
     counts.publishable_entities = completeEntries.filter(({ proposed_target }) => proposed_target !== null).length;
@@ -713,15 +746,43 @@ function migrationInventory(projectRoot, sourceRoot, resolveDescriptorPath) {
     counts.conflicts = counts.duplicate + counts.conflict;
     counts.relationships = completeEntries.reduce((total, entry) => total + entry.relationships.length, 0);
     counts.unresolved_relationships = completeEntries.reduce((total, entry) => total + entry.relationships.filter((relationship) => relationship.status === "unresolved").length, 0);
-    counts.blockers = completeEntries.filter((entry) => BLOCKING.has(entry.classification) || entry.relationships.some((relationship) => relationship.status === "unresolved")).length;
-    const diagnostics = completeEntries.flatMap((entry) => [
-        ...(BLOCKING.has(entry.classification) ? [{ classification: entry.classification, path: entry.source_paths[0], source_identity: entry.source_identity, message: observations.find((item) => item.key === entry.source_identity)?.message ?? `${entry.classification} source requires explicit recovery`, recovery: entry.recovery }] : []),
-        ...entry.relationships.filter((relationship) => relationship.status === "unresolved").map((relationship) => {
-            const target = relationship.target_source_identity ?? "missing structured reference";
-            return { classification: "unresolved_relationship", path: entry.source_paths[0], source_identity: entry.source_identity, relationship_field: relationship.field, target_source_identity: relationship.target_source_identity, message: `source '${entry.source_identity}' relationship '${relationship.field}' references unresolved target '${target}'`, recovery: `Repair relationship '${relationship.field}' on '${entry.source_identity}' to reference an inventoried source identity instead of '${target}', then run agentera state migrate entities --project '${project.replaceAll("'", "'\\''")}' --dry-run --format json.` };
-        }),
-        ...targetDiagnostics.filter(({ sourceIdentity }) => sourceIdentity === entry.source_identity).map((diagnostic) => ({ classification: "corrupt", path: entry.source_paths[0], source_identity: entry.source_identity, message: `target_invalid: ${diagnostic.message}`, recovery: entry.recovery })),
-    ]);
+    const rootDiagnostics = completeEntries
+        .filter((entry) => causal.rootReasons.has(entry.source_identity))
+        .map((entry) => {
+        const unresolved = entry.relationships.find((relationship) => relationship.status === "unresolved");
+        const reason = causal.rootReasons.get(entry.source_identity) ?? `${entry.classification} source requires explicit recovery`;
+        const observationMessage = observations.find((item) => item.key === entry.source_identity)?.message;
+        return {
+            classification: entry.classification,
+            path: entry.source_paths[0],
+            source_identity: entry.source_identity,
+            ...(unresolved ? { relationship_field: unresolved.field, target_source_identity: unresolved.target_source_identity } : {}),
+            message: reason === `${entry.classification} source requires explicit recovery` && observationMessage ? observationMessage : reason,
+            recovery: entry.recovery,
+        };
+    });
+    const dependentDiagnostics = completeEntries.flatMap((entry) => {
+        if (causal.rootReasons.has(entry.source_identity))
+            return [];
+        return entry.relationships.flatMap((relationship) => {
+            if (relationship.status !== "resolved" || !relationship.target_source_identity)
+                return [];
+            return causal.rootsFor(relationship.target_source_identity).map((rootSourceIdentity) => ({
+                classification: "dependent_blocker",
+                path: entry.source_paths[0],
+                source_identity: entry.source_identity,
+                relationship_field: relationship.field,
+                target_source_identity: relationship.target_source_identity,
+                root_source_identity: rootSourceIdentity,
+                message: `source '${entry.source_identity}' relationship '${relationship.field}' is blocked by root source '${rootSourceIdentity}'`,
+                recovery: recovery(project, entry.source_paths[0]),
+            }));
+        });
+    });
+    const diagnostics = [...rootDiagnostics, ...dependentDiagnostics].sort((left, right) => `${left.source_identity}\0${left.classification}\0${left.relationship_field ?? ""}\0${left.target_source_identity ?? ""}\0${left.root_source_identity ?? ""}`.localeCompare(`${right.source_identity}\0${right.classification}\0${right.relationship_field ?? ""}\0${right.target_source_identity ?? ""}\0${right.root_source_identity ?? ""}`));
+    counts.root_blockers = rootDiagnostics.length;
+    counts.dependent_blockers = dependentDiagnostics.length;
+    counts.blockers = counts.root_blockers + counts.dependent_blockers;
     const digestEntries = completeEntries.map(({ record: _record, ...entry }) => entry);
     const digestResidues = preservedResidues.map(({ record: _record, ...entry }) => entry);
     const digestBody = { source_fingerprint: fingerprint, authority, selectors: { project, filter: INVENTORY_FILTER, order: INVENTORY_ORDER }, entries: digestEntries, preserved_residues: digestResidues, preserved_singletons: preserved, counts, diagnostics };
@@ -763,12 +824,12 @@ export function previewEntityMigration(projectRoot, sourceRoot, options = {}) {
         const body = { ...base, entries, diagnostics: pageDiagnostics, omitted: start > 0 || entries.length < completeEntries.length, omitted_count: completeEntries.length - entries.length, diagnostics_omitted_count: diagnostics.length - pageDiagnostics.length, omission_reason: omissionReason, page_after: options.after ?? null, next_after: nextAfter, retrieval: { command } };
         return Math.max(Buffer.byteLength(JSON.stringify(body, null, 2), "utf8"), Buffer.byteLength(YAML.stringify(body), "utf8"));
     };
-    while (entries.length > 0 && serializedBytes() > MAX_OUTPUT_BYTES) {
+    while (entries.length > 0 && serializedBytes() > ENTITY_MIGRATION_PREVIEW_MAX_OUTPUT_BYTES) {
         entries = entries.slice(0, -1);
         omissionReason = "output_byte_budget";
     }
     if (entries.length === 0 && start < completeEntries.length)
-        throw new Error("the next whole migration entry exceeds the 32768-byte output budget; repair that source before retrying");
+        throw new Error(`the next whole migration entry exceeds the ${ENTITY_MIGRATION_PREVIEW_MAX_OUTPUT_BYTES}-byte output budget; repair that source before retrying`);
     const outputDiagnostics = diagnosticsForEntries();
     const nextAfter = start + entries.length < completeEntries.length ? entries.at(-1)?.source_identity ?? null : null;
     const retrieval = { command: nextAfter ? `agentera state migrate entities --project '${quotedProject}' --after '${nextAfter.replaceAll("'", "'\\''")}' --source-fingerprint ${fingerprint} --preview-digest ${previewDigest} --limit ${requestedLimit} --dry-run --format json` : restartCommand };