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

package/dist/state/todoDocsEntities.js

@@ -18,8 +18,11 @@ import { parseTodoMarkdownListItem, renderTodoPublicRecord } from "../cli/todoMa
 import { evaluateTodoReadinessQueue } from "../cli/todoReadinessSelection.js";
 import { artifactSchemasDir, loadArtifactRecord, registryModelPath, resolveArtifactPath } from "../registries/artifactRegistry.js";
 import { inspectTodoReconciliation, publishTodoReconciliation, recoverTodoReconciliation, todoCreateRequestSha256 } from "./todoReconciliationTransaction.js";
-import { loadTodoReconciliationActivation, todoLegacyRowFingerprint, todoReconciliationActivationBytes, TODO_RECONCILIATION_ACTIVATION_PATH, TODO_RECONCILIATION_ITEM_LIMIT, } from "./todoReconciliationActivation.js";
+import { loadTodoReconciliationActivation, todoLegacyRowFingerprint, todoReconciliationActivationBytes, TODO_RECONCILIATION_ACTIVATION_PATH, TODO_RECONCILIATION_ITEM_LIMIT, TODO_ACTIVATION_APPLY_COMMAND, TODO_ACTIVATION_PREVIEW_COMMAND, TODO_REPAIR_APPLY_COMMAND, TODO_REPAIR_PREVIEW_COMMAND, todoActivationEffect, todoRepairEffect, unchangedTodoActivationEffect, } from "./todoReconciliationActivation.js";
+import { planTodoRepair } from "./todoReconciliationRepair.js";
+import { readTodoMarkdown, renderManagedMarkdown } from "./todoMarkdownProjection.js";
 const ID = /^[a-z]{10}$/;
+const SHA256 = /^[a-f0-9]{64}$/;
 const TODO = { artifact: "todo", boundary: "todo_item", order: "severity_then_status_then_markdown_order_then_id" };
 const DOCS = { artifact: "docs", boundary: "documentation_inventory_entry", order: "path_then_id" };
 function mapping(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
@@ -41,7 +44,7 @@ function failure(kind, artifact, message, recovery, id, exitCode = 1) {
     const family = kind === "cursor_invalid" || kind === "cursor_snapshot_unavailable" ? entityListFamily(artifact) : undefined;
     return new StateRetrievalFailure({ schemaVersion: "agentera.stateFailure.v1", status: "fail", error: { class: kind, message, syntax: family?.syntax ?? `agentera state ${artifact} get --id ID --format json`, example: family?.example ?? `agentera state ${artifact} get --id ${id ?? "qjtrmnpvka"} --format json`, recovery, artifact, ...(id ? { id } : {}) } }, exitCode);
 }
-function relevant(root, sourceRoot, artifact, supplied, sourceBinding) {
+export function relevant(root, sourceRoot, artifact, supplied, sourceBinding) {
     if (supplied)
         assertEntityDiscoveryOrigin(root, sourceRoot, supplied);
     const discovery = supplied ?? discoverEntities(root, sourceRoot, sourceBinding);
@@ -73,13 +76,13 @@ function assertState(root, sourceRoot, sourceBinding) {
 function markdownSeverity(section) {
     return section === "critical" || section === "degraded" || section === "normal" || section === "annoying" ? section : null;
 }
-function todoPublicPath(root, sourceRoot) {
+export function todoPublicPath(root, sourceRoot) {
     const todo = loadArtifactRecord("todo", artifactSchemasDir(sourceRoot), registryModelPath(sourceRoot));
     if (!todo)
         throw new Error("artifact registry is missing the canonical 'todo' record");
     return resolveArtifactPath(todo, root, { strictWrite: true });
 }
-function todoReconciliationBinding(root, sourceRoot) {
+export function todoReconciliationBinding(root, sourceRoot) {
     const publicPath = relative(root, todoPublicPath(root, sourceRoot));
     const docsRecord = loadArtifactRecord("docs", artifactSchemasDir(sourceRoot), registryModelPath(sourceRoot));
     if (!docsRecord)
@@ -107,7 +110,6 @@ export function assertTodoReconciliationReadable(root, sourceRoot, id) {
         throw failure("unsupported_state", "todo", `TODO reconciliation transaction '${pending[0]}' is pending; no mixed TODO state is readable`, "Retry the exact non-dry-run TODO mutation to complete recovery, then repeat this read.", id);
 }
 const RECONCILIATION_VERSION = "agentera.todoReconciliation.v1";
-const TODO_MARKDOWN_MAX_BYTES = 1024 * 1024;
 const TODO_DRIFT_ITEM_LIMIT = 20;
 const PUBLIC_FIELDS = ["description", "severity", "status"];
 function publicSnapshot(record, order) {
@@ -135,33 +137,7 @@ function todoAuthority() {
         operational: { owner: "agentera", source: "canonical_entity_file", fields: ["readiness", "dependencies", "blocked", "gate", "evidence", "lifecycle"] },
     };
 }
-function readTodoMarkdown(target) {
-    if (!fs.existsSync(target))
-        return { bytes: Buffer.from(""), text: "" };
-    const stat = fs.lstatSync(target);
-    if (!stat.isFile() || stat.isSymbolicLink())
-        reject({
-            class: "conflict",
-            message: "managed TODO Markdown must be a regular file",
-            recovery: "Restore the docs-mapped TODO artifact as a regular file within the project and retry; no state was changed.",
-        });
-    if (stat.size > TODO_MARKDOWN_MAX_BYTES)
-        reject({
-            class: "conflict",
-            message: `managed TODO Markdown exceeds the ${TODO_MARKDOWN_MAX_BYTES}-byte reconciliation bound`,
-            recovery: "Compact unmanaged or resolved Markdown content below the declared bound and retry; no state was changed.",
-        });
-    const bytes = fs.readFileSync(target);
-    let text;
-    try {
-        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-    }
-    catch {
-        reject({ class: "conflict", message: "managed TODO Markdown is not valid UTF-8", recovery: "Restore valid UTF-8 TODO Markdown and retry; no state was changed." });
-    }
-    return { bytes, text: text };
-}
-function managedRows(markdown, activation, entities) {
+export function managedRows(markdown, activation, entities) {
     const result = new Map();
     const order = new Map();
     const legacy = [];
@@ -169,7 +145,7 @@ function managedRows(markdown, activation, entities) {
     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" : null;
+            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;
@@ -191,6 +167,8 @@ function managedRows(markdown, activation, entities) {
         result.set(item.id, { ...row, id: item.id });
     });
     const retainedLegacyRows = [];
+    const matchedRows = result.size;
+    let convertedRows = 0;
     if (activation) {
         const retained = new Set(activation.retained_legacy_rows);
         for (const row of legacy) {
@@ -236,6 +214,7 @@ function managedRows(markdown, activation, entities) {
             if (matched?.id) {
                 claimed.add(matched.id);
                 result.set(matched.id, { ...row, id: matched.id });
+                convertedRows += 1;
                 continue;
             }
             const fingerprint = todoLegacyRowFingerprint(row.section, row.sourceLine);
@@ -254,13 +233,29 @@ function managedRows(markdown, activation, entities) {
             message: `TODO.md exceeds the ${TODO_RECONCILIATION_ITEM_LIMIT}-item reconciliation or legacy-activation bound`,
             recovery: `Compact retained resolved rows until each bounded set has at most ${TODO_RECONCILIATION_ITEM_LIMIT} items, then retry once; no state was changed.`,
         });
-    return { rows: result, retainedLegacyRows };
+    return { rows: result, retainedLegacyRows, matchedRows, convertedRows };
 }
 function rowSnapshot(row, record) {
     return { ...row.snapshot, severity: row.section === "resolved" ? String(record.severity) : row.snapshot.severity };
 }
 function inspectTodoReadView(root, sourceRoot, entities) {
-    const activation = loadTodoReconciliationActivation(root)?.record ?? null;
+    let activation;
+    try {
+        activation = loadTodoReconciliationActivation(root)?.record ?? null;
+    }
+    catch {
+        return {
+            rows: new Map(),
+            drift: {
+                schema_version: RECONCILIATION_VERSION,
+                status: "invalid_lifecycle",
+                read_effect: "none",
+                authority: todoAuthority(),
+                counts: { managed: 0, drifted: 0, conflicts: 1 },
+                items: [],
+            },
+        };
+    }
     if (!activation) {
         return {
             rows: new Map(),
@@ -274,10 +269,29 @@ function inspectTodoReadView(root, sourceRoot, entities) {
             },
         };
     }
-    const markdownPath = todoPublicPath(root, sourceRoot);
-    const markdown = readTodoMarkdown(markdownPath).text;
     const todoEntities = entities.filter(({ boundary }) => boundary === TODO.boundary);
-    const rows = managedRows(markdown, activation, todoEntities).rows;
+    let markdown;
+    let rows;
+    try {
+        markdown = readTodoMarkdown(todoPublicPath(root, sourceRoot)).text;
+        rows = managedRows(markdown, activation, todoEntities).rows;
+    }
+    catch (error) {
+        if (error instanceof StateWriteInputError && /Markdown/i.test(error.body.message))
+            throw error;
+        return {
+            rows: new Map(),
+            drift: {
+                schema_version: RECONCILIATION_VERSION,
+                status: "unsafe",
+                read_effect: "none",
+                next_write_boundary: "atomic_reconciliation",
+                authority: todoAuthority(),
+                counts: { managed: 0, drifted: 0, conflicts: 1 },
+                items: [],
+            },
+        };
+    }
     const items = [];
     const entityIds = new Set();
     for (const entity of todoEntities) {
@@ -391,46 +405,9 @@ function withBaseline(record, value) {
     const publicValue = Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
     return { ...record, reconciliation: { schema_version: RECONCILIATION_VERSION, public: publicValue } };
 }
-function sectionFor(record) { return record.status === "resolved" ? "resolved" : String(record.severity); }
-function headingFor(section) { return section === "resolved" ? "## ✓ Resolved" : `## → ${section[0].toUpperCase()}${section.slice(1)}`; }
-function rowFor(id, record) { return `- [${record.status === "resolved" ? "x" : " "}] [id:${id}] ${renderTodoPublicRecord(record)}`; }
-function renderManagedMarkdown(markdown, records, existing) {
-    const byLine = new Map([...existing.values()].map((row) => [row.line, row]));
-    const retained = new Set();
-    const lines = markdown.split(/\r?\n/).flatMap((line, index) => {
-        const row = byLine.get(index);
-        if (!row)
-            return [line];
-        const record = records.get(row.id);
-        if (!record || sectionFor(record) !== row.section)
-            return [];
-        retained.add(row.id);
-        return [rowFor(row.id, record)];
-    });
-    for (const section of ["critical", "degraded", "normal", "annoying", "resolved"]) {
-        const ids = [...records.entries()].filter(([id, record]) => !retained.has(id) && sectionFor(record) === section).sort(([left], [right]) => {
-            const a = existing.get(left);
-            const b = existing.get(right);
-            return (a?.section === section ? a.snapshot.order : Number.MAX_SAFE_INTEGER) - (b?.section === section ? b.snapshot.order : Number.MAX_SAFE_INTEGER) || left.localeCompare(right);
-        }).map(([id]) => id);
-        if (!ids.length)
-            continue;
-        let heading = lines.findIndex((line) => line.trim().toLowerCase() === headingFor(section).toLowerCase());
-        if (heading < 0) {
-            if (lines.at(-1)?.trim())
-                lines.push("");
-            lines.push(headingFor(section));
-            heading = lines.length - 1;
-        }
-        let insert = heading + 1;
-        while (insert < lines.length && !/^##\s+/.test(lines[insert].trim()))
-            insert += 1;
-        while (insert > heading + 1 && !lines[insert - 1].trim())
-            insert -= 1;
-        lines.splice(insert, 0, ...ids.map((id) => rowFor(id, records.get(id))));
-    }
-    return `${lines.join("\n").replace(/\n*$/, "")}\n`;
-}
+function inactiveTodoMutation() { reject({ class: "conflict", message: "TODO reconciliation is inactive; ordinary TODO mutations cannot activate it implicitly", syntax: TODO_ACTIVATION_PREVIEW_COMMAND, example: TODO_ACTIVATION_APPLY_COMMAND, recovery: `Run exactly '${TODO_ACTIVATION_PREVIEW_COMMAND}', review every reported effect, then run exactly '${TODO_ACTIVATION_APPLY_COMMAND}'; no state was changed.` }); }
+function activationEnvelope(effect, dryRun, replay, transactionId, targets, recovered) { return { schemaVersion: "agentera.stateWrite.v1", command: "state todo activate", status: "pass", path: TODO_RECONCILIATION_ACTIVATION_PATH, artifact: "todo", operation: { verb: "activate", dry_run: dryRun, idempotent_replay: replay }, validation: { status: "pass", violations: [] }, activation: effect, apply_command: TODO_ACTIVATION_APPLY_COMMAND.replace("EFFECT_SHA256", String(effect.effect_sha256)), reconciliation: { transaction_id: transactionId, targets, recovered } }; }
+function repairEnvelope(effect, dryRun, replay, transactionId, targets, recovered) { return { schemaVersion: "agentera.stateWrite.v1", command: "state todo repair", status: "pass", path: TODO_RECONCILIATION_ACTIVATION_PATH, artifact: "todo", operation: { verb: "repair", dry_run: dryRun, idempotent_replay: replay }, validation: { status: "pass", violations: [] }, repair: effect, apply_command: TODO_REPAIR_APPLY_COMMAND.replace("EFFECT_SHA256", String(effect.effect_sha256)), reconciliation: { transaction_id: transactionId, targets, recovered } }; }
 function envelope(command, entity, artifact, record, dryRun) {
     return { schemaVersion: "agentera.stateWrite.v1", command, status: "pass", path: entity.path, id: entity.id, artifact, record, operation: { verb: command.split(" ").at(-1), dry_run: dryRun, idempotent_replay: entity.replay }, validation: { status: "pass", violations: [] } };
 }
@@ -687,6 +664,20 @@ export function mutateTodoDocsEntity(req, options = {}) {
         context.assertValid();
         const todoBinding = artifact === "todo" ? todoReconciliationBinding(req.projectRoot, sourceRoot) : null;
         const pending = todoBinding ? inspectTodoReconciliation(pinnedRoot, todoBinding) : [];
+        const initialActivation = artifact === "todo" ? loadTodoReconciliationActivation(pinnedRoot) : null;
+        if (artifact === "todo" && ["activate", "repair"].includes(req.spec.verb)) {
+            const repairing = req.spec.verb === "repair";
+            const previewCommand = repairing ? TODO_REPAIR_PREVIEW_COMMAND : TODO_ACTIVATION_PREVIEW_COMMAND;
+            const applyCommand = repairing ? TODO_REPAIR_APPLY_COMMAND : TODO_ACTIVATION_APPLY_COMMAND;
+            if (repairing && !initialActivation)
+                reject({ class: "conflict", message: "TODO repair requires an existing reconciliation activation marker", recovery: `Use '${TODO_ACTIVATION_PREVIEW_COMMAND}' for an inactive project; no state was changed.` });
+            if (req.dryRun && (req.values.confirmed === true || req.values.effect_sha256 !== undefined))
+                reject({ class: "mutually_exclusive", message: `TODO ${req.spec.verb} --dry-run cannot include apply confirmation`, recovery: `Run exactly '${previewCommand}' or the preview's exact apply_command; no state was changed.` });
+            if (!req.dryRun && (req.values.confirmed !== true || !SHA256.test(String(req.values.effect_sha256 ?? ""))))
+                reject({ class: "missing_argument", message: `TODO ${req.spec.verb} apply requires the preview effect SHA-256 and explicit --yes confirmation`, syntax: previewCommand, example: applyCommand, recovery: `Run exactly '${previewCommand}', review every reported effect, then run its exact apply_command; no state was changed.` });
+        }
+        else if (artifact === "todo" && !initialActivation)
+            inactiveTodoMutation();
         if (req.dryRun && pending.length)
             reject({ class: "conflict", message: `TODO reconciliation transaction '${pending[0]}' requires recovery before dry-run`, recovery: "Retry the exact TODO mutation without --dry-run once to complete recovery; this dry-run changed no state." });
         const createRequest = artifact === "todo" && req.spec.verb === "create" ? mutationRecord(req, undefined) : null;
@@ -694,6 +685,7 @@ export function mutateTodoDocsEntity(req, options = {}) {
         const recoveryReceipts = todoBinding && !req.dryRun
             ? recoverTodoReconciliation(context, sourceRoot, todoBinding, {
                 createRequestSha256,
+                ...(["activate", "repair"].includes(req.spec.verb) ? { activationEffectSha256: String(req.values.effect_sha256) } : {}),
                 beforeCommit: () => assertState(pinnedRoot, sourceRoot, sourceBinding),
             })
             : [];
@@ -706,10 +698,7 @@ export function mutateTodoDocsEntity(req, options = {}) {
             const recoveredCreate = recoveryReceipts.find((receipt) => receipt.create);
             if (recoveredCreate?.create) {
                 const created = selectedById(entities, "todo", recoveredCreate.create.created_id);
-                return {
-                    ...envelope("state todo create", { id: created.id, path: created.path, replay: true }, "todo", created.record, false),
-                    reconciliation: { transaction_id: recoveredCreate.transaction_id, targets: 0, recovered },
-                };
+                return { ...envelope("state todo create", { id: created.id, path: created.path, replay: true }, "todo", created.record, false), reconciliation: { transaction_id: recoveredCreate.transaction_id, targets: 0, recovered } };
             }
             const publicFile = todoPublicPath(pinnedRoot, sourceRoot);
             const publicRelative = todoBinding.publicPath;
@@ -720,6 +709,96 @@ export function mutateTodoDocsEntity(req, options = {}) {
             const todoEntities = entities.filter(({ boundary }) => boundary === TODO.boundary);
             const loadedActivation = loadTodoReconciliationActivation(pinnedRoot);
             const activation = loadedActivation?.record ?? null;
+            if (req.spec.verb === "activate") {
+                if (activation) {
+                    const effect = unchangedTodoActivationEffect(publicRelative, markdownBefore, activation.retained_legacy_rows.length, activation.effect_sha256);
+                    if (!req.dryRun && req.values.effect_sha256 !== effect.effect_sha256)
+                        reject({ class: "conflict", message: "TODO activation replay does not match the authorized effect", recovery: `Use the exact apply_command returned by ${activation.effect_sha256 ? "the original activation preview" : "the active no-op preview"}; no state was changed.` });
+                    return activationEnvelope(effect, req.dryRun, true, null, 0, recovered);
+                }
+                const scan = managedRows(markdown, null, todoEntities);
+                const rows = scan.rows;
+                const reconciled = reconcileTodoRecords(todoEntities, rows, true);
+                for (const [todoId, record] of reconciled.records) {
+                    const violations = recordViolations("todo", record, sourceRoot);
+                    if (violations.length)
+                        reject({ class: "schema_violation", message: "todo entity input is invalid", violations });
+                    if (record.readiness !== undefined)
+                        assertTodoReferences(todoId, record, [...reconciled.records].map(([entityId, entityRecord]) => ({ boundary: TODO.boundary, id: entityId, record: entityRecord })));
+                }
+                const visibleRecords = new Map([...reconciled.records].filter(([todoId]) => reconciled.visible.has(todoId)));
+                const rendered = renderManagedMarkdown(markdown, visibleRecords, rows);
+                let activationBytesAfter = todoReconciliationActivationBytes(scan.retainedLegacyRows, "0".repeat(64));
+                const activationAfter = JSON.parse(activationBytesAfter);
+                const finalRows = managedRows(rendered, activationAfter, todoEntities).rows;
+                for (const [todoId, record] of reconciled.records) {
+                    const row = finalRows.get(todoId);
+                    reconciled.records.set(todoId, withBaseline(record, row ? rowSnapshot(row, record) : { present: false }));
+                }
+                const targets = todoEntities.map((entity) => ({ path: entity.relativePath, before: exactDiscoveredEntityBytes(entity), after: canonicalEntityEnvelopeBytes({ id: entity.id, artifact: "todo", record: reconciled.records.get(entity.id), migrationProvenance: entity.migrationProvenance ?? undefined }) }));
+                targets.push({ path: TODO_RECONCILIATION_ACTIVATION_PATH, before: null, after: activationBytesAfter });
+                targets.push({ path: publicRelative, before: publicExists ? markdownBefore : null, after: rendered });
+                const resurrectedIds = [...reconciled.visible].filter((todoId) => { const row = rows.get(todoId); return !row || (reconciled.records.get(todoId)?.status === "resolved" && !row.item.id); }).sort();
+                const preliminaryEffect = todoActivationEffect(scan, targets, publicRelative, markdownBefore, rendered, resurrectedIds);
+                activationBytesAfter = todoReconciliationActivationBytes(scan.retainedLegacyRows, String(preliminaryEffect.effect_sha256));
+                targets.find((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH).after = activationBytesAfter;
+                const effect = todoActivationEffect(scan, targets, publicRelative, markdownBefore, rendered, resurrectedIds);
+                if (effect.effect_sha256 !== preliminaryEffect.effect_sha256)
+                    throw new Error("TODO activation effect authorization is not self-consistent");
+                if (req.dryRun)
+                    return activationEnvelope(effect, true, false, null, effect.targets.length, recovered);
+                if (req.values.effect_sha256 !== effect.effect_sha256)
+                    reject({ class: "conflict", message: "TODO activation effects changed after preview", syntax: TODO_ACTIVATION_PREVIEW_COMMAND, example: TODO_ACTIVATION_APPLY_COMMAND, recovery: `Rerun exactly '${TODO_ACTIVATION_PREVIEW_COMMAND}', review the changed bounded effects, then run its new exact apply_command; no state was changed.` });
+                const transaction = publishTodoReconciliation(context, sourceRoot, todoBinding, targets, {
+                    activationEffectSha256: String(effect.effect_sha256),
+                    interruptAfterTarget: options.interruptAfterTarget,
+                    beforeCommit: () => {
+                        assertState(pinnedRoot, sourceRoot, sourceBinding);
+                        const currentBinding = todoReconciliationBinding(req.projectRoot, sourceRoot);
+                        if (currentBinding.publicPath !== todoBinding.publicPath || currentBinding.mappingSha256 !== todoBinding.mappingSha256)
+                            reject({ class: "conflict", message: "TODO reconciliation mapping changed during activation publication", recovery: "Preserve the changed docs mapping and retry activation after every transaction target is restored; no mapping bytes were overwritten." });
+                    },
+                });
+                context.assertValid();
+                return activationEnvelope(effect, false, false, transaction.id, transaction.targetCount, recovered);
+            }
+            if (req.spec.verb === "repair") {
+                if (!activation || !loadedActivation)
+                    throw new Error("TODO repair lost its required activation marker");
+                const plan = planTodoRepair(markdown, activation, todoEntities);
+                let activationBytesAfter = todoReconciliationActivationBytes(plan.retainedLegacyRows, "0".repeat(64), "repair");
+                const targets = todoEntities.map((entity) => ({ path: entity.relativePath, before: exactDiscoveredEntityBytes(entity), after: canonicalEntityEnvelopeBytes({ id: entity.id, artifact: "todo", record: plan.records.get(entity.id), migrationProvenance: entity.migrationProvenance ?? undefined }) }));
+                targets.push({ path: TODO_RECONCILIATION_ACTIVATION_PATH, before: loadedActivation.bytes, after: activationBytesAfter });
+                targets.push({ path: publicRelative, before: publicExists ? markdownBefore : null, after: plan.rendered });
+                const substantiveChange = targets.some((target) => target.path !== TODO_RECONCILIATION_ACTIVATION_PATH && (target.before === null || !target.before.equals(Buffer.from(target.after))));
+                if (!req.dryRun && !substantiveChange && activation.effect_operation === "repair" && req.values.effect_sha256 === activation.effect_sha256) {
+                    const replayEffect = todoRepairEffect(plan.diagnosis, [], publicRelative, markdownBefore, markdown);
+                    replayEffect.effect_sha256 = activation.effect_sha256;
+                    return repairEnvelope(replayEffect, false, true, null, 0, recovered);
+                }
+                const preliminaryEffect = todoRepairEffect(plan.diagnosis, targets, publicRelative, markdownBefore, plan.rendered);
+                activationBytesAfter = todoReconciliationActivationBytes(plan.retainedLegacyRows, String(preliminaryEffect.effect_sha256), "repair");
+                targets.find((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH).after = activationBytesAfter;
+                const effect = todoRepairEffect(plan.diagnosis, targets, publicRelative, markdownBefore, plan.rendered);
+                if (effect.effect_sha256 !== preliminaryEffect.effect_sha256)
+                    throw new Error("TODO repair effect authorization is not self-consistent");
+                if (req.dryRun)
+                    return repairEnvelope(effect, true, false, null, effect.targets.length, recovered);
+                if (req.values.effect_sha256 !== effect.effect_sha256)
+                    reject({ class: "conflict", message: "TODO repair effects changed after preview", syntax: TODO_REPAIR_PREVIEW_COMMAND, example: TODO_REPAIR_APPLY_COMMAND, recovery: `Rerun exactly '${TODO_REPAIR_PREVIEW_COMMAND}', review the changed bounded effects, then run its new exact apply_command; no state was changed.` });
+                const transaction = publishTodoReconciliation(context, sourceRoot, todoBinding, targets, {
+                    activationEffectSha256: String(effect.effect_sha256),
+                    interruptAfterTarget: options.interruptAfterTarget,
+                    beforeCommit: () => {
+                        assertState(pinnedRoot, sourceRoot, sourceBinding);
+                        const currentBinding = todoReconciliationBinding(req.projectRoot, sourceRoot);
+                        if (currentBinding.publicPath !== todoBinding.publicPath || currentBinding.mappingSha256 !== todoBinding.mappingSha256)
+                            reject({ class: "conflict", message: "TODO reconciliation mapping changed during repair publication", recovery: "Preserve the changed docs mapping and retry repair after every transaction target is restored; no mapping bytes were overwritten." });
+                    },
+                });
+                context.assertValid();
+                return repairEnvelope(effect, false, false, transaction.id, transaction.targetCount, recovered);
+            }
             const activating = activation === null;
             const scan = managedRows(markdown, activation, todoEntities);
             const rows = scan.rows;
@@ -983,4 +1062,3 @@ export function listTodoDocsEntities(root, artifact, limit, cursor, filters = {}
     const response = () => { const remaining = selected.length - start - page.length; const next = remaining && page.length ? encodeListCursor({ snapshot_id: snap, order: definition(artifact).order, filters, selector: selectorKey, after: page.at(-1).id, ...(artifact === "todo" ? { limit: take } : {}) }, root, declared.authorityPath) : undefined; return { schemaVersion: "agentera.stateList.v1", command: `state ${artifact} list`, status: remaining ? "degraded" : "ok", entries: page.map((entity) => entry(root, entity, view?.rows.get(entity.id), queueRanks.get(entity.id), actionability.get(entity.id), view?.drift)), ...(view ? { reconciliation: view.drift } : {}), counts: { total: selected.length, returned: page.length, remaining }, order: definition(artifact).order, filters, snapshot: { id: snap, first_page: !cursor, has_more: Boolean(remaining), candidate_count: selected.length }, source: { artifact, authority: "canonical_entity_files", root: declared.entityRoot }, source_contract: { authority: "references/artifacts/state-storage-authority.yaml", detail: "full", cursor: "opaque_snapshot_cursor" }, retrieval: { ...(next ? { continue: `agentera state ${artifact} list${filterFlags}${selectorFlags} --limit ${take} --cursor ${next} --format json` } : {}) }, ...(remaining ? { omitted: true, omitted_count: remaining, omission_reason: "page_limit", next_cursor: next } : {}) }; };
     return projectEntityList(response(), selector, projectionOptions);
 }
-//# sourceMappingURL=todoDocsEntities.js.map

package/dist/state/todoDocsEntityValidation.js

@@ -156,4 +156,3 @@ export function todoDocsRecordViolations(boundary, record, sourceRoot) {
     }
     return violations;
 }
-//# sourceMappingURL=todoDocsEntityValidation.js.map

package/dist/state/todoMarkdownProjection.js

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import { renderTodoPublicRecord } from "../cli/todoMarkdown.js";
+import { reject } from "./write/errors.js";
+const TODO_MARKDOWN_MAX_BYTES = 1024 * 1024;
+export function readTodoMarkdown(target) {
+    if (!fs.existsSync(target))
+        return { bytes: Buffer.from(""), text: "" };
+    const stat = fs.lstatSync(target);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        reject({ class: "conflict", message: "managed TODO Markdown must be a regular file", recovery: "Restore the docs-mapped TODO artifact as a regular file within the project and retry; no state was changed." });
+    if (stat.size > TODO_MARKDOWN_MAX_BYTES)
+        reject({ class: "conflict", message: `managed TODO Markdown exceeds the ${TODO_MARKDOWN_MAX_BYTES}-byte reconciliation bound`, recovery: "Compact unmanaged or resolved Markdown content below the declared bound and retry; no state was changed." });
+    const bytes = fs.readFileSync(target);
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        reject({ class: "conflict", message: "managed TODO Markdown is not valid UTF-8", recovery: "Restore valid UTF-8 TODO Markdown and retry; no state was changed." });
+    }
+    return { bytes, text: text };
+}
+function sectionFor(record) { return record.status === "resolved" ? "resolved" : String(record.severity); }
+function headingFor(section) { return section === "resolved" ? "## ✓ Resolved" : `## → ${section[0].toUpperCase()}${section.slice(1)}`; }
+function rowFor(id, record) { return `- [${record.status === "resolved" ? "x" : " "}] [id:${id}] ${renderTodoPublicRecord(record)}`; }
+export function renderManagedMarkdown(markdown, records, existing) {
+    const byLine = new Map([...existing.values()].map((row) => [row.line, row]));
+    const retained = new Set();
+    const lines = markdown.split(/\r?\n/).flatMap((line, index) => { const row = byLine.get(index); if (!row)
+        return [line]; const record = records.get(row.id); if (!record || sectionFor(record) !== row.section)
+        return []; retained.add(row.id); return [rowFor(row.id, record)]; });
+    for (const section of ["critical", "degraded", "normal", "annoying", "resolved"]) {
+        const ids = [...records.entries()].filter(([id, record]) => !retained.has(id) && sectionFor(record) === section).sort(([left], [right]) => { const a = existing.get(left); const b = existing.get(right); return (a?.section === section ? a.snapshot.order : Number.MAX_SAFE_INTEGER) - (b?.section === section ? b.snapshot.order : Number.MAX_SAFE_INTEGER) || left.localeCompare(right); }).map(([id]) => id);
+        if (!ids.length)
+            continue;
+        let heading = lines.findIndex((line) => line.trim().toLowerCase() === headingFor(section).toLowerCase());
+        if (heading < 0) {
+            if (lines.at(-1)?.trim())
+                lines.push("");
+            lines.push(headingFor(section));
+            heading = lines.length - 1;
+        }
+        let insert = heading + 1;
+        while (insert < lines.length && !/^##\s+/.test(lines[insert].trim()))
+            insert += 1;
+        while (insert > heading + 1 && !lines[insert - 1].trim())
+            insert -= 1;
+        lines.splice(insert, 0, ...ids.map((id) => rowFor(id, records.get(id))));
+    }
+    return `${lines.join("\n").replace(/\n*$/, "")}\n`;
+}

package/dist/state/todoReconciliationActivation.js

@@ -2,11 +2,18 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { reject } from "./write/errors.js";
+import { CANONICAL_DEVELOPMENT_CLI } from "../core/developmentChannel.js";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
 export const TODO_RECONCILIATION_ACTIVATION_PATH = ".agentera/todo-reconciliation-activation.json";
 export const TODO_RECONCILIATION_ACTIVATION_VERSION = "agentera.todoReconciliationActivation.v1";
 export const TODO_RECONCILIATION_ITEM_LIMIT = 256;
 const MAX_ACTIVATION_BYTES = 32 * 1024;
 const SHA256 = /^[a-f0-9]{64}$/;
+export const TODO_ACTIVATION_PREVIEW_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo activate --dry-run --format json`;
+export const TODO_ACTIVATION_APPLY_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo activate --effect-sha256 EFFECT_SHA256 --yes --format json`;
+export const TODO_REPAIR_PREVIEW_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo repair --dry-run --format json`;
+export const TODO_REPAIR_APPLY_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo repair --effect-sha256 EFFECT_SHA256 --yes --format json`;
+const CHANGE_LIMIT = 20;
 function activationFailure(message) {
     reject({
         class: "conflict",
@@ -17,15 +24,19 @@ function activationFailure(message) {
 export function todoLegacyRowFingerprint(section, line) {
     return createHash("sha256").update(section).update("\0").update(line).digest("hex");
 }
-export function todoReconciliationActivationBytes(retainedLegacyRows) {
+export function todoReconciliationActivationBytes(retainedLegacyRows, effectSha256, effectOperation = "activate") {
     const retained = [...retainedLegacyRows].sort();
     if (retained.length > TODO_RECONCILIATION_ITEM_LIMIT
         || new Set(retained).size !== retained.length
         || retained.some((digest) => !SHA256.test(digest)))
         activationFailure("TODO reconciliation activation has invalid retained legacy-row identities");
+    if (effectSha256 !== undefined && !SHA256.test(effectSha256))
+        activationFailure("TODO reconciliation activation has an invalid effect authorization");
     return `${JSON.stringify({
         schema_version: TODO_RECONCILIATION_ACTIVATION_VERSION,
         retained_legacy_rows: retained,
+        ...(effectSha256 ? { effect_sha256: effectSha256 } : {}),
+        ...(effectSha256 ? { effect_operation: effectOperation } : {}),
     })}\n`;
 }
 export function loadTodoReconciliationActivation(root) {
@@ -51,13 +62,71 @@ export function loadTodoReconciliationActivation(root) {
         activationFailure("TODO reconciliation activation is not a mapping");
     }
     const record = value;
-    if (Object.keys(record).sort().join(",") !== "retained_legacy_rows,schema_version"
+    if (!["retained_legacy_rows,schema_version", "effect_operation,effect_sha256,retained_legacy_rows,schema_version", "effect_sha256,retained_legacy_rows,schema_version"].includes(Object.keys(record).sort().join(","))
         || record.schema_version !== TODO_RECONCILIATION_ACTIVATION_VERSION
         || !Array.isArray(record.retained_legacy_rows)
         || record.retained_legacy_rows.length > TODO_RECONCILIATION_ITEM_LIMIT
         || record.retained_legacy_rows.some((digest) => typeof digest !== "string" || !SHA256.test(digest))
-        || new Set(record.retained_legacy_rows).size !== record.retained_legacy_rows.length)
+        || new Set(record.retained_legacy_rows).size !== record.retained_legacy_rows.length
+        || (record.effect_sha256 !== undefined && (typeof record.effect_sha256 !== "string" || !SHA256.test(record.effect_sha256)))
+        || (record.effect_operation !== undefined && !["activate", "repair"].includes(record.effect_operation)))
         activationFailure("TODO reconciliation activation has an invalid canonical record");
     return { record: record, bytes };
 }
-//# sourceMappingURL=todoReconciliationActivation.js.map
+function sha256(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+function boundedPublicChanges(before, after) {
+    const beforeLines = before.split(/\r?\n/);
+    const afterLines = after.split(/\r?\n/);
+    const changes = [];
+    let count = 0;
+    for (let index = 0; index < Math.max(beforeLines.length, afterLines.length); index += 1) {
+        if (beforeLines[index] === afterLines[index])
+            continue;
+        count += 1;
+        if (changes.length < CHANGE_LIMIT)
+            changes.push({ line: index + 1, before: (beforeLines[index] ?? "").slice(0, 240), after: (afterLines[index] ?? "").slice(0, 240) });
+    }
+    return { count, items: changes, omitted_count: count - changes.length };
+}
+export function todoActivationEffect(scan, targets, publicPath, markdownBefore, rendered, resurrectedIds) {
+    const changedTargets = targets.filter((target) => target.before === null || !target.before.equals(Buffer.from(target.after))).map((target) => ({ path: target.path, before_sha256: target.before === null ? null : sha256(target.before), after_sha256: sha256(target.after) }));
+    const evidence = {
+        counts: { matched: scan.matchedRows, converted: scan.convertedRows, retained: scan.retainedLegacyRows.length, conflicting: 0 }, targets: changedTargets,
+        public_document: { path: publicPath, changed: !markdownBefore.equals(Buffer.from(rendered)), before_bytes: markdownBefore.length, after_bytes: Buffer.byteLength(rendered), before_sha256: sha256(markdownBefore), after_sha256: sha256(rendered), changed_lines: boundedPublicChanges(markdownBefore.toString("utf8"), rendered) },
+        risks: { resurrected_count: resurrectedIds.length, resurrected_ids: resurrectedIds.slice(0, CHANGE_LIMIT), omitted_count: Math.max(0, resurrectedIds.length - CHANGE_LIMIT) },
+    };
+    const authorizedTargets = changedTargets.map((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH ? { ...target, after_sha256: "activation_effect_authorization" } : target);
+    return { ...evidence, effect_sha256: sha256(canonicalRecordJson({ ...evidence, targets: authorizedTargets })) };
+}
+export function unchangedTodoActivationEffect(publicPath, markdown, retained, authorizedEffectSha256) {
+    const evidence = { counts: { matched: 0, converted: 0, retained, conflicting: 0 }, targets: [], public_document: { path: publicPath, changed: false, before_bytes: markdown.length, after_bytes: markdown.length, before_sha256: sha256(markdown), after_sha256: sha256(markdown), changed_lines: { count: 0, items: [], omitted_count: 0 } }, risks: { resurrected_count: 0, resurrected_ids: [], omitted_count: 0 } };
+    return { ...evidence, effect_sha256: authorizedEffectSha256 ?? sha256(canonicalRecordJson(evidence)) };
+}
+export function todoRepairEffect(diagnosis, targets, publicPath, markdownBefore, rendered) {
+    const changedTargets = targets
+        .filter((target) => target.before === null || !target.before.equals(Buffer.from(target.after)))
+        .map((target) => ({ path: target.path, before_sha256: target.before === null ? null : sha256(target.before), after_sha256: sha256(target.after) }));
+    const evidence = {
+        diagnosis,
+        targets: changedTargets,
+        public_document: {
+            path: publicPath,
+            changed: !markdownBefore.equals(Buffer.from(rendered)),
+            before_bytes: markdownBefore.length,
+            after_bytes: Buffer.byteLength(rendered),
+            before_sha256: sha256(markdownBefore),
+            after_sha256: sha256(rendered),
+            changed_lines: boundedPublicChanges(markdownBefore.toString("utf8"), rendered),
+        },
+    };
+    const activationTarget = targets.find((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH);
+    let normalizedActivationSha256 = null;
+    if (activationTarget) {
+        const parsed = JSON.parse(activationTarget.after);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || typeof parsed.effect_sha256 !== "string")
+            throw new Error("TODO repair activation target cannot be normalized for effect authorization");
+        normalizedActivationSha256 = sha256(canonicalRecordJson({ ...parsed, effect_sha256: "activation_effect_authorization" }));
+    }
+    const authorizedTargets = changedTargets.map((target) => target.path === TODO_RECONCILIATION_ACTIVATION_PATH ? { ...target, after_sha256: normalizedActivationSha256 } : target);
+    return { ...evidence, effect_sha256: sha256(canonicalRecordJson({ ...evidence, targets: authorizedTargets })) };
+}