@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/generated-environment/transaction.js

@@ -0,0 +1,1770 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { sha256Hex } from '../sha256.js';
+import { constants } from 'node:fs';
+import { lstat, mkdtemp, open, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { isProxy } from 'node:util/types';
+import { isDeepStrictEqual } from 'node:util';
+import { authenticatedExecutionOutcome } from '../environment-exec/execute.js';
+import { libexecProgram } from '../environment-exec/libexec-program.js';
+import { fileFingerprint, recordVerifiedDigest, verifiedDigest } from '../environment-exec/verified-digest.js';
+import { errorCause, snapshotGeneratedJson, RefusalError, tryParseJson, hasErrorCode } from '../environment/contract.js';
+import { readState } from '../environment/state.js';
+import { parseOwnershipManifest, projectGeneratedPathFacts, classifyGeneratedPaths, removeSharedOwnership, renderSharedPostimage } from '../surfaces/ownership.js';
+import { reservedPathSegment } from '../surfaces/contract.js';
+import { isInspectedBootstrapOutputs } from '../surfaces/skill-contract.js';
+import { exactKeys } from '../exact-keys.js';
+import { refusalOutcome as refuse } from '../refusal.js';
+const SHA256 = /^[a-f0-9]{64}$/;
+const OWNERSHIP_PATH = '.cockpit/generated-environment-ownership.json';
+const BOOTSTRAP_CONFIGURATION_PATH = 'cockpit.toml';
+const MAX_OWNERSHIP_BYTES = 1_048_576;
+const MAX_OWNED_FILES = 256;
+const MAX_EXECUTABLE_BYTES = 536_870_912;
+const MAX_GENERATED_BYTES = 16_777_216;
+const MAX_HELPER_FRAME_BYTES = 65_536;
+const HELPER_TIMEOUT_MS = 10_000;
+const MAX_AUTHENTICATED_READ_BATCH = 64;
+const MAX_AUTHENTICATED_READ_BATCH_BYTES = 67_108_864;
+const MAX_AUTHENTICATED_READ_BATCH_RECEIPT_BYTES = MAX_HELPER_FRAME_BYTES * (MAX_AUTHENTICATED_READ_BATCH + 1);
+const MAX_PUBLICATION_BATCH_GROUPS = 8;
+const TRANSACTION_TIMEOUT_MS = 180_000;
+// Reserve the final deadline slots so forward work cannot consume rollback's budget.
+const PUBLICATION_HELPER_SLOT_MS = 500;
+const PUBLICATION_HELPER_CALLS_PER_GROUP = 6;
+const compareCodeUnits = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+function ownRecord(value) {
+    try {
+        if (value === null || typeof value !== 'object' || Array.isArray(value) || isProxy(value)
+            || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+            return undefined;
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        if (Object.getOwnPropertySymbols(value).length > 0
+            || Object.values(descriptors).some((descriptor) => descriptor.get || descriptor.set || !descriptor.enumerable))
+            return undefined;
+        return Object.fromEntries(Object.entries(descriptors).map(([key, descriptor]) => [key, descriptor.value]));
+    }
+    catch {
+        // a guard over caller-supplied values; a throwing accessor or proxy trap is malformed input the caller refuses.
+        return undefined;
+    }
+}
+function confined(root, path) {
+    if (typeof path !== 'string' || path.length === 0 || path.includes('\0') || isAbsolute(path))
+        return undefined;
+    const target = resolve(root, path);
+    const offset = relative(root, target);
+    return offset !== '' && offset !== '..' && !offset.startsWith(`..${sep}`) && !isAbsolute(offset) ? target : undefined;
+}
+// Every anchored read and publication step runs in libexec/generated-filesystem.cjs, which
+// explains why that work needs its own process. The helper enforces these bounds; each request
+// carries them so they keep one owner here.
+const HELPER_PROGRAM = 'generated-filesystem.cjs';
+const HELPER_LIMITS = Object.freeze({
+    fileBytes: MAX_GENERATED_BYTES,
+    frameBytes: MAX_HELPER_FRAME_BYTES,
+    readBatchEntries: MAX_AUTHENTICATED_READ_BATCH,
+    readBatchBytes: MAX_AUTHENTICATED_READ_BATCH_BYTES,
+    readBatchReceiptBytes: MAX_AUTHENTICATED_READ_BATCH_RECEIPT_BYTES,
+    publicationGroups: MAX_PUBLICATION_BATCH_GROUPS,
+});
+function helperFrame(request) {
+    return JSON.stringify({ ...request, limits: HELPER_LIMITS });
+}
+function helperFrameBytes(request) {
+    return Buffer.byteLength(helperFrame(request));
+}
+async function digestFile(path, maxBytes) {
+    let handle;
+    try {
+        const before = await lstat(path);
+        if (!before.isFile() || before.isSymbolicLink() || before.size > maxBytes || (before.mode & 0o111) === 0)
+            return undefined;
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.size > maxBytes)
+            return undefined;
+        const fingerprint = fileFingerprint(path, opened);
+        const known = verifiedDigest(fingerprint);
+        if (known)
+            return known;
+        const hash = createHash('sha256');
+        const chunk = Buffer.allocUnsafe(Math.min(maxBytes + 1, 1_048_576));
+        let total = 0;
+        while (true) {
+            const { bytesRead } = await handle.read(chunk, 0, Math.min(chunk.length, maxBytes - total + 1), null);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+            if (total > maxBytes)
+                return undefined;
+            hash.update(chunk.subarray(0, bytesRead));
+        }
+        const after = await handle.stat();
+        if (after.size !== opened.size || after.mtimeMs !== opened.mtimeMs)
+            return undefined;
+        const digest = hash.digest('hex');
+        if (fileFingerprint(path, after) === fingerprint)
+            recordVerifiedDigest(fingerprint, digest);
+        return digest;
+    }
+    catch {
+        // an unavailable authority is refused by the caller.
+        return undefined;
+    }
+    finally {
+        try {
+            await handle?.close();
+        }
+        catch { /* Unavailable authority remains a refusal. */ }
+    }
+}
+export async function nodeAuthority() {
+    try {
+        const canonicalPath = await realpath(process.execPath);
+        const digest = await digestFile(canonicalPath, MAX_EXECUTABLE_BYTES);
+        return digest ? {
+            canonicalPath,
+            invocationPath: canonicalPath,
+            sha256: digest,
+            executionMode: 'verified-path',
+        } : undefined;
+    }
+    catch {
+        // an unavailable authority is refused by the caller.
+        return undefined;
+    }
+}
+async function publicationAnchor(root, parent) {
+    let path = root;
+    const segments = parent === '.' ? [] : parent.split('/');
+    const chain = [];
+    const anchored = async (missing) => {
+        const status = await lstat(path);
+        return status.isDirectory() && !status.isSymbolicLink()
+            ? { path, identity: { dev: status.dev, ino: status.ino }, chain, segments: missing }
+            : undefined;
+    };
+    for (const [index, segment] of segments.entries()) {
+        const candidate = join(path, segment);
+        try {
+            const status = await lstat(candidate);
+            if (!status.isDirectory() || status.isSymbolicLink())
+                return undefined;
+            path = candidate;
+            chain.push({ name: segment, dev: status.dev, ino: status.ino });
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'ENOENT'))
+                return undefined;
+            return anchored(segments.slice(index));
+        }
+    }
+    return anchored([]);
+}
+async function nestedPublicationAuthority(groupPath, groupExists, segments) {
+    if (!groupExists)
+        return { chain: [], segments };
+    const chain = [];
+    let current = groupPath;
+    for (const [index, name] of segments.entries()) {
+        if (!safePublicationSegment(name))
+            return undefined;
+        current = resolve(current, name);
+        try {
+            const status = await lstat(current);
+            if (!status.isDirectory() || status.isSymbolicLink())
+                return undefined;
+            chain.push({ name, dev: status.dev, ino: status.ino });
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'ENOENT'))
+                return undefined;
+            return { chain, segments: segments.slice(index) };
+        }
+    }
+    return { chain, segments: [] };
+}
+function helperStep(node, cwd, parent, request, inputs, deadline, stdoutLimitBytes = MAX_HELPER_FRAME_BYTES) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        return undefined;
+    const requestBytes = helperFrame(request);
+    if (Buffer.byteLength(requestBytes) > MAX_HELPER_FRAME_BYTES)
+        return undefined;
+    // An unauthenticated program is one more unavailable step: the caller refuses or compensates,
+    // and a transaction that has started keeps its recovery inputs.
+    let program;
+    try {
+        program = libexecProgram(HELPER_PROGRAM);
+    }
+    catch { /* an unauthenticated helper program is unavailable; the caller refuses or compensates. */
+        return undefined;
+    }
+    return {
+        id: `generated-filesystem-${request.action}-${request.nonce}`,
+        argv: [node.canonicalPath, '--', program.path, requestBytes, ...inputs.map(({ path }) => path)],
+        argv0: node.invocationPath,
+        cwd,
+        env: {},
+        timeoutMs: Math.min(HELPER_TIMEOUT_MS, remaining),
+        spawnNotAfter: new Date(deadline).toISOString(),
+        stdoutLimitBytes,
+        stderrLimitBytes: 16_384,
+        paths: [cwd],
+        ports: [],
+        labels: { action: request.action, parent },
+        expected: [],
+        consumedFiles: [
+            { path: node.canonicalPath, sha256: node.sha256, maxBytes: MAX_EXECUTABLE_BYTES, argvIndexes: [0], executable: true, executionMode: node.executionMode },
+            { path: program.path, sha256: program.sha256, maxBytes: program.maxBytes, argvIndexes: [2], executable: false },
+            ...inputs.map(({ path, sha256: digest }, index) => ({ path, sha256: digest, maxBytes: MAX_GENERATED_BYTES, argvIndexes: [4 + index], executable: false })),
+        ],
+        filesystemChecks: [{ path: cwd, expected: 'directory' }],
+        compensation: [],
+    };
+}
+function helperRecord(value, keys) {
+    const record = ownRecord(value);
+    return record && exactKeys(record, keys) ? record : undefined;
+}
+function directoryIdentity(value) {
+    const record = helperRecord(value, ['dev', 'ino']);
+    return record && Number.isSafeInteger(record.dev) && Number.isSafeInteger(record.ino)
+        ? { dev: record.dev, ino: record.ino } : undefined;
+}
+export async function readAnchoredFile(root, path, maxBytes, node, adapters, deadline) {
+    const action = 'read-file';
+    const target = confined(root, path);
+    if (!target || constants.O_NOFOLLOW === undefined || !Number.isSafeInteger(maxBytes)
+        || maxBytes < 1 || maxBytes > MAX_GENERATED_BYTES)
+        return { kind: 'invalid' };
+    const parts = relative(root, target).split(sep);
+    if (parts.length < 1 || parts.some((part) => part === '' || part === '.' || part === '..'))
+        return { kind: 'invalid' };
+    let rootStatus;
+    try {
+        rootStatus = await lstat(root);
+        if (!rootStatus.isDirectory() || rootStatus.isSymbolicLink())
+            return { kind: 'invalid' };
+    }
+    catch {
+        // an unobservable root is an invalid anchored read the caller refuses.
+        return { kind: 'invalid' };
+    }
+    let directory;
+    try {
+        directory = await mkdtemp(join(tmpdir(), 'cockpit-generated-read-'));
+    }
+    catch {
+        // an unobservable root is an invalid anchored read the caller refuses.
+        return { kind: 'invalid' };
+    }
+    try {
+        const nonce = randomBytes(16).toString('hex');
+        const output = join(directory, 'source');
+        const request = {
+            version: 1, nonce, action, maxBytes,
+            identity: { dev: rootStatus.dev, ino: rootStatus.ino },
+            segments: parts.slice(0, -1), name: parts.at(-1), output,
+        };
+        const helperDeadline = Math.min(Date.now() + HELPER_TIMEOUT_MS, deadline ?? Number.MAX_SAFE_INTEGER);
+        const rawReceipt = await runHelper(adapters, helperStep(node, root, '.', request, [], helperDeadline));
+        const missing = helperRecord(rawReceipt, ['version', 'nonce', 'action', 'kind']);
+        if (missing?.version === 1 && missing.nonce === nonce && missing.action === action && missing.kind === 'missing') {
+            return { kind: 'missing' };
+        }
+        const receipt = helperRecord(rawReceipt, ['version', 'nonce', 'action', 'kind', 'identity', 'sha256']);
+        if (!receipt || receipt.version !== 1 || receipt.nonce !== nonce || receipt.action !== action
+            || receipt.kind !== 'complete' || typeof receipt.sha256 !== 'string' || !SHA256.test(receipt.sha256)) {
+            return { kind: 'invalid' };
+        }
+        const rawIdentity = helperRecord(receipt.identity, ['root', 'chain', 'file']);
+        const readRoot = directoryIdentity(rawIdentity?.root);
+        const file = directoryIdentity(rawIdentity?.file);
+        const chain = Array.isArray(rawIdentity?.chain) ? rawIdentity.chain.map(directoryIdentity) : undefined;
+        if (!readRoot || readRoot.dev !== rootStatus.dev || readRoot.ino !== rootStatus.ino
+            || !file || !chain || chain.length !== parts.length - 1 || chain.some((entry) => !entry))
+            return { kind: 'invalid' };
+        const handle = await open(output, constants.O_RDONLY | constants.O_NOFOLLOW);
+        let bytes;
+        try {
+            const before = await handle.stat();
+            if (!before.isFile() || before.size > maxBytes)
+                return { kind: 'invalid' };
+            const chunks = [];
+            const chunk = Buffer.allocUnsafe(65_536);
+            let total = 0;
+            while (true) {
+                const { bytesRead } = await handle.read(chunk, 0, Math.min(chunk.length, maxBytes - total + 1), null);
+                if (bytesRead === 0)
+                    break;
+                total += bytesRead;
+                if (total > maxBytes)
+                    return { kind: 'invalid' };
+                chunks.push(Buffer.from(chunk.subarray(0, bytesRead)));
+            }
+            const after = await handle.stat();
+            if (total !== before.size || after.dev !== before.dev || after.ino !== before.ino
+                || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) {
+                return { kind: 'invalid' };
+            }
+            bytes = Buffer.concat(chunks, total);
+        }
+        finally {
+            await handle.close();
+        }
+        if (sha256Hex(bytes) !== receipt.sha256)
+            return { kind: 'invalid' };
+        return {
+            kind: 'complete', bytes, sha256: receipt.sha256,
+            identity: { root: readRoot, chain: chain, file },
+        };
+    }
+    catch {
+        // a failed anchored read is invalid; the caller refuses it.
+        return { kind: 'invalid' };
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+export async function readAnchoredEntry(root, path, maxBytes, node, adapters) {
+    const target = confined(root, path);
+    if (!target || maxBytes < 1 || maxBytes > MAX_GENERATED_BYTES)
+        return { kind: 'invalid' };
+    const parts = relative(root, target).split(sep);
+    let rootStatus;
+    try {
+        rootStatus = await lstat(root);
+    }
+    catch { /* an unobservable root is an invalid anchored read the caller refuses. */
+        return { kind: 'invalid' };
+    }
+    if (!rootStatus.isDirectory() || rootStatus.isSymbolicLink())
+        return { kind: 'invalid' };
+    let directory;
+    try {
+        directory = await mkdtemp(join(tmpdir(), 'cockpit-generated-entry-'));
+        const nonce = randomBytes(16).toString('hex');
+        const output = join(directory, 'source');
+        const request = { version: 1, nonce, action: 'read-entry', maxBytes,
+            identity: { dev: rootStatus.dev, ino: rootStatus.ino }, segments: parts.slice(0, -1), name: parts.at(-1), output };
+        const value = await runHelper(adapters, helperStep(node, root, '.', request, [], Date.now() + HELPER_TIMEOUT_MS));
+        const simple = ownRecord(value);
+        if (!simple || simple.version !== 1 || simple.nonce !== nonce || simple.action !== 'read-entry' || typeof simple.kind !== 'string')
+            return { kind: 'invalid' };
+        if ((simple.kind === 'missing' || simple.kind === 'other') && exactKeys(simple, ['version', 'nonce', 'action', 'kind']))
+            return { kind: simple.kind };
+        if (simple.kind === 'symlink' && exactKeys(simple, ['version', 'nonce', 'action', 'kind', 'target', 'identity'])) {
+            const identity = directoryIdentity(simple.identity);
+            return identity && typeof simple.target === 'string' ? { kind: 'symlink', target: simple.target, identity } : { kind: 'invalid' };
+        }
+        if (simple.kind !== 'file' || !exactKeys(simple, ['version', 'nonce', 'action', 'kind', 'identity', 'mode', 'sha256'])
+            || typeof simple.sha256 !== 'string' || !SHA256.test(simple.sha256) || !Number.isSafeInteger(simple.mode))
+            return { kind: 'invalid' };
+        const identityRow = ownRecord(simple.identity);
+        const readRoot = directoryIdentity(identityRow?.root);
+        const file = directoryIdentity(identityRow?.file);
+        const chain = Array.isArray(identityRow?.chain) ? identityRow.chain.map(directoryIdentity) : undefined;
+        if (!readRoot || !file || !chain || chain.some(row => !row))
+            return { kind: 'invalid' };
+        const handle = await open(output, constants.O_RDONLY | constants.O_NOFOLLOW);
+        let bytes;
+        try {
+            const before = await handle.stat();
+            if (!before.isFile() || before.size > maxBytes)
+                return { kind: 'invalid' };
+            const chunks = [];
+            const chunk = Buffer.allocUnsafe(65_536);
+            let total = 0;
+            while (true) {
+                const { bytesRead } = await handle.read(chunk, 0, Math.min(chunk.length, maxBytes - total + 1), null);
+                if (bytesRead === 0)
+                    break;
+                total += bytesRead;
+                if (total > maxBytes)
+                    return { kind: 'invalid' };
+                chunks.push(Buffer.from(chunk.subarray(0, bytesRead)));
+            }
+            const after = await handle.stat();
+            if (total !== before.size || after.dev !== before.dev || after.ino !== before.ino
+                || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) {
+                return { kind: 'invalid' };
+            }
+            bytes = Buffer.concat(chunks, total);
+        }
+        finally {
+            await handle.close();
+        }
+        if (sha256Hex(bytes) !== simple.sha256)
+            return { kind: 'invalid' };
+        return { kind: 'file', bytes, sha256: simple.sha256, mode: simple.mode,
+            identity: { root: readRoot, chain: chain, file } };
+    }
+    catch { /* a failed anchored read is invalid; the caller refuses it. */
+        return { kind: 'invalid' };
+    }
+    finally {
+        if (directory)
+            await rm(directory, { recursive: true, force: true });
+    }
+}
+/** Move one authenticated regular file to a portable authored destination through the publication helper. */
+export async function relocateAnchoredFile(root, sourcePath, destinationPath, maxBytes, expectedSha256, node, adapters) {
+    return relocateAnchoredFileWithDestinationPolicy(root, sourcePath, destinationPath, maxBytes, expectedSha256, node, adapters, 'relocate-file', safePublicationSegment);
+}
+async function relocateAnchoredFileWithDestinationPolicy(root, sourcePath, destinationPath, maxBytes, expectedSha256, node, adapters, action, destinationSegment) {
+    const sourceTarget = confined(root, sourcePath);
+    const destinationTarget = confined(root, destinationPath);
+    if (!sourceTarget || !destinationTarget || sourceTarget === destinationTarget || !SHA256.test(expectedSha256)
+        || !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_GENERATED_BYTES) {
+        return { kind: 'refusal', recovery: 'unchanged' };
+    }
+    const sourceParts = relative(root, sourceTarget).split(sep);
+    const destinationParts = relative(root, destinationTarget).split(sep);
+    if (sourceParts.some(part => !safeAnchoredSegment(part)) || destinationParts.some(part => !destinationSegment(part))) {
+        return { kind: 'refusal', recovery: 'unchanged' };
+    }
+    const source = await readAnchoredFile(root, sourcePath, maxBytes, node, adapters);
+    const destination = await readAnchoredEntry(root, destinationPath, maxBytes, node, adapters);
+    if (source.kind !== 'complete' || source.sha256 !== expectedSha256 || destination.kind !== 'missing') {
+        return { kind: 'refusal', recovery: 'unchanged' };
+    }
+    const nonce = randomBytes(16).toString('hex');
+    const request = {
+        version: 1, nonce, action, identity: source.identity.root,
+        source: {
+            chain: sourceParts.slice(0, -1).map((name, index) => ({ name, ...source.identity.chain[index] })),
+            name: sourceParts.at(-1), file: source.identity.file, sha256: source.sha256, maxBytes,
+        },
+        destination: { segments: destinationParts.slice(0, -1), name: destinationParts.at(-1) },
+    };
+    const receipt = await runHelper(adapters, helperStep(node, root, 'adoption', request, [], Date.now() + HELPER_TIMEOUT_MS));
+    const complete = helperRecord(receipt, ['version', 'nonce', 'action', 'kind', 'sha256']);
+    if (complete?.version === 1 && complete.nonce === nonce && complete.action === action
+        && complete.kind === 'complete' && complete.sha256 === expectedSha256) {
+        return { kind: 'complete', sha256: expectedSha256 };
+    }
+    const refusal = ownRecord(receipt);
+    const safeFailure = (value) => typeof value === 'string' && value.length > 0 && value.length <= 512;
+    const recovered = refusal && exactKeys(refusal, ['version', 'nonce', 'action', 'kind', 'reason', 'failure'])
+        && refusal.version === 1 && refusal.nonce === nonce && refusal.action === action
+        && refusal.kind === 'refusal' && refusal.reason === 'relocate-failed' && safeFailure(refusal.failure);
+    const recoveryFailed = refusal && exactKeys(refusal, ['version', 'nonce', 'action', 'kind', 'reason', 'failure', 'recoveryFailures', 'retained'])
+        && refusal.version === 1 && refusal.nonce === nonce && refusal.action === action
+        && refusal.kind === 'refusal' && refusal.reason === 'relocate-recovery-failed' && Array.isArray(refusal.retained)
+        && safeFailure(refusal.failure) && Array.isArray(refusal.recoveryFailures)
+        && refusal.recoveryFailures.length > 0 && refusal.recoveryFailures.every(safeFailure)
+        && refusal.retained.every(path => typeof path === 'string' && confined(root, path) !== undefined);
+    const retainedPaths = recoveryFailed
+        ? refusal.retained : undefined;
+    const possibleCaptures = [
+        [...sourceParts.slice(0, -1), `.cockpit-adopt-source-${nonce}`].join('/'),
+        [...destinationParts.slice(0, -1), `.cockpit-adopt-destination-${nonce}`].join('/'),
+    ];
+    return {
+        kind: 'refusal', recovery: recovered ? 'unchanged' : 'indeterminate',
+        ...((recovered || recoveryFailed) ? { failure: refusal.failure } : { failure: 'filesystem-helper-receipt-unavailable' }),
+        ...(recoveryFailed ? { recoveryFailures: refusal.recoveryFailures } : {}),
+        ...(!recovered ? { retainedPaths: retainedPaths ?? possibleCaptures } : {}),
+    };
+}
+/** Confirm or restore the original side of an anchored relocation without following either path. */
+export async function restoreAnchoredFile(root, originalPath, relocatedPath, maxBytes, expectedSha256, node, adapters) {
+    const original = await readAnchoredFile(root, originalPath, maxBytes, node, adapters);
+    const relocated = await readAnchoredFile(root, relocatedPath, maxBytes, node, adapters);
+    if (original.kind === 'complete' && original.sha256 === expectedSha256 && relocated.kind === 'missing') {
+        return { kind: 'complete', sha256: expectedSha256 };
+    }
+    if (original.kind === 'missing' && relocated.kind === 'complete' && relocated.sha256 === expectedSha256) {
+        return relocateAnchoredFileWithDestinationPolicy(root, relocatedPath, originalPath, maxBytes, expectedSha256, node, adapters, 'restore-file', safeAnchoredSegment);
+    }
+    return { kind: 'refusal', recovery: 'indeterminate' };
+}
+async function readPrivateOutput(path, maxBytes) {
+    let handle;
+    let result;
+    let closeFailed = false;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const before = await handle.stat();
+        if (!before.isFile() || before.size > maxBytes)
+            return undefined;
+        const chunks = [];
+        const chunk = Buffer.allocUnsafe(65_536);
+        let total = 0;
+        while (true) {
+            const { bytesRead } = await handle.read(chunk, 0, Math.min(chunk.length, maxBytes - total + 1), null);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+            if (total > maxBytes)
+                return undefined;
+            chunks.push(Buffer.from(chunk.subarray(0, bytesRead)));
+        }
+        const after = await handle.stat();
+        result = total === before.size && after.dev === before.dev && after.ino === before.ino
+            && after.size === before.size && after.mtimeMs === before.mtimeMs && after.ctimeMs === before.ctimeMs
+            ? Buffer.concat(chunks, total) : undefined;
+    }
+    catch {
+        // an unavailable authority is refused by the caller.
+        return undefined;
+    }
+    finally {
+        try {
+            await handle?.close();
+        }
+        catch { /* A descriptor that cannot be closed voids the read, so its result is discarded. */
+            closeFailed = true;
+        }
+    }
+    return closeFailed ? undefined : result;
+}
+async function readAnchoredBatch(root, requests, node, adapters, deadline) {
+    if (requests.length < 1 || requests.length > MAX_AUTHENTICATED_READ_BATCH || constants.O_NOFOLLOW === undefined
+        || requests.reduce((total, request) => total + request.maxBytes, 0) > MAX_AUTHENTICATED_READ_BATCH_BYTES)
+        return undefined;
+    const resolved = requests.map((request) => {
+        const target = confined(root, request.path);
+        if (!target || !Number.isSafeInteger(request.maxBytes) || request.maxBytes < 1 || request.maxBytes > MAX_GENERATED_BYTES)
+            return undefined;
+        const parts = relative(root, target).split(sep);
+        return parts.length > 0 && parts.every(part => part !== '' && part !== '.' && part !== '..')
+            ? { ...request, target, parts } : undefined;
+    });
+    if (resolved.some(request => request === undefined)
+        || new Set(resolved.map(request => request?.target)).size !== resolved.length)
+        return undefined;
+    if (requests.length === 1) {
+        const single = requests[0];
+        const result = single.action === 'read-entry'
+            ? await readAnchoredEntry(root, single.path, single.maxBytes, node, adapters)
+            : await readAnchoredFile(root, single.path, single.maxBytes, node, adapters, deadline);
+        return result.kind === 'invalid' ? { kind: 'invalid', index: 0 }
+            : { kind: 'complete', results: [result] };
+    }
+    let rootStatus;
+    try {
+        rootStatus = await lstat(root);
+        if (!rootStatus.isDirectory() || rootStatus.isSymbolicLink())
+            return undefined;
+    }
+    catch {
+        // an unavailable authority is refused by the caller.
+        return undefined;
+    }
+    let directory;
+    try {
+        directory = await mkdtemp(join(tmpdir(), 'cockpit-generated-read-batch-'));
+        const nonce = randomBytes(16).toString('hex');
+        const entries = resolved.map((request, index) => ({
+            nonce: randomBytes(16).toString('hex'),
+            action: request.action,
+            maxBytes: request.maxBytes,
+            segments: request.parts.slice(0, -1),
+            name: request.parts.at(-1),
+            output: join(directory, `source-${index}`),
+        }));
+        if (new Set(entries.map(entry => entry.nonce)).size !== entries.length)
+            return undefined;
+        const receiptOutput = join(directory, 'receipt');
+        const request = {
+            version: 1, nonce, action: 'read-batch',
+            identity: { dev: rootStatus.dev, ino: rootStatus.ino },
+            entries,
+            receiptOutput,
+        };
+        if (helperFrameBytes(request) > MAX_HELPER_FRAME_BYTES)
+            return { kind: 'split' };
+        const helperDeadline = Math.min(Date.now() + HELPER_TIMEOUT_MS, deadline ?? Number.MAX_SAFE_INTEGER);
+        const raw = await runHelper(adapters, helperStep(node, root, '.', request, [], helperDeadline));
+        const refusal = helperRecord(raw, ['version', 'nonce', 'action', 'kind', 'failedNonce']);
+        if (refusal?.version === 1 && refusal.nonce === nonce && refusal.action === 'read-batch' && refusal.kind === 'refusal'
+            && typeof refusal.failedNonce === 'string') {
+            const index = entries.findIndex(entry => entry.nonce === refusal.failedNonce);
+            return index >= 0 ? { kind: 'invalid', index } : undefined;
+        }
+        const summary = helperRecord(raw, ['version', 'nonce', 'action', 'kind', 'receiptBytes', 'receiptSha256']);
+        if (!summary || summary.version !== 1 || summary.nonce !== nonce || summary.action !== 'read-batch'
+            || summary.kind !== 'complete' || !Number.isSafeInteger(summary.receiptBytes)
+            || summary.receiptBytes < 1 || summary.receiptBytes > MAX_AUTHENTICATED_READ_BATCH_RECEIPT_BYTES
+            || typeof summary.receiptSha256 !== 'string' || !SHA256.test(summary.receiptSha256))
+            return undefined;
+        const receiptBytes = await readPrivateOutput(receiptOutput, MAX_AUTHENTICATED_READ_BATCH_RECEIPT_BYTES);
+        if (!receiptBytes || receiptBytes.length !== summary.receiptBytes || sha256Hex(receiptBytes) !== summary.receiptSha256)
+            return undefined;
+        const receiptText = new TextDecoder('utf-8', { fatal: true }).decode(receiptBytes);
+        const receiptValue = JSON.parse(receiptText);
+        if (JSON.stringify(receiptValue) + '\n' !== receiptText)
+            return undefined;
+        const receipt = helperRecord(receiptValue, ['version', 'nonce', 'action', 'kind', 'entries']);
+        if (!receipt || receipt.version !== 1 || receipt.nonce !== nonce || receipt.action !== 'read-batch'
+            || receipt.kind !== 'complete' || !Array.isArray(receipt.entries) || receipt.entries.length !== entries.length)
+            return undefined;
+        const results = [];
+        for (const [index, expected] of entries.entries()) {
+            const row = ownRecord(receipt.entries[index]);
+            if (!row || row.nonce !== expected.nonce || row.action !== expected.action || row.name !== expected.name
+                || row.maxBytes !== expected.maxBytes || typeof row.kind !== 'string')
+                return undefined;
+            if (!Array.isArray(row.segments) || row.segments.length !== expected.segments.length
+                || row.segments.some((segment, segmentIndex) => segment !== expected.segments[segmentIndex]))
+                return undefined;
+            const boundKeys = ['nonce', 'action', 'segments', 'name', 'maxBytes', 'kind'];
+            if (row.kind === 'missing') {
+                if (!exactKeys(row, boundKeys))
+                    return undefined;
+                results.push({ kind: 'missing' });
+                continue;
+            }
+            if (row.kind === 'other') {
+                if (expected.action !== 'read-entry' || !exactKeys(row, boundKeys))
+                    return undefined;
+                results.push({ kind: 'other' });
+                continue;
+            }
+            if (row.kind === 'symlink') {
+                if (expected.action !== 'read-entry' || !exactKeys(row, [...boundKeys, 'target', 'identity']) || typeof row.target !== 'string')
+                    return undefined;
+                const identity = directoryIdentity(row.identity);
+                if (!identity)
+                    return undefined;
+                results.push({ kind: 'symlink', target: row.target, identity });
+                continue;
+            }
+            const expectedKind = expected.action === 'read-entry' ? 'file' : 'complete';
+            const keys = expected.action === 'read-entry'
+                ? [...boundKeys, 'identity', 'mode', 'sha256'] : [...boundKeys, 'identity', 'sha256'];
+            if (row.kind !== expectedKind || !exactKeys(row, keys) || typeof row.sha256 !== 'string' || !SHA256.test(row.sha256)
+                || expected.action === 'read-entry' && !Number.isSafeInteger(row.mode))
+                return undefined;
+            const identityRow = helperRecord(row.identity, ['root', 'chain', 'file']);
+            const readRoot = directoryIdentity(identityRow?.root);
+            const file = directoryIdentity(identityRow?.file);
+            const chain = Array.isArray(identityRow?.chain) ? identityRow.chain.map(directoryIdentity) : undefined;
+            const parts = resolved[index].parts;
+            if (!readRoot || readRoot.dev !== rootStatus.dev || readRoot.ino !== rootStatus.ino || !file || !chain
+                || chain.length !== parts.length - 1 || chain.some(entry => !entry))
+                return undefined;
+            const bytes = await readPrivateOutput(expected.output, expected.maxBytes);
+            if (!bytes || sha256Hex(bytes) !== row.sha256)
+                return { kind: 'invalid', index };
+            const identity = { root: readRoot, chain: chain, file };
+            results.push(expected.action === 'read-entry'
+                ? { kind: 'file', bytes, sha256: row.sha256, mode: row.mode, identity }
+                : { kind: 'complete', bytes, sha256: row.sha256, identity });
+        }
+        return { kind: 'complete', results };
+    }
+    catch {
+        // an unavailable authority is refused by the caller.
+        return undefined;
+    }
+    finally {
+        if (directory)
+            await rm(directory, { recursive: true, force: true });
+    }
+}
+export async function readAnchoredBatches(root, requests, node, adapters, deadline) {
+    const results = [];
+    let offset = 0;
+    while (offset < requests.length) {
+        if (deadline !== undefined && Date.now() >= deadline)
+            return undefined;
+        let end = offset;
+        let requestedBytes = 0;
+        const targets = new Set();
+        while (end < requests.length && end - offset < MAX_AUTHENTICATED_READ_BATCH) {
+            const next = requests[end];
+            const target = confined(root, next.path);
+            if (target && targets.has(target))
+                break;
+            if (requestedBytes + next.maxBytes > MAX_AUTHENTICATED_READ_BATCH_BYTES)
+                break;
+            if (target)
+                targets.add(target);
+            requestedBytes += next.maxBytes;
+            end += 1;
+        }
+        if (end === offset)
+            return undefined;
+        let batch = await readAnchoredBatch(root, requests.slice(offset, end), node, adapters, deadline);
+        while (batch?.kind === 'split') {
+            end = offset + Math.ceil((end - offset) / 2);
+            batch = await readAnchoredBatch(root, requests.slice(offset, end), node, adapters, deadline);
+        }
+        if (!batch)
+            return undefined;
+        if (batch.kind === 'invalid')
+            return { kind: 'invalid', index: offset + batch.index };
+        results.push(...batch.results);
+        offset = end;
+    }
+    return { kind: 'complete', results };
+}
+export async function readAnchoredConfigSource(root, path, node, adapters, deadline) {
+    const read = await readAnchoredFile(root, path, MAX_GENERATED_BYTES, node, adapters, deadline);
+    return read.kind === 'complete'
+        ? { bytes: read.bytes, sha256: read.sha256, identity: read.identity }
+        : undefined;
+}
+function safeAnchoredSegment(value) {
+    return typeof value === 'string' && value.length > 0 && value !== '.' && value !== '..'
+        && !value.includes('/') && !value.includes('\\') && !value.includes('\0');
+}
+function safePublicationSegment(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 255 && Buffer.byteLength(value, 'utf8') <= 255
+        && !/[<>:"/\\|?*\x00-\x1f\x7f]/.test(value) && !/[. ]$/.test(value)
+        && !/^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(value);
+}
+export function portablePublicationPaths(paths) {
+    const prefixes = new Map();
+    for (const path of paths) {
+        let prefix = '';
+        for (const segment of path.split('/')) {
+            if (!safePublicationSegment(segment))
+                return false;
+            prefix = prefix ? `${prefix}/${segment}` : segment;
+            // Missing parents have no inode to compare, so reject aliases before either spelling can be created.
+            const key = prefix.normalize('NFC').toUpperCase().normalize('NFC');
+            const prior = prefixes.get(key);
+            if (prior !== undefined && prior !== prefix)
+                return false;
+            prefixes.set(key, prefix);
+        }
+    }
+    return true;
+}
+function helperChain(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const chain = [];
+    for (const item of value) {
+        const row = helperRecord(item, ['name', 'dev', 'ino', 'created']);
+        if (!row || !safePublicationSegment(row.name) || !Number.isSafeInteger(row.dev)
+            || !Number.isSafeInteger(row.ino) || typeof row.created !== 'boolean')
+            return undefined;
+        chain.push({ name: row.name, dev: row.dev, ino: row.ino, created: row.created });
+    }
+    return chain;
+}
+// Directories a prepare batch created, keyed by their path from the transaction root. The first row
+// naming a missing directory must report creating it; a later group or entry that walks through it
+// must report the same inode as already present.
+function createdRowsValid(prefix, rows, created) {
+    const names = [...prefix];
+    for (const row of rows) {
+        names.push(row.name);
+        const key = names.join('/');
+        const prior = created.get(key);
+        if (prior) {
+            if (row.created || row.dev !== prior.dev || row.ino !== prior.ino)
+                return false;
+        }
+        else {
+            if (!row.created)
+                return false;
+            created.set(key, { dev: row.dev, ino: row.ino });
+        }
+    }
+    return true;
+}
+function preparedEntryChainsValid(entries, requests, prefix, created) {
+    for (const [entryIndex, entry] of entries.entries()) {
+        const request = requests[entryIndex];
+        if (!request || entry.chain.length !== request.chain.length + request.segments.length)
+            return false;
+        const existing = entry.chain.slice(0, request.chain.length);
+        const missing = entry.chain.slice(request.chain.length);
+        if (existing.some((directory, index) => directory.name !== request.chain[index].name || directory.dev !== request.chain[index].dev
+            || directory.ino !== request.chain[index].ino || directory.created)
+            || missing.some((directory, index) => directory.name !== request.segments[index])
+            || !createdRowsValid([...prefix, ...existing.map(directory => directory.name)], missing, created))
+            return false;
+    }
+    return true;
+}
+function parsePreparedGroup(value, row, created) {
+    const receipt = helperRecord(value, ['nonce', 'identity', 'chain', 'entries']);
+    if (!receipt || receipt.nonce !== row.request.nonce || !Array.isArray(receipt.entries))
+        return undefined;
+    const identity = directoryIdentity(receipt.identity);
+    const chain = helperChain(receipt.chain);
+    const final = chain?.at(-1) ?? row.anchor.identity;
+    if (!identity || !chain || chain.length !== row.anchor.segments.length
+        || chain.some((directory, index) => directory.name !== row.anchor.segments[index])
+        || !createdRowsValid(row.anchor.chain.map(directory => directory.name), chain, created)
+        || final.dev !== identity.dev || final.ino !== identity.ino
+        || receipt.entries.length !== row.group.mutations.length)
+        return undefined;
+    const requests = row.request.entries;
+    const entries = [];
+    for (const [index, item] of receipt.entries.entries()) {
+        const entry = helperRecord(item, ['chain', 'name', 'operation', 'sha256', 'target', 'stage', 'backup', 'priorKind', 'priorSha256', 'priorTarget', 'priorMode', 'priorIdentity']);
+        const priorIdentity = entry ? entry.priorIdentity === null ? null : directoryIdentity(entry.priorIdentity) : undefined;
+        const entryChain = entry ? helperChain(entry.chain) : undefined;
+        const request = requests[index];
+        const mutation = row.group.mutations[index];
+        const expectedStage = `.cockpit-stage-${row.request.nonce}-${index}`;
+        const expectedBackup = `.cockpit-backup-${row.request.nonce}-${index}`;
+        if (!entry || !request || !mutation || !entryChain || !safePublicationSegment(entry.name) || !['write-file', 'write-symlink', 'remove-file', 'remove-symlink'].includes(String(entry.operation))
+            || entry.stage !== null && typeof entry.stage !== 'string' || entry.sha256 !== null && (typeof entry.sha256 !== 'string' || !SHA256.test(entry.sha256))
+            || entry.target !== null && typeof entry.target !== 'string'
+            || entry.backup !== null && typeof entry.backup !== 'string'
+            || !['missing', 'file', 'symlink'].includes(String(entry.priorKind))
+            || entry.priorSha256 !== null && (typeof entry.priorSha256 !== 'string' || !SHA256.test(entry.priorSha256))
+            || entry.priorTarget !== null && typeof entry.priorTarget !== 'string'
+            || entry.priorMode !== null && (!Number.isSafeInteger(entry.priorMode) || entry.priorMode < 0 || entry.priorMode > 0o777)
+            || priorIdentity === undefined || (entry.priorKind === 'missing') !== (priorIdentity === null)
+            || (entry.priorKind === 'file') !== (entry.priorSha256 !== null) || (entry.priorKind === 'file') !== (entry.priorMode !== null)
+            || (entry.priorKind === 'file') !== (entry.backup !== null) || (entry.priorKind === 'symlink') !== (entry.priorTarget !== null)
+            || entry.stage !== (request.operation === 'write-file' || request.operation === 'write-symlink' ? expectedStage : null)
+            || entry.backup !== (entry.priorKind === 'file' ? expectedBackup : null)
+            || entry.name !== basename(mutation.path) || entry.operation !== mutation.operation
+            || entry.sha256 !== (mutation.sha256 ?? null) || entry.target !== (mutation.target ?? null))
+            return undefined;
+        entries.push({ ...entry, chain: entryChain, priorIdentity });
+    }
+    const parent = row.group.parent === '.' ? [] : row.group.parent.split('/');
+    if (new Set(entries.map(entry => [...entry.chain.map(directory => directory.name), entry.name].join('/'))).size !== entries.length
+        || !preparedEntryChainsValid(entries, requests, parent, created))
+        return undefined;
+    return {
+        parent: row.group.parent,
+        path: row.path,
+        start: row.anchor.identity,
+        identity,
+        chain,
+        entries,
+        logicalWeight: row.group.logicalWeight,
+    };
+}
+// A refusal still lists the groups prepared before it, so the caller can roll those back.
+function parsePrepareBatchReceipt(value, batch) {
+    const receipt = ownRecord(value);
+    if (!receipt || receipt.version !== 1 || receipt.nonce !== batch.request.nonce || receipt.action !== 'prepare-batch'
+        || !Array.isArray(receipt.groups))
+        return undefined;
+    const complete = receipt.kind === 'complete' && exactKeys(receipt, ['version', 'nonce', 'action', 'kind', 'groups'])
+        && receipt.groups.length === batch.rows.length;
+    const refused = receipt.kind === 'refusal' && exactKeys(receipt, ['version', 'nonce', 'action', 'kind', 'reason', 'groups'])
+        && (receipt.reason === 'prepare-failed' || receipt.reason === 'prepare-cleanup-failed') && receipt.groups.length < batch.rows.length;
+    if (!complete && !refused)
+        return undefined;
+    const created = new Map();
+    const groups = [];
+    for (const [index, item] of receipt.groups.entries()) {
+        const group = parsePreparedGroup(item, batch.rows[index], created);
+        if (!group)
+            return undefined;
+        groups.push(group);
+    }
+    return { complete, groups };
+}
+function parseRollbackReceipt(value, nonce) {
+    const receipt = helperRecord(value, ['version', 'nonce', 'action', 'kind']);
+    return receipt?.version === 1 && receipt.nonce === nonce && receipt.action === 'rollback' && receipt.kind === 'complete';
+}
+function parsePublicationBatchReceipt(value, request) {
+    const refusal = helperRecord(value, ['version', 'nonce', 'action', 'kind', 'reason']);
+    if (request.action === 'commit-batch' && refusal?.version === 1 && refusal.nonce === request.nonce && refusal.action === request.action
+        && refusal.kind === 'refusal' && refusal.reason === 'verify-failed')
+        return 'verify-failed';
+    const receipt = helperRecord(value, ['version', 'nonce', 'action', 'kind', 'groups']);
+    if (!receipt || receipt.version !== 1 || receipt.nonce !== request.nonce || receipt.action !== request.action
+        || receipt.kind !== 'complete' || !Array.isArray(receipt.groups) || receipt.groups.length !== request.groups.length)
+        return 'failed';
+    const nonces = new Set();
+    return receipt.groups.every((value, index) => {
+        const row = helperRecord(value, ['nonce', 'parent', 'kind']);
+        const expected = request.groups[index];
+        if (!row || !expected || typeof row.nonce !== 'string' || nonces.has(row.nonce))
+            return false;
+        nonces.add(row.nonce);
+        return row.nonce === expected.nonce && row.parent === expected.parent && row.kind === 'complete';
+    }) ? 'complete' : 'failed';
+}
+async function publicationBatchRequest(root, rootIdentity, groups, action) {
+    const rootStatus = await lstat(root);
+    if (!rootStatus.isDirectory() || rootStatus.isSymbolicLink()
+        || rootStatus.dev !== rootIdentity.dev || rootStatus.ino !== rootIdentity.ino)
+        return undefined;
+    const nonce = randomBytes(16).toString('hex');
+    const rows = [];
+    for (const group of groups.slice(0, MAX_PUBLICATION_BATCH_GROUPS)) {
+        const target = group.parent === '.' ? root : confined(root, group.parent);
+        if (!target || target !== group.path)
+            return undefined;
+        let current = root;
+        const chain = [];
+        for (const name of group.parent === '.' ? [] : group.parent.split('/')) {
+            if (name.length === 0 || name === '.' || name === '..' || name.includes('\\') || name.includes('\0'))
+                return undefined;
+            current = resolve(current, name);
+            const status = await lstat(current);
+            if (!status.isDirectory() || status.isSymbolicLink())
+                return undefined;
+            chain.push({ name, dev: status.dev, ino: status.ino });
+        }
+        const final = chain.at(-1) ?? rootIdentity;
+        if (final.dev !== group.identity.dev || final.ino !== group.identity.ino)
+            return undefined;
+        const row = {
+            nonce: randomBytes(16).toString('hex'),
+            parent: group.parent,
+            identity: group.identity,
+            chain,
+            entries: group.entries,
+        };
+        const candidate = { version: 1, nonce, action, identity: rootIdentity, groups: [...rows, row] };
+        if (helperFrameBytes(candidate) > MAX_HELPER_FRAME_BYTES)
+            break;
+        rows.push(row);
+    }
+    return rows.length > 0
+        ? { version: 1, nonce, action, identity: rootIdentity, groups: rows }
+        : undefined;
+}
+// `verify-failed` is reported only while no request of this run has completed, so it means that
+// nothing this run would change has changed.
+async function runPublicationBatches(action, root, rootIdentity, groups, node, adapters, nextForwardDeadline, callsPerGroup = 1, first) {
+    let offset = 0;
+    while (offset < groups.length) {
+        const request = offset === 0 && first ? first : await publicationBatchRequest(root, rootIdentity, groups.slice(offset), action);
+        const logicalWeight = request?.groups.reduce((count, _row, index) => count + groups[offset + index].logicalWeight, 0);
+        const deadline = logicalWeight === undefined ? undefined : nextForwardDeadline(callsPerGroup * logicalWeight);
+        if (!request || deadline === undefined)
+            return offset === 0 ? 'verify-failed' : 'failed';
+        const receipt = await runHelper(adapters, helperStep(node, root, 'generated-environment', request, [], deadline));
+        const outcome = parsePublicationBatchReceipt(receipt, request);
+        if (outcome !== 'complete')
+            return outcome === 'verify-failed' && offset === 0 ? 'verify-failed' : 'failed';
+        offset += request.groups.length;
+    }
+    return 'complete';
+}
+// publish-batch validates every group in its request before it publishes any, and commit-batch
+// verifies every group before it retires any backup. A transaction that fits one request therefore
+// needs one helper call per stage; a larger one first checks every group across separate requests,
+// so no request publishes or commits while a later group is unchecked. Either way the stage spends
+// two forward slots per group. `verify-failed` means no backup was retired.
+async function runPublicationStage(stage, root, rootIdentity, groups, node, adapters, nextForwardDeadline) {
+    const check = stage === 'publish' ? 'validate-batch' : 'verify-batch';
+    const action = stage === 'publish' ? 'publish-batch' : 'commit-batch';
+    const single = await publicationBatchRequest(root, rootIdentity, groups, action);
+    if (!single)
+        return 'verify-failed';
+    // The request that decided this path is the one sent, so it cannot split after the decision.
+    if (single.groups.length === groups.length) {
+        return runPublicationBatches(action, root, rootIdentity, groups, node, adapters, nextForwardDeadline, 2, single);
+    }
+    const checked = await runPublicationBatches(check, root, rootIdentity, groups, node, adapters, nextForwardDeadline);
+    if (checked !== 'complete')
+        return 'verify-failed';
+    return runPublicationBatches(action, root, rootIdentity, groups, node, adapters, nextForwardDeadline);
+}
+async function runHelper(adapters, step) {
+    if (!step)
+        return undefined;
+    try {
+        const outcome = authenticatedExecutionOutcome(await adapters.execute(step), step);
+        if (!outcome || outcome.kind !== 'complete' || outcome.stderr.byteLength !== 0)
+            return undefined;
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(outcome.stdout);
+        const value = JSON.parse(text);
+        return `${JSON.stringify(value)}\n` === text ? value : undefined;
+    }
+    catch {
+        // unparseable input is malformed; the caller refuses it.
+        return undefined;
+    }
+}
+export function expectedState(entry) {
+    if (entry.kind === 'missing')
+        return { kind: 'missing' };
+    if (entry.kind === 'file')
+        return { kind: 'file', sha256: entry.sha256, identity: entry.identity.file };
+    if (entry.kind === 'symlink')
+        return { kind: 'symlink', target: entry.target, identity: entry.identity };
+    return undefined;
+}
+async function stageInputs(files) {
+    let directory;
+    try {
+        directory = await mkdtemp(join(tmpdir(), 'cockpit-generated-input-'));
+        const inputs = [];
+        for (const [index, file] of files.entries()) {
+            if (Buffer.byteLength(file.bytes) > MAX_GENERATED_BYTES)
+                throw new RefusalError('generated input is oversized');
+            const path = join(directory, String(index));
+            const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            try {
+                await handle.writeFile(file.bytes);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            inputs.push({ path, sha256: file.sha256 });
+        }
+        return { directory, inputs };
+    }
+    catch {
+        // staging failed; the caller refuses and no inputs are retained.
+        if (directory)
+            await rm(directory, { recursive: true, force: true });
+        return undefined;
+    }
+}
+async function recordRecovery(directory, groups) {
+    const path = join(directory, `recovery-${String(groups.length).padStart(4, '0')}.json`);
+    let handle;
+    let directoryHandle;
+    try {
+        handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        const durableGroups = groups.map(({ logicalWeight: _logicalWeight, ...group }) => group);
+        await handle.writeFile(`${JSON.stringify({ version: 1, groups: durableGroups })}\n`);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        directoryHandle = await open(directory, constants.O_RDONLY | constants.O_NOFOLLOW);
+        await directoryHandle.sync();
+        return true;
+    }
+    catch {
+        // a recovery record that is not durable keeps publication closed.
+        return false;
+    }
+    finally {
+        try {
+            await handle?.close();
+        }
+        catch { /* A missing durable recovery record keeps publication closed. */ }
+        try {
+            await directoryHandle?.close();
+        }
+        catch { /* The recovery record was already synced before directory cleanup. */ }
+    }
+}
+function publicationEntrySegments(parent, path) {
+    const group = parent === '.' ? [] : parent.split('/');
+    const leafParent = dirname(path) === '.' ? [] : dirname(path).split('/');
+    if (group.some((segment, index) => segment !== leafParent[index]))
+        return undefined;
+    const segments = leafParent.slice(group.length);
+    return segments.every(segment => segment.length > 0 && segment !== '.' && segment !== '..'
+        && !segment.includes('/') && !segment.includes('\\') && !segment.includes('\0')) ? segments : undefined;
+}
+function groupFrameBounded(parent, entries) {
+    const identity = { dev: Number.MAX_SAFE_INTEGER, ino: Number.MAX_SAFE_INTEGER };
+    const chain = (parent === '.' ? [] : parent.split('/')).map(name => ({ name, ...identity, created: false }));
+    const requestEntries = entries.map((entry, index) => {
+        const segments = publicationEntrySegments(parent, entry.path);
+        return segments && { chain: segments.map(name => ({ name, ...identity })), segments: [], name: basename(entry.path), operation: entry.operation,
+            expected: entry.expected, sha256: entry.sha256 ?? null, target: entry.target ?? null,
+            input: entry.operation === 'write-file' ? Number.MAX_SAFE_INTEGER - index : null };
+    });
+    if (requestEntries.some(entry => entry === undefined))
+        return false;
+    const receiptEntries = entries.map((entry, index) => ({ chain: publicationEntrySegments(parent, entry.path).map(name => ({ name, ...identity, created: false })),
+        name: basename(entry.path), operation: entry.operation,
+        sha256: entry.sha256 ?? null, target: entry.target ?? null, stage: `.cockpit-stage-${'0'.repeat(32)}-${index}`,
+        backup: `.cockpit-backup-${'0'.repeat(32)}-${index}`, priorKind: entry.expected.kind,
+        priorSha256: entry.expected.sha256 ?? null, priorTarget: entry.expected.target ?? null,
+        priorMode: entry.expected.kind === 'file' ? 511 : null, priorIdentity: entry.expected.identity ?? null }));
+    const nonce = '0'.repeat(32);
+    const group = { nonce, parent, identity, chain, entries: receiptEntries };
+    const anchor = chain.map(({ created: _created, ...row }) => row);
+    const requests = [
+        { version: 1, nonce, action: 'prepare-batch', identity, groups: [{ nonce, parent, anchor, identity, segments: [], entries: requestEntries }] },
+        { version: 1, nonce, action: 'validate-batch', identity, groups: [group] },
+        { version: 1, nonce, action: 'publish-batch', identity, groups: [group] },
+        { version: 1, nonce, action: 'verify-batch', identity, groups: [group] },
+        { version: 1, nonce, action: 'rollback', identity, start: identity, chain, entries: receiptEntries },
+        { version: 1, nonce, action: 'commit-batch', identity, groups: [group] },
+    ];
+    const receipt = { version: 1, nonce, action: 'prepare-batch', kind: 'complete', groups: [{ nonce, identity, chain, entries: receiptEntries }] };
+    return requests.every(frame => helperFrameBytes(frame) + 1 <= MAX_HELPER_FRAME_BYTES)
+        && Buffer.byteLength(JSON.stringify(receipt)) + 1 <= MAX_HELPER_FRAME_BYTES;
+}
+function groupMutations(mutations) {
+    const grouped = new Map();
+    for (const mutation of mutations) {
+        const parent = dirname(mutation.path);
+        const phase = mutation.phase === 'ledger' ? 'ledger' : mutation.operation.startsWith('write-') ? 'write' : 'remove';
+        const key = `${phase}\0${parent}`;
+        const group = grouped.get(key) ?? { parent, phase, rows: [] };
+        group.rows.push(mutation);
+        grouped.set(key, group);
+    }
+    const logical = [];
+    const phaseOrder = { write: 0, remove: 1, ledger: 2 };
+    for (const { parent, phase, rows } of [...grouped.values()].sort((left, right) => phaseOrder[left.phase] - phaseOrder[right.phase]
+        || compareCodeUnits(left.parent, right.parent))) {
+        let chunk = [];
+        for (const row of rows.sort((left, right) => compareCodeUnits(left.path, right.path))) {
+            const candidate = [...chunk, row];
+            if (!groupFrameBounded(parent, candidate)) {
+                if (chunk.length === 0 || !groupFrameBounded(parent, [row]))
+                    return undefined;
+                logical.push({ parent, phase, mutations: chunk });
+                chunk = [row];
+            }
+            else
+                chunk = candidate;
+        }
+        if (chunk.length > 0)
+            logical.push({ parent, phase, mutations: chunk });
+    }
+    const clusters = new Map();
+    for (const group of logical) {
+        const anchor = group.mutations.every(row => row.compactAnchor === group.mutations[0]?.compactAnchor)
+            ? group.mutations[0]?.compactAnchor : undefined;
+        if (!anchor)
+            continue;
+        const key = `${group.phase}\0${anchor}`;
+        const cluster = clusters.get(key) ?? [];
+        cluster.push(group);
+        clusters.set(key, cluster);
+    }
+    const compacted = new Set();
+    const result = [];
+    for (const group of logical) {
+        const anchor = group.mutations.every(row => row.compactAnchor === group.mutations[0]?.compactAnchor)
+            ? group.mutations[0]?.compactAnchor : undefined;
+        const key = anchor ? `${group.phase}\0${anchor}` : undefined;
+        const cluster = key ? clusters.get(key) : undefined;
+        if (!key || !cluster || compacted.has(key)) {
+            if (!key || !cluster)
+                result.push({ ...group, logicalWeight: 1 });
+            continue;
+        }
+        compacted.add(key);
+        const parents = new Set(cluster.map(row => row.parent));
+        const entries = cluster.flatMap(row => row.mutations).sort((left, right) => compareCodeUnits(left.path, right.path));
+        if (parents.size > 1 && groupFrameBounded(anchor, entries)) {
+            result.push({ parent: anchor, phase: group.phase, mutations: entries, logicalWeight: 1 });
+        }
+        else
+            for (const row of cluster)
+                result.push({ ...row, logicalWeight: 1 });
+    }
+    result.sort((left, right) => phaseOrder[left.phase] - phaseOrder[right.phase] || compareCodeUnits(left.parent, right.parent));
+    const merged = [];
+    for (const group of result) {
+        const prior = merged.at(-1);
+        const mutations = prior && prior.phase === group.phase && prior.parent === group.parent
+            ? [...prior.mutations, ...group.mutations].sort((left, right) => compareCodeUnits(left.path, right.path)) : undefined;
+        if (prior && mutations && groupFrameBounded(group.parent, mutations)) {
+            merged[merged.length - 1] = { ...prior, mutations, logicalWeight: prior.logicalWeight + group.logicalWeight };
+        }
+        else
+            merged.push(group);
+    }
+    return merged.map(({ phase: _phase, ...group }) => group);
+}
+async function prepareBatch(root, rootIdentity, groups, files, staged) {
+    const nonce = randomBytes(16).toString('hex');
+    const rows = [];
+    let inputs = [];
+    for (const group of groups.slice(0, MAX_PUBLICATION_BATCH_GROUPS)) {
+        const anchor = await publicationAnchor(root, group.parent);
+        if (!anchor)
+            return undefined;
+        const path = group.parent === '.' ? root : resolve(root, group.parent);
+        const groupInputs = [...inputs];
+        const entries = [];
+        for (const mutation of group.mutations) {
+            const segments = publicationEntrySegments(group.parent, mutation.path);
+            const nested = segments && await nestedPublicationAuthority(path, anchor.segments.length === 0, segments);
+            if (!nested)
+                return undefined;
+            let input = null;
+            if (mutation.operation === 'write-file') {
+                input = groupInputs.length;
+                groupInputs.push(staged[files.findIndex(file => file.path === mutation.path)]);
+            }
+            entries.push({ chain: nested.chain, segments: nested.segments,
+                name: basename(mutation.path), operation: mutation.operation, expected: mutation.expected,
+                sha256: mutation.sha256 ?? null, target: mutation.target ?? null, input });
+        }
+        const request = { nonce: randomBytes(16).toString('hex'), parent: group.parent, anchor: anchor.chain,
+            identity: anchor.identity, segments: anchor.segments, entries };
+        const candidate = { version: 1, nonce, action: 'prepare-batch', identity: rootIdentity,
+            groups: [...rows.map(row => row.request), request] };
+        if (helperFrameBytes(candidate) > MAX_HELPER_FRAME_BYTES)
+            break;
+        rows.push({ group, anchor, path, request });
+        inputs = groupInputs;
+    }
+    return rows.length > 0 ? {
+        request: { version: 1, nonce, action: 'prepare-batch', identity: rootIdentity,
+            groups: rows.map(row => row.request) },
+        rows,
+        inputs,
+    } : undefined;
+}
+async function compensate(groups, node, adapters, transactionDeadline) {
+    const rollback = [...groups].reverse();
+    let remainingWeight = rollback.reduce((count, group) => count + group.logicalWeight, 0);
+    for (const [index, group] of rollback.entries()) {
+        const nonce = randomBytes(16).toString('hex');
+        const request = { version: 1, nonce, action: 'rollback', identity: group.identity, start: group.start, chain: group.chain, entries: group.entries };
+        remainingWeight -= group.logicalWeight;
+        const deadline = transactionDeadline - remainingWeight * PUBLICATION_HELPER_SLOT_MS;
+        const receipt = await runHelper(adapters, helperStep(node, group.path, group.parent, request, [], deadline));
+        if (!parseRollbackReceipt(receipt, nonce))
+            return false;
+    }
+    return true;
+}
+function staleRemovalRequest(prepared, mutations) {
+    const entries = [];
+    for (const mutation of mutations.filter((candidate) => candidate.phase === 'stale')) {
+        const current = mutation.expected;
+        if (current.kind !== 'file' && current.kind !== 'symlink' || !current.identity
+            || mutation.operation !== 'write-file' && mutation.operation !== 'remove-file' && mutation.operation !== 'remove-symlink')
+            return undefined;
+        entries.push({
+            path: mutation.path,
+            operation: mutation.operation,
+            current: {
+                kind: current.kind,
+                ...(current.sha256 ? { sha256: current.sha256 } : {}),
+                ...(current.target ? { target: current.target } : {}),
+                dev: current.identity.dev,
+                ino: current.identity.ino,
+            },
+            ...(mutation.sha256 ? { resultSha256: mutation.sha256 } : {}),
+        });
+    }
+    if (entries.length === 0)
+        return undefined;
+    const payload = {
+        format: 'cockpit-stale-removal-request/v1',
+        cockpitId: prepared.cockpitId,
+        generation: prepared.generation,
+        sourceSha256: prepared.sourceSha256,
+        entries: entries.sort((left, right) => compareCodeUnits(left.path, right.path)),
+    };
+    return { ...payload, digest: sha256Hex(JSON.stringify(payload)) };
+}
+async function staleRemovalApproved(request, adapters) {
+    if (!adapters.authorizeStaleRemoval)
+        return false;
+    try {
+        const approval = ownRecord(await adapters.authorizeStaleRemoval(request));
+        return !!approval
+            && exactKeys(approval, ['format', 'digest'])
+            && approval.format === 'cockpit-stale-removal-approval/v1'
+            && approval.digest === request.digest;
+    }
+    catch {
+        // a throwing approval authority is no approval; the caller refuses.
+        return false;
+    }
+}
+function sameExpected(left, right) {
+    return left.kind === right.kind && left.sha256 === right.sha256 && left.target === right.target
+        && left.identity?.dev === right.identity?.dev && left.identity?.ino === right.identity?.ino;
+}
+function sameIdentity(left, right) {
+    return left.root.dev === right.root.dev && left.root.ino === right.root.ino
+        && left.file.dev === right.file.dev && left.file.ino === right.file.ino
+        && left.chain.length === right.chain.length
+        && left.chain.every((row, index) => row.dev === right.chain[index]?.dev && row.ino === right.chain[index]?.ino);
+}
+function exactPath(root, path) {
+    return path.length <= 4096 && !/[\\\x00-\x1f\x7f*?\[\]{}]/.test(path)
+        && path.split('/').every(part => safePublicationSegment(part)
+            // Folding to upper case first also catches spellings that only fold onto a reserved
+            // name, such as a dotless i or long s, on case-insensitive filesystems.
+            && !reservedPathSegment(part.normalize('NFC').toUpperCase().normalize('NFC'))) && confined(root, path) !== undefined;
+}
+function classifyEntry(fact, current) {
+    if (!fact)
+        return undefined;
+    const entry = fact.entry;
+    const observation = current.kind === 'file' ? { path: entry.path, kind: 'file', bytes: current.bytes,
+        identity: JSON.stringify(current.identity), confinement: 'confined' }
+        : { path: entry.path, kind: current.kind, confinement: current.kind === 'missing' ? 'confined' : 'unknown' };
+    const classified = classifyGeneratedPaths([fact], [observation]);
+    return classified.kind === 'complete' ? classified.paths[0]?.state : undefined;
+}
+async function admitBootstrapPlan(input, adapters) {
+    const supplied = ownRecord(input);
+    const refreshInput = supplied && 'refresh' in supplied ? ownRecord(supplied.refresh) : undefined;
+    if (!supplied || !exactKeys(supplied, refreshInput
+        ? ['mode', 'root', 'rootIdentity', 'node', 'inspected', 'mutations', 'refresh']
+        : ['mode', 'root', 'rootIdentity', 'node', 'inspected', 'mutations']) || supplied.mode !== 'bootstrap'
+        || !isInspectedBootstrapOutputs(supplied.inspected)) {
+        return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap publication input is not an exact bounded plan', 'generated-environment');
+    }
+    const serializable = snapshotGeneratedJson({ mode: supplied.mode, root: supplied.root, rootIdentity: supplied.rootIdentity,
+        node: supplied.node, mutations: supplied.mutations });
+    if (!serializable || serializable.mode !== 'bootstrap' || !isAbsolute(serializable.root) || resolve(serializable.root) !== serializable.root
+        || !directoryIdentity(serializable.rootIdentity)
+        || !serializable.node || !isAbsolute(serializable.node.canonicalPath) || !SHA256.test(serializable.node.sha256)
+        || !Array.isArray(serializable.mutations) || serializable.mutations.length > MAX_OWNED_FILES) {
+        return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap publication input is not an exact bounded plan', 'generated-environment');
+    }
+    const { node } = serializable;
+    const inspected = supplied.inspected;
+    const desired = inspected.files.map(file => ({
+        kind: 'file', path: file.path, harnesses: [file.target], scope: 'always',
+        capability: 'instructed', writer: 'cockpit', schemaVersion: 1,
+        ownership: 'whole-file', bytes: file.bytes, sha256: file.sha256,
+    }));
+    const mutations = [...serializable.mutations];
+    if (mutations.length > desired.length || new Set(mutations.map(row => row.path)).size !== mutations.length
+        || mutations.some(row => !exactPath(serializable.root, row.path) || row.phase !== 'desired' || row.operation !== 'write-file'
+            || typeof row.bytes !== 'string' || row.sha256 !== sha256Hex(row.bytes))) {
+        return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap publication contains an undeclared or non-exact operation', 'generated-environment');
+    }
+    const paths = desired.map(entry => entry.path);
+    if (!portablePublicationPaths(paths) || mutations.some(row => !paths.includes(row.path))) {
+        return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap publication operation is outside the selected target output set', 'generated-environment');
+    }
+    let prior;
+    if (refreshInput) {
+        if (!exactKeys(refreshInput, ['address', 'commandSha256', 'revision']) || !Number.isSafeInteger(refreshInput.revision)
+            || refreshInput.revision < 0 || !SHA256.test(refreshInput.commandSha256)) {
+            return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap refresh authority is not exact', 'generated-environment');
+        }
+        const observed = await readState(refreshInput.address);
+        const record = observed.kind === 'complete' ? observed.value : undefined;
+        if (!record)
+            return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap refresh state could not be authenticated', 'generated-environment');
+        const priorPreviewSha256 = sha256Hex(JSON.stringify({ target: record.target, sources: record.value.sources,
+            files: record.value.published }));
+        if (record.revision !== refreshInput.revision || record.value.commandSha256 !== refreshInput.commandSha256
+            || record.value.previewSha256 !== priorPreviewSha256 || record.value.stage !== 'surface-published'
+            || record.value.checkoutRoot !== serializable.root
+            || record.target !== inspected.target || record.value.target !== inspected.target
+            || JSON.stringify(record.value.published.map(row => row.path)) !== JSON.stringify(paths)) {
+            return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap refresh authority does not match the fixed output set', 'generated-environment');
+        }
+        prior = record.value.published;
+    }
+    const reads = await readAnchoredBatches(serializable.root, [...paths.map(path => ({ path, action: 'read-entry', maxBytes: MAX_GENERATED_BYTES })),
+        { path: OWNERSHIP_PATH, action: 'read-entry', maxBytes: MAX_OWNERSHIP_BYTES },
+        ...(prior ? [{ path: BOOTSTRAP_CONFIGURATION_PATH, action: 'read-entry', maxBytes: MAX_GENERATED_BYTES }] : [])], node, adapters);
+    if (!reads || reads.kind !== 'complete' || reads.results.length !== paths.length + 1 + (prior ? 1 : 0)) {
+        return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap destinations could not be classified safely', 'generated-environment');
+    }
+    const ledger = reads.results[paths.length];
+    if (ledger.kind !== 'missing')
+        return refuse('GENERATED_OWNERSHIP_INVALID', 'bootstrap publication cannot replace ownership metadata', OWNERSHIP_PATH);
+    const configuration = prior && reads.results[paths.length + 1];
+    if (configuration && configuration.kind !== 'missing')
+        return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap refresh requires configuration to remain absent', BOOTSTRAP_CONFIGURATION_PATH);
+    const checks = [];
+    for (const [index, entry] of desired.entries()) {
+        if (entry.kind !== 'file')
+            return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap output is not a whole file', entry.path);
+        const current = reads.results[index];
+        if (current.kind === 'complete' || current.kind === 'invalid' || current.kind === 'other' || current.kind === 'symlink') {
+            return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap destination is not an anchored regular file or missing', entry.path);
+        }
+        const expected = expectedState(current);
+        if (!expected)
+            return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap destination state is unknown', entry.path);
+        const mutation = mutations.find(row => row.path === entry.path);
+        if (mutation && (!sameExpected(expected, mutation.expected) || mutation.bytes !== entry.bytes || mutation.sha256 !== entry.sha256)) {
+            return refuse('GENERATED_SOURCE_CHANGED', 'bootstrap destination or postimage changed after classification', entry.path);
+        }
+        const priorEntry = prior?.[index];
+        const refreshCurrent = priorEntry?.path === entry.path && current.kind === 'file'
+            && (current.sha256 === priorEntry.sha256 || current.sha256 === entry.sha256);
+        const refreshMutation = refreshCurrent && current.sha256 === priorEntry.sha256 && priorEntry.sha256 !== entry.sha256;
+        if (prior
+            ? !refreshCurrent || refreshMutation !== (mutation !== undefined)
+            : current.kind === 'missing' ? !mutation : current.kind !== 'file' || current.sha256 !== entry.sha256 || mutation !== undefined) {
+            return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap plan must write each missing output and preserve each exact output', entry.path);
+        }
+        checks.push({ path: entry.path, expected, maxBytes: current.kind === 'file' ? Math.max(1, current.bytes.byteLength) : 1,
+            ...(current.kind === 'file' ? { identity: current.identity } : {}) });
+    }
+    checks.push({ path: OWNERSHIP_PATH, expected: { kind: 'missing' }, maxBytes: 1 });
+    if (prior)
+        checks.push({ path: BOOTSTRAP_CONFIGURATION_PATH,
+            expected: { kind: 'missing' }, maxBytes: 1 });
+    const groups = groupMutations(mutations);
+    const count = groups?.reduce((total, group) => total + group.logicalWeight, 0) ?? 0;
+    if (!groups || count > desired.length || count * PUBLICATION_HELPER_CALLS_PER_GROUP * PUBLICATION_HELPER_SLOT_MS > TRANSACTION_TIMEOUT_MS) {
+        return refuse('GENERATED_PUBLICATION_FAILED', 'bootstrap publication exceeds the bounded helper schedule', 'generated-environment');
+    }
+    const ordered = groups.flatMap(group => group.mutations);
+    const changes = ordered.map(row => ({ operation: 'write', path: row.path }));
+    const plan = { changes, record: { root: serializable.root, rootIdentity: serializable.rootIdentity, node,
+            mutations: ordered, groups, changes, checks } };
+    return { kind: 'complete', plan };
+}
+async function planCurrent(record, adapters, deadline, published = false) {
+    const checks = published ? record.checks.filter(row => !record.mutations.some(mutation => mutation.path === row.path)) : record.checks;
+    const reads = await readAnchoredBatches(record.root, checks.map(row => ({ path: row.path, action: 'read-entry', maxBytes: row.maxBytes })), record.node, adapters, deadline);
+    return reads?.kind === 'complete' && reads.results.length === checks.length && reads.results.every((read, index) => {
+        if (read.kind === 'complete')
+            return false;
+        const expected = checks[index];
+        const state = expectedState(read);
+        return state !== undefined && sameExpected(state, expected.expected)
+            && (!expected.identity || read.kind === 'file' && sameIdentity(read.identity, expected.identity));
+    });
+}
+/** Admit exact classified leaves against the observed durable ledger, never raw delete authority. */
+export async function admitPublicationPlan(input, adapters) {
+    try {
+        return await admitPlan(input, adapters);
+    }
+    catch (error) {
+        return refuse('GENERATED_PUBLICATION_FAILED', `publication input, ownership or target observation could not be authenticated: ${errorCause(error)}`, 'generated-environment');
+    }
+}
+async function admitPlan(input, adapters) {
+    const supplied = ownRecord(input);
+    if (supplied?.mode === 'bootstrap')
+        return admitBootstrapPlan(input, adapters);
+    const captured = snapshotGeneratedJson(supplied);
+    const fields = ownRecord(captured);
+    if (!captured || !fields || !exactKeys(fields, ['authority', 'generation', 'sourceSha256', 'rootIdentity', 'node', 'mode', 'ledgerExpected', 'nextLedgerBytes', 'mutations',
+        ...(Object.hasOwn(fields, 'surfaceActions') ? ['surfaceActions'] : [])])
+        || captured.mode !== 'sync'
+        || !captured.authority || !isAbsolute(captured.authority.root)
+        || dirname(captured.authority.configPath) !== captured.authority.root
+        || !SHA256.test(captured.generation) || !SHA256.test(captured.sourceSha256)
+        || !directoryIdentity(captured.rootIdentity) || !Array.isArray(captured.mutations) || captured.mutations.length > MAX_OWNED_FILES
+        || !captured.node || !isAbsolute(captured.node.canonicalPath) || !SHA256.test(captured.node.sha256)) {
+        return refuse('GENERATED_PUBLICATION_FAILED', 'publication input is not a bounded exact plan', 'generated-environment');
+    }
+    const { authority, node } = captured;
+    const ledger = await readAnchoredEntry(authority.root, OWNERSHIP_PATH, MAX_OWNERSHIP_BYTES, node, adapters);
+    const ledgerState = expectedState(ledger);
+    if (!ledgerState || !captured.ledgerExpected || !sameExpected(ledgerState, captured.ledgerExpected)) {
+        return refuse('GENERATED_OWNERSHIP_INVALID', 'generated ownership metadata changed after observation', OWNERSHIP_PATH);
+    }
+    let prior;
+    if (ledger.kind === 'file') {
+        let parsed;
+        try {
+            parsed = parseOwnershipManifest(new TextDecoder('utf-8', { fatal: true }).decode(ledger.bytes), authority);
+        }
+        catch { /* Invalid bytes refuse below. */ }
+        if (!parsed || parsed.kind !== 'complete')
+            return refuse('GENERATED_OWNERSHIP_INVALID', 'publication requires authenticated ownership metadata', OWNERSHIP_PATH);
+        prior = parsed.manifest;
+    }
+    else if (ledger.kind !== 'missing') {
+        return refuse('GENERATED_OWNERSHIP_INVALID', 'generated ownership metadata is not a regular file', OWNERSHIP_PATH);
+    }
+    const parsedNext = typeof captured.nextLedgerBytes === 'string' ? parseOwnershipManifest(captured.nextLedgerBytes, authority) : undefined;
+    if (parsedNext?.kind !== 'complete' || parsedNext.manifest.cockpitId !== authority.cockpitId || parsedNext.manifest.generation !== captured.generation
+        || parsedNext.manifest.source.sha256 !== captured.sourceSha256)
+        return refuse('GENERATED_OWNERSHIP_INVALID', 'publication ledger does not match its declared authority', OWNERSHIP_PATH);
+    const next = parsedNext.manifest;
+    const priorProjection = prior && projectGeneratedPathFacts(prior, authority, []);
+    if (priorProjection && priorProjection.kind !== 'complete')
+        return refuse('GENERATED_OWNERSHIP_INVALID', 'publication requires authenticated prior ownership facts', OWNERSHIP_PATH);
+    const nextProjection = projectGeneratedPathFacts(next, authority, []);
+    if (nextProjection.kind !== 'complete')
+        return refuse('GENERATED_OWNERSHIP_INVALID', 'publication requires authenticated resulting ownership facts', OWNERSHIP_PATH);
+    const priorFacts = new Map(priorProjection?.facts.map(fact => [fact.path, fact]));
+    const nextFacts = new Map(nextProjection.facts.map(fact => [fact.path, fact]));
+    // Only an unchanged authenticated estate can authorize restoration of corrupt bytes.
+    const restorationEstate = prior?.format === 'cockpit-generated-ownership/v3'
+        && next.format === 'cockpit-generated-ownership/v3' && prior.cockpitId === next.cockpitId
+        && prior.generation === next.generation && prior.source.path === next.source.path && prior.source.sha256 === next.source.sha256
+        && prior.producer !== null && next.producer !== null && prior.producer.package === next.producer.package
+        && prior.producer.version === next.producer.version && prior.producer.sourceRevision === next.producer.sourceRevision
+        && isDeepStrictEqual(prior.entries, next.entries);
+    const mutations = [...captured.mutations];
+    if (!portablePublicationPaths(mutations.map(row => row.path)))
+        return refuse('GENERATED_PUBLICATION_FAILED', 'generated output names alias or cannot be transferred between supported filesystems; rename the declared outputs and rerun npx --no cockpit sync --config <your cockpit.toml> --dry-run', 'generated-environment');
+    if (new Set(mutations.map(row => row.path)).size !== mutations.length
+        || mutations.some(row => !exactPath(authority.root, row.path) || row.path === OWNERSHIP_PATH || row.phase === 'ledger'
+            || !['desired', 'stale'].includes(row.phase) || !['write-file', 'write-symlink', 'remove-file', 'remove-symlink'].includes(row.operation))) {
+        return refuse('GENERATED_PUBLICATION_FAILED', 'publication contains an undeclared or non-exact operation', 'generated-environment');
+    }
+    const paths = [...new Set([...(prior?.entries ?? []).map(row => row.path), ...next.entries.map(row => row.path)])].sort(compareCodeUnits);
+    if (!portablePublicationPaths(paths))
+        return refuse('GENERATED_PUBLICATION_FAILED', 'generated output names alias or cannot be transferred between supported filesystems; rename the declared outputs and rerun npx --no cockpit sync --config <your cockpit.toml> --dry-run', 'generated-environment');
+    if (mutations.some(row => !paths.includes(row.path)))
+        return refuse('GENERATED_PUBLICATION_FAILED', 'publication operation is absent from both ownership ledgers', 'generated-environment');
+    // Sizes allocate bounded batches; anchored reads still authenticate every target and refuse growth.
+    const maxBytes = await Promise.all(paths.map(async (path) => {
+        if (!exactPath(authority.root, path))
+            return undefined;
+        try {
+            const status = await lstat(join(authority.root, path));
+            if (!status.isFile() || status.isSymbolicLink())
+                return 1;
+            if (!Number.isSafeInteger(status.size) || status.size < 0)
+                return undefined;
+            return Math.min(MAX_GENERATED_BYTES, Math.max(1, status.size));
+        }
+        catch (error) {
+            return hasErrorCode(error, 'ENOENT') ? 1 : undefined;
+        }
+    }));
+    if (maxBytes.some(limit => limit === undefined))
+        return refuse('GENERATED_PUBLICATION_FAILED', 'publication targets could not be classified safely', 'generated-environment');
+    const reads = await readAnchoredBatches(authority.root, paths.map((path, index) => ({ path, action: 'read-entry', maxBytes: maxBytes[index] })), node, adapters);
+    if (!reads || reads.kind !== 'complete' || reads.results.length !== paths.length)
+        return refuse('GENERATED_PUBLICATION_FAILED', 'publication targets could not be classified safely', 'generated-environment');
+    const checks = [];
+    for (const [index, path] of paths.entries()) {
+        const current = reads.results[index];
+        if (current.kind === 'complete')
+            return refuse('GENERATED_PUBLICATION_FAILED', 'publication observation has the wrong kind', path);
+        const expected = expectedState(current);
+        if (!expected)
+            return refuse('GENERATED_PUBLICATION_FAILED', 'publication target kind is unknown', path);
+        const previous = prior?.entries.find(row => row.path === path);
+        const desired = next.entries.find(row => row.path === path);
+        const priorFact = priorFacts.get(path);
+        const nextFact = nextFacts.get(path);
+        if (previous && !priorFact || desired && !nextFact)
+            return refuse('GENERATED_OWNERSHIP_INVALID', 'publication target lacks authenticated ownership facts', path);
+        const mutation = mutations.find(row => row.path === path);
+        if (mutation && !sameExpected(expected, mutation.expected))
+            return refuse('GENERATED_SOURCE_CHANGED', 'publication target changed after classification', path);
+        const priorState = previous && classifyEntry(priorFact, current);
+        const restoration = restorationEstate && priorState === 'modified' && current.kind === 'file'
+            && previous?.kind === 'file' && desired?.kind === 'file' && mutation?.phase === 'desired'
+            && mutation.operation === 'write-file' && mutation.sha256 === previous.sha256;
+        if (previous && current.kind !== 'missing' && priorState !== 'unchanged' && !restoration)
+            return refuse('GENERATED_STALE_ARTIFACT_DRIFT', 'owned target has changed or its confinement is unknown', path);
+        if (!mutation) {
+            if (desired ? classifyEntry(nextFact, current) !== 'unchanged' : current.kind !== 'missing') {
+                return refuse('GENERATED_PUBLICATION_FAILED', 'complete publication plan omitted a required operation', path);
+            }
+        }
+        else if (!desired) {
+            if (!previous || priorState !== 'unchanged' || mutation.phase !== 'stale')
+                return refuse('GENERATED_PUBLICATION_FAILED', 'destructive operation lacks exact classified prior ownership', path);
+            if (previous.kind === 'shared-region' && current.kind === 'file') {
+                const removed = removeSharedOwnership(new TextDecoder('utf-8', { fatal: true }).decode(current.bytes), previous, prior);
+                if (removed.kind !== 'complete' || mutation.operation !== 'write-file' || mutation.bytes !== removed.bytes
+                    || mutation.sha256 !== sha256Hex(removed.bytes))
+                    return refuse('GENERATED_PUBLICATION_FAILED', 'shared removal must preserve the exact foreign postimage', path);
+            }
+            else if (mutation.operation !== 'remove-file') {
+                return refuse('GENERATED_PUBLICATION_FAILED', 'removal does not name the exact owned leaf kind', path);
+            }
+        }
+        else {
+            if (mutation.phase !== 'desired' || mutation.operation.startsWith('remove-') || !previous && current.kind !== 'missing' && desired.kind !== 'shared-region') {
+                return refuse('GENERATED_PUBLICATION_FAILED', 'write destination lacks applicable ownership', path);
+            }
+            if (mutation.operation !== 'write-file' || typeof mutation.bytes !== 'string' || Buffer.byteLength(mutation.bytes) > MAX_GENERATED_BYTES
+                || mutation.sha256 !== sha256Hex(mutation.bytes))
+                return refuse('GENERATED_PUBLICATION_FAILED', 'file publication has invalid bounded bytes', path);
+            const post = { kind: 'file', bytes: Buffer.from(mutation.bytes), sha256: mutation.sha256, identity: current.kind === 'file' ? current.identity
+                    : { root: captured.rootIdentity, chain: [], file: captured.rootIdentity }, mode: 0o600 };
+            if (classifyEntry(nextFact, post) !== 'unchanged')
+                return refuse('GENERATED_PUBLICATION_FAILED', 'write postimage differs from its declared ownership', path);
+            if (desired.kind === 'shared-region') {
+                const before = current.kind === 'file' ? new TextDecoder('utf-8', { fatal: true }).decode(current.bytes) : desired.region.format === 'opencode-json-root-properties' ? '{}' : '';
+                const action = captured.surfaceActions?.find(row => row.path === path);
+                if (!action || action.kind !== 'write' || action.desired.kind !== 'shared-region')
+                    return refuse('GENERATED_PUBLICATION_FAILED', 'shared write has no matching planned surface write', path);
+                // A deleted shared file has no foreign bytes left to protect, so it is recreated from an
+                // empty base exactly as the surface planner did; the prior region would demand bytes that are gone.
+                const rendered = renderSharedPostimage(before, action.desired, current.kind === 'missing' ? undefined : previous);
+                if (rendered.kind !== 'complete' || rendered.bytes !== mutation.bytes || action.postimage !== mutation.bytes)
+                    return refuse('GENERATED_PUBLICATION_FAILED', 'shared write would change foreign bytes', path);
+            }
+        }
+        checks.push({ path, expected, maxBytes: current.kind === 'file' ? Math.max(1, current.bytes.byteLength) : 1, ...(current.kind === 'file' ? { identity: current.identity } : {}) });
+    }
+    checks.push({ path: OWNERSHIP_PATH, expected: ledgerState, maxBytes: ledger.kind === 'file' ? Math.max(1, ledger.bytes.byteLength) : 1, ...(ledger.kind === 'file' ? { identity: ledger.identity } : {}) });
+    if (ledger.kind !== 'file' || ledger.sha256 !== sha256Hex(captured.nextLedgerBytes))
+        mutations.push({ path: OWNERSHIP_PATH, phase: 'ledger', operation: 'write-file',
+            bytes: captured.nextLedgerBytes, sha256: sha256Hex(captured.nextLedgerBytes), expected: ledgerState });
+    const groups = groupMutations(mutations);
+    const count = groups?.reduce((total, group) => total + group.logicalWeight, 0) ?? 0;
+    if (!groups || count > MAX_OWNED_FILES + 1 || count * PUBLICATION_HELPER_CALLS_PER_GROUP * PUBLICATION_HELPER_SLOT_MS > TRANSACTION_TIMEOUT_MS) {
+        return refuse('GENERATED_PUBLICATION_FAILED', 'generated publication exceeds the bounded helper schedule', 'generated-environment');
+    }
+    const ordered = groups.flatMap(group => group.mutations);
+    const staleRemoval = staleRemovalRequest({ cockpitId: authority.cockpitId, generation: captured.generation, sourceSha256: captured.sourceSha256 }, ordered);
+    if (ordered.some(row => row.phase === 'stale') && !staleRemoval)
+        return refuse('GENERATED_STALE_APPROVAL_INVALID', 'stale operations cannot be bound to exact current identities', 'generated-environment');
+    const changes = ordered.map(row => ({ operation: row.operation.startsWith('remove-') ? 'remove' : 'write', path: row.path }));
+    const plan = { changes, ...(staleRemoval ? { staleRemoval } : {}),
+        record: { root: authority.root, rootIdentity: captured.rootIdentity, node, mutations: ordered, groups, changes, checks, ...(staleRemoval ? { staleRemoval } : {}) } };
+    return { kind: 'complete', plan };
+}
+function publicationApproved(plan, adapters) {
+    const { staleRemoval } = plan.record;
+    plan.approval ??= Promise.resolve().then(() => staleRemoval ? staleRemovalApproved(staleRemoval, adapters) : true);
+    return plan.approval;
+}
+function approvalRefusal(record) {
+    return {
+        kind: 'refusal', artifact: null, destination: null, result: null, status: 2,
+        diagnostics: [{
+                severity: 'error',
+                code: 'GENERATED_STALE_APPROVAL_REQUIRED',
+                message: `stale generated ownership requires independent approval bound to the exact current entries (stale-removal digest ${record.staleRemoval.digest})`,
+                target: record.staleRemoval.entries[0].path,
+                fix: 'a person runs npx --no cockpit sync --config <your cockpit.toml> --interactive in a terminal outside CI, reviews the stale entries it lists, and types the digest it shows only if every removal is intended',
+            }],
+    };
+}
+/** Asks for approval before another owner writes; the run reuses this answer instead of asking again. */
+export async function authorizePublicationPlan(plan, adapters) {
+    const admitted = plan;
+    return await publicationApproved(admitted, adapters) ? true : approvalRefusal(admitted.record);
+}
+export async function runPublicationPlan(plan, adapters) {
+    try {
+        return await runPlan(plan, adapters);
+    }
+    catch (error) {
+        return refuse('GENERATED_PUBLICATION_FAILED', `publication owner revalidation failed: ${errorCause(error)}`, 'generated-environment');
+    }
+}
+async function runPlan(plan, adapters) {
+    const admitted = plan;
+    const { record } = admitted;
+    if (adapters.dryRun) {
+        const current = await adapters.revalidate(undefined, 'preview');
+        if (current !== true)
+            return typeof current === 'object' ? current : refuse('GENERATED_SOURCE_CHANGED', 'publication preview inputs changed', 'generated-environment');
+        if (!await planCurrent(record, adapters))
+            return refuse('GENERATED_SOURCE_CHANGED', 'publication preview identities changed', 'generated-environment');
+        return { kind: 'complete', changes: record.changes, committedPaths: [], ...(record.staleRemoval ? { staleRemoval: record.staleRemoval } : {}) };
+    }
+    if (!await publicationApproved(admitted, adapters))
+        return approvalRefusal(record);
+    return applyPrepared(record, adapters);
+}
+async function applyPrepared(prepared, adapters) {
+    const { mutations: publicationMutations, groups } = prepared;
+    const publicationFiles = publicationMutations.filter(row => row.operation === 'write-file')
+        .map(row => ({ path: row.path, bytes: row.bytes, sha256: row.sha256 }));
+    const logicalGroupCount = groups.reduce((count, group) => count + group.logicalWeight, 0);
+    const transactionDeadline = Date.now() + TRANSACTION_TIMEOUT_MS;
+    const forwardCutoff = transactionDeadline - logicalGroupCount * PUBLICATION_HELPER_SLOT_MS;
+    let forwardCallsRemaining = logicalGroupCount * (PUBLICATION_HELPER_CALLS_PER_GROUP - 1);
+    const nextForwardDeadline = (calls = 1) => {
+        if (!Number.isSafeInteger(calls) || calls < 1 || calls > forwardCallsRemaining)
+            return undefined;
+        forwardCallsRemaining -= calls;
+        return forwardCutoff - forwardCallsRemaining * PUBLICATION_HELPER_SLOT_MS;
+    };
+    const node = prepared.node;
+    if (publicationMutations.length === 0) {
+        const transactionRootCurrent = async () => {
+            const current = await lstat(prepared.root);
+            return current.isDirectory() && !current.isSymbolicLink()
+                && current.dev === prepared.rootIdentity.dev && current.ino === prepared.rootIdentity.ino;
+        };
+        if (Date.now() >= forwardCutoff || !await transactionRootCurrent()) {
+            return refuse('GENERATED_SOURCE_CHANGED', 'generated transaction root changed or its deadline expired', 'generated-environment');
+        }
+        // Without writes, final canonical validation and exact admitted identities suffice.
+        const current = await adapters.revalidate(forwardCutoff, 'after-publish');
+        if (current !== true)
+            return typeof current === 'object' ? current : refuse('GENERATED_SOURCE_CHANGED', 'generated inputs changed during unchanged publication', 'generated-environment');
+        if (Date.now() >= forwardCutoff || !await planCurrent(prepared, adapters, forwardCutoff)
+            || !await transactionRootCurrent() || Date.now() >= forwardCutoff) {
+            return refuse('GENERATED_SOURCE_CHANGED', 'generated inputs or target identities changed during unchanged publication', 'generated-environment');
+        }
+        return { kind: 'complete', changes: prepared.changes, committedPaths: [] };
+    }
+    const staged = await stageInputs(publicationFiles);
+    if (!node || !staged)
+        return refuse('GENERATED_PUBLICATION_FAILED', 'generated publication authority could not be prepared', 'generated-environment');
+    const applied = [];
+    let retainInputs = false;
+    try {
+        const transactionRoot = await lstat(prepared.root);
+        const transactionRootIdentity = prepared.rootIdentity;
+        if (!transactionRoot.isDirectory() || transactionRoot.isSymbolicLink()
+            || transactionRoot.dev !== transactionRootIdentity.dev || transactionRoot.ino !== transactionRootIdentity.ino) {
+            throw new RefusalError('generated transaction root is unsafe');
+        }
+        const transactionRootCurrent = async () => {
+            const current = await lstat(prepared.root);
+            return current.isDirectory() && !current.isSymbolicLink()
+                && current.dev === transactionRootIdentity.dev && current.ino === transactionRootIdentity.ino;
+        };
+        if (Date.now() >= forwardCutoff)
+            throw new RefusalError('generated helper schedule exhausted');
+        const beforeStage = await adapters.revalidate(forwardCutoff, 'before-stage');
+        if (beforeStage !== true)
+            return typeof beforeStage === 'object' ? beforeStage : refuse('GENERATED_SOURCE_CHANGED', 'generated inputs changed before staging', 'generated-environment');
+        if (!await planCurrent(prepared, adapters, forwardCutoff)) {
+            return refuse('GENERATED_SOURCE_CHANGED', 'generated inputs or target identities changed before staging', 'generated-environment');
+        }
+        for (const mutation of publicationMutations)
+            if (!confined(prepared.root, mutation.path)) {
+                return refuse('GENERATED_PATH_UNSAFE', 'generated destination is not confined', mutation.path);
+            }
+        // One helper call prepares as many groups as one request frame holds. Prepare never changes a
+        // target, so a run interrupted inside a batch leaves only stage and backup files beside them.
+        for (let next = 0; next < groups.length;) {
+            if (!await transactionRootCurrent())
+                throw new RefusalError('generated transaction root changed');
+            const batch = await prepareBatch(prepared.root, transactionRootIdentity, groups.slice(next), publicationFiles, staged.inputs);
+            const deadline = batch && nextForwardDeadline(batch.rows.reduce((count, row) => count + row.group.logicalWeight, 0));
+            if (!batch || deadline === undefined)
+                throw new RefusalError('generated destination parent is unsafe or its helper schedule is exhausted');
+            const raw = await runHelper(adapters, helperStep(node, prepared.root, 'generated-environment', batch.request, batch.inputs, deadline, MAX_HELPER_FRAME_BYTES * (batch.rows.length + 1)));
+            const receipt = parsePrepareBatchReceipt(raw, batch);
+            if (receipt && receipt.groups.length > 0) {
+                applied.push(...receipt.groups);
+                if (!await recordRecovery(staged.directory, applied))
+                    throw new RefusalError('generated recovery record could not be persisted');
+            }
+            if (!receipt?.complete)
+                throw new RefusalError('generated filesystem helper refused publication');
+            if (!await transactionRootCurrent())
+                throw new RefusalError('generated transaction root changed');
+            next += batch.rows.length;
+        }
+        if (Date.now() >= forwardCutoff)
+            throw new RefusalError('generated helper schedule exhausted');
+        const inputsCurrent = await adapters.revalidate(forwardCutoff, 'before-publish');
+        if (inputsCurrent !== true || !await planCurrent(prepared, adapters, forwardCutoff) || !await transactionRootCurrent()) {
+            if (!await compensate(applied, node, adapters, transactionDeadline)) {
+                retainInputs = true;
+                return refuse('GENERATED_COMPENSATION_FAILED', 'generated inputs changed after preparation and retained backups could not be safely restored; recover retained local backups before retrying', `${applied.at(-1)?.parent ?? 'generated-environment'}; inputs=${staged.directory}`);
+            }
+            return typeof inputsCurrent === 'object' ? inputsCurrent : refuse('GENERATED_SOURCE_CHANGED', 'a generated input changed immediately before publication', 'generated-environment');
+        }
+        if (await runPublicationStage('publish', prepared.root, transactionRootIdentity, applied, node, adapters, nextForwardDeadline) !== 'complete')
+            throw new RefusalError('generated filesystem helper did not confirm publication');
+        if (Date.now() >= forwardCutoff)
+            throw new RefusalError('generated helper schedule exhausted');
+        if (await adapters.revalidate(forwardCutoff, 'after-publish') !== true || !await planCurrent(prepared, adapters, forwardCutoff, true)) {
+            throw new RefusalError('generated input or unchanged target changed during publication');
+        }
+        // A postcheck failure before any backup was retired still rolls back. Retirement can be
+        // partial, so any later or unknown failure retains recovery instead of rolling back.
+        const finalized = await runPublicationStage('commit', prepared.root, transactionRootIdentity, applied, node, adapters, nextForwardDeadline).catch(() => 'failed');
+        if (finalized === 'verify-failed')
+            throw new RefusalError('generated postcheck failed');
+        if (finalized !== 'complete' || forwardCallsRemaining !== 0) {
+            retainInputs = true;
+            return refuse('GENERATED_COMPENSATION_FAILED', 'generated bytes were published but retained backups could not be safely finalized; recover retained local backups before retrying', `${applied.at(-1)?.parent ?? 'generated-environment'}; inputs=${staged.directory}`);
+        }
+        return { kind: 'complete', changes: prepared.changes, committedPaths: prepared.changes.map(row => row.path) };
+    }
+    catch (error) {
+        if (!await compensate(applied, node, adapters, transactionDeadline)) {
+            retainInputs = true;
+            return refuse('GENERATED_COMPENSATION_FAILED', `generated publication failed (${errorCause(error)}) and prior bytes could not be fully restored; recover retained local backups before retrying`, `${applied.at(-1)?.parent ?? 'generated-environment'}; inputs=${staged.directory}`);
+        }
+        return refuse('GENERATED_PUBLICATION_FAILED', `generated files were not published (filesystem transaction refused: ${errorCause(error)})`, 'generated-environment');
+    }
+    finally {
+        if (!retainInputs)
+            await rm(staged.directory, { recursive: true, force: true });
+    }
+}