agentera 3.0.0-dev.8 → 3.0.0-dev.81

package/dist/state/planIdentity.js

@@ -0,0 +1,47 @@
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+import { deriveLegacyPlanIdentity } from "./retrievalAuthority.js";
+// These identities are accepted only while reading legacy aggregate plan
+// sources. Canonical entity plans use the bare envelope ID assigned by the
+// writer; neither composite form is a public selector.
+export const PERSISTED_PLAN_ID = /^plan:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+export const LEGACY_PLAN_ID = /^legacy-plan:[0-9a-f]{64}$/;
+export const PLAN_ID = /^(plan:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|legacy-plan:[0-9a-f]{64})$/;
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function normalizeStatus(value) {
+    if (value === "active")
+        return "open";
+    if (value === "completed")
+        return "complete";
+    return value;
+}
+/** Canonical read-compatible plan shape used only for identity comparison and legacy derivation. */
+export function canonicalPlanIdentityDocument(document) {
+    const normalized = structuredClone(document);
+    const header = mapping(normalized.header);
+    normalized.header = header.status === undefined
+        ? { ...header }
+        : { ...header, status: normalizeStatus(header.status) };
+    if (Array.isArray(normalized.entries)) {
+        normalized.tasks = normalized.entries;
+        delete normalized.entries;
+    }
+    return normalized;
+}
+export function resolvePlanIdentity(document) {
+    const canonicalDocument = canonicalPlanIdentityDocument(document);
+    const persisted = mapping(canonicalDocument.header).id;
+    const canonicalJson = canonicalRecordJson(canonicalDocument);
+    if (persisted !== undefined) {
+        if (typeof persisted !== "string" || !PERSISTED_PLAN_ID.test(persisted)) {
+            throw new Error("legacy plan header.id is not a valid migration-only identity");
+        }
+        return { stableId: persisted, persisted: true, canonicalJson };
+    }
+    return {
+        stableId: deriveLegacyPlanIdentity(canonicalJson),
+        persisted: false,
+        canonicalJson,
+    };
+}

package/dist/state/planLineageValidation.js

@@ -0,0 +1,52 @@
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function planStatus(plan) {
+    const header = plan.record?.header;
+    return mapping(header) ? header.status : undefined;
+}
+export function planLineageIssues(plans, recovery) {
+    const plansById = new Map(plans.map((plan) => [plan.id, plan]));
+    const successorsByPredecessor = new Map();
+    const issues = [];
+    for (const successor of plans) {
+        const predecessorId = successor.record?.previous_plan_archived;
+        if (typeof predecessorId !== "string")
+            continue;
+        const predecessor = plansById.get(predecessorId);
+        if (predecessorId === successor.id || (predecessor && planStatus(predecessor) !== "archived")) {
+            issues.push({
+                code: "unresolved_relation",
+                path: successor.relativePath,
+                id: successor.id,
+                artifact: successor.artifact ?? undefined,
+                boundary: successor.boundary ?? undefined,
+                relation: "previous_plan_archived",
+                targetId: predecessorId,
+                message: predecessorId === successor.id
+                    ? `plan '${successor.id}' cannot name itself as its archived predecessor`
+                    : `plan '${successor.id}' predecessor '${predecessorId}' must be archived`,
+                recovery: recovery(`set record.previous_plan_archived in '${successor.relativePath}' to one distinct archived plan ID, or remove the writer-owned field from invalid state`),
+            });
+        }
+        successorsByPredecessor.set(predecessorId, [...(successorsByPredecessor.get(predecessorId) ?? []), successor]);
+    }
+    for (const [predecessorId, successors] of successorsByPredecessor) {
+        if (successors.length < 2)
+            continue;
+        for (const successor of successors) {
+            issues.push({
+                code: "conflicting_ownership",
+                path: successor.relativePath,
+                id: successor.id,
+                artifact: successor.artifact ?? undefined,
+                boundary: successor.boundary ?? undefined,
+                relation: "previous_plan_archived",
+                targetId: predecessorId,
+                message: `archived predecessor '${predecessorId}' has multiple successor plan records: ${successors.map((candidate) => candidate.id).sort().join(", ")}`,
+                recovery: recovery(`retain record.previous_plan_archived on only one canonical successor of archived plan '${predecessorId}'`),
+            });
+        }
+    }
+    return issues;
+}

package/dist/state/planReplacementTransaction.js

@@ -0,0 +1,475 @@
+import { createHash } from "node:crypto";
+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 { FILE_REPLACEMENT_METADATA_NAME, FILE_REPLACEMENT_RECOVERY_VERSION, validateEntityRecoveryDirectory, } from "./entityPublicationContext.js";
+import { reject } from "./write/errors.js";
+const VERSION = "agentera.planReplacementTransaction.v1";
+const DIRECTORY = ".agentera/.entity-recovery/plan-replacement";
+const MAX_JOURNAL_BYTES = 4 * 1024 * 1024;
+const MAX_TARGET_BYTES = 1024 * 1024;
+const MAX_TARGETS = 102;
+const ID = /^[a-z]{10}$/;
+const TARGET = /^\.agentera\/entities\/plan\/(?:plan|plan_task)\/[a-z]{10}\.yaml$/;
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function encode(value) {
+    return Buffer.from(value).toString("base64");
+}
+function decode(value) {
+    return Buffer.from(value, "base64");
+}
+function exactBase64(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        return encode(decode(value)) === value;
+    }
+    catch {
+        return false;
+    }
+}
+function same(left, right) {
+    return left === null ? right === null : right !== null && left.equals(right);
+}
+function journalPath(id) {
+    return `${DIRECTORY}/${id}.json`;
+}
+function invalid(message) {
+    throw new Error(`plan replacement journal ${message}`);
+}
+function conflict(message) {
+    reject({
+        class: "conflict",
+        message,
+        recovery: "Preserve the pending plan replacement journal, canonical target bytes, and retained recovery roles. Retry only the exact original state plan replace request after reconciling any reported concurrent bytes; no competing bytes were overwritten.",
+    });
+}
+function targetPath(boundary, id) {
+    return `.agentera/entities/plan/${boundary}/${id}.yaml`;
+}
+function parseEnvelope(bytes, label) {
+    try {
+        const value = loadYamlMapping(bytes.toString("utf8"));
+        if (!mapping(value))
+            throw new Error("not a mapping");
+        return value;
+    }
+    catch {
+        invalid(`${label} is not a valid canonical entity envelope`);
+    }
+}
+function parseJournal(bytes, fileName) {
+    if (bytes.length > MAX_JOURNAL_BYTES)
+        invalid("exceeds its byte bound");
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        invalid("is not valid bounded UTF-8 JSON");
+    }
+    if (!mapping(parsed))
+        invalid("is not a mapping");
+    const value = parsed;
+    if (Object.keys(value).sort().join(",") !== "id,operation,schema_version,targets"
+        || value.schema_version !== VERSION
+        || typeof value.id !== "string"
+        || !/^[a-f0-9]{24}$/.test(value.id)
+        || !mapping(value.operation)
+        || !Array.isArray(value.targets)
+        || value.targets.length < 2
+        || value.targets.length > MAX_TARGETS)
+        invalid("is malformed");
+    const operation = value.operation;
+    if (Object.keys(operation).sort().join(",") !== "input_sha256,kind,predecessor,successor"
+        || !["existing", "create"].includes(String(operation.kind))
+        || typeof operation.predecessor !== "string"
+        || typeof operation.successor !== "string"
+        || !ID.test(operation.predecessor)
+        || !ID.test(operation.successor)
+        || operation.predecessor === operation.successor
+        || typeof operation.input_sha256 !== "string"
+        || !/^[a-f0-9]{64}$/.test(operation.input_sha256))
+        invalid("has an invalid operation identity");
+    const paths = new Set();
+    for (const target of value.targets) {
+        if (!mapping(target)
+            || Object.keys(target).sort().join(",") !== "after,before,path"
+            || typeof target.path !== "string"
+            || !TARGET.test(target.path)
+            || paths.has(target.path)
+            || (target.before !== null && !exactBase64(target.before))
+            || !exactBase64(target.after)
+            || decode(target.after).length > MAX_TARGET_BYTES
+            || (target.before !== null && decode(target.before).length > MAX_TARGET_BYTES))
+            invalid("has an invalid target");
+        paths.add(target.path);
+    }
+    const body = value.targets;
+    const identity = { operation, targets: body };
+    const expectedId = sha256(canonicalRecordJson(identity)).slice(0, 24);
+    if (value.id !== expectedId || (fileName !== undefined && fileName !== `${value.id}.json`)) {
+        invalid("identity does not match its operation and complete target set");
+    }
+    const predecessor = body.find((target) => target.path === targetPath("plan", operation.predecessor));
+    const successor = body.find((target) => target.path === targetPath("plan", operation.successor));
+    if (!predecessor || predecessor.before === null || !successor)
+        invalid("does not include both canonical plan targets");
+    if (operation.kind === "create" && successor.before !== null)
+        invalid("create target has a predecessor byte baseline");
+    if (operation.kind === "existing" && successor.before === null)
+        invalid("existing successor target lacks a byte baseline");
+    const predecessorEnvelope = parseEnvelope(decode(predecessor.after), "predecessor after target");
+    const successorEnvelope = parseEnvelope(decode(successor.after), "successor after target");
+    const predecessorHeader = mapping(predecessorEnvelope.record?.header)
+        ? predecessorEnvelope.record.header
+        : {};
+    const successorRecord = mapping(successorEnvelope.record) ? successorEnvelope.record : {};
+    if (predecessorEnvelope.id !== operation.predecessor
+        || predecessorEnvelope.artifact !== "plan"
+        || predecessorHeader.status !== "archived"
+        || successorEnvelope.id !== operation.successor
+        || successorEnvelope.artifact !== "plan"
+        || successorRecord.previous_plan_archived !== operation.predecessor
+        || successorRecord.replacement_input_sha256 !== operation.input_sha256)
+        invalid("does not encode the declared predecessor archive and immutable successor identity");
+    const taskTargets = body.filter((target) => target.path.includes("/plan_task/"));
+    if (operation.kind === "existing" && taskTargets.length)
+        invalid("existing-successor operation includes unexpected task targets");
+    if (operation.kind === "create") {
+        for (const target of taskTargets) {
+            if (target.before !== null)
+                invalid("create task target has a predecessor byte baseline");
+            const envelope = parseEnvelope(decode(target.after), "created task after target");
+            if (!mapping(envelope.record) || envelope.artifact !== "plan" || envelope.record.plan !== operation.successor) {
+                invalid("created task target does not belong to the declared successor");
+            }
+        }
+    }
+    return { schema_version: VERSION, id: value.id, operation: operation, targets: body };
+}
+function readJournal(root, name) {
+    const file = path.join(root, DIRECTORY, name);
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_JOURNAL_BYTES)
+        invalid("file is not a safe bounded regular file");
+    return parseJournal(fs.readFileSync(file), name);
+}
+function pendingJournalNames(root) {
+    const directory = path.join(root, DIRECTORY);
+    if (!fs.existsSync(directory))
+        return [];
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        invalid("directory is not a safe real directory");
+    const names = fs.readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.name.endsWith(".json"))
+        .map((entry) => {
+        if (!entry.isFile() || entry.isSymbolicLink())
+            invalid("directory contains an unsafe journal entry");
+        return entry.name;
+    })
+        .sort();
+    if (names.length > 1)
+        invalid("has multiple pending operations");
+    return names;
+}
+export function inspectPendingPlanReplacement(root) {
+    const name = pendingJournalNames(root)[0];
+    if (!name)
+        return null;
+    const journal = readJournal(root, name);
+    return {
+        predecessor: journal.operation.predecessor,
+        successor: journal.operation.successor,
+        kind: journal.operation.kind,
+        inputSha256: journal.operation.input_sha256,
+        targetCount: journal.targets.length,
+    };
+}
+function assertExactRetry(journal, retry) {
+    const operation = journal.operation;
+    const matches = operation.predecessor === retry.predecessor
+        && (operation.kind === "existing"
+            ? retry.successor === operation.successor && retry.inputSha256 === undefined
+            : retry.successor === undefined && retry.inputSha256 === operation.input_sha256);
+    if (!matches) {
+        conflict(operation.kind === "existing"
+            ? `pending plan replacement for predecessor '${operation.predecessor}' requires successor '${operation.successor}', not this request`
+            : `pending plan replacement for predecessor '${operation.predecessor}' requires the exact original successor input`);
+    }
+}
+function bytesAt(root, relative) {
+    const file = path.join(root, relative);
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error("is not a safe regular file");
+        return fs.readFileSync(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw new Error(`plan replacement target '${relative}' ${error.message}`);
+    }
+}
+function fsyncDirectory(directory) {
+    if (process.platform === "win32")
+        return;
+    const descriptor = fs.openSync(directory, "r");
+    try {
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function parseFileRecoveryMetadata(file) {
+    let parsed;
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024)
+            throw new Error("is unsafe or over bound");
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(fs.readFileSync(file)));
+    }
+    catch {
+        conflict(`plan replacement retained recovery metadata '${file}' is invalid`);
+    }
+    if (!mapping(parsed))
+        conflict(`plan replacement retained recovery metadata '${file}' is not a mapping`);
+    const value = parsed;
+    if (Object.keys(value).sort().join(",") !== "after_sha256,before_sha256,schema_version,target_path"
+        || value.schema_version !== FILE_REPLACEMENT_RECOVERY_VERSION
+        || typeof value.target_path !== "string"
+        || typeof value.before_sha256 !== "string"
+        || typeof value.after_sha256 !== "string"
+        || !/^[a-f0-9]{64}$/.test(value.before_sha256)
+        || !/^[a-f0-9]{64}$/.test(value.after_sha256))
+        conflict(`plan replacement retained recovery metadata '${file}' has an invalid canonical record`);
+    return value;
+}
+function roleBytes(file, label) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        conflict(`plan replacement ${label} '${file}' is unsafe`);
+    return fs.readFileSync(file);
+}
+function removeExactRole(file, expected) {
+    if (!roleBytes(file, "recovery role").equals(expected))
+        conflict(`plan replacement recovery role '${file}' changed`);
+    fs.unlinkSync(file);
+}
+function recoverImmutableStage(root, target) {
+    if (target.before !== null)
+        return;
+    const absolute = path.join(root, target.path);
+    const directory = path.dirname(absolute);
+    if (!fs.existsSync(directory))
+        return;
+    const name = path.basename(absolute);
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`^\\.${escaped}\\.\\d+\\.[a-f0-9-]+\\.tmp$`);
+    const stages = fs.readdirSync(directory).filter((candidate) => pattern.test(candidate));
+    if (stages.length > 1)
+        conflict(`plan replacement target '${target.path}' has multiple retained immutable publication stages`);
+    if (!stages.length)
+        return;
+    const stage = path.join(directory, stages[0]);
+    const after = decode(target.after);
+    if (!roleBytes(stage, "immutable publication stage").equals(after)) {
+        conflict(`plan replacement target '${target.path}' retained immutable publication stage changed`);
+    }
+    const current = bytesAt(root, target.path);
+    if (current !== null && !current.equals(after)) {
+        conflict(`plan replacement target '${target.path}' has concurrent canonical bytes beside its immutable publication stage`);
+    }
+    removeExactRole(stage, after);
+    fsyncDirectory(directory);
+}
+function recoverReplacementRoles(context, target) {
+    if (target.before === null)
+        return;
+    const root = context.pinnedPath();
+    const recoveryRoot = path.join(root, ".agentera/.entity-recovery");
+    if (!fs.existsSync(recoveryRoot))
+        return;
+    const targetDirectory = path.dirname(context.pinnedPath(target.path));
+    const recoveryRootIdentity = validateEntityRecoveryDirectory(context.validatedRoot, recoveryRoot, targetDirectory, "private entity recovery root '.agentera/.entity-recovery'");
+    const entries = fs.readdirSync(recoveryRoot, { withFileTypes: true });
+    if (entries.length > 128)
+        conflict("private entity recovery root exceeds its bounded entry count");
+    const before = decode(target.before);
+    const after = decode(target.after);
+    const matches = [];
+    for (const entry of entries) {
+        if (entry.name === ".gitignore" || entry.name === "plan-replacement")
+            continue;
+        const directory = path.join(recoveryRoot, entry.name);
+        const identity = validateEntityRecoveryDirectory(context.validatedRoot, directory, targetDirectory, `private entity recovery attempt '${path.relative(root, directory).split(path.sep).join("/")}'`);
+        const metadata = path.join(directory, FILE_REPLACEMENT_METADATA_NAME);
+        if (!fs.existsSync(metadata))
+            continue;
+        const value = parseFileRecoveryMetadata(metadata);
+        if (value.target_path !== target.path)
+            continue;
+        if (value.before_sha256 !== sha256(before) || value.after_sha256 !== sha256(after)) {
+            conflict(`plan replacement target '${target.path}' retained recovery role digests do not match its pending journal`);
+        }
+        const names = fs.readdirSync(directory).sort();
+        if (names.some((name) => !["original.previous", "replacement.tmp", FILE_REPLACEMENT_METADATA_NAME].includes(name))) {
+            conflict(`plan replacement target '${target.path}' retained recovery attempt contains an unknown role`);
+        }
+        const previous = path.join(directory, "original.previous");
+        const stage = path.join(directory, "replacement.tmp");
+        if (fs.existsSync(previous) && !roleBytes(previous, "prior-byte role").equals(before)) {
+            conflict(`plan replacement target '${target.path}' retained prior-byte role changed`);
+        }
+        if (fs.existsSync(stage) && !roleBytes(stage, "replacement stage").equals(after)) {
+            conflict(`plan replacement target '${target.path}' retained replacement stage changed`);
+        }
+        matches.push({ directory, identity, metadata, ...(fs.existsSync(previous) ? { previous } : {}), ...(fs.existsSync(stage) ? { stage } : {}) });
+    }
+    if (matches.length > 1)
+        conflict(`plan replacement target '${target.path}' has multiple retained recovery attempts`);
+    const match = matches[0];
+    if (!match)
+        return;
+    const current = bytesAt(root, target.path);
+    if (!same(current, before) && !same(current, after)) {
+        conflict(`plan replacement target '${target.path}' has concurrent canonical bytes beside retained recovery roles`);
+    }
+    validateEntityRecoveryDirectory(context.validatedRoot, recoveryRoot, targetDirectory, "private entity recovery root '.agentera/.entity-recovery'", recoveryRootIdentity);
+    validateEntityRecoveryDirectory(context.validatedRoot, match.directory, targetDirectory, `private entity recovery attempt '${path.relative(root, match.directory).split(path.sep).join("/")}'`, match.identity);
+    if (match.stage)
+        removeExactRole(match.stage, after);
+    if (match.previous)
+        removeExactRole(match.previous, before);
+    removeExactRole(match.metadata, roleBytes(match.metadata, "replacement metadata"));
+    fs.rmdirSync(match.directory);
+    fsyncDirectory(recoveryRoot);
+}
+function applyTarget(context, sourceRoot, target) {
+    const root = context.pinnedPath();
+    recoverImmutableStage(root, target);
+    recoverReplacementRoles(context, target);
+    const before = target.before === null ? null : decode(target.before);
+    const after = decode(target.after);
+    const current = bytesAt(root, target.path);
+    if (same(current, after))
+        return null;
+    if (!same(current, before)) {
+        conflict(`plan replacement target '${target.path}' changed after journal preparation`);
+    }
+    if (before === null) {
+        const identity = context.publishImmutable(target.path, after.toString("utf8"));
+        if (!identity)
+            conflict(`plan replacement target '${target.path}' appeared during publication`);
+        return identity;
+    }
+    return context.replaceExisting(target.path, before, after.toString("utf8"), entityExactGetMaxBytes(sourceRoot)).publishedIdentity;
+}
+function rollback(context, sourceRoot, applied) {
+    const failures = [];
+    for (const { target, identity } of [...applied].reverse()) {
+        try {
+            if (target.before === null) {
+                const result = context.removeExact(target.path, identity, false);
+                if (result !== "removed")
+                    throw new Error(`exact removal returned ${result}`);
+            }
+            else {
+                context.restoreExact(target.path, identity, decode(target.before).toString("utf8"), entityExactGetMaxBytes(sourceRoot));
+            }
+        }
+        catch (error) {
+            failures.push(`${target.path}: ${error.message}`);
+        }
+    }
+    return failures;
+}
+function finishJournal(context, relative, bytes, knownIdentity) {
+    const identity = knownIdentity ?? context.replaceExisting(relative, bytes, bytes.toString("utf8"), MAX_JOURNAL_BYTES).publishedIdentity;
+    if (context.removeExact(relative, identity) !== "removed") {
+        throw new Error(`plan replacement journal '${relative}' changed before cleanup`);
+    }
+}
+function completeJournal(context, sourceRoot, journal, bytes, relative, options, knownIdentity) {
+    const applied = [];
+    try {
+        for (const target of journal.targets) {
+            const identity = applyTarget(context, sourceRoot, target);
+            if (identity)
+                applied.push({ target, identity });
+        }
+        options.validate();
+        context.assertValid();
+        finishJournal(context, relative, bytes, knownIdentity);
+    }
+    catch (error) {
+        const failures = rollback(context, sourceRoot, applied);
+        if (failures.length) {
+            conflict(`plan replacement could not restore every target after failure: ${failures.join("; ")}`);
+        }
+        throw error;
+    }
+}
+export function recoverPendingPlanReplacement(context, sourceRoot, retry, options) {
+    const root = context.pinnedPath();
+    let pending;
+    try {
+        pending = inspectPendingPlanReplacement(root);
+    }
+    catch (error) {
+        reject({
+            class: "conflict",
+            message: `pending plan replacement journal is invalid: ${error.message}`,
+            recovery: "Preserve '.agentera/.entity-recovery/plan-replacement', restore its last valid journal bytes, and retry the exact non-dry-run plan replacement; no journal target bytes were changed.",
+        });
+    }
+    if (!pending)
+        return null;
+    const name = pendingJournalNames(root)[0];
+    const file = path.join(root, DIRECTORY, name);
+    const bytes = fs.readFileSync(file);
+    const journal = parseJournal(bytes, name);
+    assertExactRetry(journal, retry);
+    completeJournal(context, sourceRoot, journal, bytes, journalPath(journal.id), options);
+    return pending;
+}
+export function publishPlanReplacement(context, sourceRoot, operation, targets, options) {
+    if (!ID.test(operation.predecessor)
+        || !ID.test(operation.successor)
+        || operation.predecessor === operation.successor
+        || !/^[a-f0-9]{64}$/.test(operation.inputSha256)
+        || targets.length < 2
+        || targets.length > MAX_TARGETS
+        || new Set(targets.map((target) => target.path)).size !== targets.length
+        || targets.some((target) => !TARGET.test(target.path) || Buffer.byteLength(target.after) > MAX_TARGET_BYTES || (target.before !== null && target.before.length > MAX_TARGET_BYTES))) {
+        reject({ class: "schema_violation", message: "plan replacement transaction has invalid bounded targets", recovery: "Recompute the complete plan replacement target set from the locked canonical snapshot and retry; no state was changed." });
+    }
+    const body = targets.map((target) => ({ path: target.path, before: target.before === null ? null : encode(target.before), after: encode(target.after) }));
+    const journalOperation = {
+        kind: operation.kind,
+        predecessor: operation.predecessor,
+        successor: operation.successor,
+        input_sha256: operation.inputSha256,
+    };
+    const id = sha256(canonicalRecordJson({ operation: journalOperation, targets: body })).slice(0, 24);
+    const journal = { schema_version: VERSION, id, operation: journalOperation, targets: body };
+    const bytes = Buffer.from(`${JSON.stringify(journal)}\n`);
+    parseJournal(bytes, `${id}.json`);
+    const relative = journalPath(id);
+    recoverImmutableStage(context.pinnedPath(), { path: relative, before: null, after: bytes.toString("base64") });
+    const identity = context.publishImmutable(relative, bytes.toString("utf8"));
+    if (!identity) {
+        conflict(`plan replacement journal '${id}' already exists; retry the exact operation once so it can be recovered before another target set is prepared`);
+    }
+    completeJournal(context, sourceRoot, journal, bytes, relative, options, identity);
+}