agentera 3.0.0-dev.6 → 3.0.0-dev.69

package/dist/state/todoDocsEntityValidation.js

@@ -0,0 +1,158 @@
+import path from "node:path";
+import { loadTodoReadinessContract, todoReadinessRecordViolations } from "../registries/todoReadinessContract.js";
+export const TODO_SEVERITIES = ["critical", "degraded", "normal", "annoying"];
+export const TODO_STATUSES = ["open", "resolved"];
+export const TODO_KIND_RE = /^[a-z][a-z0-9_-]{0,31}$/;
+export const DOC_STATUSES = ["current", "stale", "missing", "intent", "generated"];
+const TODO_INPUT_FIELDS = new Set([
+    "kind", "target_version", "title", "requirements", "acceptance", "release_blocker", "severity", "readiness",
+]);
+const TODO_CLEARABLE_FIELDS = new Set(["target_version", "requirements", "acceptance", "readiness"]);
+const TODO_LIFECYCLE_REASON_MAX_CODE_POINTS = 500;
+const TODO_RECONCILIATION_VERSION = "agentera.todoReconciliation.v1";
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stringList(value, field) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
+        return [`${field} must be a list of strings`];
+    return [];
+}
+function publicTodoViolations(record) {
+    const violations = [];
+    const typed = record.title !== undefined || record.kind !== undefined || record.target_version !== undefined
+        || record.requirements !== undefined || record.acceptance !== undefined || record.release_blocker !== undefined;
+    if (!typed && (typeof record.description !== "string" || !record.description.trim()))
+        violations.push("title or legacy description is required");
+    if (typed) {
+        if (typeof record.kind !== "string" || !TODO_KIND_RE.test(record.kind))
+            violations.push("kind must be a lowercase identifier of at most 32 characters");
+        if (typeof record.title !== "string" || !record.title.trim())
+            violations.push("title is required");
+        if (record.target_version !== undefined && record.target_version !== null && (typeof record.target_version !== "string" || !record.target_version.trim()))
+            violations.push("target_version must be a non-empty string or null");
+        if (record.requirements !== undefined)
+            violations.push(...stringList(record.requirements, "requirements"));
+        if (record.acceptance !== undefined)
+            violations.push(...stringList(record.acceptance, "acceptance"));
+        if (record.release_blocker !== undefined && typeof record.release_blocker !== "boolean")
+            violations.push("release_blocker must be a boolean");
+    }
+    return violations;
+}
+export function todoInputViolations(input, mode) {
+    const violations = [];
+    for (const field of Object.keys(input)) {
+        if (!TODO_INPUT_FIELDS.has(field))
+            violations.push(`unsupported TODO input field '${field}'`);
+    }
+    if (mode === "create") {
+        for (const field of ["kind", "target_version", "title", "requirements", "acceptance", "release_blocker", "severity"]) {
+            if (!(field in input))
+                violations.push(`${field} is required in a full typed TODO record`);
+        }
+    }
+    else if (Object.keys(input).length === 0) {
+        violations.push("TODO update requires at least one patch field");
+    }
+    if (input.kind !== undefined && (typeof input.kind !== "string" || !TODO_KIND_RE.test(input.kind)))
+        violations.push("kind must be a lowercase identifier of at most 32 characters");
+    if (input.title !== undefined && (typeof input.title !== "string" || !input.title.trim()))
+        violations.push("title must be a non-empty string");
+    if (input.target_version !== undefined && input.target_version !== null && (typeof input.target_version !== "string" || !input.target_version.trim()))
+        violations.push("target_version must be a non-empty string or null");
+    if (input.requirements !== undefined && input.requirements !== null)
+        violations.push(...stringList(input.requirements, "requirements"));
+    if (input.acceptance !== undefined && input.acceptance !== null)
+        violations.push(...stringList(input.acceptance, "acceptance"));
+    if (input.release_blocker !== undefined && typeof input.release_blocker !== "boolean")
+        violations.push("release_blocker must be a boolean; false is the typed non-blocking value");
+    if (input.severity !== undefined && !TODO_SEVERITIES.includes(input.severity))
+        violations.push(`severity must be one of: ${TODO_SEVERITIES.join(", ")}`);
+    if (input.description !== undefined)
+        violations.push("description is a retired legacy field; use title and the typed TODO record");
+    if (mode === "update") {
+        for (const field of ["kind", "title", "severity", "release_blocker", "description"])
+            if (input[field] === null)
+                violations.push(`${field} cannot be cleared; omit it or supply a typed value`);
+        for (const field of ["target_version", "requirements", "acceptance", "readiness"])
+            if (input[field] === null && !TODO_CLEARABLE_FIELDS.has(field))
+                violations.push(`${field} is not clearable`);
+    }
+    if (input.readiness !== undefined && input.readiness !== null) {
+        const readiness = mapping(input.readiness) ? input.readiness : null;
+        if (!readiness)
+            violations.push("readiness must be a complete mapping or null");
+        else {
+            const dependencies = readiness.dependencies;
+            const normalized = Array.isArray(dependencies)
+                ? dependencies.map((dependency) => typeof dependency === "string" ? { artifact: "todo", id: dependency } : dependency)
+                : dependencies;
+            violations.push(...todoReadinessRecordViolations({ ...readiness, dependencies: normalized }));
+        }
+    }
+    return [...new Set(violations)];
+}
+export function todoDocsRecordViolations(boundary, record, sourceRoot) {
+    const violations = [];
+    if (boundary === "todo_item") {
+        if (!TODO_SEVERITIES.includes(record.severity))
+            violations.push(`severity must be one of: ${TODO_SEVERITIES.join(", ")}`);
+        if (!TODO_STATUSES.includes(record.status))
+            violations.push(`status must be one of: ${TODO_STATUSES.join(", ")}`);
+        violations.push(...publicTodoViolations(record));
+        if (record.lifecycle !== undefined) {
+            if (!mapping(record.lifecycle))
+                violations.push("lifecycle must be a mapping");
+            else {
+                const lifecycle = record.lifecycle;
+                if (!["set-severity", "supersede", "resolve", "reopen"].includes(String(lifecycle.operation)))
+                    violations.push("lifecycle.operation is invalid");
+                if (typeof lifecycle.reason !== "string" || !lifecycle.reason.trim())
+                    violations.push("lifecycle.reason must be a non-empty string");
+                else if ([...lifecycle.reason].length > TODO_LIFECYCLE_REASON_MAX_CODE_POINTS)
+                    violations.push(`lifecycle.reason must be at most ${TODO_LIFECYCLE_REASON_MAX_CODE_POINTS} code points`);
+                if (!/^\d{4}-\d{2}-\d{2}$/.test(String(lifecycle.date ?? "")))
+                    violations.push("lifecycle.date must be YYYY-MM-DD");
+                if (lifecycle.replacement !== undefined && !/^[a-z]{10}$/.test(String(lifecycle.replacement)))
+                    violations.push("lifecycle.replacement must be a ten-letter TODO ID");
+            }
+        }
+        if (record.readiness !== undefined) {
+            const contract = sourceRoot
+                ? loadTodoReadinessContract(path.join(sourceRoot, "skills/agentera/schemas/artifacts/todo.yaml"), path.join(sourceRoot, "skills/agentera/protocol.yaml"), path.join(sourceRoot, "skills/agentera/capability_schema_contract.yaml"))
+                : undefined;
+            violations.push(...todoReadinessRecordViolations(record.readiness, contract));
+        }
+        if (record.reconciliation !== undefined) {
+            if (!mapping(record.reconciliation) || record.reconciliation.schema_version !== TODO_RECONCILIATION_VERSION || !mapping(record.reconciliation.public))
+                violations.push("reconciliation must be a canonical TODO public baseline");
+            else {
+                const baseline = record.reconciliation.public;
+                if (typeof baseline.present !== "boolean")
+                    violations.push("reconciliation.public.present must be a boolean");
+                if (baseline.present) {
+                    if (typeof baseline.description !== "string" || !baseline.description.trim())
+                        violations.push("reconciliation.public.description is required when present");
+                    if (!TODO_SEVERITIES.includes(baseline.severity))
+                        violations.push(`reconciliation.public.severity must be one of: ${TODO_SEVERITIES.join(", ")}`);
+                    if (!TODO_STATUSES.includes(baseline.status))
+                        violations.push(`reconciliation.public.status must be one of: ${TODO_STATUSES.join(", ")}`);
+                    if (!Number.isSafeInteger(baseline.order) || Number(baseline.order) < 1)
+                        violations.push("reconciliation.public.order must be a positive integer");
+                }
+            }
+        }
+    }
+    if (boundary === "documentation_inventory_entry") {
+        if (typeof record.document !== "string" || !record.document.trim())
+            violations.push("document is required");
+        if (typeof record.path !== "string" || !record.path.trim())
+            violations.push("path is required record data");
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(String(record.last_updated ?? "")))
+            violations.push("last_updated must be YYYY-MM-DD");
+        if (!DOC_STATUSES.includes(record.status))
+            violations.push(`status must be one of: ${DOC_STATUSES.join(", ")}`);
+    }
+    return violations;
+}

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

@@ -0,0 +1,182 @@
+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`;
+export const TODO_OWNER_CORRECTION_INPUT_VERSION = "agentera.todoOwnerCorrection.v1";
+export const TODO_OWNER_CORRECTION_PREVIEW_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo correct-owners --input OWNER_MAPPING.yaml --dry-run --format json`;
+export const TODO_OWNER_CORRECTION_APPLY_COMMAND = `${CANONICAL_DEVELOPMENT_CLI} state todo correct-owners --input OWNER_MAPPING.yaml --effect-sha256 EFFECT_SHA256 --yes --format json`;
+export const TODO_UNSAFE_INACTIVE_RECOVERY = `Owner correction required: run exactly '${TODO_OWNER_CORRECTION_PREVIEW_COMMAND}', then use its exact apply_command; no state was changed.`;
+export const TODO_ACTIVATION_RISK_LIMIT = 20;
+function activationFailure(message) {
+    reject({
+        class: "conflict",
+        message,
+        recovery: `Preserve '${TODO_RECONCILIATION_ACTIVATION_PATH}', restore its last valid committed bytes, and retry the exact TODO mutation; no state was changed.`,
+    });
+}
+export function todoLegacyRowFingerprint(section, line) {
+    return createHash("sha256").update(section).update("\0").update(line).digest("hex");
+}
+export function todoReconciliationActivationBytes(retainedLegacyRows, effectSha256, effectOperation = "activate", ownerMappingSha256) {
+    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");
+    if (ownerMappingSha256 !== undefined && !SHA256.test(ownerMappingSha256))
+        activationFailure("TODO reconciliation activation has an invalid owner-mapping authorization");
+    if (effectOperation === "correct-owners" && (effectSha256 === undefined || ownerMappingSha256 === undefined))
+        activationFailure("TODO owner correction activation requires effect and owner-mapping authorization");
+    if (effectOperation !== "correct-owners" && ownerMappingSha256 !== undefined)
+        activationFailure("TODO reconciliation activation owner-mapping authorization requires owner correction");
+    return `${JSON.stringify({
+        schema_version: TODO_RECONCILIATION_ACTIVATION_VERSION,
+        retained_legacy_rows: retained,
+        ...(effectSha256 ? { effect_sha256: effectSha256 } : {}),
+        ...(effectSha256 ? { effect_operation: effectOperation } : {}),
+        ...(ownerMappingSha256 ? { owner_mapping_sha256: ownerMappingSha256 } : {}),
+    })}\n`;
+}
+export function loadTodoReconciliationActivation(root) {
+    const target = path.join(root, TODO_RECONCILIATION_ACTIVATION_PATH);
+    if (!fs.existsSync(target))
+        return null;
+    const stat = fs.lstatSync(target);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        activationFailure("TODO reconciliation activation must be a regular file");
+    }
+    const bytes = fs.readFileSync(target);
+    if (bytes.length > MAX_ACTIVATION_BYTES) {
+        activationFailure("TODO reconciliation activation exceeds its 32768-byte bound");
+    }
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        activationFailure("TODO reconciliation activation is not valid bounded UTF-8 JSON");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        activationFailure("TODO reconciliation activation is not a mapping");
+    }
+    const record = value;
+    if (!["retained_legacy_rows,schema_version", "effect_operation,effect_sha256,retained_legacy_rows,schema_version", "effect_operation,effect_sha256,owner_mapping_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
+        || (record.effect_sha256 !== undefined && (typeof record.effect_sha256 !== "string" || !SHA256.test(record.effect_sha256)))
+        || (record.effect_operation !== undefined && !["activate", "repair", "correct-owners"].includes(record.effect_operation))
+        || (record.owner_mapping_sha256 !== undefined && (typeof record.owner_mapping_sha256 !== "string" || !SHA256.test(record.owner_mapping_sha256)))
+        || (record.effect_operation === "correct-owners" && (record.effect_sha256 === undefined || record.owner_mapping_sha256 === undefined))
+        || (record.effect_operation !== "correct-owners" && record.owner_mapping_sha256 !== undefined))
+        activationFailure("TODO reconciliation activation has an invalid canonical record");
+    return { record: record, bytes };
+}
+function sha256(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+export function todoActivationRisks(resurrectedIds) {
+    return {
+        resurrected_count: resurrectedIds.length,
+        resurrected_ids: resurrectedIds.slice(0, TODO_ACTIVATION_RISK_LIMIT),
+        omitted_count: Math.max(0, resurrectedIds.length - TODO_ACTIVATION_RISK_LIMIT),
+    };
+}
+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 < TODO_ACTIVATION_RISK_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: todoActivationRisks(resurrectedIds),
+    };
+    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: todoActivationRisks([]) };
+    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 })) };
+}
+export function todoOwnerCorrectionEffect(diagnosis, ownerMappingSha256, 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,
+        owner_mapping_sha256: ownerMappingSha256,
+        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 owner correction 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 })) };
+}

package/dist/state/todoReconciliationInspection.js

@@ -0,0 +1,171 @@
+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_OWNER_CORRECTION_APPLY_COMMAND, TODO_OWNER_CORRECTION_PREVIEW_COMMAND, TODO_RECONCILIATION_ACTIVATION_PATH, TODO_REPAIR_APPLY_COMMAND, TODO_REPAIR_PREVIEW_COMMAND, TODO_UNSAFE_INACTIVE_RECOVERY, loadTodoReconciliationActivation, todoReconciliationActivationBytes, } from "./todoReconciliationActivation.js";
+import { planTodoRepair } from "./todoReconciliationRepair.js";
+import { readTodoMarkdown } from "./todoMarkdownProjection.js";
+import { inactiveTodoActivationSafety } from "./todoActivationSafety.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, risks) {
+    const bounded = boundedCounts(rawCounts);
+    const active = state === "healthy_active" || state === "unsafe_active";
+    const preview = state === "unsafe_inactive" ? TODO_OWNER_CORRECTION_PREVIEW_COMMAND : state === "inactive" ? TODO_ACTIVATION_PREVIEW_COMMAND : active ? TODO_REPAIR_PREVIEW_COMMAND : null;
+    const apply = state === "unsafe_inactive" ? TODO_OWNER_CORRECTION_APPLY_COMMAND : 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,
+        ...(risks === undefined ? {} : { risks }),
+        preview_command: preview,
+        apply_command: apply,
+        recovery_command: state === "unsafe_inactive" ? TODO_UNSAFE_INACTIVE_RECOVERY : 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);
+            if (entities.length === 0 && scan.matchedRows === 0 && scan.retainedLegacyRows.length === 0)
+                return null;
+            const safety = inactiveTodoActivationSafety(scan, entities);
+            return inspection(safety.safe ? "inactive" : "unsafe_inactive", safety.counts, safety.safe ? undefined : safety.risks);
+        }
+        catch (error) {
+            return inspection("unsafe_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"];
+}