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

package/dist/state/todoReconciliationInspection.js

@@ -0,0 +1,173 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { renderTodoPublicRecord } from "../cli/todoMarkdown.js";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+import { detectStateMode } from "./stateMode.js";
+import { StateWriteInputError } from "./write/errors.js";
+import { TODO_ACTIVATION_APPLY_COMMAND, TODO_ACTIVATION_PREVIEW_COMMAND, TODO_RECONCILIATION_ACTIVATION_PATH, TODO_REPAIR_APPLY_COMMAND, TODO_REPAIR_PREVIEW_COMMAND, loadTodoReconciliationActivation, todoReconciliationActivationBytes, } from "./todoReconciliationActivation.js";
+import { planTodoRepair } from "./todoReconciliationRepair.js";
+import { readTodoMarkdown } from "./todoMarkdownProjection.js";
+import { managedRows, relevant, todoPublicPath } from "./todoDocsEntities.js";
+const DIAGNOSTIC_LIMIT = 20;
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function numberValue(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : 0;
+}
+function boundedCounts(value) {
+    const raw = {
+        matched: numberValue(value.matched),
+        converted: numberValue(value.converted),
+        retained: numberValue(value.retained),
+        duplicate: numberValue(value.duplicate),
+        stale: numberValue(value.stale),
+        conflicting: numberValue(value.conflicting),
+    };
+    const counts = Object.fromEntries(Object.entries(raw).map(([key, count]) => [key, Math.min(count, DIAGNOSTIC_LIMIT)]));
+    const omitted = Object.values(raw).reduce((total, count) => total + Math.max(0, count - DIAGNOSTIC_LIMIT), numberValue(value.omitted_count));
+    return { ...counts, omitted: Math.min(DIAGNOSTIC_LIMIT, omitted) };
+}
+function recovery(preview, apply) {
+    return `Run exactly '${preview}', review its bounded read-only effect, then run exactly the preview's exact apply_command (the supported form is '${apply}'); no state was changed.`;
+}
+function invalidLifecycle() {
+    return {
+        state: "invalid_lifecycle",
+        status: "action_required",
+        counts: { matched: 0, converted: 0, retained: 0, duplicate: 0, stale: 0, conflicting: 0 },
+        omitted_count: 0,
+        preview_command: null,
+        apply_command: null,
+        recovery_command: "Restore the valid committed TODO reconciliation lifecycle metadata, then rerun `npx -y agentera@next check validate state --format json`; no state was changed.",
+    };
+}
+function inspection(state, rawCounts) {
+    const bounded = boundedCounts(rawCounts);
+    const active = state === "healthy_active" || state === "unsafe_active";
+    const preview = state === "inactive" ? TODO_ACTIVATION_PREVIEW_COMMAND : active ? TODO_REPAIR_PREVIEW_COMMAND : null;
+    const apply = state === "inactive" ? TODO_ACTIVATION_APPLY_COMMAND : active ? TODO_REPAIR_APPLY_COMMAND : null;
+    return {
+        state,
+        status: state === "healthy_active" ? "operable" : "action_required",
+        counts: {
+            matched: bounded.matched,
+            converted: bounded.converted,
+            retained: bounded.retained,
+            duplicate: bounded.duplicate,
+            stale: bounded.stale,
+            conflicting: bounded.conflicting,
+        },
+        omitted_count: bounded.omitted,
+        preview_command: preview,
+        apply_command: apply,
+        recovery_command: preview && apply ? recovery(preview, apply) : "",
+    };
+}
+function errorCounts(error) {
+    if (!(error instanceof StateWriteInputError) || !mapping(error.body.diagnosis))
+        return { conflicting: 1 };
+    const diagnosis = error.body.diagnosis;
+    return {
+        ...(mapping(diagnosis.counts) ? diagnosis.counts : { conflicting: 1 }),
+        ...(diagnosis.omitted_count !== undefined ? { omitted_count: diagnosis.omitted_count } : {}),
+    };
+}
+/** Read-only classification shared by prime, doctor, and whole-state validation. */
+export function inspectTodoReconciliationState(root, sourceRoot = resolveSourceRoot(), discovery) {
+    try {
+        if (detectStateMode(root, sourceRoot) !== "entities")
+            return null;
+    }
+    catch {
+        return invalidLifecycle();
+    }
+    const activationPath = path.join(root, TODO_RECONCILIATION_ACTIVATION_PATH);
+    if (!fs.existsSync(activationPath)) {
+        try {
+            if (!fs.existsSync(todoPublicPath(root, sourceRoot)))
+                return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    const entities = relevant(root, sourceRoot, "todo", discovery).filter(({ boundary }) => boundary === "todo_item");
+    let activation;
+    try {
+        activation = loadTodoReconciliationActivation(root);
+    }
+    catch {
+        return invalidLifecycle();
+    }
+    if (!activation) {
+        try {
+            const scan = managedRows(readTodoMarkdown(todoPublicPath(root, sourceRoot)).text, null, entities);
+            const entityIds = new Set(entities.map(({ id }) => id));
+            const orphaned = [...scan.rows.keys()].filter((id) => !entityIds.has(id)).length;
+            return inspection("inactive", {
+                matched: scan.matchedRows,
+                converted: scan.convertedRows,
+                retained: scan.retainedLegacyRows.length,
+                conflicting: orphaned,
+            });
+        }
+        catch (error) {
+            return inspection("inactive", errorCounts(error));
+        }
+    }
+    try {
+        const plan = planTodoRepair(readTodoMarkdown(todoPublicPath(root, sourceRoot)).text, activation.record, entities);
+        const counts = mapping(plan.diagnosis.counts) ? plan.diagnosis.counts : {};
+        const unsafe = numberValue(counts.duplicate) > 0 || numberValue(counts.stale) > 0 || numberValue(counts.conflicting) > 0;
+        return inspection(unsafe ? "unsafe_active" : "healthy_active", counts);
+    }
+    catch (error) {
+        return inspection("unsafe_active", errorCounts(error));
+    }
+}
+function publicSnapshot(record, order) {
+    return { present: true, description: renderTodoPublicRecord(record), severity: String(record.severity), status: String(record.status), ...(order === undefined ? {} : { order }) };
+}
+function baseline(record) {
+    const reconciliation = record.reconciliation;
+    if (!mapping(reconciliation) || reconciliation.schema_version !== "agentera.todoReconciliation.v1" || !mapping(reconciliation.public))
+        return null;
+    return structuredClone(reconciliation.public);
+}
+function rowSnapshot(row, record) {
+    return { ...row.snapshot, severity: row.section === "resolved" ? String(record.severity) : row.snapshot.severity };
+}
+function samePublic(left, right, includeOrder = true) {
+    const fields = includeOrder ? ["present", "description", "severity", "status", "order"] : ["present", "description", "severity", "status"];
+    return fields.every((field) => left[field] === right[field]);
+}
+export function todoCutoverPublicProjectionViolations(markdown, targets) {
+    let rows;
+    try {
+        const activation = JSON.parse(todoReconciliationActivationBytes([]));
+        rows = managedRows(markdown, activation, targets.map(({ id, record }) => ({ boundary: "todo_item", id, record }))).rows;
+    }
+    catch (error) {
+        return [error instanceof StateWriteInputError ? error.body.message : error.message];
+    }
+    const targetIds = new Set(targets.map(({ id }) => id));
+    if (targetIds.size !== targets.length)
+        return ["pending TODO cutover target IDs are not unique"];
+    const unexpected = [...rows.keys()].find((id) => !targetIds.has(id));
+    if (unexpected)
+        return [`final managed TODO Markdown ID '${unexpected}' has no journal entity target`];
+    for (const { id, record } of targets) {
+        const row = rows.get(id);
+        if (!row)
+            return [`journal TODO entity '${id}' has no final managed Markdown row`];
+        const projected = rowSnapshot(row, record);
+        const prior = baseline(record);
+        if (!prior || canonicalRecordJson(prior) !== canonicalRecordJson(projected))
+            return [`journal TODO entity '${id}' has no exact final public baseline`];
+        if (!samePublic(publicSnapshot(record), projected, false))
+            return [`journal TODO entity '${id}' public values do not match its final managed Markdown row`];
+    }
+    return rows.size === targets.length ? [] : ["final managed TODO Markdown rows do not match the journal entity target set"];
+}

package/dist/state/todoReconciliationRepair.js

@@ -0,0 +1,170 @@
+import { parseTodoMarkdownListItem, renderTodoPublicRecord } from "../cli/todoMarkdown.js";
+import { reject } from "./write/errors.js";
+import { todoLegacyRowFingerprint, TODO_REPAIR_PREVIEW_COMMAND } from "./todoReconciliationActivation.js";
+const RECONCILIATION_VERSION = "agentera.todoReconciliation.v1";
+const DIAGNOSTIC_LIMIT = 20;
+function mapping(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function severity(section) { return ["critical", "degraded", "normal", "annoying"].includes(section) ? section : null; }
+function baseline(record) {
+    const reconciliation = mapping(record.reconciliation) ? record.reconciliation : null;
+    const value = reconciliation?.schema_version === RECONCILIATION_VERSION && mapping(reconciliation.public) ? reconciliation.public : null;
+    return value && typeof value.present === "boolean" ? structuredClone(value) : null;
+}
+function publicSnapshot(record) { return { present: true, description: renderTodoPublicRecord(record), severity: String(record.severity), status: String(record.status) }; }
+function rowSnapshot(row, record) { return { ...row.snapshot, severity: row.section === "resolved" ? String(record.severity) : row.snapshot.severity }; }
+function samePublic(left, right) { return ["present", "description", "severity", "status"].every((field) => left[field] === right[field]); }
+function withBaseline(record, value) { return { ...record, reconciliation: { schema_version: RECONCILIATION_VERSION, public: Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined)) } }; }
+function importMarkdown(record, row) {
+    const result = structuredClone(record);
+    const description = row.item.public_description ?? row.item.description;
+    if (result.title !== undefined) {
+        result.kind = row.item.kind ?? result.kind;
+        result.target_version = row.item.target_version ?? null;
+        result.title = row.item.title ?? description;
+    }
+    else
+        result.description = description;
+    if (row.section !== "resolved")
+        result.severity = row.snapshot.severity;
+    result.status = row.item.status;
+    return result;
+}
+function rowFor(id, record) { return `- [${record.status === "resolved" ? "x" : " "}] [id:${id}] ${renderTodoPublicRecord(record)}`; }
+function scanRows(markdown) {
+    const managed = new Map();
+    const legacy = [];
+    const order = new Map();
+    let section = null;
+    markdown.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" : heading === "notes" ? null : section;
+        const item = parseTodoMarkdownListItem(line.trim());
+        if (!item)
+            return;
+        const rowSeverity = section ? severity(section) : null;
+        if (item.id && !rowSeverity && section !== "resolved")
+            reject({ class: "conflict", message: `TODO repair found managed ID '${item.id}' outside a managed section`, recovery: `Move '${item.id}' under one declared TODO severity or the resolved section, then preview repair again; no state was changed.` });
+        if (!section)
+            return;
+        const key = section === "resolved" ? "resolved" : rowSeverity;
+        const publicOrder = (order.get(key) ?? 0) + 1;
+        order.set(key, publicOrder);
+        const row = { line: index, section: key, sourceLine: line, item, snapshot: { present: true, description: item.public_description ?? item.description, ...(section === "resolved" ? {} : { severity: rowSeverity }), status: item.status, order: publicOrder } };
+        if (item.id) {
+            const rows = managed.get(item.id) ?? [];
+            rows.push({ ...row, id: item.id });
+            managed.set(item.id, rows);
+        }
+        else
+            legacy.push(row);
+    });
+    return { managed, legacy };
+}
+export function planTodoRepair(markdown, activation, entities) {
+    const { managed, legacy } = scanRows(markdown);
+    const retained = new Set(activation.retained_legacy_rows);
+    const retainedRows = [];
+    const conflicts = [];
+    for (const row of legacy) {
+        const fingerprint = todoLegacyRowFingerprint(row.section, row.sourceLine);
+        if (retained.has(fingerprint))
+            retainedRows.push(row);
+        else
+            conflicts.push(`line ${row.line + 1}: ID-less managed row has no activation provenance`);
+    }
+    for (const [id, rows] of managed) {
+        if (rows.length > 1)
+            conflicts.push(`ID '${id}' occurs at lines ${rows.map((row) => row.line + 1).join(", ")}`);
+        if (!entities.some((entity) => entity.id === id))
+            conflicts.push(`ID '${id}' has no canonical entity`);
+    }
+    const identityKey = (description, rowSeverity) => `${String(description)}\0${String(rowSeverity)}`;
+    const rowKey = (row, record) => identityKey(row.snapshot.description, row.section === "resolved" ? baseline(record)?.severity ?? record.severity : row.snapshot.severity);
+    const entityKeys = (record) => { const current = publicSnapshot(record); const keys = new Set([identityKey(current.description, current.severity)]); const prior = baseline(record); if (prior?.present)
+        keys.add(identityKey(prior.description, prior.severity)); return keys; };
+    const legacyCandidates = new Map();
+    const items = [];
+    for (const row of retainedRows) {
+        const matches = entities.filter((entity) => entity.id && entity.record && managed.get(entity.id)?.length === 1 && rowKey(managed.get(entity.id)[0], entity.record) === rowKey(row, entity.record));
+        const unproven = entities.filter((entity) => entity.id && entity.record && !managed.has(entity.id) && entityKeys(entity.record).has(rowKey(row, entity.record)));
+        legacyCandidates.set(row.line, matches);
+        if (matches.length > 1)
+            conflicts.push(`line ${row.line + 1}: retained row matches multiple canonical managed IDs`);
+        else if (matches.length === 0 && unproven.length) {
+            conflicts.push(`line ${row.line + 1}: decision legacy_without_managed_identity cannot assign canonical ID '${unproven[0].id}'`);
+            if (items.length < DIAGNOSTIC_LIMIT)
+                items.push({ decision: "legacy_without_managed_identity", id: unproven.length === 1 ? unproven[0].id : null, source_line: row.line + 1 });
+        }
+        else if (matches.length === 0 && items.length < DIAGNOSTIC_LIMIT)
+            items.push({ decision: "retained_unrelated", source_line: row.line + 1 });
+    }
+    const records = new Map();
+    const selected = new Map();
+    const remove = new Set();
+    const claimedLegacy = new Set();
+    let duplicate = 0;
+    let stale = 0;
+    let matched = 0;
+    for (const entity of entities) {
+        if (!entity.id || !entity.record)
+            continue;
+        const managedRows = managed.get(entity.id) ?? [];
+        if (managedRows.length > 1)
+            continue;
+        const managedRow = managedRows[0];
+        const candidates = retainedRows.filter((row) => legacyCandidates.get(row.line)?.length === 1 && legacyCandidates.get(row.line)?.[0]?.id === entity.id);
+        if (candidates.length > 1) {
+            conflicts.push(`ID '${entity.id}' matches retained rows at lines ${candidates.map((row) => row.line + 1).join(", ")}`);
+            continue;
+        }
+        const legacyRow = candidates[0];
+        let chosen;
+        let decision;
+        if (managedRow && legacyRow) {
+            duplicate += 1;
+            decision = "duplicate_collapsed";
+            chosen = legacyRow;
+            remove.add(managedRow.line);
+            claimedLegacy.add(legacyRow.line);
+        }
+        else if (managedRow) {
+            matched += 1;
+            decision = "managed_matched";
+            chosen = managedRow;
+        }
+        else {
+            const prior = baseline(entity.record);
+            if (entity.record.status === "open" || prior?.present)
+                conflicts.push(`ID '${entity.id}' has no one-to-one public row`);
+            records.set(entity.id, withBaseline(entity.record, { present: false }));
+            continue;
+        }
+        const projected = rowSnapshot(chosen, entity.record);
+        const stalePublic = !samePublic(publicSnapshot(entity.record), projected);
+        const imported = importMarkdown(entity.record, chosen);
+        if (stalePublic)
+            stale += 1;
+        records.set(entity.id, imported);
+        selected.set(entity.id, chosen);
+        if (items.length < DIAGNOSTIC_LIMIT)
+            items.push({ id: entity.id, decision, source_line: chosen.line + 1, stale_public: stalePublic });
+    }
+    for (const row of retainedRows)
+        if ((legacyCandidates.get(row.line) ?? []).length === 1 && !claimedLegacy.has(row.line))
+            conflicts.push(`line ${row.line + 1}: retained row was not claimed by its canonical entity`);
+    const retainedCount = retainedRows.filter((row) => !claimedLegacy.has(row.line)).length;
+    if (conflicts.length)
+        reject({ class: "conflict", message: `TODO repair requires complete one-to-one evidence; found ${conflicts.length} conflicting decision${conflicts.length === 1 ? "" : "s"}`, violations: [...conflicts.slice(0, DIAGNOSTIC_LIMIT), ...(conflicts.length > DIAGNOSTIC_LIMIT ? [`${conflicts.length - DIAGNOSTIC_LIMIT} additional conflicts omitted`] : [])], diagnosis: { counts: { duplicate, stale, matched, retained: retainedCount, conflicting: conflicts.length }, items, omitted_count: Math.max(0, duplicate + matched + retainedCount - items.length), conflicts_omitted_count: Math.max(0, conflicts.length - DIAGNOSTIC_LIMIT) }, recovery: `Resolve every reported identity or provenance conflict, then rerun exactly '${TODO_REPAIR_PREVIEW_COMMAND}'; no state was changed.` });
+    const replacements = new Map();
+    for (const [id, row] of selected)
+        replacements.set(row.line, rowFor(id, records.get(id)));
+    const rendered = `${markdown.split(/\r?\n/).flatMap((line, index) => remove.has(index) ? [] : [replacements.get(index) ?? line]).join("\n").replace(/\n*$/, "")}\n`;
+    const final = scanRows(rendered).managed;
+    for (const [id, record] of records) {
+        const row = final.get(id)?.[0];
+        records.set(id, withBaseline(record, row ? rowSnapshot(row, record) : { present: false }));
+    }
+    const retainedLegacyRows = retainedRows.filter((row) => !claimedLegacy.has(row.line)).map((row) => todoLegacyRowFingerprint(row.section, row.sourceLine)).sort();
+    return { records, retainedLegacyRows, rendered, diagnosis: { counts: { duplicate, stale, matched, retained: retainedLegacyRows.length, conflicting: 0 }, items, omitted_count: Math.max(0, duplicate + matched + retainedLegacyRows.length - items.length) } };
+}

package/dist/state/todoReconciliationTransaction.js

@@ -6,13 +6,14 @@ import { canonicalRecordJson } from "./archiveDiscovery.js";
 import { entityExactGetMaxBytes } from "./entityStorage.js";
 import { FILE_REPLACEMENT_METADATA_NAME, FILE_REPLACEMENT_RECOVERY_VERSION, validateEntityRecoveryDirectory, } from "./entityPublicationContext.js";
 import { ExactReplacementConflictError, FileReplacementError } from "./exactReplacementRecovery.js";
-import { TODO_RECONCILIATION_ACTIVATION_PATH, TODO_RECONCILIATION_ITEM_LIMIT, } from "./todoReconciliationActivation.js";
+import { TODO_RECONCILIATION_ACTIVATION_PATH } from "./todoReconciliationActivation.js";
 import { reject } from "./write/errors.js";
 const VERSION = "agentera.todoReconciliationTransaction.v1";
 const DIRECTORY = ".agentera/.todo-reconciliation";
 const MAX_JOURNAL_BYTES = 4 * 1024 * 1024;
 const MAX_TARGET_BYTES = 1024 * 1024;
-const MAX_TARGETS = TODO_RECONCILIATION_ITEM_LIMIT + 2;
+const MAX_TARGETS = Math.floor(MAX_JOURNAL_BYTES / 32);
+const ENTITY_MODE_MARKER = ".agentera/state-mode.yaml";
 export class InjectedTodoReconciliationInterruption extends Error {
     publishedTargets;
     constructor(publishedTargets) {
@@ -53,7 +54,8 @@ function same(left, right) {
 function validTarget(relative, publicPath) {
     return relative === publicPath
         || relative === TODO_RECONCILIATION_ACTIVATION_PATH
-        || /^\.agentera\/entities\/todo\/todo_item\/[a-z]{10}\.yaml$/.test(relative);
+        || relative === ENTITY_MODE_MARKER
+        || /^\.agentera\/entities\/[a-z][a-z0-9_]*\/[a-z][a-z0-9_]*\/[a-z]{10}\.yaml$/.test(relative);
 }
 function createReceiptFromTargets(targets) {
     const created = targets.filter((target) => target.before === null && /^\.agentera\/entities\/todo\/todo_item\/[a-z]{10}\.yaml$/.test(target.path));
@@ -97,9 +99,7 @@ function parseJournal(bytes, fileName) {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
         invalidJournal("TODO reconciliation journal is not a mapping");
     const value = parsed;
-    const expectedKeys = value.create === undefined
-        ? "id,mapping_sha256,public_path,schema_version,targets"
-        : "create,id,mapping_sha256,public_path,schema_version,targets";
+    const expectedKeys = ["schema_version", "id", "public_path", "mapping_sha256", "targets", ...(value.create === undefined ? [] : ["create"]), ...(value.activation_effect_sha256 === undefined ? [] : ["activation_effect_sha256"])].sort().join(",");
     if (Object.keys(value).sort().join(",") !== expectedKeys
         || value.schema_version !== VERSION
         || typeof value.id !== "string"
@@ -111,6 +111,8 @@ function parseJournal(bytes, fileName) {
         || value.targets.length < 1
         || value.targets.length > MAX_TARGETS)
         invalidJournal("TODO reconciliation journal is malformed");
+    if (value.activation_effect_sha256 !== undefined && !/^[a-f0-9]{64}$/.test(value.activation_effect_sha256))
+        invalidJournal("TODO reconciliation journal has an invalid activation effect authorization");
     if (value.create !== undefined && (!value.create
         || typeof value.create !== "object"
         || Array.isArray(value.create)
@@ -137,12 +139,17 @@ function parseJournal(bytes, fileName) {
         paths.add(target.path);
     }
     const body = value.targets;
+    const activates = body.some((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH);
+    if (!activates && value.activation_effect_sha256 !== undefined)
+        invalidJournal("TODO reconciliation journal effect authorization has no activation target");
     const inferredCreate = createReceiptFromTargets(body);
     if (value.create && (!inferredCreate
         || value.create.created_id !== inferredCreate.created_id
         || value.create.request_sha256 !== inferredCreate.request_sha256))
         invalidJournal("TODO reconciliation create receipt does not match its canonical entity target");
-    const identity = value.create ? { create: value.create, targets: body } : body;
+    const identity = value.create || value.activation_effect_sha256
+        ? { ...(value.create ? { create: value.create } : {}), ...(value.activation_effect_sha256 ? { activation_effect_sha256: value.activation_effect_sha256 } : {}), targets: body }
+        : body;
     const expectedId = createHash("sha256").update(canonicalRecordJson(identity)).digest("hex").slice(0, 24);
     if (value.id !== expectedId || (fileName !== undefined && fileName !== `${value.id}.json`)) {
         invalidJournal("TODO reconciliation journal identity does not match its canonical targets");
@@ -151,7 +158,7 @@ function parseJournal(bytes, fileName) {
     return { ...value, ...(create ? { create } : {}) };
 }
 function targetLimit(target, sourceRoot) {
-    return target.path.startsWith(".agentera/entities/todo/todo_item/") ? entityExactGetMaxBytes(sourceRoot) : MAX_TARGET_BYTES;
+    return target.path.startsWith(".agentera/entities/") ? entityExactGetMaxBytes(sourceRoot) : MAX_TARGET_BYTES;
 }
 function assertBinding(journal, binding) {
     if (journal.public_path !== binding.publicPath || journal.mapping_sha256 !== binding.mappingSha256)
@@ -441,9 +448,22 @@ export function recoverTodoReconciliation(context, sourceRoot, binding, options
                 message: `pending TODO create for '${journal.create.created_id}' does not match this request`,
                 recovery: `Retry the exact original TODO create input to recover '${journal.create.created_id}'; no transaction target bytes were changed.`,
             });
+        if (journal.activation_effect_sha256 && options.activationEffectSha256 !== journal.activation_effect_sha256)
+            reject({
+                class: "conflict",
+                message: "pending TODO activation does not match the authorized preview effect",
+                recovery: "Retry the exact activation apply command returned by the original preview; no transaction target bytes were changed.",
+            });
+        options.beforeRecovery?.(journal.targets.map((target) => ({
+            path: target.path,
+            before: target.before === null ? null : decode(target.before),
+            after: decode(target.after),
+        })));
         const applied = [];
         try {
             for (const target of journal.targets) {
+                if (target.path === ENTITY_MODE_MARKER)
+                    options.beforeActivation?.();
                 const identity = applyTarget(context, root, target, sourceRoot, journal.public_path);
                 if (identity)
                     applied.push({ target, identity });
@@ -473,10 +493,16 @@ export function recoverTodoReconciliation(context, sourceRoot, binding, options
 }
 export function publishTodoReconciliation(context, sourceRoot, binding, targets, options = {}) {
     const normalized = targets
-        .filter((target) => !same(target.before, Buffer.from(target.after)))
-        .sort((left, right) => Number(left.path === binding.publicPath) - Number(right.path === binding.publicPath) || left.path.localeCompare(right.path));
+        .filter((target) => options.retainUnchangedTargets || !same(target.before, Buffer.from(target.after)))
+        .sort((left, right) => Number(left.path === ENTITY_MODE_MARKER) - Number(right.path === ENTITY_MODE_MARKER)
+        || Number(left.path === binding.publicPath) - Number(right.path === binding.publicPath)
+        || left.path.localeCompare(right.path));
     const body = normalized.map((target) => ({ path: target.path, before: target.before === null ? null : encode(target.before), after: encode(target.after) }));
-    const identity = options.create ? { create: options.create, targets: body } : body;
+    if (options.activationEffectSha256 && !normalized.some((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH))
+        reject({ class: "schema_violation", message: "TODO activation authorization requires its activation target", recovery: "Recompute the complete activation target set from a fresh dry-run; no state was changed." });
+    const identity = options.create || options.activationEffectSha256
+        ? { ...(options.create ? { create: options.create } : {}), ...(options.activationEffectSha256 ? { activation_effect_sha256: options.activationEffectSha256 } : {}), targets: body }
+        : body;
     const id = createHash("sha256").update(canonicalRecordJson(identity)).digest("hex").slice(0, 24);
     if (!normalized.length)
         return { id, targetCount: 0 };
@@ -486,7 +512,7 @@ export function publishTodoReconciliation(context, sourceRoot, binding, targets,
         reject({
             class: "schema_violation",
             message: "TODO reconciliation transaction has invalid or duplicate bounded targets",
-            recovery: `Reduce the managed TODO working set to at most ${TODO_RECONCILIATION_ITEM_LIMIT} items and retry; no state was changed.`,
+            recovery: "Reduce the managed TODO working set or cutover entity inventory below the declared journal bounds and retry; no state was changed.",
         });
     const publicTarget = normalized.find((target) => target.path === binding.publicPath && target.before !== null);
     if (publicTarget) {
@@ -506,6 +532,7 @@ export function publishTodoReconciliation(context, sourceRoot, binding, targets,
         public_path: binding.publicPath,
         mapping_sha256: binding.mappingSha256,
         ...(options.create ? { create: options.create } : {}),
+        ...(options.activationEffectSha256 ? { activation_effect_sha256: options.activationEffectSha256 } : {}),
         targets: body,
     };
     const bytes = `${JSON.stringify(journal)}\n`;
@@ -524,6 +551,8 @@ export function publishTodoReconciliation(context, sourceRoot, binding, targets,
     const applied = [];
     try {
         for (const target of journal.targets) {
+            if (target.path === ENTITY_MODE_MARKER)
+                options.beforeActivation?.();
             const identity = applyTarget(context, context.pinnedPath(), target, sourceRoot, journal.public_path);
             if (identity)
                 applied.push({ target, identity });
@@ -551,4 +580,3 @@ export function publishTodoReconciliation(context, sourceRoot, binding, targets,
         throw error;
     }
 }
-//# sourceMappingURL=todoReconciliationTransaction.js.map

package/dist/state/write/assign.js

@@ -18,4 +18,3 @@ export function localDate(now = new Date()) {
 export function localTimestamp(now = new Date()) {
     return `${localDate(now)} ${String(now.getHours()).padStart(2, "0")}:${String(now.getMinutes()).padStart(2, "0")}`;
 }
-//# sourceMappingURL=assign.js.map

package/dist/state/write/candidateMutation.js

@@ -267,4 +267,3 @@ export function mutateCandidate(req, doc, recovered) {
     throw new Error(`unsupported transaction ${req.artifact} ${req.spec.verb}`);
 }
 export { normalizedDecisionPayload };
-//# sourceMappingURL=candidateMutation.js.map

package/dist/state/write/errors.js

@@ -9,4 +9,3 @@ export class StateWriteInputError extends Error {
 export function reject(body) {
     throw new StateWriteInputError(body);
 }
-//# sourceMappingURL=errors.js.map

package/dist/state/write/experimentPublication.js

@@ -190,4 +190,3 @@ export function executeExperimentPublication(req, transaction) {
         }
     }
 }
-//# sourceMappingURL=experimentPublication.js.map

package/dist/state/write/explain.js

@@ -330,4 +330,3 @@ export function renderExplainText(explain) {
     lines.push("", "Recovery:", `  ${String(explain.recovery ?? "Correct the input and retry; no state was changed.")}`, "", "Example:", `  ${String(explain.example ?? "")}`);
     return lines.join("\n") + "\n";
 }
-//# sourceMappingURL=explain.js.map

package/dist/state/write/fields.js

@@ -59,4 +59,3 @@ export function schemaBudget(artifact, validator = new ArtifactSchemaValidator()
     }
     return result;
 }
-//# sourceMappingURL=fields.js.map

package/dist/state/write/glossaryPublication.js

@@ -261,4 +261,3 @@ export function publishGlossary(req, root, options = {}) {
         };
     }, options, root);
 }
-//# sourceMappingURL=glossaryPublication.js.map

package/dist/state/write/grammar.js

@@ -1,7 +1,8 @@
 import crypto from "node:crypto";
+import { projectRuntimeOperationExamples, projectRuntimeOperationRecovery, } from "../../core/developmentInvocation.js";
 import { resolveSourceRoot } from "../../core/sourceRoot.js";
 import { loadStateStorageAuthority } from "../stateStorageAuthority.js";
-import { runtimeOperationSpecs } from "./runtimeOperations.js";
+import { runtimeOperationSpec, runtimeOperationSpecs } from "./runtimeOperations.js";
 export const MUTATION_CLASSES = [
     "record_payload",
     "simple_transition",
@@ -84,6 +85,9 @@ function parseOperation(raw, index) {
         throw new Error(`invalid mutation grammar: ${p} must be a mapping`);
     const artifact = requiredString(raw.artifact, `${p}.artifact`);
     const verb = requiredString(raw.verb, `${p}.verb`);
+    const runtime = runtimeOperationSpec(artifact, verb);
+    if (!runtime)
+        throw new Error(`invalid mutation grammar: ${p} operation '${artifact}.${verb}' is not code-owned`);
     const mutationClass = requiredString(raw.class, `${p}.class`);
     if (!MUTATION_CLASSES.includes(mutationClass))
         throw new Error(`invalid mutation grammar: ${p}.class '${mutationClass}' is unsupported`);
@@ -113,8 +117,8 @@ function parseOperation(raw, index) {
         preconditions: strings(raw.preconditions, `${p}.preconditions`),
         ownedFields: strings(raw.owned_fields, `${p}.owned_fields`),
         input,
-        recovery: requiredString(raw.recovery, `${p}.recovery`),
-        examples: strings(raw.examples, `${p}.examples`),
+        recovery: projectRuntimeOperationRecovery(raw.recovery, artifact, verb),
+        examples: projectRuntimeOperationExamples(raw.examples, artifact, verb),
         bounds: mapping(raw.bounds) ? clonePlain(raw.bounds) : (() => { throw new Error(`invalid mutation grammar: ${p}.bounds must be a mapping`); })(),
         fields: fields(raw.fields, `${p}.fields`),
         allowForce: raw.allow_force === true,
@@ -160,6 +164,9 @@ function operationParityProjection(operation) {
             cli_owned_fields: operation.input.cliOwnedFields,
         },
         fields: operation.fields.map(declaredFieldProjection),
+        recovery: operation.recovery,
+        examples: operation.examples,
+        projection: { format_values: runtimeOperationSpec(operation.artifact, operation.verb)?.projection.formatValues ?? [] },
         allow_force: operation.allowForce,
         compacts: operation.compacts,
         bounds: operation.input.mode === "structured"
@@ -181,6 +188,9 @@ function runtimeParityProjection(operation) {
             cli_owned_fields: operation.cliOwnedFields,
         },
         fields: operation.fields.map(runtimeFieldProjection),
+        recovery: operation.projection.recovery.runtime,
+        examples: operation.projection.examples.map(({ runtime }) => runtime),
+        projection: { format_values: operation.projection.formatValues },
         allow_force: operation.allowForce,
         compacts: operation.compacts,
         bounds: { max_input_utf8_bytes: operation.inputMaxBytes },
@@ -268,4 +278,3 @@ export function mutationGrammarPayload(sourceRoot = resolveSourceRoot()) {
         operations: grammar.operations,
     };
 }
-//# sourceMappingURL=grammar.js.map

package/dist/state/write/helpers.js

@@ -27,4 +27,3 @@ export function mappingPath(entry, field) {
     }
     return value;
 }
-//# sourceMappingURL=helpers.js.map

package/dist/state/write/index.js

@@ -10,4 +10,3 @@ export * from "./validate.js";
 export * from "./serialize.js";
 export * from "./errors.js";
 export * from "./glossaryPublication.js";
-//# sourceMappingURL=index.js.map

package/dist/state/write/input.js

@@ -365,4 +365,3 @@ export function loadStructuredInput(source, readStdin, maxBytes) {
         throw new Error(`input is not valid YAML or JSON: ${error.message}`);
     }
 }
-//# sourceMappingURL=input.js.map

package/dist/state/write/lock.js

@@ -835,4 +835,3 @@ export function acquireWriterLock(projectRoot, timeoutMs = 2000, expectedRoot) {
         throw error;
     }
 }
-//# sourceMappingURL=lock.js.map

package/dist/state/write/mutation.js

@@ -232,4 +232,3 @@ export function withStateMutation(projectRoot, operation, options = {}, validate
         lock.release();
     }
 }
-//# sourceMappingURL=mutation.js.map

package/dist/state/write/operations.js

@@ -167,4 +167,3 @@ export function stateWriterContract(targets = WRITABLE_ARTIFACTS, mode = "full")
         unsupported_targets: uniqueTargets.filter((target) => stateWriterArtifactContract(target, mode) === null),
     };
 }
-//# sourceMappingURL=operations.js.map

package/dist/state/write/planEvaluation.js

@@ -126,4 +126,3 @@ export function planTaskRecordViolations(task, prefix = "plan task") {
     }
     return [...violations, ...planEvaluationMetadataViolations(task.evaluation, `${prefix}.evaluation`, task.status)];
 }
-//# sourceMappingURL=planEvaluation.js.map

package/dist/state/write/planPublication.js

@@ -177,4 +177,3 @@ export function validatePlanPublicationCandidate(bytes, options = {}) {
         example: "agentera state plan create --input plan.yaml --format json",
     });
 }
-//# sourceMappingURL=planPublication.js.map