agentera 3.0.0-dev.41 → 3.0.0-dev.46

package/dist/state/entityMigrationPreview.js

@@ -2,13 +2,12 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
-import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { fullEntityUpgradePreviewCommand } from "../upgrade/upgradeCommands.js";
 import { loadYamlMapping } from "../core/yaml.js";
 import { discoverPlanArtifacts, planDocumentParts } from "../cli/planArtifacts.js";
-import { parseTodoMarkdownListItem, renderTodoPublicRecord } from "../cli/todoMarkdown.js";
 import { assertRealpathBoundary, docsPathOverridesFromBytes, loadArtifactRecord, resolveArtifactPath } from "../registries/artifactRegistry.js";
 import { canonicalRecordJson, validateStateRecord } from "./archiveDiscovery.js";
-import { canonicalEntityEnvelopeBytes, discoverEntities, entityForbiddenCanonicalAliases, entityPreservedAggregateCollections, 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";
@@ -22,7 +21,20 @@ import { legacyIdentity } from "./legacyIdentity.js";
 import { canonicalMigrationRecord } from "./canonicalMigrationRecord.js";
 import { legacySummaryRecord } from "./legacySummaryRecord.js";
 import { applyCausalBlockers } from "./entityMigrationCausality.js";
+import { todoMigrationObservations, todoReconciliationMigrationPlan } from "./entityMigrationTodo.js";
+import { detectStateMode } from "./stateMode.js";
+import { TODO_RECONCILIATION_ACTIVATION_PATH } from "./todoReconciliationActivation.js";
 import { projectPathIsStable as migrationPathIsStable, readProjectFileSnapshot, resolveProjectDescriptorPath, snapshotProjectPath as snapshotMigrationPath, } from "./safeProjectFile.js";
+export function classifyEntityCutoverProject(project, sourceRoot) {
+    if (detectStateMode(project, sourceRoot) === "entities")
+        return "v3";
+    const stateRoot = path.join(project, ".agentera");
+    const aggregateNames = ["plan.yaml", "progress.yaml", "decisions.yaml", "health.yaml"];
+    const aggregateCount = aggregateNames.filter((name) => fs.existsSync(path.join(stateRoot, name))).length;
+    if (!fs.existsSync(stateRoot) || aggregateCount === 0 && !fs.existsSync(path.join(stateRoot, "entities")))
+        return "clean";
+    return fs.existsSync(path.join(stateRoot, "entities")) || aggregateCount === 1 ? "partial" : "v2";
+}
 export const ENTITY_MIGRATION_PREVIEW_MAX_OUTPUT_BYTES = 32_768;
 const DEFAULT_LIMIT = 100;
 const MAX_LIMIT = 1000;
@@ -127,8 +139,10 @@ function collectSources(root, validatedRoot, todoPath, docsSnapshot, descriptorP
     const archives = directoryFiles(root, validatedRoot, ".agentera/archive", (candidate) => /^\.agentera\/archive\/(progress|decisions|health)\/.+/.test(candidate)
         || PLAN_ARCHIVE_SOURCE.test(candidate), descriptorPathResolver);
     const objectives = [".agentera/optimize", ".agentera/optimera"].flatMap((directory) => directoryFiles(root, validatedRoot, directory, (candidate) => /\/(objective|experiments)\.yaml$/.test(candidate), descriptorPathResolver));
-    const collected = [...exact, ...archives, ...objectives];
-    const missingRoots = [".agentera/archive/", ".agentera/optimize/", ".agentera/optimera/"]
+    const todoEntities = directoryFiles(root, validatedRoot, ".agentera/entities/todo/todo_item", (candidate) => candidate.endsWith(".yaml"), descriptorPathResolver);
+    const activation = readMigrationSource(validatedRoot, TODO_RECONCILIATION_ACTIVATION_PATH, descriptorPathResolver);
+    const collected = [...exact, ...archives, ...objectives, ...todoEntities, activation];
+    const missingRoots = [".agentera/archive/", ".agentera/optimize/", ".agentera/optimera/", ".agentera/entities/todo/todo_item/"]
         .filter((directory) => {
         if (collected.some((source) => source.kind === "unsafe" && source.relative === directory))
             return false;
@@ -152,13 +166,6 @@ function authorityBinding(sourceRoot) {
     }
     return { authority_schema_version: authority.schema_version, authority_sha256: hash(bytes) };
 }
-export function entityMigrationAuthorityProjection(sourceRoot = resolveSourceRoot()) {
-    const authorityPath = path.join(sourceRoot, AUTHORITY_PATH);
-    const authority = loadYamlMapping(fs.readFileSync(authorityPath, "utf8"));
-    if (!mapping(authority.entity_migration))
-        throw new Error(`state storage authority '${authorityPath}' has no entity migration contract`);
-    return { authority: AUTHORITY_PATH, ...authority.entity_migration };
-}
 function sourceFingerprint(files) {
     return hash(canonicalRecordJson(files.map((file) => ({
         path: file.relative,
@@ -177,7 +184,7 @@ function parseYaml(source) {
     return loadYamlMapping(source.bytes.toString("utf8"));
 }
 function recovery(project, pathName) {
-    return `Repair '${pathName}', then run agentera state migrate entities --project '${project.replaceAll("'", "'\\''")}' --dry-run --format json.`;
+    return `Repair '${pathName}', then run ${fullEntityUpgradePreviewCommand(project)}.`;
 }
 function unsafeSourceMessage(pathName) {
     return `source path '${pathName}' is a symbolic link, non-file, or unreadable; replace it with a readable regular file inside the project`;
@@ -476,41 +483,8 @@ function objectiveObservations(root, files, observations) {
         observations.push({ key: `${artifact}:corrupt:${source.relative}`, artifact, boundary: artifact === "objective" ? "objective" : "experiment", path: source.relative, provenance: artifact === "objective" ? "objective_candidate" : "experiment_projection", record: null, detail: "corrupt", relationships: [], message: unsafeSourceMessage(source.relative) });
     }
 }
-function todoAndDocs(root, todoPath, files, observations) {
-    const todo = files.find((source) => source.relative === todoPath);
-    if (todo?.kind === "file" && todo.bytes) {
-        let section = "normal";
-        todo.bytes.toString("utf8").split(/\r?\n/).forEach((line, index) => {
-            const heading = line.trim().match(/^##\s+(.+)$/)?.[1]?.toLowerCase();
-            if (heading)
-                section = heading.includes("critical") ? "critical" : heading.includes("degraded") ? "degraded" : heading.includes("annoying") ? "annoying" : heading.includes("resolved") ? "resolved" : heading.includes("normal") ? "normal" : section;
-            const item = parseTodoMarkdownListItem(line.trim());
-            if (!item)
-                return;
-            const severity = section === "resolved" ? "normal" : section;
-            const record = item.kind
-                ? { kind: item.kind, target_version: item.target_version ?? null, title: item.title ?? item.description, requirements: [], acceptance: [], release_blocker: false, severity, status: item.status }
-                : { severity, status: item.status, description: item.description };
-            const violations = todoDocsRecordViolations("todo_item", record);
-            observations.push({ key: `${todoPath}:line:${index + 1}`, artifact: "todo", boundary: "todo_item", path: todoPath, provenance: "current_canonical", record, detail: violations.length ? "corrupt" : "full", relationships: [], message: violations.length ? violations.join("; ") : undefined });
-        });
-    }
-    else if (todo?.kind === "unsafe") {
-        observations.push({ key: "todo:document", artifact: "todo", boundary: "todo_item", path: todoPath, provenance: "current_canonical", record: null, detail: "corrupt", relationships: [], message: unsafeSourceMessage(todoPath) });
-    }
-    const existingTodos = discoverEntities(root, resolveSourceRoot()).entities.filter((entity) => entity.boundary === "todo_item" && entity.id && entity.record);
-    for (const entity of existingTodos) {
-        const row = todoMarkdownRowForMigration(todo?.kind === "file" && todo.bytes ? todo.bytes.toString("utf8") : "", entity.id);
-        if (!row)
-            continue;
-        const severityMatches = row.severity === "resolved" || row.severity === null || entity.record.severity === row.severity;
-        const publicText = row.item.public_description ?? row.item.description;
-        const entityText = renderTodoPublicRecord(entity.record);
-        const textMatches = entity.record.title !== undefined ? entityText === publicText : entityText === row.item.description || entityText === publicText;
-        const publicMatches = entity.record.status === row.item.status && severityMatches && textMatches;
-        if (!publicMatches)
-            observations.push({ key: `conflict:todo:public:${entity.id}`, artifact: "todo", boundary: "todo_item", path: todoPath, provenance: "public_authority_conflict", record: null, detail: "corrupt", relationships: [], message: `TODO.md and Agentera disagree on public values for TODO '${entity.id}'` });
-    }
+function todoAndDocs(root, sourceRoot, todoPath, files, observations) {
+    observations.push(...todoMigrationObservations(root, sourceRoot, todoPath, files));
     const docs = files.find((source) => source.relative === ".agentera/docs.yaml");
     if (docs?.kind === "file") {
         try {
@@ -535,18 +509,6 @@ function todoAndDocs(root, todoPath, files, observations) {
         observations.push({ key: "docs:document", artifact: "docs", boundary: "documentation_inventory_entry", path: docs.relative, provenance: "current_canonical", record: null, detail: "corrupt", relationships: [], message: unsafeSourceMessage(docs.relative) });
     }
 }
-function todoMarkdownRowForMigration(text, id) {
-    let section = "normal";
-    for (const line of text.split(/\r?\n/)) {
-        const heading = line.trim().match(/^##\s+(.+)$/)?.[1]?.toLowerCase();
-        if (heading)
-            section = heading.includes("critical") ? "critical" : heading.includes("degraded") ? "degraded" : heading.includes("annoying") ? "annoying" : heading.includes("resolved") ? "resolved" : heading.includes("normal") ? "normal" : section;
-        const item = parseTodoMarkdownListItem(line.trim());
-        if (item?.id === id)
-            return { severity: section === "resolved" ? "resolved" : ["critical", "degraded", "normal", "annoying"].includes(section) ? section : null, item };
-    }
-    return null;
-}
 function preservedSingletons(files) {
     const declarations = [
         { boundary: "vision", source_path: ".agentera/vision.yaml" },
@@ -624,7 +586,8 @@ function buildEntries(project, sourceRoot, fingerprint, observations, forbiddenA
             ? [...canonicalSummaryBodies(group, forbiddenAliases)].sort()
             : [];
         const identityBinding = canonicalSummaries.length === 1 ? hash(canonicalRecordJson(canonicalSummaries)) : fingerprint;
-        ids.set(key, entityMigrationId(identityBinding, key));
+        const explicitIds = [...new Set(group.map((item) => item.explicitId).filter((id) => id !== undefined))];
+        ids.set(key, explicitIds.length === 1 ? explicitIds[0] : entityMigrationId(identityBinding, key));
     }
     const collisions = new Set();
     const idOwners = new Map();
@@ -732,16 +695,17 @@ function migrationInventory(projectRoot, sourceRoot, resolveDescriptorPath) {
     decisionEvidence(sourceRoot, files, observations);
     planObservations(project, files, observations);
     objectiveObservations(project, files, observations);
-    todoAndDocs(project, todoPath, files, observations);
+    todoAndDocs(project, sourceRoot, todoPath, files, observations);
     const preserved = preservedSingletons(files);
     const completeInventory = buildEntries(project, sourceRoot, fingerprint, observations, entityForbiddenCanonicalAliases(sourceRoot));
     const preservedResidues = completeInventory.filter((entry) => entry.classification === "historical_projection_residue");
     const completeEntries = completeInventory.filter((entry) => entry.classification !== "historical_projection_residue");
+    const todoReconciliation = todoReconciliationMigrationPlan(todoPath, files, completeEntries);
     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, migrationProvenance: entry.canonical_migration_provenance }));
     }
-    let causal = applyCausalBlockers(completeEntries, project, (sourcePath) => recovery(project, sourcePath));
+    let causal = applyCausalBlockers(completeEntries, (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);
@@ -754,7 +718,7 @@ function migrationInventory(projectRoot, sourceRoot, resolveDescriptorPath) {
             entry.recovery = recovery(project, entry.source_paths[0]);
         causal.rootReasons.set(entry.source_identity, `target_invalid: ${diagnostic.message}`);
     }
-    causal = applyCausalBlockers(completeEntries, project, (sourcePath) => recovery(project, sourcePath), causal.rootReasons);
+    causal = applyCausalBlockers(completeEntries, (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;
@@ -805,12 +769,12 @@ function migrationInventory(projectRoot, sourceRoot, resolveDescriptorPath) {
     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 };
+    const digestBody = { source_fingerprint: fingerprint, authority, selectors: { project, filter: INVENTORY_FILTER, order: INVENTORY_ORDER }, entries: digestEntries, preserved_residues: digestResidues, preserved_singletons: preserved, counts, diagnostics, todo_reconciliation: todoReconciliation ?? null };
     const previewDigest = hash(canonicalRecordJson(digestBody));
     const sources = files.map((file) => {
         return { path: file.relative, presence: file.kind === "file" ? "file" : "missing", size: file.bytes?.byteLength ?? 0, sha256: file.bytes ? hash(file.bytes) : null, mode: file.kind === "file" ? file.mode : null, dev: file.kind === "file" ? String(file.dev) : null, ino: file.kind === "file" ? String(file.ino) : null, type: file.kind === "file" ? file.type : null, bytes_base64: file.bytes?.toString("base64") ?? null };
     });
-    return { project, source_fingerprint: fingerprint, preview_digest: previewDigest, ...authority, preserved_singletons: preserved, entries: completeEntries, preserved_residues: preservedResidues, sources, counts, diagnostics };
+    return { project, source_fingerprint: fingerprint, preview_digest: previewDigest, ...authority, preserved_singletons: preserved, entries: completeEntries, preserved_residues: preservedResidues, sources, counts, diagnostics, ...(todoReconciliation ? { todo_reconciliation: todoReconciliation } : {}) };
 }
 export function planEntityMigration(projectRoot, sourceRoot, options = {}) {
     return migrationInventory(projectRoot, sourceRoot, options.resolveDescriptorPath ?? resolveProjectDescriptorPath);
@@ -822,7 +786,7 @@ export function previewEntityMigration(projectRoot, sourceRoot, options = {}) {
     const completeEntries = inventory.entries.map(({ record: _record, ...entry }) => entry);
     const preservedResidues = inventory.preserved_residues.map(({ record: _record, ...entry }) => entry);
     const requestedLimit = Math.max(1, Math.min(options.limit ?? DEFAULT_LIMIT, MAX_LIMIT));
-    const restartCommand = `agentera state migrate entities --project '${project.replaceAll("'", "'\\''")}' --limit ${requestedLimit} --dry-run --format json`;
+    const restartCommand = fullEntityUpgradePreviewCommand(project);
     if (options.after !== undefined && (options.sourceFingerprint !== fingerprint || options.previewDigest !== previewDigest)) {
         throw new EntityMigrationContinuationError(restartCommand);
     }
@@ -835,12 +799,11 @@ export function previewEntityMigration(projectRoot, sourceRoot, options = {}) {
         return diagnostics.filter((diagnostic) => identities.has(diagnostic.source_identity));
     };
     let omissionReason = start > 0 || start + entries.length < completeEntries.length ? "result_limit" : null;
-    const quotedProject = project.replaceAll("'", "'\\''");
-    const base = { schemaVersion: "agentera.entityMigrationPreview.v1", command: "state migrate entities", status: counts.blockers > 0 ? "blocked" : "ready", mode: "preview", project, read_only: true, mutation_intent: false, mutation_performed: false, source_fingerprint: fingerprint, preview_digest: previewDigest, preserved_singletons: preserved, preserved_residues: preservedResidues, counts, source_contract: { authority: AUTHORITY_PATH, ...authority, zero_write: true, scalar_truncation: "forbidden", apply_owner: "full development-channel upgrade --yes" } };
+    const base = { schemaVersion: "agentera.entityMigrationPreview.v1", command: "upgrade", status: counts.blockers > 0 ? "blocked" : "ready", mode: "preview", project, read_only: true, mutation_intent: false, mutation_performed: false, source_fingerprint: fingerprint, preview_digest: previewDigest, preserved_singletons: preserved, preserved_residues: preservedResidues, counts, source_contract: { authority: AUTHORITY_PATH, ...authority, zero_write: true, scalar_truncation: "forbidden", apply_owner: "full development-channel upgrade --yes" } };
     const serializedBytes = () => {
         const pageDiagnostics = diagnosticsForEntries();
         const nextAfter = start + entries.length < completeEntries.length ? entries.at(-1)?.source_identity ?? null : null;
-        const command = nextAfter ? `agentera state migrate entities --project '${quotedProject}' --after '${nextAfter.replaceAll("'", "'\\''")}' --source-fingerprint ${fingerprint} --preview-digest ${previewDigest} --limit ${requestedLimit} --dry-run --format json` : restartCommand;
+        const command = restartCommand;
         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"));
     };
@@ -852,7 +815,7 @@ export function previewEntityMigration(projectRoot, sourceRoot, options = {}) {
         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 };
+    const retrieval = { command: restartCommand };
     return { ...base, status: base.status, mode: "preview", entries, diagnostics: outputDiagnostics, omitted: start > 0 || entries.length < completeEntries.length, omitted_count: completeEntries.length - entries.length, diagnostics_omitted_count: diagnostics.length - outputDiagnostics.length, omission_reason: omissionReason, page_after: options.after ?? null, next_after: nextAfter, retrieval };
 }
 export class EntityMigrationContinuationError extends Error {
@@ -869,7 +832,7 @@ export class EntityMigrationBindingError extends Error {
     classification = "source_changed";
     restartCommand;
     constructor(current) {
-        const restartCommand = `agentera state migrate entities --project '${current.project.replaceAll("'", "'\\''")}' --dry-run --format json`;
+        const restartCommand = fullEntityUpgradePreviewCommand(current.project);
         super(`entity migration source or migration authority changed after preview; rerun ${restartCommand}`);
         this.current = current;
         this.restartCommand = restartCommand;
@@ -881,4 +844,3 @@ export function assertEntityMigrationBinding(expectedSourceFingerprint, expected
         throw new EntityMigrationBindingError(current);
     return effect();
 }
-//# sourceMappingURL=entityMigrationPreview.js.map

package/dist/state/entityMigrationTodo.js

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+import { parseTodoMarkdownListItem, renderTodoPublicRecord } from "../cli/todoMarkdown.js";
+import { discoverEntities } from "./entityStorage.js";
+import { todoDocsRecordViolations } from "./todoDocsEntityValidation.js";
+import { TODO_RECONCILIATION_ACTIVATION_PATH, todoReconciliationActivationBytes } from "./todoReconciliationActivation.js";
+function migrationTodoRows(text) {
+    let section = "normal";
+    const orders = new Map();
+    const rows = [];
+    text.split(/\r?\n/).forEach((line, index) => {
+        const heading = line.trim().match(/^##\s+(.+)$/)?.[1]?.toLowerCase();
+        if (heading) {
+            if (heading.includes("critical"))
+                section = "critical";
+            else if (heading.includes("degraded"))
+                section = "degraded";
+            else if (heading.includes("annoying"))
+                section = "annoying";
+            else if (heading.includes("resolved"))
+                section = "resolved";
+            else if (heading.includes("normal"))
+                section = "normal";
+            else if (heading === "notes")
+                section = "unmanaged";
+        }
+        const item = parseTodoMarkdownListItem(line.trim());
+        if (!item || section === "unmanaged")
+            return;
+        const severity = section === "resolved" ? "normal" : section;
+        const order = (orders.get(section) ?? 0) + 1;
+        orders.set(section, order);
+        const record = item.kind && item.kind !== "x"
+            ? { kind: item.kind, target_version: item.target_version ?? null, title: item.title ?? item.description, requirements: [], acceptance: [], release_blocker: false, severity, status: item.status }
+            : { severity, status: item.status, description: item.public_description ?? item.description };
+        rows.push({ index, section, order, item, record });
+    });
+    return rows;
+}
+function importMigrationTodoPublic(entity, row) {
+    const record = structuredClone(entity);
+    if (row.record.title !== undefined) {
+        delete record.description;
+        record.kind = row.record.kind;
+        record.target_version = row.record.target_version;
+        record.title = row.record.title;
+    }
+    else {
+        for (const field of ["kind", "target_version", "title"])
+            delete record[field];
+        record.description = row.record.description;
+    }
+    if (row.section !== "resolved")
+        record.severity = row.record.severity;
+    record.status = row.record.status;
+    return record;
+}
+export function todoMigrationObservations(root, sourceRoot, todoPath, files) {
+    const observations = [];
+    const todo = files.find((source) => source.relative === todoPath);
+    const activation = files.find((source) => source.relative === TODO_RECONCILIATION_ACTIVATION_PATH);
+    if (activation?.kind === "file")
+        observations.push({ key: "todo:activation:stale", artifact: "todo", boundary: "todo_item", path: TODO_RECONCILIATION_ACTIVATION_PATH, provenance: "preexisting_activation", record: null, detail: "corrupt", relationships: [], message: "TODO reconciliation activation exists before entity cutover" });
+    if (todo?.kind === "file" && todo.bytes) {
+        const rows = migrationTodoRows(todo.bytes.toString("utf8"));
+        const existing = discoverEntities(root, sourceRoot).entities.filter((entity) => entity.boundary === "todo_item");
+        if (existing.length > 0) {
+            const invalid = existing.find((entity) => entity.classification !== "valid" || !entity.id || !entity.record);
+            if (invalid)
+                observations.push({ key: `todo:entity:invalid:${invalid.relativePath}`, artifact: "todo", boundary: "todo_item", path: invalid.relativePath, provenance: "precreated_entity", record: null, detail: "corrupt", relationships: [], message: "pre-created TODO entity evidence is not canonical" });
+            const claimed = new Set();
+            for (const row of rows) {
+                let matches = existing.filter((entity) => entity.classification === "valid" && entity.id && entity.record && !claimed.has(entity.id));
+                if (row.item.id)
+                    matches = matches.filter((entity) => entity.id === row.item.id);
+                else
+                    matches = matches.filter((entity) => renderTodoPublicRecord(entity.record) === (row.item.public_description ?? row.item.description) && (row.section === "resolved" || entity.record.severity === row.record.severity));
+                if (matches.length !== 1) {
+                    observations.push({ key: `todo:row:${row.index + 1}`, artifact: "todo", boundary: "todo_item", path: todoPath, provenance: "precreated_entity_match", record: null, detail: "corrupt", relationships: [], message: matches.length === 0 ? `TODO.md line ${row.index + 1} has no one-to-one canonical entity match` : `TODO.md line ${row.index + 1} has multiple canonical entity matches` });
+                    continue;
+                }
+                const entity = matches[0];
+                claimed.add(entity.id);
+                const record = importMigrationTodoPublic(entity.record, row);
+                const violations = todoDocsRecordViolations("todo_item", record, sourceRoot);
+                observations.push({ key: `${todoPath}:line:${row.index + 1}`, artifact: "todo", boundary: "todo_item", path: todoPath, provenance: "precreated_entity_match", record, detail: violations.length ? "corrupt" : "full", relationships: [], message: violations.length ? violations.join("; ") : undefined, explicitId: entity.id });
+            }
+            for (const entity of existing)
+                if (entity.id && !claimed.has(entity.id))
+                    observations.push({ key: `todo:entity:unmatched:${entity.id}`, artifact: "todo", boundary: "todo_item", path: entity.relativePath, provenance: "precreated_entity_match", record: null, detail: "corrupt", relationships: [], message: `canonical TODO entity '${entity.id}' has no one-to-one TODO.md row match` });
+        }
+        else {
+            for (const row of rows) {
+                const violations = todoDocsRecordViolations("todo_item", row.record, sourceRoot);
+                observations.push({ key: `${todoPath}:line:${row.index + 1}`, artifact: "todo", boundary: "todo_item", path: todoPath, provenance: "current_canonical", record: row.record, detail: violations.length ? "corrupt" : "full", relationships: [], message: violations.length ? violations.join("; ") : undefined });
+            }
+        }
+    }
+    else if (todo?.kind === "unsafe")
+        observations.push({ key: "todo:document", artifact: "todo", boundary: "todo_item", path: todoPath, provenance: "current_canonical", record: null, detail: "corrupt", relationships: [], message: `source path '${todoPath}' is a symbolic link, non-file, or unreadable; replace it with a readable regular file inside the project` });
+    return observations;
+}
+export function todoReconciliationMigrationPlan(todoPath, files, entries) {
+    const todo = files.find((source) => source.relative === todoPath);
+    if (todo?.kind !== "file" || !todo.bytes)
+        return undefined;
+    const rows = migrationTodoRows(todo.bytes.toString("utf8"));
+    const byLine = new Map(entries.filter((entry) => entry.boundary === "todo_item" && entry.proposed_target).flatMap((entry) => {
+        const match = new RegExp(`^${todoPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:line:(\\d+)$`).exec(entry.source_identity);
+        return match ? [[Number(match[1]) - 1, entry]] : [];
+    }));
+    if (byLine.size !== rows.length)
+        return undefined;
+    const lines = todo.bytes.toString("utf8").split(/\r?\n/);
+    for (const row of rows) {
+        const entry = byLine.get(row.index);
+        if (!entry?.proposed_target)
+            return undefined;
+        const record = structuredClone(entry.record);
+        record.reconciliation = { schema_version: "agentera.todoReconciliation.v1", public: { present: true, description: renderTodoPublicRecord(record), severity: String(record.severity), status: String(record.status), order: row.order } };
+        entry.record = record;
+        if (!row.item.id)
+            lines[row.index] = lines[row.index].replace(/^(\s*-\s+\[[ xX]\]\s+)/, `$1[id:${entry.proposed_target.id}] `);
+    }
+    const docs = files.find((source) => source.relative === ".agentera/docs.yaml");
+    const mappingBytes = docs?.kind === "file" ? docs.bytes : Buffer.from("<absent>");
+    return {
+        public_path: todoPath,
+        mapping_sha256: createHash("sha256").update(todoPath).update("\0").update(mappingBytes).digest("hex"),
+        markdown_before_base64: todo.bytes.toString("base64"),
+        markdown_after: `${lines.join("\n").replace(/\n*$/, "")}\n`,
+        activation_after: todoReconciliationActivationBytes([]),
+    };
+}

package/dist/state/entityPublicationContext.js

@@ -804,4 +804,3 @@ export class EntityPublicationContext {
         }
     }
 }
-//# sourceMappingURL=entityPublicationContext.js.map

package/dist/state/entityRetrievalHelp.js

@@ -1,8 +1,8 @@
+import { projectEntityDevelopmentValue, } from "../core/developmentInvocation.js";
 import { resolveSourceRoot } from "../core/sourceRoot.js";
-import { ENTITY_LIST_RUNTIME_FAMILIES, ENTITY_LIST_RUNTIME_REGISTRY, runtimeEntityFamilyForHelpArgs, runtimeEntityListFamilyForHelpArgs, } from "./entityListRuntimeRegistry.js";
+import { ENTITY_LIST_RUNTIME_FAMILIES, ENTITY_LIST_RUNTIME_BOUNDS, ENTITY_LIST_RUNTIME_FORMATS, ENTITY_LIST_RUNTIME_REGISTRY, ENTITY_LIST_RUNTIME_SELECTORS, runtimeEntityFamilyForHelpArgs, runtimeEntityListFamilyForHelpArgs, } from "./entityListRuntimeRegistry.js";
 import { loadStateStorageAuthority } from "./stateStorageAuthority.js";
 export const ENTITY_LIST_HELP_SCHEMA_VERSION = "agentera.entityListHelp.v1";
-const RUNTIME_FORMATS = ["text", "json", "yaml"];
 let cache;
 function isMapping(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -36,14 +36,6 @@ function exactKeys(value, required, optional, prefix, errors) {
         if (!allowed.has(field))
             errors.push(`${prefix}.unknown.${field}`);
 }
-function expectedListSyntax(family) {
-    const base = `agentera state ${family.commandTokens.join(" ")} list`;
-    const identifier = family.familyIdentifier
-        ? ` ${family.familyIdentifier.required ? family.familyIdentifier.syntax : `[${family.familyIdentifier.syntax}]`}`
-        : "";
-    const filters = family.filters.map(({ flag }) => ` [${flag}]`).join("");
-    return `${base}${identifier}${filters} [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json`;
-}
 function valueFlag(syntax) {
     const tokens = syntax.split(" ");
     if (tokens.length !== 2 || !/^--[a-z][a-z0-9-]*$/.test(tokens[0]) || tokens[1].length === 0)
@@ -78,10 +70,10 @@ function exampleGrammarIssue(example, family, pattern) {
         return "type";
     const tokens = example.split(" ");
     if (example.trim() !== example
-        || tokens.some((token) => token.length === 0 || !/^[A-Za-z0-9_.,:/|=+\-]+$/.test(token))
+        || tokens.some((token) => token.length === 0 || !/^[A-Za-z0-9_@.,:/|=+\-]+$/.test(token))
         || tokens.join(" ") !== example)
         return "lexical_form";
-    const prefix = ["agentera", "state", ...family.commandTokens, "list"];
+    const prefix = ["npx", "-y", "agentera@next", "state", ...family.commandTokens, "list"];
     if (tokens.length < prefix.length || !prefix.every((token, index) => tokens[index] === token))
         return "command";
     const identifierSyntax = family.familyIdentifier?.syntax;
@@ -232,9 +224,9 @@ export function validateEntityListHelp(value) {
         errors.push("entity_target.public_retrieval.list_help.schema_version");
     if (!sameStrings(defaults.summary_fields, ["id", "artifact", "retrieval.get"]))
         errors.push("entity_target.public_retrieval.list_help.defaults.summary_fields");
-    if (!sameStrings(defaults.formats, RUNTIME_FORMATS))
+    if (!sameStrings(defaults.formats, ENTITY_LIST_RUNTIME_FORMATS))
         errors.push("entity_target.public_retrieval.list_help.defaults.formats");
-    for (const [field, flag] of [["ids_only", "--ids-only"], ["fields", "--fields FIELDS"]]) {
+    for (const [field, flag] of [["ids_only", ENTITY_LIST_RUNTIME_SELECTORS.idsOnly], ["fields", ENTITY_LIST_RUNTIME_SELECTORS.fields]]) {
         const selector = requireMapping(selectors, field, "entity_target.public_retrieval.list_help.defaults.selectors", errors);
         exactKeys(selector, ["flag", "description"], [], `entity_target.public_retrieval.list_help.defaults.selectors.${field}`, errors);
         if (selector.flag !== flag || typeof selector.description !== "string" || selector.description.trim() === "")
@@ -247,6 +239,11 @@ export function validateEntityListHelp(value) {
             errors.push(`entity_target.public_retrieval.list_help.defaults.bounds.${field}.value`);
     if (Number(bounds.minimum) > Number(bounds.default) || Number(bounds.default) > Number(bounds.maximum))
         errors.push("entity_target.public_retrieval.list_help.defaults.bounds.order");
+    if (bounds.minimum !== ENTITY_LIST_RUNTIME_BOUNDS.minimum
+        || bounds.default !== ENTITY_LIST_RUNTIME_BOUNDS.default
+        || bounds.maximum !== ENTITY_LIST_RUNTIME_BOUNDS.maximum
+        || bounds.max_utf8_bytes !== ENTITY_LIST_RUNTIME_BOUNDS.maxUtf8Bytes)
+        errors.push("entity_target.public_retrieval.list_help.defaults.bounds.runtime_parity");
     const runtimeKeys = Object.keys(ENTITY_LIST_RUNTIME_REGISTRY).sort();
     for (const [surface, record] of [["commands", commands], ["list_help.families", families]]) {
         const actual = Object.keys(record).sort();
@@ -260,7 +257,7 @@ export function validateEntityListHelp(value) {
     const api = mapping(value.api);
     const apiList = mapping(api.list);
     const outputBounds = mapping(policy.output_bounds);
-    if (!sameStrings(api.formats, RUNTIME_FORMATS))
+    if (!sameStrings(api.formats, ENTITY_LIST_RUNTIME_FORMATS))
         errors.push("api.formats");
     if (bounds.minimum !== apiList.minimum_limit)
         errors.push("entity_target.public_retrieval.list_help.defaults.bounds.minimum_authority_parity");
@@ -282,7 +279,9 @@ export function validateEntityListHelp(value) {
         exactKeys(family, ["command_tokens", "bare_read", "filters", "example"], ["bare_recovery", "family_identifier", "summary_fields", "summary_field_notes"], prefix, errors);
         if (family.bare_read !== "alias" && family.bare_read !== "correction")
             errors.push(`${prefix}.bare_read`);
-        if (family.bare_read === "correction" && (typeof family.bare_recovery !== "string" || !family.bare_recovery.startsWith("agentera state ")))
+        if (family.bare_read !== runtime.bareRead)
+            errors.push(`${prefix}.bare_read.runtime_parity`);
+        if (family.bare_read === "correction" && family.bare_recovery !== runtime.projection.bareRecovery)
             errors.push(`${prefix}.bare_recovery`);
         if (family.bare_read === "alias" && family.bare_recovery !== undefined)
             errors.push(`${prefix}.bare_recovery.unexpected`);
@@ -292,7 +291,7 @@ export function validateEntityListHelp(value) {
             errors.push(`${prefix}.filters`);
         const rawFilters = Array.isArray(family.filters) ? family.filters : [];
         const filterNames = rawFilters.map((raw) => mapping(raw).name);
-        if (!sameStrings(filterNames, runtime.filters))
+        if (!sameStrings(filterNames, runtime.filters.map(({ name }) => name)))
             errors.push(`${prefix}.filters.runtime_parity`);
         const parsedFilters = [];
         rawFilters.forEach((raw, index) => {
@@ -313,6 +312,12 @@ export function validateEntityListHelp(value) {
                 if (!parsedFlag || parsedFlag.valueSyntax !== declaredValues.join("|"))
                     errors.push(`${prefix}.filters[${index}].flag_value_syntax`);
             }
+            const codeFilter = runtime.filters[index];
+            if (!codeFilter
+                || codeFilter.name !== name
+                || codeFilter.flag !== filter.flag
+                || JSON.stringify(codeFilter.values) !== JSON.stringify(filter.values))
+                errors.push(`${prefix}.filters[${index}].runtime_parity`);
             parsedFilters.push({ flag: String(filter.flag), name, values: Array.isArray(filter.values) ? strings(filter.values) : String(filter.values) });
         });
         const identifier = family.family_identifier === undefined ? undefined : mapping(family.family_identifier);
@@ -382,10 +387,12 @@ export function validateEntityListHelp(value) {
             formats: strings(defaults.formats),
             example: String(family.example),
         };
-        if (command.list !== expectedListSyntax(projected))
+        if (command.list !== runtime.projection.list)
             errors.push(`${prefix}.list_command`);
-        if (command.get !== `agentera state ${runtime.commandTokens.join(" ")} get --id ID --format json`)
+        if (command.get !== runtime.projection.get)
             errors.push(`${prefix}.get_command`);
+        if (family.example !== runtime.projection.example)
+            errors.push(`${prefix}.example.runtime_parity`);
         const exampleIssue = exampleGrammarIssue(family.example, projected, acceptedIdentity);
         if (exampleIssue)
             errors.push(`${prefix}.example.${exampleIssue}`);
@@ -427,9 +434,12 @@ export function entityListFamilies(sourceRoot = resolveSourceRoot()) {
             const note = mapping(raw);
             return [name, { description: String(note.description), ownership: String(note.ownership), persisted: note.persisted === true, filter: note.filter === true }];
         }));
-        return {
+        const sourceHelp = {
             key,
-            commandTokens: strings(family.command_tokens), syntax: String(command.list), get: String(command.get), bareRead: family.bare_read === "alias" ? "alias" : "correction", ...(typeof family.bare_recovery === "string" ? { bareRecovery: family.bare_recovery } : {}),
+            commandTokens: strings(family.command_tokens),
+            syntax: String(command.list),
+            get: String(command.get),
+            bareRead: family.bare_read === "alias" ? "alias" : "correction",
             filters: family.filters.map((raw) => { const filter = mapping(raw); return { flag: String(filter.flag), name: String(filter.name), values: Array.isArray(filter.values) ? strings(filter.values) : String(filter.values) }; }),
             ...(identifier ? { familyIdentifier: { syntax: String(identifier.syntax), required: identifier.required === true, description: String(identifier.description) } } : {}),
             summaryFields: family.summary_fields === undefined ? strings(defaults.summary_fields) : strings(family.summary_fields),
@@ -441,7 +451,28 @@ export function entityListFamilies(sourceRoot = resolveSourceRoot()) {
                 mutualExclusion: defaultSelectors.mutual_exclusion === true,
             },
             bounds: { minimum: Number(defaultBounds.minimum), default: Number(defaultBounds.default), maximum: Number(defaultBounds.maximum), maxUtf8Bytes: Number(defaultBounds.max_utf8_bytes) },
-            formats: strings(defaults.formats), example: String(family.example),
+            formats: strings(defaults.formats),
+            example: String(family.example),
+        };
+        return {
+            key,
+            commandTokens: sourceHelp.commandTokens,
+            syntax: projectEntityDevelopmentValue(command.list, key, "list"),
+            get: projectEntityDevelopmentValue(command.get, key, "get"),
+            bareRead: sourceHelp.bareRead,
+            ...(typeof family.bare_recovery === "string" ? { bareRecovery: projectEntityDevelopmentValue(family.bare_recovery, key, "bareRecovery") } : {}),
+            filters: sourceHelp.filters,
+            ...(identifier ? { familyIdentifier: { syntax: String(identifier.syntax), required: identifier.required === true, description: String(identifier.description) } } : {}),
+            summaryFields: family.summary_fields === undefined ? strings(defaults.summary_fields) : strings(family.summary_fields),
+            minimumFields: [...strings(projection.minimum_fields), ...strings(familyMinimumFields[key])],
+            summaryFieldNotes: notes,
+            selectors: {
+                idsOnly: { flag: String(mapping(defaultSelectors.ids_only).flag), description: String(mapping(defaultSelectors.ids_only).description) },
+                fields: { flag: String(mapping(defaultSelectors.fields).flag), description: String(mapping(defaultSelectors.fields).description) },
+                mutualExclusion: defaultSelectors.mutual_exclusion === true,
+            },
+            bounds: { minimum: Number(defaultBounds.minimum), default: Number(defaultBounds.default), maximum: Number(defaultBounds.maximum), maxUtf8Bytes: Number(defaultBounds.max_utf8_bytes) },
+            formats: strings(defaults.formats), example: projectEntityDevelopmentValue(family.example, key, "example"),
         };
     });
     cache = { revision: authority.revision, families };
@@ -473,4 +504,3 @@ export function entityListAuthorityProjection(sourceRoot = resolveSourceRoot())
     entityListFamilies(sourceRoot);
     return mapping(mapping(loadStateStorageAuthority(sourceRoot).document.entity_target).public_retrieval);
 }
-//# sourceMappingURL=entityRetrievalHelp.js.map

package/dist/state/entityStorage.js

@@ -894,4 +894,3 @@ export function allocateAndPublishEntity(request, candidate) {
         });
     });
 }
-//# sourceMappingURL=entityStorage.js.map

package/dist/state/exactReplacementRecovery.js

@@ -16,4 +16,3 @@ export class FileReplacementError extends Error {
             this.code = code;
     }
 }
-//# sourceMappingURL=exactReplacementRecovery.js.map

package/dist/state/experimentArchive.js

@@ -61,4 +61,3 @@ export function assertExperimentArchiveReplay(publication) {
         recovery: "Retry only with the byte-equivalent experiment record for this stable identity.",
     });
 }
-//# sourceMappingURL=experimentArchive.js.map

package/dist/state/experimentIdentity.js

@@ -200,4 +200,3 @@ export function validateExperimentPublicationIdentity(discovery, projection, obj
     }
     return stableId;
 }
-//# sourceMappingURL=experimentIdentity.js.map

package/dist/state/healthEntities.js

@@ -260,4 +260,3 @@ export function listHealthEntities(root, limit, dimension, cursor, options = {})
     };
     return projectEntityList(response(), selector, projectionOptions);
 }
-//# sourceMappingURL=healthEntities.js.map

package/dist/state/healthEntityValidation.js

@@ -16,4 +16,3 @@ export function healthEntityViolations(record) {
     }
     return violations;
 }
-//# sourceMappingURL=healthEntityValidation.js.map

package/dist/state/healthRepair.js

@@ -67,4 +67,3 @@ export function repairHealthProjectionBytes(bytes, number, keep) {
     }
     return { bytes, removed };
 }
-//# sourceMappingURL=healthRepair.js.map

package/dist/state/installRoot.js

@@ -316,4 +316,3 @@ export function formatResolvedAppHome(explicitRoot, opts = {}) {
     }
     return resolvedPath;
 }
-//# sourceMappingURL=installRoot.js.map

package/dist/state/legacyEntityCutoverEvidence.js

@@ -63,4 +63,3 @@ export function loadLegacyEntityCutoverTargets(projectRoot, markerBytes) {
     }
     return targets;
 }
-//# sourceMappingURL=legacyEntityCutoverEvidence.js.map

package/dist/state/legacyIdentity.js

@@ -45,4 +45,3 @@ export function legacyIdentity(value, artifactId, entryNumberField) {
 export function legacyEntryNumber(value, artifactId, entryNumberField) {
     return legacyIdentity(value, artifactId, entryNumberField).number;
 }
-//# sourceMappingURL=legacyIdentity.js.map

package/dist/state/legacySummaryRecord.js

@@ -4,4 +4,3 @@ export function legacySummaryRecord(value) {
         return value;
     return typeof value === "string" ? { summary: value } : null;
 }
-//# sourceMappingURL=legacySummaryRecord.js.map

package/dist/state/listAccounting.js

@@ -52,4 +52,3 @@ export function provenanceCounts(entries) {
     counts.candidate_count = entries.length;
     return counts;
 }
-//# sourceMappingURL=listAccounting.js.map