agentera 3.0.0-dev.41 → 3.0.0-dev.47

package/dist/state/entityCutover.js

@@ -4,12 +4,17 @@ import path from "node:path";
 import { dumpYamlMapping, loadYamlMapping } from "../core/yaml.js";
 import { canonicalRecordJson } from "./archiveDiscovery.js";
 import { verifyEntityCutoverGitSource } from "./entityCutoverGit.js";
-import { canonicalEntityEnvelopeBytes, validateEntityState } from "./entityStorage.js";
+import { canonicalEntityEnvelope, canonicalEntityEnvelopeBytes, validateEntityState } from "./entityStorage.js";
 import { planEntityMigration, validateEntityMigrationTargets } from "./entityMigrationPreview.js";
 import { loadLegacyEntityCutoverTargets } from "./legacyEntityCutoverEvidence.js";
 import { validateRealProjectRoot } from "./projectRoot.js";
 import { readProjectFileSnapshot } from "./safeProjectFile.js";
 import { acquireWriterLock } from "./write/lock.js";
+import { EntityPublicationContext } from "./entityPublicationContext.js";
+import { todoReconciliationBinding } from "./todoDocsEntities.js";
+import { todoCutoverPublicProjectionViolations } from "./todoReconciliationInspection.js";
+import { TODO_RECONCILIATION_ACTIVATION_PATH, todoReconciliationActivationBytes } from "./todoReconciliationActivation.js";
+import { inspectTodoReconciliation, publishTodoReconciliation, recoverTodoReconciliation } from "./todoReconciliationTransaction.js";
 export const MIGRATION_ROOT = ".agentera/migrations/entities";
 export const FORWARD_MANIFEST = `${MIGRATION_ROOT}/forward.yaml`;
 export const ENTITY_MODE_MARKER = ".agentera/state-mode.yaml";
@@ -114,7 +119,7 @@ function listFiles(project, relativeRoot) {
     visit(absoluteRoot);
     return found.sort();
 }
-function validateExistingTargets(project, targets) {
+function validateExistingTargets(project, targets, mutableTodoTargets = new Set()) {
     const expected = new Map(targets.map((target) => [target.path, target]));
     for (const relative of listFiles(project, ".agentera/entities")) {
         if (!expected.has(relative))
@@ -124,8 +129,11 @@ function validateExistingTargets(project, targets) {
         const observed = readProjectFileSnapshot(validateRealProjectRoot(project), target.path);
         if (observed.kind === "missing")
             continue;
-        if (observed.kind !== "file" || hash(observed.bytes) !== target.sha256)
+        if (observed.kind !== "file" || hash(observed.bytes) !== target.sha256) {
+            if (observed.kind === "file" && mutableTodoTargets.has(target.path))
+                continue;
             throw new EntityCutoverError(`first unresolved path '${target.path}': existing target is not an exact converted match`);
+        }
     }
 }
 function validateActiveEntityCutover(project, markerBytes, sourceRoot) {
@@ -162,13 +170,18 @@ function inspect(projectRoot, sourceRoot, requireGit, writerLockHeld = false, ac
     const project = validateRealProjectRoot(projectRoot).path;
     const marker = markerSnapshot(project);
     if (marker.kind === "file")
-        return { inspection: { phase: "active", entityCount: validateActiveEntityCutover(project, marker.bytes, sourceRoot) } };
+        return { inspection: { phase: "active", entityCount: validateActiveEntityCutover(project, marker.bytes, sourceRoot), todoReconciliation: false } };
     if (marker.kind !== "missing")
         throw new EntityCutoverError(`first unresolved path '${ENTITY_MODE_MARKER}': marker path is unsafe`);
+    const binding = todoReconciliationBinding(project, sourceRoot);
+    if (inspectTodoReconciliation(project, binding).length > 0) {
+        return { inspection: { phase: "ready", entityCount: 1, todoReconciliation: true } };
+    }
     const plan = planEntityMigration(project, sourceRoot);
     assertPlanReady(plan, sourceRoot);
     const targets = targetsForPlan(plan);
-    validateExistingTargets(project, targets);
+    const mutableTodoTargets = new Set(plan.todo_reconciliation ? plan.entries.filter(({ boundary }) => boundary === "todo_item").map((entry) => entry.proposed_target.path) : []);
+    validateExistingTargets(project, targets, mutableTodoTargets);
     let head;
     if (requireGit) {
         const allowedPaths = new Set([FORWARD_MANIFEST, ENTITY_MODE_MARKER, ...targets.map(({ path: target }) => target)]);
@@ -180,13 +193,15 @@ function inspect(projectRoot, sourceRoot, requireGit, writerLockHeld = false, ac
         const binding = verifyEntityCutoverGitSource(project, plan, { paths: allowedPaths, prefixes: writerLockHeld ? [".agentera/.writer.lock"] : [] });
         head = binding.head;
     }
-    return { inspection: { phase: "ready", entityCount: targets.length }, plan, ...(head ? { head } : {}) };
+    return { inspection: { phase: "ready", entityCount: targets.length, todoReconciliation: Boolean(plan.todo_reconciliation) }, plan, ...(head ? { head } : {}) };
 }
 export function inspectEntityCutoverForUpgrade(projectRoot, sourceRoot, requireGit = false, activeUpgradeLockPaths = []) {
     return inspect(projectRoot, sourceRoot, requireGit, false, activeUpgradeLockPaths).inspection;
 }
 export function prepareEntityCutoverForUpgrade(projectRoot, sourceRoot, activeUpgradeLockPaths = []) {
     const current = inspect(projectRoot, sourceRoot, true, false, activeUpgradeLockPaths);
+    if (current.inspection.phase === "ready" && !current.plan)
+        return { project: validateRealProjectRoot(projectRoot).path, sourceRoot, head: "", sourceFingerprint: "", previewDigest: "", recovery: true };
     if (current.inspection.phase === "active" || !current.plan || !current.head)
         throw new EntityCutoverError("entity authority is already active; no cutover preparation is available");
     return { project: current.plan.project, sourceRoot, head: current.head, sourceFingerprint: current.plan.source_fingerprint, previewDigest: current.plan.preview_digest };
@@ -222,8 +237,11 @@ function publishTargets(project, plan) {
         const bytes = canonicalEntityEnvelopeBytes({ id: target.id, artifact: entry.artifact, record: entry.record, migrationProvenance: entry.canonical_migration_provenance });
         const observed = readProjectFileSnapshot(validateRealProjectRoot(project), target.path);
         if (observed.kind === "file") {
-            if (hash(observed.bytes) !== hash(bytes))
+            if (hash(observed.bytes) !== hash(bytes)) {
+                if (plan.todo_reconciliation && entry.boundary === "todo_item")
+                    continue;
                 throw new EntityCutoverError(`first unresolved path '${target.path}': existing target is not an exact converted match`);
+            }
             continue;
         }
         if (observed.kind !== "missing")
@@ -238,6 +256,142 @@ function publishTargets(project, plan) {
         fault("entity_published");
     }
 }
+function upgradePublicationContext(project, activeUpgradeLockPaths) {
+    const lockPath = activeUpgradeLockPaths.find((candidate) => path.dirname(candidate) === path.join(project, ".agentera"));
+    if (!lockPath || !fs.existsSync(lockPath))
+        throw new EntityCutoverError("active project upgrade lock is unavailable for recoverable TODO cutover");
+    const relative = path.relative(project, lockPath).split(path.sep).join("/");
+    return EntityPublicationContext.open(validateRealProjectRoot(project), relative, fs.readFileSync(lockPath));
+}
+function validatePendingEntityCutoverTargets(project, sourceRoot, binding, targets) {
+    const entityTargets = new Map();
+    let activation;
+    let publicTarget;
+    let marker;
+    for (const target of targets) {
+        const match = /^\.agentera\/entities\/([a-z][a-z0-9_]*)\/([a-z][a-z0-9_]*)\/([a-z]{10})\.yaml$/.exec(target.path);
+        if (match) {
+            entityTargets.set(target.path, { artifact: match[1], boundary: match[2], id: match[3], target });
+            continue;
+        }
+        if (target.path === TODO_RECONCILIATION_ACTIVATION_PATH && !activation)
+            activation = target;
+        else if (target.path === binding.publicPath && !publicTarget)
+            publicTarget = target;
+        else if (target.path === ENTITY_MODE_MARKER && !marker)
+            marker = target;
+        else
+            throw new EntityCutoverError(`first unresolved path '${target.path}': pending TODO cutover journal has an unexpected target`);
+    }
+    if (!activation || !publicTarget || !marker || targets.length !== entityTargets.size + 3) {
+        throw new EntityCutoverError("first unresolved path '.agentera/.todo-reconciliation': pending TODO cutover journal target set is incomplete");
+    }
+    if (activation.before !== null || !activation.after.equals(Buffer.from(todoReconciliationActivationBytes([])))) {
+        throw new EntityCutoverError(`first unresolved path '${TODO_RECONCILIATION_ACTIVATION_PATH}': pending TODO cutover activation target is invalid`);
+    }
+    if (publicTarget.before === null || marker.before !== null) {
+        throw new EntityCutoverError("first unresolved path '.agentera/.todo-reconciliation': pending TODO cutover baselines are invalid");
+    }
+    const currentEntityPaths = listFiles(project, ".agentera/entities");
+    const expectedEntityPaths = [...entityTargets.keys()].sort();
+    if (canonicalRecordJson(currentEntityPaths) !== canonicalRecordJson(expectedEntityPaths)) {
+        const unexpected = currentEntityPaths.find((target) => !entityTargets.has(target));
+        const missing = expectedEntityPaths.find((target) => !currentEntityPaths.includes(target));
+        const unresolved = unexpected ?? missing ?? ".agentera/entities";
+        throw new EntityCutoverError(`first unresolved path '${unresolved}': canonical entity is not part of the pending journal's complete validated target set`);
+    }
+    for (const target of targets) {
+        const observed = readProjectFileSnapshot(validateRealProjectRoot(project), target.path);
+        if (observed.kind === "missing" && target.before === null)
+            continue;
+        if (observed.kind === "file" && (observed.bytes.equals(target.after) || target.before?.equals(observed.bytes)))
+            continue;
+        throw new EntityCutoverError(`first unresolved path '${target.path}': pending TODO cutover target changed outside its journal baseline`);
+    }
+    const finalEntities = [...entityTargets.values()].sort((left, right) => left.target.path.localeCompare(right.target.path)).map(({ artifact, boundary, id, target }) => {
+        let envelope;
+        try {
+            envelope = canonicalEntityEnvelope(target.after.toString("utf8"), { id, artifact, boundary }, sourceRoot, { kind: "migration_preview", projectRoot: project });
+        }
+        catch (error) {
+            throw new EntityCutoverError(`first unresolved path '${target.path}': pending cutover final entity is invalid: ${error.message}`);
+        }
+        return { artifact, boundary, id, record: envelope.record };
+    });
+    const projectionIssue = todoCutoverPublicProjectionViolations(publicTarget.after.toString("utf8"), finalEntities.filter(({ artifact, boundary }) => artifact === "todo" && boundary === "todo_item"))[0];
+    if (projectionIssue)
+        throw new EntityCutoverError(`first unresolved path '${binding.publicPath}': ${projectionIssue}`);
+    const markerValue = loadYamlMapping(marker.after.toString("utf8"));
+    if (!exactKeys(markerValue, ["schemaVersion", "mode", "source_fingerprint", "preview_digest"])
+        || markerValue.schemaVersion !== "agentera.stateMode.v1"
+        || markerValue.mode !== "entities"
+        || typeof markerValue.source_fingerprint !== "string"
+        || typeof markerValue.preview_digest !== "string"
+        || !SHA256.test(markerValue.source_fingerprint)
+        || !SHA256.test(markerValue.preview_digest)) {
+        throw new EntityCutoverError(`first unresolved path '${ENTITY_MODE_MARKER}': pending TODO cutover authority target is invalid`);
+    }
+    const validation = validateEntityState(project, sourceRoot, { kind: "migration_preview", projectRoot: project });
+    if (!validation.valid || validation.entityCount !== entityTargets.size) {
+        const issue = validation.issues[0];
+        throw new EntityCutoverError(`first unresolved path '${issue?.path ?? ".agentera/entities"}': TODO cutover entity graph is invalid (${validation.entityCount}/${entityTargets.size})${issue ? `: ${issue.message}` : ""}`);
+    }
+}
+function recoverPendingTodoCutover(project, sourceRoot, activeUpgradeLockPaths) {
+    const binding = todoReconciliationBinding(project, sourceRoot);
+    if (!inspectTodoReconciliation(project, binding).length)
+        return null;
+    const context = upgradePublicationContext(project, activeUpgradeLockPaths);
+    let journalTargets;
+    try {
+        recoverTodoReconciliation(context, sourceRoot, binding, {
+            beforeRecovery: (targets) => {
+                validatePendingEntityCutoverTargets(project, sourceRoot, binding, targets);
+                journalTargets = targets;
+            },
+            beforeActivation: () => {
+                if (!journalTargets)
+                    throw new EntityCutoverError("pending TODO cutover targets were not validated before recovery");
+                validatePendingEntityCutoverTargets(project, sourceRoot, binding, journalTargets);
+            },
+        });
+    }
+    finally {
+        context.close();
+    }
+    const marker = markerSnapshot(project);
+    if (marker.kind !== "file")
+        throw new EntityCutoverError(`first unresolved path '${ENTITY_MODE_MARKER}': recovered cutover did not publish its authority marker`);
+    return { status: "complete", phase: "active", idempotent: false, mutation_performed: true, entity_count: validateActiveEntityCutover(project, marker.bytes, sourceRoot) };
+}
+function publishTodoCutover(project, sourceRoot, plan, activeUpgradeLockPaths) {
+    const reconciliation = plan.todo_reconciliation;
+    if (!reconciliation) {
+        publishMarker(project, plan);
+        return;
+    }
+    const markerBytes = dumpYamlMapping({ schemaVersion: "agentera.stateMode.v1", mode: "entities", source_fingerprint: plan.source_fingerprint, preview_digest: plan.preview_digest });
+    const targets = plan.entries.map((entry) => {
+        const target = entry.proposed_target;
+        const before = readProjectFileSnapshot(validateRealProjectRoot(project), target.path);
+        if (before.kind !== "file")
+            throw new EntityCutoverError(`first unresolved path '${target.path}': cutover target was not published before reconciliation`);
+        return { path: target.path, before: before.bytes, after: canonicalEntityEnvelopeBytes({ id: target.id, artifact: entry.artifact, record: entry.record, migrationProvenance: entry.canonical_migration_provenance }) };
+    });
+    targets.push({ path: TODO_RECONCILIATION_ACTIVATION_PATH, before: null, after: reconciliation.activation_after }, { path: reconciliation.public_path, before: Buffer.from(reconciliation.markdown_before_base64, "base64"), after: reconciliation.markdown_after }, { path: ENTITY_MODE_MARKER, before: null, after: markerBytes });
+    const validatedTargets = targets.map((target) => ({ path: target.path, before: target.before, after: Buffer.from(target.after) }));
+    const context = upgradePublicationContext(project, activeUpgradeLockPaths);
+    try {
+        publishTodoReconciliation(context, sourceRoot, { publicPath: reconciliation.public_path, mappingSha256: reconciliation.mapping_sha256 }, targets, {
+            retainUnchangedTargets: true,
+            interruptAfterTarget: process.env.NODE_ENV === "test" && process.env.AGENTERA_FAULT_INJECT_TODO_CUTOVER_AFTER_TARGET ? Number(process.env.AGENTERA_FAULT_INJECT_TODO_CUTOVER_AFTER_TARGET) : undefined,
+            beforeActivation: () => validatePendingEntityCutoverTargets(project, sourceRoot, { publicPath: reconciliation.public_path, mappingSha256: reconciliation.mapping_sha256 }, validatedTargets),
+        });
+    }
+    finally {
+        context.close();
+    }
+}
 function publishMarker(project, plan) {
     const markerBytes = dumpYamlMapping({ schemaVersion: "agentera.stateMode.v1", mode: "entities", source_fingerprint: plan.source_fingerprint, preview_digest: plan.preview_digest });
     const existing = markerSnapshot(project);
@@ -262,6 +416,18 @@ function publishMarker(project, plan) {
     }
 }
 export function applyPreparedEntityCutover(prepared, activeUpgradeLockPaths = []) {
+    if (prepared.recovery) {
+        const lock = acquireWriterLock(prepared.project, 2000);
+        try {
+            const recovered = recoverPendingTodoCutover(prepared.project, prepared.sourceRoot, activeUpgradeLockPaths);
+            if (!recovered)
+                throw new EntityCutoverError("prepared TODO cutover recovery journal is missing");
+            return recovered;
+        }
+        finally {
+            lock.release();
+        }
+    }
     const before = inspect(prepared.project, prepared.sourceRoot, true, false, activeUpgradeLockPaths);
     if (before.inspection.phase === "active")
         return { status: "complete", phase: "active", idempotent: true, mutation_performed: false, entity_count: before.inspection.entityCount };
@@ -281,7 +447,7 @@ export function applyPreparedEntityCutover(prepared, activeUpgradeLockPaths = []
             const issue = validation.issues[0];
             throw new EntityCutoverError(`first unresolved path '${issue?.path ?? ".agentera/entities"}': converted entity graph is invalid (${validation.entityCount}/${plan.entries.length})${issue ? `: ${issue.message}` : ""}`);
         }
-        publishMarker(prepared.project, plan);
+        publishTodoCutover(prepared.project, prepared.sourceRoot, plan, activeUpgradeLockPaths);
         const marker = markerSnapshot(prepared.project);
         if (marker.kind !== "file")
             throw new EntityCutoverError(`first unresolved path '${ENTITY_MODE_MARKER}': marker was not published`);
@@ -291,4 +457,3 @@ export function applyPreparedEntityCutover(prepared, activeUpgradeLockPaths = []
         lock.release();
     }
 }
-//# sourceMappingURL=entityCutover.js.map

package/dist/state/entityCutoverGit.js

@@ -125,4 +125,3 @@ export function verifyEntityCutoverGitSource(projectRoot, plan, allowlist = {})
         throw new EntityCutoverGitError("Git HEAD changed during v2-to-v3 preflight");
     return { head };
 }
-//# sourceMappingURL=entityCutoverGit.js.map

package/dist/state/entityGlossaryAuthority.js

@@ -11,4 +11,3 @@ export function loadEntityGlossaryAuthority(path) {
     cache = { path, bytes, contract };
     return contract;
 }
-//# sourceMappingURL=entityGlossaryAuthority.js.map

package/dist/state/entityListProjection.js

@@ -185,4 +185,3 @@ export function projectEntityList(response, selector, options) {
         return minimum;
     fail(options, `the requested summary rows cannot fit the ${options.maxUtf8Bytes}-byte ${options.format} list budget`, "Request fewer rows and retry; no rows were returned partially.", 1);
 }
-//# sourceMappingURL=entityListProjection.js.map

package/dist/state/entityListRuntimeRegistry.js

@@ -1,16 +1,52 @@
+import { CANONICAL_DEVELOPMENT_CLI } from "../core/developmentChannel.js";
 const COMMON_SUMMARY_FIELDS = ["id", "artifact", "retrieval.get"];
+export const ENTITY_LIST_RUNTIME_FORMATS = ["text", "json", "yaml"];
+export const ENTITY_LIST_RUNTIME_BOUNDS = {
+    minimum: 1,
+    default: 20,
+    maximum: 100,
+    maxUtf8Bytes: 32768,
+};
+export const ENTITY_LIST_RUNTIME_SELECTORS = {
+    idsOnly: "--ids-only",
+    fields: "--fields FIELDS",
+};
+function family(options) {
+    const identifier = options.familyIdentifier
+        ? ` ${options.familyIdentifier.required ? options.familyIdentifier.syntax : `[${options.familyIdentifier.syntax}]`}`
+        : "";
+    const filters = options.filters.map(({ flag }) => ` [${flag}]`).join("");
+    const root = `${CANONICAL_DEVELOPMENT_CLI} state ${options.commandTokens.join(" ")}`;
+    const projection = {
+        list: `${root} list${identifier}${filters} [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json`,
+        get: `${root} get --id ID --format json`,
+        example: `${CANONICAL_DEVELOPMENT_CLI} ${options.exampleArguments}`,
+        ...(options.bareRecoveryArguments ? { bareRecovery: `${CANONICAL_DEVELOPMENT_CLI} ${options.bareRecoveryArguments}` } : {}),
+    };
+    const { exampleArguments: _example, bareRecoveryArguments: _bareRecovery, ...runtime } = options;
+    return { ...runtime, projection };
+}
 export const ENTITY_LIST_RUNTIME_REGISTRY = {
-    progress: { key: "progress", commandTokens: ["progress"], parser: "generic", artifact: "progress", boundary: "progress_cycle", filters: ["topic", "status"], summaryFields: COMMON_SUMMARY_FIELDS },
-    decisions: { key: "decisions", commandTokens: ["decisions"], parser: "generic", artifact: "decisions", boundary: "decision", filters: ["topic"], summaryFields: COMMON_SUMMARY_FIELDS },
-    health: { key: "health", commandTokens: ["health"], parser: "generic", artifact: "health", boundary: "health_audit", filters: ["dimension"], summaryFields: COMMON_SUMMARY_FIELDS },
-    plans: { key: "plans", commandTokens: ["plan"], parser: "plans", artifact: "plan", boundary: "plan", filters: ["status"], summaryFields: COMMON_SUMMARY_FIELDS },
-    plan_tasks: { key: "plan_tasks", commandTokens: ["plan", "tasks"], parser: "plan_tasks", artifact: "plan", boundary: "plan_task", boundsBoundary: "plan", filters: [], familyIdentifier: { syntax: "PLAN_ID", required: false }, summaryFields: COMMON_SUMMARY_FIELDS },
-    objective: { key: "objective", commandTokens: ["objective"], parser: "generic", artifact: "objective", boundary: "objective", filters: [], summaryFields: COMMON_SUMMARY_FIELDS },
-    experiments: { key: "experiments", commandTokens: ["experiments"], parser: "experiments", artifact: "experiments", boundary: "experiment", filters: [], familyIdentifier: { syntax: "--objective ID", required: true }, summaryFields: COMMON_SUMMARY_FIELDS },
-    todo: { key: "todo", commandTokens: ["todo"], parser: "generic", artifact: "todo", boundary: "todo_item", filters: ["severity", "status"], summaryFields: ["id", "artifact", "public_order", "readiness", "actionability", "queue_rank", "reconciliation", "retrieval.get"] },
-    docs: { key: "docs", commandTokens: ["docs"], parser: "generic", artifact: "docs", boundary: "documentation_inventory_entry", filters: ["topic", "status"], summaryFields: COMMON_SUMMARY_FIELDS },
+    progress: family({ key: "progress", commandTokens: ["progress"], parser: "generic", artifact: "progress", boundary: "progress_cycle", bareRead: "alias", filters: [{ name: "topic", flag: "--topic TEXT", values: "free_text" }, { name: "status", flag: "--status STATUS", values: "free_text" }], summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state progress list --limit 20 --format json" }),
+    decisions: family({ key: "decisions", commandTokens: ["decisions"], parser: "generic", artifact: "decisions", boundary: "decision", bareRead: "alias", filters: [{ name: "topic", flag: "--topic TEXT", values: "free_text" }], summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state decisions list --limit 20 --format json" }),
+    health: family({ key: "health", commandTokens: ["health"], parser: "generic", artifact: "health", boundary: "health_audit", bareRead: "correction", filters: [{ name: "dimension", flag: "--dimension DIMENSION", values: "free_text" }], summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state health list --limit 20 --format json", bareRecoveryArguments: "state health list --limit 20 --format json" }),
+    plans: family({ key: "plans", commandTokens: ["plan"], parser: "plans", artifact: "plan", boundary: "plan", bareRead: "correction", filters: [{ name: "status", flag: "--status open|complete|archived", values: ["open", "complete", "archived"] }], summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state plan list --status open --limit 20 --format json", bareRecoveryArguments: "state plan list --status open --limit 20 --format json" }),
+    plan_tasks: family({ key: "plan_tasks", commandTokens: ["plan", "tasks"], parser: "plan_tasks", artifact: "plan", boundary: "plan_task", boundsBoundary: "plan", bareRead: "correction", filters: [], familyIdentifier: { syntax: "PLAN_ID", required: false }, summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state plan tasks list --limit 20 --format json", bareRecoveryArguments: "state plan tasks list --limit 20 --format json" }),
+    objective: family({ key: "objective", commandTokens: ["objective"], parser: "generic", artifact: "objective", boundary: "objective", bareRead: "correction", filters: [], summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state objective list --limit 20 --format json", bareRecoveryArguments: "state objective list --limit 20 --format json" }),
+    experiments: family({ key: "experiments", commandTokens: ["experiments"], bareRecoveryCommandTokens: ["objective"], parser: "experiments", artifact: "experiments", boundary: "experiment", bareRead: "correction", filters: [], familyIdentifier: { syntax: "--objective ID", required: true }, summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state experiments list --objective qjtrmnpvka --limit 20 --format json", bareRecoveryArguments: "state objective list --limit 20 --format json" }),
+    todo: family({ key: "todo", commandTokens: ["todo"], parser: "generic", artifact: "todo", boundary: "todo_item", bareRead: "alias", filters: [{ name: "severity", flag: "--severity SEVERITY", values: "free_text" }, { name: "status", flag: "--status STATUS", values: "free_text" }], summaryFields: ["id", "artifact", "public_order", "readiness", "actionability", "queue_rank", "reconciliation", "retrieval.get"], exampleArguments: "state todo list --severity critical --ids-only --limit 20 --format json" }),
+    docs: family({ key: "docs", commandTokens: ["docs"], parser: "generic", artifact: "docs", boundary: "documentation_inventory_entry", bareRead: "correction", filters: [{ name: "topic", flag: "--topic TEXT", values: "free_text" }, { name: "status", flag: "--status STATUS", values: "free_text" }], summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state docs list --limit 20 --format json", bareRecoveryArguments: "state docs list --limit 20 --format json" }),
 };
-export const ENTITY_LIST_RUNTIME_FAMILIES = Object.values(ENTITY_LIST_RUNTIME_REGISTRY);
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+deepFreeze(ENTITY_LIST_RUNTIME_REGISTRY);
+export const ENTITY_LIST_RUNTIME_FAMILIES = Object.freeze(Object.values(ENTITY_LIST_RUNTIME_REGISTRY));
 export function runtimeEntityFamiliesForCommand(command) {
     return ENTITY_LIST_RUNTIME_FAMILIES.filter(({ commandTokens }) => commandTokens[0] === command);
 }
@@ -47,4 +83,3 @@ export function runtimeEntityFamilyForHelpArgs(args) {
 export function runtimeGenericEntityListFamily(artifact) {
     return ENTITY_LIST_RUNTIME_FAMILIES.find((family) => family.parser === "generic" && family.artifact === artifact);
 }
-//# sourceMappingURL=entityListRuntimeRegistry.js.map

package/dist/state/entityMigrationCausality.js

@@ -4,9 +4,8 @@
  * 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()) {
+export function applyCausalBlockers(entries, 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) {
@@ -15,7 +14,7 @@ export function applyCausalBlockers(entries, project, recoveryFor, rootReasons =
             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.`;
+            entry.recovery = `Repair relationship '${unresolved.field}' on '${entry.source_identity}' to reference an inventoried source identity instead of '${target}', then run ${recoveryFor(entry.source_paths[0] ?? "migration source")}`;
         }
         if (["duplicate", "conflict", "corrupt", "unsupported"].includes(entry.classification) && !rootReasons.has(entry.source_identity))
             rootReasons.set(entry.source_identity, `${entry.classification} source requires explicit recovery`);
@@ -60,7 +59,7 @@ export function applyCausalBlockers(entries, project, recoveryFor, rootReasons =
             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.`;
+            entry.recovery = `Break the relationship cycle containing '${root}', then run ${recoveryFor(entry.source_paths[0] ?? "migration source")}`;
         }
     };
     for (const sourceIdentity of [...byIdentity.keys()].sort())
@@ -96,4 +95,3 @@ export function applyCausalBlockers(entries, project, recoveryFor, rootReasons =
     }
     return { rootReasons, rootsFor: resolveRoots };
 }
-//# sourceMappingURL=entityMigrationCausality.js.map

package/dist/state/entityMigrationIdentity.js

@@ -3,4 +3,3 @@ export function entityMigrationId(sourceFingerprint, sourceIdentity) {
     const bytes = createHash("sha256").update(`agentera.entity-preview.v1\0${sourceFingerprint}\0${sourceIdentity}`, "utf8").digest();
     return Array.from(bytes.subarray(0, 10), (byte) => String.fromCharCode(97 + byte % 26)).join("");
 }
-//# sourceMappingURL=entityMigrationIdentity.js.map