agentera 3.0.0-dev.79 → 3.0.0-dev.80

package/dist/state/todoDocsEntities.js

@@ -23,6 +23,9 @@ import { normalizeTodoOwnerCorrectionEvidence, planTodoOwnerCorrection, planTodo
 import { readTodoMarkdown, renderManagedMarkdown } from "./todoMarkdownProjection.js";
 import { inactiveTodoActivationSafety, rejectUnsafeInactiveTodoActivation, unsafeInactiveDuplicateDiagnosis } from "./todoActivationSafety.js";
 import { assertTodoSeverityHeadingStructure, todoSeveritySectionForHeading } from "./todoSeverityHeadings.js";
+import { parseTodoUpdateBatch, todoUpdateBatchEffectSha256 } from "./todoUpdateBatch.js";
+import { parseTodoCreateBatch, resolveTodoCreateBatchRecords, todoCreateBatchEffectSha256 } from "./todoCreateBatch.js";
+import { matchesTodoTransitionBatchPostState, parseTodoTransitionBatch, todoTransitionBatchPostStateSha256 } from "./todoTransitionBatch.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" };
@@ -411,7 +414,7 @@ function importMarkdown(record, row) {
     result.status = row.item.status;
     return result;
 }
-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 withBaseline(record, value) { const publicValue = Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined)); const transitionBatch = mapping(record.reconciliation) && mapping(record.reconciliation.transition_batch) ? structuredClone(record.reconciliation.transition_batch) : null; return { ...record, reconciliation: { schema_version: RECONCILIATION_VERSION, public: publicValue, ...(transitionBatch ? { transition_batch: transitionBatch } : {}) } }; }
 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 } }; }
@@ -671,6 +674,9 @@ export function mutateTodoDocsEntity(req, options = {}) {
         const todoBinding = artifact === "todo" ? todoReconciliationBinding(req.projectRoot, sourceRoot) : null;
         const correctingOwners = artifact === "todo" && req.spec.verb === "correct-owners";
         const ownerEvidence = correctingOwners ? normalizeTodoOwnerCorrectionEvidence(req.input ?? {}) : null;
+        const batch = artifact === "todo" && req.spec.verb === "update" ? parseTodoUpdateBatch(req.input) : null;
+        const createBatch = artifact === "todo" && req.spec.verb === "create" ? parseTodoCreateBatch(req.input) : null;
+        const transitionBatch = artifact === "todo" ? parseTodoTransitionBatch(req.input, req.spec.verb) : null;
         const pending = todoBinding ? inspectTodoReconciliation(pinnedRoot, todoBinding) : [];
         if (artifact === "todo")
             assertTodoSeverityHeadingStructure(readTodoMarkdown(todoPublicPath(pinnedRoot, sourceRoot)).text);
@@ -690,13 +696,15 @@ export function mutateTodoDocsEntity(req, options = {}) {
             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;
+        const createRequest = artifact === "todo" && req.spec.verb === "create" && !createBatch ? mutationRecord(req, undefined) : null;
         const createRequestSha256 = createRequest ? todoCreateRequestSha256(createRequest) : undefined;
         const recoveryReceipts = todoBinding && !req.dryRun
             ? recoverTodoReconciliation(context, sourceRoot, todoBinding, {
                 createRequestSha256,
                 ...(["activate", "repair", "correct-owners"].includes(req.spec.verb) ? { activationEffectSha256: String(req.values.effect_sha256) } : {}),
                 ...(correctingOwners ? { ownerMappingSha256: ownerEvidence.sha256 } : {}),
+                ...(batch || transitionBatch ? { updateBatch: { effectSha256: String(req.values.effect_sha256 ?? ""), input: req.input } } : {}),
+                ...(createBatch ? { createBatch: { effectSha256: String(req.values.effect_sha256 ?? ""), input: req.input } } : {}),
                 beforeCommit: () => assertState(pinnedRoot, sourceRoot, sourceBinding),
             })
             : [];
@@ -711,6 +719,15 @@ export function mutateTodoDocsEntity(req, options = {}) {
                 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 } };
             }
+            const recoveredBatch = recoveryReceipts.find((receipt) => receipt.update_batch_effect_sha256);
+            if (recoveredBatch?.update_batch_effect_sha256 && (batch || transitionBatch)) {
+                const verb = transitionBatch?.verb ?? "update";
+                const entries = transitionBatch?.entries ?? batch;
+                return { schemaVersion: "agentera.stateWrite.v1", command: `state todo ${verb}`, status: "pass", artifact: "todo", records: entries.map(({ id }) => ({ id, record: selectedById(entities, "todo", id).record })), operation: { verb, dry_run: false, idempotent_replay: true }, validation: { status: "pass", violations: [] }, effect_sha256: recoveredBatch.update_batch_effect_sha256, apply_command: null, reconciliation: { transaction_id: recoveredBatch.transaction_id, targets: recoveredBatch.target_count, recovered } };
+            }
+            const recoveredCreateBatch = recoveryReceipts.find((receipt) => receipt.create_batch);
+            if (recoveredCreateBatch?.create_batch && createBatch)
+                return { schemaVersion: "agentera.stateWrite.v1", command: "state todo create", status: "pass", artifact: "todo", records: Object.entries(recoveredCreateBatch.create_batch.local_refs).map(([local_ref, id]) => ({ local_ref, id, record: selectedById(entities, "todo", id).record })), local_refs: recoveredCreateBatch.create_batch.local_refs, operation: { verb: "create", dry_run: false, idempotent_replay: true }, validation: { status: "pass", violations: [] }, effect_sha256: recoveredCreateBatch.create_batch.effect_sha256, apply_command: null, reconciliation: { transaction_id: recoveredCreateBatch.transaction_id, targets: recoveredCreateBatch.target_count, recovered } };
             const publicFile = todoPublicPath(pinnedRoot, sourceRoot);
             const publicRelative = todoBinding.publicPath;
             const publicExists = fs.existsSync(publicFile);
@@ -868,6 +885,199 @@ export function mutateTodoDocsEntity(req, options = {}) {
             const scan = managedRows(markdown, activation, todoEntities);
             const rows = scan.rows;
             const reconciled = reconcileTodoRecords(todoEntities, rows, activating);
+            if (createBatch) {
+                if (!req.dryRun && (!req.values.confirmed || !SHA256.test(String(req.values.effect_sha256 ?? ""))))
+                    reject({ class: "invalid_request", message: "todo create batch apply requires its preview effect SHA-256 and --yes", recovery: "Run the same batch input with --dry-run, review it, then repeat that input with the returned --effect-sha256 value and --yes; no state was changed." });
+                const inputSha256 = createHash("sha256").update(canonicalRecordJson(req.input)).digest("hex");
+                const prior = todoEntities.filter(({ record }) => mapping(record?.reconciliation) && mapping(record.reconciliation.create_batch) && record.reconciliation.create_batch.input_sha256 === inputSha256);
+                if (prior.length) {
+                    const createReceipt = prior[0].record.reconciliation.create_batch;
+                    const localRefs = createReceipt.local_refs;
+                    if (prior.length !== createBatch.length || prior.some(({ id, record }) => canonicalRecordJson(record.reconciliation.create_batch) !== canonicalRecordJson(createReceipt) || !Object.values(localRefs).includes(id)) || req.values.effect_sha256 !== createReceipt.effect_sha256)
+                        reject({ class: "conflict", message: "existing TODO create batch receipt is incomplete or does not match this effect authorization", recovery: "Restore the complete original create batch result or use its exact input and effect SHA-256; no state was changed." });
+                    return { schemaVersion: "agentera.stateWrite.v1", command: "state todo create", status: "pass", artifact: "todo", records: createBatch.map(({ local_ref }) => { const id = localRefs[local_ref]; return { local_ref, id, record: selectedById(todoEntities, "todo", id).record }; }), local_refs: localRefs, operation: { verb: "create", dry_run: false, idempotent_replay: true }, validation: { status: "pass", violations: [] }, effect_sha256: createReceipt.effect_sha256, apply_command: null, reconciliation: { transaction_id: null, targets: 0, recovered } };
+                }
+                const allocated = new Set();
+                const localIds = new Map();
+                for (const { local_ref } of createBatch) {
+                    let salt = 0;
+                    let id;
+                    do {
+                        const digest = createHash("sha256").update(inputSha256).update("\0").update(local_ref).update("\0").update(String(salt++)).digest();
+                        id = Array.from(digest.subarray(0, 10), (byte) => String.fromCharCode(97 + byte % 26)).join("");
+                        try {
+                            id = allocateEntityId(context.pinnedPath(), () => id, sourceRoot);
+                        }
+                        catch (error) {
+                            if (!String(error.message).includes("could not allocate"))
+                                throw error;
+                            continue;
+                        }
+                    } while (allocated.has(id));
+                    allocated.add(id);
+                    localIds.set(local_ref, id);
+                }
+                const resolved = resolveTodoCreateBatchRecords(createBatch, localIds);
+                for (const { local_ref, record } of resolved) {
+                    const id = localIds.get(local_ref);
+                    reconciled.records.set(id, mutationRecord({ ...req, input: record, values: {}, callerPayload: record }, undefined));
+                    reconciled.visible.add(id);
+                }
+                const referenceEntities = [...reconciled.records].map(([todoId, record]) => ({ boundary: TODO.boundary, id: todoId, record }));
+                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, recovery: "Correct the batch record and preview the complete batch again; no state was changed." });
+                    if (record.readiness !== undefined)
+                        assertTodoReferences(todoId, record, referenceEntities);
+                }
+                const visibleRecords = new Map([...reconciled.records].filter(([todoId]) => reconciled.visible.has(todoId)));
+                const rendered = renderManagedMarkdown(markdown, visibleRecords, rows);
+                const activationBytesAfter = activation ? loadedActivation.bytes.toString("utf8") : todoReconciliationActivationBytes(scan.retainedLegacyRows);
+                const activationAfter = activation ?? JSON.parse(activationBytesAfter);
+                const finalRows = managedRows(rendered, activationAfter, [...todoEntities, ...[...localIds.values()].map((id) => ({ boundary: TODO.boundary, id, record: reconciled.records.get(id) }))]).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 localRefs = Object.fromEntries(localIds);
+                const existingTargets = 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 }) }));
+                const newTargets = [...localIds.values()].map((id) => ({ path: relative(req.projectRoot, targetPath(req.projectRoot, sourceRoot, "todo", id)), before: null, after: "" }));
+                const targets = [...existingTargets, ...newTargets];
+                if (activating)
+                    targets.push({ path: TODO_RECONCILIATION_ACTIVATION_PATH, before: null, after: activationBytesAfter });
+                targets.push({ path: publicRelative, before: publicExists ? markdownBefore : null, after: rendered });
+                const ordered = targets.filter((target) => target.before === null || !target.before.equals(Buffer.from(target.after))).sort((left, right) => Number(left.path === TODO_RECONCILIATION_ACTIVATION_PATH) - Number(right.path === TODO_RECONCILIATION_ACTIVATION_PATH) || Number(left.path === publicRelative) - Number(right.path === publicRelative) || left.path.localeCompare(right.path));
+                let effectSha256 = todoCreateBatchEffectSha256(req.input, todoBinding.mappingSha256, localRefs, ordered.filter((target) => !newTargets.includes(target)).map((target) => ({ path: target.path, before_sha256: target.before === null ? null : createHash("sha256").update(target.before).digest("hex"), after_sha256: createHash("sha256").update(target.after).digest("hex") })));
+                const batchReceipt = { effect_sha256: effectSha256, input_sha256: inputSha256, local_refs: localRefs };
+                for (const [localRef, id] of localIds) {
+                    const record = reconciled.records.get(id);
+                    record.reconciliation = { ...record.reconciliation, create_batch: batchReceipt };
+                    newTargets.find((target) => target.path.endsWith(`/${id}.yaml`)).after = canonicalEntityEnvelopeBytes({ id, artifact: "todo", record });
+                }
+                effectSha256 = todoCreateBatchEffectSha256(req.input, todoBinding.mappingSha256, localRefs, ordered.filter((target) => !newTargets.includes(target)).map((target) => ({ path: target.path, before_sha256: target.before === null ? null : createHash("sha256").update(target.before).digest("hex"), after_sha256: createHash("sha256").update(target.after).digest("hex") })));
+                batchReceipt.effect_sha256 = effectSha256;
+                for (const [, id] of localIds) {
+                    const record = reconciled.records.get(id);
+                    record.reconciliation.create_batch = batchReceipt;
+                    newTargets.find((target) => target.path.endsWith(`/${id}.yaml`)).after = canonicalEntityEnvelopeBytes({ id, artifact: "todo", record });
+                }
+                const response = { schemaVersion: "agentera.stateWrite.v1", command: "state todo create", status: "pass", artifact: "todo", records: createBatch.map(({ local_ref }) => ({ local_ref, id: localIds.get(local_ref), record: reconciled.records.get(localIds.get(local_ref)) })), local_refs: localRefs, operation: { verb: "create", dry_run: req.dryRun, idempotent_replay: false }, validation: { status: "pass", violations: [] }, effect_sha256: effectSha256, apply_command: req.dryRun ? `agentera state todo create --input <same-input> --effect-sha256 ${effectSha256} --yes --format json` : null };
+                if (req.dryRun)
+                    return { ...response, reconciliation: { transaction_id: null, targets: targets.length, recovered } };
+                if (req.values.effect_sha256 !== effectSha256)
+                    reject({ class: "conflict", message: "TODO create batch effects changed after preview", recovery: "Rerun the same batch input with --dry-run, review the new bounded effect, then use its exact effect SHA-256; no state was changed." });
+                const transaction = publishTodoReconciliation(context, sourceRoot, todoBinding, targets, { createBatch: batchReceipt, 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 create batch publication", recovery: "Preserve the changed docs mapping and retry after every transaction target is restored; no mapping bytes were overwritten." }); } });
+                context.assertValid();
+                return { ...response, reconciliation: { transaction_id: transaction.id, targets: transaction.targetCount, recovered } };
+            }
+            if (transitionBatch) {
+                const verb = transitionBatch.verb;
+                if (!req.dryRun && (!req.values.confirmed || !SHA256.test(String(req.values.effect_sha256 ?? ""))))
+                    reject({ class: "invalid_request", message: `todo ${verb} batch apply requires its preview effect SHA-256 and --yes`, recovery: "Run the same batch input with --dry-run, review it, then repeat that input with the returned --effect-sha256 value and --yes; no state was changed." });
+                const inputSha256 = createHash("sha256").update(canonicalRecordJson(req.input)).digest("hex");
+                const priorReceipts = transitionBatch.entries.map(({ id }) => mapping(reconciled.records.get(id)?.reconciliation) ? reconciled.records.get(id).reconciliation.transition_batch : null);
+                if (priorReceipts.every((receipt) => mapping(receipt) && receipt.input_sha256 === inputSha256 && receipt.verb === verb && receipt.effect_sha256 === req.values.effect_sha256)) {
+                    const divergent = transitionBatch.entries.find((entry, index) => !matchesTodoTransitionBatchPostState(reconciled.records.get(entry.id), priorReceipts[index], entry, verb));
+                    if (divergent)
+                        reject({ class: "conflict", message: `TODO ${verb} batch member '${divergent.id}' no longer matches its authorized post-state`, recovery: "Preserve the current singleton result and preview a fresh batch from current state; no state was changed." });
+                    return { schemaVersion: "agentera.stateWrite.v1", command: `state todo ${verb}`, status: "pass", artifact: "todo", records: transitionBatch.entries.map(({ id }) => ({ id, record: reconciled.records.get(id) })), operation: { verb, dry_run: false, idempotent_replay: true }, validation: { status: "pass", violations: [] }, effect_sha256: req.values.effect_sha256, apply_command: null, reconciliation: { transaction_id: null, targets: 0, recovered } };
+                }
+                for (const { id } of transitionBatch.entries) {
+                    selectedById(todoEntities, "todo", id);
+                    if (verb === "resolve" && reconciled.records.get(id).status !== "open")
+                        reject({ class: "conflict", message: "TODO resolve requires an open item", recovery: "Remove already-resolved items from the batch, then preview the complete open-item batch again; no state was changed." });
+                }
+                const requestedRecords = [];
+                for (const entry of transitionBatch.entries) {
+                    const values = { id: entry.id, ...(entry.severity ? { severity: entry.severity } : {}), lifecycle: { reason: entry.reason, date: entry.date } };
+                    const record = transitionRecord({ ...req, input: null, values, callerPayload: values }, reconciled.records.get(entry.id), todoEntities.map((entity) => ({ ...entity, record: reconciled.records.get(entity.id) })));
+                    reconciled.records.set(entry.id, record);
+                    requestedRecords.push({ id: entry.id, record });
+                }
+                for (const [todoId, record] of reconciled.records) {
+                    const violations = recordViolations("todo", record, sourceRoot);
+                    if (violations.length)
+                        reject({ class: "schema_violation", message: `todo ${verb} batch input is invalid`, violations, recovery: "Correct the complete batch and preview it again; no state was changed." });
+                }
+                const visibleRecords = new Map([...reconciled.records].filter(([todoId]) => reconciled.visible.has(todoId)));
+                const rendered = renderManagedMarkdown(markdown, visibleRecords, rows);
+                const activationBytesAfter = activation ? loadedActivation.bytes.toString("utf8") : todoReconciliationActivationBytes(scan.retainedLegacyRows);
+                const activationAfter = activation ?? 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 }));
+                }
+                for (const { id } of transitionBatch.entries) {
+                    const reconciliation = reconciled.records.get(id).reconciliation;
+                    delete reconciliation.transition_batch;
+                }
+                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: publicRelative, before: publicExists ? markdownBefore : null, after: rendered });
+                const effectTargets = targets.filter((target) => target.before === null || !target.before.equals(Buffer.from(target.after))).sort((left, right) => Number(left.path === publicRelative) - Number(right.path === publicRelative) || left.path.localeCompare(right.path));
+                const effectSha256 = todoUpdateBatchEffectSha256(req.input, todoBinding.mappingSha256, effectTargets.map((target) => ({ path: target.path, before_sha256: target.before === null ? null : createHash("sha256").update(target.before).digest("hex"), after_sha256: createHash("sha256").update(target.after).digest("hex") })));
+                const response = { schemaVersion: "agentera.stateWrite.v1", command: `state todo ${verb}`, status: "pass", artifact: "todo", records: requestedRecords.map(({ id }) => ({ id, record: reconciled.records.get(id) })), operation: { verb, dry_run: req.dryRun, idempotent_replay: false }, validation: { status: "pass", violations: [] }, effect_sha256: effectSha256, apply_command: req.dryRun ? `agentera state todo ${verb} --input <same-input> --effect-sha256 ${effectSha256} --yes --format json` : null };
+                if (req.dryRun)
+                    return { ...response, reconciliation: { transaction_id: null, targets: targets.length, recovered } };
+                if (req.values.effect_sha256 !== effectSha256)
+                    reject({ class: "conflict", message: `TODO ${verb} batch effects changed after preview`, recovery: "Rerun the same batch input with --dry-run, review the new bounded effect, then use its exact effect SHA-256; no state was changed." });
+                for (const { id } of transitionBatch.entries) {
+                    const record = reconciled.records.get(id);
+                    record.reconciliation = { ...record.reconciliation, transition_batch: { verb, input_sha256: inputSha256, effect_sha256: effectSha256, post_state_sha256: todoTransitionBatchPostStateSha256(record) } };
+                    const target = targets.find(({ path }) => path.endsWith(`/${id}.yaml`));
+                    target.after = canonicalEntityEnvelopeBytes({ id, artifact: "todo", record });
+                }
+                const transaction = publishTodoReconciliation(context, sourceRoot, todoBinding, targets, { updateBatchEffectSha256: effectSha256, 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 ${verb} batch publication`, recovery: "Preserve the changed docs mapping and retry after every transaction target is restored; no mapping bytes were overwritten." }); } });
+                context.assertValid();
+                return { ...response, records: transitionBatch.entries.map(({ id }) => ({ id, record: reconciled.records.get(id) })), reconciliation: { transaction_id: transaction.id, targets: transaction.targetCount, recovered } };
+            }
+            if (batch) {
+                if (!req.dryRun && (!req.values.confirmed || !SHA256.test(String(req.values.effect_sha256 ?? ""))))
+                    reject({ class: "invalid_request", message: "todo update batch apply requires its preview effect SHA-256 and --yes", recovery: "Run the same batch input with --dry-run, review it, then repeat that input with the returned --effect-sha256 value and --yes; no state was changed." });
+                const requestedRecords = [];
+                for (const { id, patch } of batch) {
+                    selectedById(todoEntities, "todo", id);
+                    const record = mutationRecord({ ...req, input: patch, values: { id }, callerPayload: patch }, reconciled.records.get(id), todoEntities.map((entity) => ({ ...entity, record: reconciled.records.get(entity.id) })));
+                    reconciled.records.set(id, record);
+                    requestedRecords.push({ id, record });
+                }
+                const referenceEntities = [...reconciled.records].map(([todoId, record]) => ({ boundary: TODO.boundary, id: todoId, record }));
+                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, recovery: "Correct the batch patch and preview the complete batch again; no state was changed." });
+                    if (record.readiness !== undefined)
+                        assertTodoReferences(todoId, record, referenceEntities);
+                }
+                const visibleRecords = new Map([...reconciled.records].filter(([todoId]) => reconciled.visible.has(todoId)));
+                const rendered = renderManagedMarkdown(markdown, visibleRecords, rows);
+                const activationBytesAfter = activation ? loadedActivation.bytes.toString("utf8") : todoReconciliationActivationBytes(scan.retainedLegacyRows);
+                const activationAfter = activation ?? 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 }) }));
+                if (activating)
+                    targets.push({ path: TODO_RECONCILIATION_ACTIVATION_PATH, before: null, after: activationBytesAfter });
+                targets.push({ path: publicRelative, before: publicExists ? markdownBefore : null, after: rendered });
+                const effectTargets = targets.filter((target) => target.before === null || !target.before.equals(Buffer.from(target.after))).sort((left, right) => Number(left.path === publicRelative) - Number(right.path === publicRelative) || left.path.localeCompare(right.path));
+                const effectSha256 = todoUpdateBatchEffectSha256(req.input, todoBinding.mappingSha256, effectTargets.map((target) => ({ path: target.path, before_sha256: target.before === null ? null : createHash("sha256").update(target.before).digest("hex"), after_sha256: createHash("sha256").update(target.after).digest("hex") })));
+                const applyCommand = `agentera state todo update --input <same-input> --effect-sha256 ${effectSha256} --yes --format json`;
+                const response = { schemaVersion: "agentera.stateWrite.v1", command: "state todo update", status: "pass", artifact: "todo", records: requestedRecords.map(({ id }) => ({ id, record: reconciled.records.get(id) })), operation: { verb: "update", dry_run: req.dryRun, idempotent_replay: false }, validation: { status: "pass", violations: [] }, effect_sha256: effectSha256, apply_command: req.dryRun ? applyCommand : null };
+                if (req.dryRun)
+                    return { ...response, reconciliation: { transaction_id: null, targets: targets.length, recovered } };
+                if (req.values.effect_sha256 !== effectSha256)
+                    reject({ class: "conflict", message: "TODO update batch effects changed after preview", recovery: "Rerun the same batch input with --dry-run, review the new bounded effect, then use its exact effect SHA-256; no state was changed." });
+                const transaction = publishTodoReconciliation(context, sourceRoot, todoBinding, targets, { updateBatchEffectSha256: effectSha256, 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 batch publication", recovery: "Preserve the changed docs mapping and retry after every transaction target is restored; no mapping bytes were overwritten." }); } });
+                context.assertValid();
+                return { ...response, reconciliation: { transaction_id: transaction.id, targets: transaction.targetCount, recovered } };
+            }
             let id;
             let requested;
             let selected;

package/dist/state/todoReconciliationTransaction.js

@@ -3,10 +3,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { loadYamlMapping } from "../core/yaml.js";
 import { canonicalRecordJson } from "./archiveDiscovery.js";
-import { entityExactGetMaxBytes } from "./entityStorage.js";
+import { canonicalEntityEnvelopeBytes, 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 } from "./todoReconciliationActivation.js";
+import { todoUpdateBatchEffectSha256 } from "./todoUpdateBatch.js";
+import { todoCreateBatchEffectSha256 } from "./todoCreateBatch.js";
 import { reject } from "./write/errors.js";
 const VERSION = "agentera.todoReconciliationTransaction.v1";
 const DIRECTORY = ".agentera/.todo-reconciliation";
@@ -62,7 +64,7 @@ function createReceiptFromTargets(targets) {
     if (!created.length)
         return undefined;
     if (created.length !== 1)
-        invalidJournal("TODO reconciliation journal has multiple immutable TODO entity targets");
+        return undefined;
     const target = created[0];
     const createdId = path.posix.basename(target.path, ".yaml");
     let envelope;
@@ -99,7 +101,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 = ["schema_version", "id", "public_path", "mapping_sha256", "targets", ...(value.create === undefined ? [] : ["create"]), ...(value.activation_effect_sha256 === undefined ? [] : ["activation_effect_sha256"]), ...(value.owner_mapping_sha256 === undefined ? [] : ["owner_mapping_sha256"])].sort().join(",");
+    const expectedKeys = ["schema_version", "id", "public_path", "mapping_sha256", "targets", ...(value.create === undefined ? [] : ["create"]), ...(value.create_batch === undefined ? [] : ["create_batch"]), ...(value.activation_effect_sha256 === undefined ? [] : ["activation_effect_sha256"]), ...(value.owner_mapping_sha256 === undefined ? [] : ["owner_mapping_sha256"]), ...(value.update_batch_effect_sha256 === undefined ? [] : ["update_batch_effect_sha256"])].sort().join(",");
     if (Object.keys(value).sort().join(",") !== expectedKeys
         || value.schema_version !== VERSION
         || typeof value.id !== "string"
@@ -115,6 +117,10 @@ function parseJournal(bytes, fileName) {
         invalidJournal("TODO reconciliation journal has an invalid activation effect authorization");
     if (value.owner_mapping_sha256 !== undefined && !/^[a-f0-9]{64}$/.test(value.owner_mapping_sha256))
         invalidJournal("TODO reconciliation journal has an invalid owner-mapping authorization");
+    if (value.update_batch_effect_sha256 !== undefined && !/^[a-f0-9]{64}$/.test(value.update_batch_effect_sha256))
+        invalidJournal("TODO reconciliation journal has an invalid update-batch effect authorization");
+    if (value.create_batch !== undefined && (!value.create_batch || typeof value.create_batch !== "object" || Array.isArray(value.create_batch) || Object.keys(value.create_batch).sort().join(",") !== "effect_sha256,input_sha256,local_refs" || !/^[a-f0-9]{64}$/.test(value.create_batch.effect_sha256) || !/^[a-f0-9]{64}$/.test(value.create_batch.input_sha256) || !value.create_batch.local_refs || typeof value.create_batch.local_refs !== "object" || Array.isArray(value.create_batch.local_refs) || Object.entries(value.create_batch.local_refs).some(([ref, id]) => !/^[a-z][a-z0-9_-]{0,63}$/.test(ref) || typeof id !== "string" || !/^[a-z]{10}$/.test(id))))
+        invalidJournal("TODO reconciliation journal has an invalid create-batch receipt");
     if (value.create !== undefined && (!value.create
         || typeof value.create !== "object"
         || Array.isArray(value.create)
@@ -151,14 +157,14 @@ function parseJournal(bytes, fileName) {
         || 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 || value.activation_effect_sha256 || value.owner_mapping_sha256
-        ? { ...(value.create ? { create: value.create } : {}), ...(value.activation_effect_sha256 ? { activation_effect_sha256: value.activation_effect_sha256 } : {}), ...(value.owner_mapping_sha256 ? { owner_mapping_sha256: value.owner_mapping_sha256 } : {}), targets: body }
+    const identity = value.create || value.create_batch || value.activation_effect_sha256 || value.owner_mapping_sha256 || value.update_batch_effect_sha256
+        ? { ...(value.create ? { create: value.create } : {}), ...(value.create_batch ? { create_batch: value.create_batch } : {}), ...(value.activation_effect_sha256 ? { activation_effect_sha256: value.activation_effect_sha256 } : {}), ...(value.owner_mapping_sha256 ? { owner_mapping_sha256: value.owner_mapping_sha256 } : {}), ...(value.update_batch_effect_sha256 ? { update_batch_effect_sha256: value.update_batch_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");
     }
-    const create = value.create ?? inferredCreate;
+    const create = value.create ?? (value.create_batch ? undefined : inferredCreate);
     return { ...value, ...(create ? { create } : {}) };
 }
 function targetLimit(target, sourceRoot) {
@@ -446,6 +452,29 @@ export function recoverTodoReconciliation(context, sourceRoot, binding, options
         const journalBytes = fs.readFileSync(path.join(root, relative));
         const journal = parseJournal(journalBytes, name);
         assertBinding(journal, binding);
+        if (journal.update_batch_effect_sha256) {
+            const supplied = options.updateBatch;
+            const transition = supplied && /^agentera\.todo(?:SetSeverity|Resolve)Batch\.v1$/.test(String(supplied.input.schema_version));
+            const requestEffectSha256 = supplied ? todoUpdateBatchEffectSha256(supplied.input, journal.mapping_sha256, journal.targets.map((target) => ({
+                path: target.path,
+                before_sha256: target.before === null ? null : createHash("sha256").update(decode(target.before)).digest("hex"),
+                after_sha256: createHash("sha256").update(transition && target.path.includes("/todo_item/") ? (() => { const value = loadYamlMapping(decode(target.after).toString("utf8")); const record = value.record; if (record.reconciliation && typeof record.reconciliation === "object" && !Array.isArray(record.reconciliation))
+                    delete record.reconciliation.transition_batch; return canonicalEntityEnvelopeBytes({ id: String(value.id), artifact: "todo", record }); })() : decode(target.after)).digest("hex"),
+            }))) : null;
+            if (!supplied || supplied.effectSha256 !== journal.update_batch_effect_sha256 || requestEffectSha256 !== journal.update_batch_effect_sha256)
+                reject({
+                    class: "conflict",
+                    message: "pending TODO update batch does not match this request and effect authorization",
+                    recovery: "Retry the exact original TODO update batch input with its preview effect SHA-256 and --yes; no transaction target bytes were changed.",
+                });
+        }
+        if (journal.create_batch) {
+            const supplied = options.createBatch;
+            const requestInputSha256 = supplied ? createHash("sha256").update(canonicalRecordJson(supplied.input)).digest("hex") : null;
+            const requestEffectSha256 = supplied ? todoCreateBatchEffectSha256(supplied.input, journal.mapping_sha256, journal.create_batch.local_refs, journal.targets.filter((target) => !(target.before === null && /^\.agentera\/entities\/todo\/todo_item\/[a-z]{10}\.yaml$/.test(target.path))).map((target) => ({ path: target.path, before_sha256: target.before === null ? null : createHash("sha256").update(decode(target.before)).digest("hex"), after_sha256: createHash("sha256").update(decode(target.after)).digest("hex") }))) : null;
+            if (!supplied || supplied.effectSha256 !== journal.create_batch.effect_sha256 || requestInputSha256 !== journal.create_batch.input_sha256 || requestEffectSha256 !== journal.create_batch.effect_sha256)
+                reject({ class: "conflict", message: "pending TODO create batch does not match this request and effect authorization", recovery: "Retry the exact original TODO create batch input with its preview effect SHA-256 and --yes; no transaction target bytes were changed." });
+        }
         if (journal.create && options.createRequestSha256 !== journal.create.request_sha256)
             reject({
                 class: "conflict",
@@ -486,6 +515,8 @@ export function recoverTodoReconciliation(context, sourceRoot, binding, options
                 transaction_id: journal.id,
                 target_count: journal.targets.length,
                 ...(journal.create ? { create: journal.create } : {}),
+                ...(journal.update_batch_effect_sha256 ? { update_batch_effect_sha256: journal.update_batch_effect_sha256 } : {}),
+                ...(journal.create_batch ? { create_batch: journal.create_batch } : {}),
             });
         }
         catch (error) {
@@ -512,8 +543,8 @@ export function publishTodoReconciliation(context, sourceRoot, binding, targets,
         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." });
     if (options.ownerMappingSha256 && !options.activationEffectSha256)
         reject({ class: "schema_violation", message: "TODO owner-mapping authorization requires its effect authorization", recovery: "Recompute the complete owner correction target set from a fresh dry-run; no state was changed." });
-    const identity = options.create || options.activationEffectSha256 || options.ownerMappingSha256
-        ? { ...(options.create ? { create: options.create } : {}), ...(options.activationEffectSha256 ? { activation_effect_sha256: options.activationEffectSha256 } : {}), ...(options.ownerMappingSha256 ? { owner_mapping_sha256: options.ownerMappingSha256 } : {}), targets: body }
+    const identity = options.create || options.createBatch || options.activationEffectSha256 || options.ownerMappingSha256 || options.updateBatchEffectSha256
+        ? { ...(options.create ? { create: options.create } : {}), ...(options.createBatch ? { create_batch: options.createBatch } : {}), ...(options.activationEffectSha256 ? { activation_effect_sha256: options.activationEffectSha256 } : {}), ...(options.ownerMappingSha256 ? { owner_mapping_sha256: options.ownerMappingSha256 } : {}), ...(options.updateBatchEffectSha256 ? { update_batch_effect_sha256: options.updateBatchEffectSha256 } : {}), targets: body }
         : body;
     const id = createHash("sha256").update(canonicalRecordJson(identity)).digest("hex").slice(0, 24);
     if (!normalized.length)
@@ -544,8 +575,10 @@ export function publishTodoReconciliation(context, sourceRoot, binding, targets,
         public_path: binding.publicPath,
         mapping_sha256: binding.mappingSha256,
         ...(options.create ? { create: options.create } : {}),
+        ...(options.createBatch ? { create_batch: options.createBatch } : {}),
         ...(options.activationEffectSha256 ? { activation_effect_sha256: options.activationEffectSha256 } : {}),
         ...(options.ownerMappingSha256 ? { owner_mapping_sha256: options.ownerMappingSha256 } : {}),
+        ...(options.updateBatchEffectSha256 ? { update_batch_effect_sha256: options.updateBatchEffectSha256 } : {}),
         targets: body,
     };
     const bytes = `${JSON.stringify(journal)}\n`;

package/dist/state/todoTransitionBatch.js

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+import { reject } from "./write/errors.js";
+const ID = /^[a-z]{10}$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const SEVERITIES = new Set(["critical", "degraded", "normal", "annoying"]);
+export function todoTransitionBatchPostStateSha256(record) {
+    const value = structuredClone(record);
+    if (value.reconciliation && typeof value.reconciliation === "object" && !Array.isArray(value.reconciliation))
+        delete value.reconciliation.transition_batch;
+    return createHash("sha256").update(canonicalRecordJson(value)).digest("hex");
+}
+export function matchesTodoTransitionBatchPostState(record, receipt, entry, verb) {
+    const lifecycle = record.lifecycle && typeof record.lifecycle === "object" && !Array.isArray(record.lifecycle) ? record.lifecycle : null;
+    return receipt.post_state_sha256 === todoTransitionBatchPostStateSha256(record)
+        && lifecycle !== null
+        && canonicalRecordJson(lifecycle) === canonicalRecordJson({ operation: verb, reason: entry.reason, date: entry.date })
+        && (verb === "set-severity" ? record.severity === entry.severity : record.status === "resolved");
+}
+export function parseTodoTransitionBatch(input, verb) {
+    if (verb !== "set-severity" && verb !== "resolve")
+        return null;
+    const version = `agentera.todo${verb === "set-severity" ? "SetSeverity" : "Resolve"}Batch.v1`;
+    if (!input || input.schema_version !== version)
+        return null;
+    const member = verb === "set-severity" ? "transitions" : "resolutions";
+    const values = input[member];
+    const violations = [];
+    if (Object.keys(input).sort().join(",") !== ["schema_version", member].sort().join(",") || !Array.isArray(values))
+        violations.push(`batch envelope must contain exactly schema_version and ${member}`);
+    if (!Array.isArray(values) || values.length < 1 || values.length > 256)
+        violations.push(`${member} must contain 1 to 256 entries`);
+    const expected = verb === "set-severity" ? "date,id,reason,severity" : "date,id,reason";
+    const entries = (Array.isArray(values) ? values : []).map((value, index) => {
+        const item = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+        if (Object.keys(item).sort().join(",") !== expected)
+            violations.push(`${member}[${index}] must contain exactly ${expected.split(",").join(", ")}`);
+        const id = String(item.id ?? "");
+        const reason = String(item.reason ?? "").trim();
+        const date = String(item.date ?? "");
+        const severity = item.severity === undefined ? undefined : String(item.severity);
+        if (!ID.test(id))
+            violations.push(`${member}[${index}].id must be a bare ten-letter TODO ID`);
+        if (!reason || [...reason].length > 500)
+            violations.push(`${member}[${index}].reason must contain 1 to 500 code points`);
+        const timestamp = Date.parse(`${date}T00:00:00Z`);
+        if (!DATE.test(date) || Number.isNaN(timestamp) || new Date(timestamp).toISOString().slice(0, 10) !== date)
+            violations.push(`${member}[${index}].date must be a valid YYYY-MM-DD date`);
+        if (verb === "set-severity" && !SEVERITIES.has(severity ?? ""))
+            violations.push(`${member}[${index}].severity is invalid`);
+        return { id, reason, date, ...(severity === undefined ? {} : { severity }) };
+    });
+    const seen = new Set();
+    for (const { id } of entries) {
+        if (id && seen.has(id))
+            violations.push(`duplicate ${verb} target '${id}'`);
+        seen.add(id);
+    }
+    if (violations.length)
+        reject({ class: "schema_violation", message: `todo ${verb} batch input is invalid`, violations, recovery: `Correct the strict ${version} envelope, then preview it again; no state was changed.` });
+    return { verb, entries };
+}
+export function todoTransitionBatchEffectSha256(input, mappingSha256, targets) {
+    return createHash("sha256").update(canonicalRecordJson({ input, mapping_sha256: mappingSha256, targets })).digest("hex");
+}

package/dist/state/todoUpdateBatch.js

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+import { todoInputViolations } from "./todoDocsEntityValidation.js";
+import { reject } from "./write/errors.js";
+export const TODO_UPDATE_BATCH_VERSION = "agentera.todoUpdateBatch.v1";
+const ID = /^[a-z]{10}$/;
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function inspectTodoUpdateBatch(input) {
+    if (!input || input.schema_version !== TODO_UPDATE_BATCH_VERSION)
+        return null;
+    const strictEnvelope = Object.keys(input).sort().join(",") === "schema_version,updates" && Array.isArray(input.updates);
+    const violations = [];
+    if (Object.keys(input).sort().join(",") !== "schema_version,updates")
+        violations.push("batch envelope must contain exactly schema_version and updates");
+    if (!Array.isArray(input.updates) || input.updates.length < 1 || input.updates.length > 256)
+        violations.push("updates must contain 1 to 256 entries");
+    const updates = (Array.isArray(input.updates) ? input.updates : []).map((value, index) => {
+        if (!mapping(value) || Object.keys(value).sort().join(",") !== "id,patch" || !ID.test(String(value.id ?? "")) || !mapping(value.patch)) {
+            violations.push(`updates[${index}] must contain exactly one bare id and one patch mapping`);
+            return { id: "", patch: {} };
+        }
+        violations.push(...todoInputViolations(value.patch, "update").map((item) => `updates[${index}].patch: ${item}`));
+        return { id: String(value.id), patch: value.patch };
+    });
+    const seen = new Set();
+    for (const { id } of updates) {
+        if (id && seen.has(id))
+            violations.push(`duplicate update target '${id}'`);
+        seen.add(id);
+    }
+    return { strictEnvelope, updates, violations };
+}
+export function parseTodoUpdateBatch(input) {
+    const inspected = inspectTodoUpdateBatch(input);
+    if (!inspected)
+        return null;
+    if (inspected.violations.length)
+        reject({ class: "schema_violation", message: "todo update batch input is invalid", violations: inspected.violations, recovery: "Correct the strict agentera.todoUpdateBatch.v1 envelope, then preview it again; no state was changed." });
+    return inspected.updates;
+}
+export function todoUpdateBatchEffectSha256(input, mappingSha256, targets) {
+    return createHash("sha256").update(canonicalRecordJson({
+        schema_version: TODO_UPDATE_BATCH_VERSION,
+        input,
+        mapping_sha256: mappingSha256,
+        targets,
+    })).digest("hex");
+}

package/dist/state/write/explain.js

@@ -300,14 +300,17 @@ function decisionsGuidance(artifact, verb, _entityHealth = false, entityArtifact
         return ["a bare ten-letter objective ID is assigned by the CLI; do not pass an identity", ...base];
     if (entityArtifact && artifact === "todo" && verb === "update")
         return [
-            "select one TODO item with its bare ten-letter --id; numeric, prefixed, composite, alias, and path identities are unavailable",
-            "the input document is a patch: omitted fields preserve state and only target_version, requirements, acceptance, and readiness accept typed clears",
+            "for a singleton, select one TODO item with its bare ten-letter --id; numeric, prefixed, composite, alias, and path identities are unavailable",
+            "for a singleton, the input document is a patch: omitted fields preserve state and only target_version, requirements, acceptance, and readiness accept typed clears",
+            "for a batch, omit --id and supply one strict agentera.todoUpdateBatch.v1 envelope; preview it with --dry-run before exact confirmed apply",
             "public fields are TODO.md-owned; readiness, dependencies, gates, and evidence are Agentera-owned",
             ...base,
         ];
     if (entityArtifact && artifact === "todo" && ["set-severity", "supersede", "resolve", "reopen"].includes(verb))
         return [
-            "select one TODO item with its bare ten-letter --id; lifecycle transitions are flag-only and accept no --input record",
+            ["set-severity", "resolve"].includes(verb)
+                ? `for a singleton, select one TODO item with its bare ten-letter --id and use only flags; for a batch, omit --id and supply the strict ${verb === "set-severity" ? "agentera.todoSetSeverityBatch.v1" : "agentera.todoResolveBatch.v1"} envelope through --input`
+                : "select one TODO item with its bare ten-letter --id; lifecycle transitions are flag-only and accept no --input record",
             "supply a reason and YYYY-MM-DD date; supersede additionally requires a distinct existing replacement ID",
             ...base,
         ];

package/dist/state/write/runtimeOperations.js

@@ -51,11 +51,11 @@ const RUNTIME_OPERATION_CORES = [
     op("todo", "activate", [f("--effect-sha256", "effect_sha256", "string"), f("--yes", "confirmed", "boolean")], { ownedFields: ["reconciliation", "public_document", "activation"], compacts: true }),
     op("todo", "repair", [f("--effect-sha256", "effect_sha256", "string"), f("--yes", "confirmed", "boolean")], { ownedFields: ["reconciliation", "public_document", "activation"], compacts: true }),
     op("todo", "correct-owners", [f("--effect-sha256", "effect_sha256", "string"), f("--yes", "confirmed", "boolean")], { ownedFields: ["reconciliation", "public_document", "activation"], inputMode: "structured", inputRoot: "one unsafe TODO owner mapping", inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], inputMaxBytes: 32768, compacts: true }),
-    op("todo", "create", [], { ownedFields: ["id", "artifact", "status", "public_order", "lifecycle"], inputMode: "structured", inputRoot: "full typed TODO record", inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], cliOwnedFields: ["id", "artifact", "status", "public_order", "lifecycle"], inputMaxBytes: 32768 }),
-    op("todo", "update", [f("--id", "id", "string", { required: true })], { selectors: ["--id"], ownedFields: ["id", "artifact", "status", "public_order", "lifecycle"], inputMode: "structured", inputRoot: "TODO record patch", inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], cliOwnedFields: ["id", "artifact", "status", "public_order", "lifecycle"], inputMaxBytes: 32768 }),
-    op("todo", "set-severity", [f("--id", "id", "string", { required: true }), f("--severity", "severity", "string", { required: true, validValues: ["critical", "degraded", "normal", "annoying"] }), f("--reason", "lifecycle.reason", "string", { required: true }), f("--date", "lifecycle.date", "date", { required: true })], { selectors: ["--id"], ownedFields: ["id", "artifact", "severity", "lifecycle"] }),
+    op("todo", "create", [f("--effect-sha256", "effect_sha256", "string"), f("--yes", "confirmed", "boolean")], { ownedFields: ["id", "artifact", "status", "public_order", "lifecycle"], inputMode: "structured", inputRoot: "full typed TODO record or agentera.todoCreateBatch.v1 envelope", inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], cliOwnedFields: ["id", "artifact", "status", "public_order", "lifecycle"], inputMaxBytes: 32768 }),
+    op("todo", "update", [f("--id", "id", "string", { required: true }), f("--effect-sha256", "effect_sha256", "string"), f("--yes", "confirmed", "boolean")], { selectors: ["--id"], ownedFields: ["id", "artifact", "status", "public_order", "lifecycle"], inputMode: "structured", inputRoot: "TODO record patch or agentera.todoUpdateBatch.v1 envelope", inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], cliOwnedFields: ["id", "artifact", "status", "public_order", "lifecycle"], inputMaxBytes: 32768 }),
+    op("todo", "set-severity", [f("--id", "id", "string", { required: true }), f("--severity", "severity", "string", { required: true, validValues: ["critical", "degraded", "normal", "annoying"] }), f("--reason", "lifecycle.reason", "string", { required: true }), f("--date", "lifecycle.date", "date", { required: true }), f("--effect-sha256", "effect_sha256", "string"), f("--yes", "confirmed", "boolean")], { selectors: ["--id"], ownedFields: ["id", "artifact", "severity", "lifecycle"], inputMode: "structured", inputRoot: "agentera.todoSetSeverityBatch.v1 envelope", inputOptional: true, inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], inputMaxBytes: 32768 }),
     op("todo", "supersede", [f("--id", "id", "string", { required: true }), f("--replacement", "lifecycle.replacement", "string", { required: true }), f("--reason", "lifecycle.reason", "string", { required: true }), f("--date", "lifecycle.date", "date", { required: true })], { selectors: ["--id"], ownedFields: ["id", "artifact", "status", "lifecycle"] }),
-    op("todo", "resolve", [f("--id", "id", "string", { required: true }), f("--reason", "lifecycle.reason", "string", { required: true }), f("--date", "lifecycle.date", "date", { required: true })], { selectors: ["--id"], ownedFields: ["id", "artifact", "status", "lifecycle"] }),
+    op("todo", "resolve", [f("--id", "id", "string", { required: true }), f("--reason", "lifecycle.reason", "string", { required: true }), f("--date", "lifecycle.date", "date", { required: true }), f("--effect-sha256", "effect_sha256", "string"), f("--yes", "confirmed", "boolean")], { selectors: ["--id"], ownedFields: ["id", "artifact", "status", "lifecycle"], inputMode: "structured", inputRoot: "agentera.todoResolveBatch.v1 envelope", inputOptional: true, inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], inputMaxBytes: 32768 }),
     op("todo", "reopen", [f("--id", "id", "string", { required: true }), f("--reason", "lifecycle.reason", "string", { required: true }), f("--date", "lifecycle.date", "date", { required: true })], { selectors: ["--id"], ownedFields: ["id", "artifact", "status", "lifecycle"] }),
     op("docs", "create", [], { ownedFields: ["id", "artifact"], inputMode: "structured", inputRoot: "one documentation inventory entry", inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], cliOwnedFields: ["id", "artifact"], inputMaxBytes: 32768 }),
     op("docs", "update", [f("--id", "id", "string", { required: true })], { selectors: ["--id"], ownedFields: ["id", "artifact"], inputMode: "structured", inputRoot: "one documentation inventory entry", inputSources: ["file", "stdin"], structuredInputSources: ["file", "stdin"], cliOwnedFields: ["id", "artifact"], inputMaxBytes: 32768 }),
@@ -99,11 +99,11 @@ const RUNTIME_OPERATION_PROJECTIONS = {
     "todo.activate": projection("Preview and review every reported safe activation effect before explicit confirmed apply; unsafe inactive evidence requires the separate effect-bound owner-correction operation.", developmentCommand("state todo activate --dry-run --format json"), developmentCommand("state todo activate --effect-sha256 EFFECT_SHA256 --yes --format json")),
     "todo.repair": projection("Preview and review every diagnosed repair decision before explicit confirmed apply; ambiguous evidence is rejected without effects.", developmentCommand("state todo repair --dry-run --format json"), developmentCommand("state todo repair --effect-sha256 EFFECT_SHA256 --yes --format json")),
     "todo.correct-owners": projection("Supply one complete id/source_line owner mapping, preview its bounded effect, then apply only the exact returned effect; malformed, ambiguous, unmatched, or stale evidence is rejected without effects.", developmentCommand("state todo correct-owners --input owner-mapping.yaml --dry-run --format json"), developmentCommand("state todo correct-owners --input owner-mapping.yaml --effect-sha256 EFFECT_SHA256 --yes --format json")),
-    "todo.create": projection(`Run ${developmentCommand("state todo explain --verb create --format json")}, remove CLI-owned fields, provide the full typed TODO record, and retry.`, developmentCommand("state todo create --input todo.yaml --format json")),
-    "todo.update": projection("Reread the TODO item, use its bare ID, supply only typed patch fields, and use null or an empty list only for declared clearable fields.", developmentCommand("state todo update --id qjtrmnpvka --input todo-patch.yaml --format json")),
-    "todo.set-severity": projection("Use the bare TODO ID, one immediate-impact severity, a reason, and a YYYY-MM-DD date; no record input is accepted.", developmentCommand('state todo set-severity --id qjtrmnpvka --severity degraded --reason "Impact changed" --date 2026-07-31 --format json')),
+    "todo.create": projection("For one item, preserve the existing full-record form. For a batch, supply agentera.todoCreateBatch.v1, preview with --dry-run, then repeat the same input with its effect SHA-256 and --yes.", developmentCommand("state todo create --input todo.yaml --format json")),
+    "todo.update": projection("For one item, preserve the existing --id and patch form. For a batch, supply agentera.todoUpdateBatch.v1, preview with --dry-run, then repeat the same input with its effect SHA-256 and --yes.", developmentCommand("state todo update --id qjtrmnpvka --input todo-patch.yaml --format json")),
+    "todo.set-severity": projection("Use singleton flags unchanged, or supply agentera.todoSetSeverityBatch.v1 through --input, preview it, then exact-apply it with the effect SHA-256 and --yes.", developmentCommand('state todo set-severity --id qjtrmnpvka --severity degraded --reason "Impact changed" --date 2026-07-31 --format json')),
     "todo.supersede": projection("Use the selected bare TODO ID, an existing distinct replacement ID, a reason, and a YYYY-MM-DD date; no record input is accepted.", developmentCommand('state todo supersede --id qjtrmnpvka --replacement zqtrmnpvka --reason "Replaced by narrower work" --date 2026-07-31 --format json')),
-    "todo.resolve": projection("Use the bare TODO ID, a reason, and a YYYY-MM-DD date; no record input is accepted.", developmentCommand('state todo resolve --id qjtrmnpvka --reason "Shipped" --date 2026-07-31 --format json')),
+    "todo.resolve": projection("Use singleton flags unchanged, or supply agentera.todoResolveBatch.v1 through --input, preview it, then exact-apply it with the effect SHA-256 and --yes.", developmentCommand('state todo resolve --id qjtrmnpvka --reason "Shipped" --date 2026-07-31 --format json')),
     "todo.reopen": projection("Use the bare resolved TODO ID, a reason, and a YYYY-MM-DD date; no record input is accepted.", developmentCommand('state todo reopen --id qjtrmnpvka --reason "Scope returned" --date 2026-07-31 --format json')),
     "docs.create": projection("Remove id and artifact from the input and retry with one schema-valid documentation inventory entry.", developmentCommand("state docs create --input documentation.yaml --format json")),
     "docs.update": projection("Reread the documentation entry, copy its bare ID to --id, remove CLI-owned fields, and retry.", developmentCommand("state docs update --id qjtrmnpvka --input documentation.yaml --format json")),