@deksden-com/dd-flow-cli 0.9.0-beta.136 → 0.9.0-beta.137

package/dist/services/release-source.js

@@ -1,194 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { createPublicKey } from "node:crypto";
-import { AppError } from "../shared/errors.js";
-import { authenticateReleaseEnvelope, releaseProducerKeyId } from "./release-envelope.js";
-import { verifyReleaseArchive } from "./release-manifest.js";
-import { downloadReleaseArchive } from "./release-download.js";
-function refuse(reason) {
-    throw new AppError("release_source", "Release source cannot be read", 1, { reason, phase: "release_source", effect: "no_effect", help: "setup" });
-}
-/** Bounded regular-file reads; paths, parser excerpts and key material never enter diagnostics. */
-export function readBoundedReleaseFile(file, maxBytes) {
-    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
-        refuse("invalid_source_limit");
-    let fd;
-    try {
-        if (!fs.lstatSync(file).isFile())
-            refuse("source_not_regular_file");
-        fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
-    }
-    catch (error) {
-        if (error instanceof AppError)
-            throw error;
-        return refuse("source_unavailable");
-    }
-    try {
-        const stat = fs.fstatSync(fd);
-        if (!stat.isFile() || stat.size < 1 || stat.size > maxBytes)
-            refuse("source_size_outside_limit");
-        const bytes = Buffer.alloc(stat.size);
-        let offset = 0;
-        while (offset < bytes.length) {
-            const received = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
-            if (!received)
-                refuse("source_changed_during_read");
-            offset += received;
-        }
-        if (fs.readSync(fd, Buffer.alloc(1), 0, 1, offset) !== 0)
-            refuse("source_changed_during_read");
-        return bytes;
-    }
-    catch (error) {
-        if (error instanceof AppError)
-            throw error;
-        return refuse("source_unavailable");
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-}
-function json(bytes) {
-    try {
-        return JSON.parse(bytes.toString("utf8"));
-    }
-    catch {
-        return refuse("invalid_source_json");
-    }
-}
-/** Explicit operator trust input is separate from the release bundle. No implicit key enrollment. */
-export function readTrustedReleaseProducers(file) {
-    const input = json(readBoundedReleaseFile(file, 1024 * 1024));
-    if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).length !== 2 || Object.keys(input).some(key => !["producers", "schema_id"].includes(key)))
-        refuse("invalid_trust_shape");
-    const settings = input;
-    if (settings.schema_id !== "dd-flow/release-trust@1" || !Array.isArray(settings.producers) || settings.producers.length < 1 || settings.producers.length > 100)
-        refuse("invalid_trust_shape");
-    const result = new Map();
-    for (const input of settings.producers) {
-        if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).length !== 3 || Object.keys(input).some(key => !["channels", "public_key_pem", "repository"].includes(key)))
-            refuse("invalid_producer_shape");
-        const producer = input;
-        if (typeof producer.public_key_pem !== "string" || !/^-----BEGIN PUBLIC KEY-----\r?\n[A-Za-z0-9+/=\r\n]+-----END PUBLIC KEY-----\r?\n?$/.test(producer.public_key_pem) ||
-            typeof producer.repository !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(producer.repository) ||
-            !Array.isArray(producer.channels) || producer.channels.length < 1 || producer.channels.length > 3 ||
-            producer.channels.some(channel => !["stable", "preview", "development"].includes(channel)) || new Set(producer.channels).size !== producer.channels.length)
-            refuse("invalid_producer_scope");
-        try {
-            const publicKey = createPublicKey(producer.public_key_pem), id = releaseProducerKeyId(publicKey);
-            if (result.has(id))
-                refuse("duplicate_producer_key");
-            result.set(id, { publicKey, repository: producer.repository, channels: new Set(producer.channels) });
-        }
-        catch (error) {
-            if (error instanceof AppError)
-                throw error;
-            return refuse("invalid_producer_key");
-        }
-    }
-    return result;
-}
-/** Authenticate metadata before reading archives; all integrity checks precede installation writes. */
-export function readLocalReleaseBundle(root, producers, compatibility) {
-    try {
-        if (!fs.lstatSync(root).isDirectory())
-            refuse("source_not_directory");
-    }
-    catch (error) {
-        if (error instanceof AppError)
-            throw error;
-        return refuse("source_unavailable");
-    }
-    const envelope = json(readBoundedReleaseFile(path.join(root, "release-envelope.json"), 24 * 1024 * 1024));
-    const authenticated = authenticateReleaseEnvelope(envelope, producers, compatibility);
-    const canonArchive = readBoundedReleaseFile(path.join(root, "canon.tgz"), Math.min(authenticated.manifest.canon.archive.bytes, 256 * 1024 * 1024));
-    const engineArchive = readBoundedReleaseFile(path.join(root, "engine.tgz"), Math.min(authenticated.manifest.engine.archive.bytes, 256 * 1024 * 1024));
-    verifyReleaseArchive(authenticated.manifest.canon.archive, canonArchive);
-    verifyReleaseArchive(authenticated.manifest.engine.archive, engineArchive);
-    return { envelope, authenticated, canonArchive, engineArchive };
-}
-function remoteUrl(input) {
-    let url;
-    try {
-        url = new URL(input);
-    }
-    catch {
-        return refuse("invalid_remote_source");
-    }
-    // The explicit source selects a transport origin, never a signing key.
-    if (url.protocol !== "https:" || url.username || url.password || url.hash || (url.port && url.port !== "443"))
-        refuse("unsafe_remote_source");
-    return url;
-}
-/** Remote metadata is untrusted until signature verification; archives are fetched only afterward.
- * Redirects, cross-origin artifacts and implicit credential forwarding are never admitted.
- */
-export async function readRemoteReleaseBundle(source, producers, compatibility, options = {}) {
-    const url = remoteUrl(source), timeoutMs = options.timeoutMs ?? 60_000;
-    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000)
-        refuse("invalid_source_timeout");
-    const fetcher = options.fetch ?? globalThis.fetch;
-    let response;
-    try {
-        response = await fetcher(url, { redirect: "error", signal: AbortSignal.timeout(timeoutMs), credentials: "omit" });
-    }
-    catch {
-        return refuse("remote_source_unavailable_or_redirect");
-    }
-    if (!response.ok || !response.body) {
-        await response.body?.cancel();
-        return refuse("remote_source_http_failure");
-    }
-    const maxBytes = 24 * 1024 * 1024, length = response.headers.get("content-length");
-    if (length !== null && (!/^[0-9]+$/.test(length) || Number(length) < 1 || Number(length) > maxBytes)) {
-        await response.body.cancel();
-        return refuse("remote_source_size_outside_limit");
-    }
-    const reader = response.body.getReader(), chunks = [];
-    let received = 0;
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            received += value.byteLength;
-            if (received > maxBytes) {
-                await reader.cancel();
-                return refuse("remote_source_size_outside_limit");
-            }
-            chunks.push(Buffer.from(value));
-        }
-    }
-    catch (error) {
-        if (error instanceof AppError)
-            throw error;
-        return refuse("remote_source_interrupted");
-    }
-    finally {
-        reader.releaseLock();
-    }
-    if (!received || (length !== null && Number(length) !== received))
-        refuse("remote_source_length_mismatch");
-    const envelope = json(Buffer.concat(chunks, received));
-    const authenticated = authenticateReleaseEnvelope(envelope, producers, compatibility);
-    if (options.expectedVersion !== undefined && authenticated.manifest.version !== options.expectedVersion)
-        refuse("selected_version_mismatch");
-    for (const artifact of [authenticated.manifest.canon.archive, authenticated.manifest.engine.archive]) {
-        if (remoteUrl(artifact.url).origin !== url.origin)
-            refuse("cross_origin_artifact_refused");
-    }
-    const archives = [];
-    for (const artifact of ["canon", "engine"]) {
-        archives.push(await downloadReleaseArchive(authenticated.manifest[artifact].archive, {
-            allowedHosts: new Set([url.hostname]), timeoutMs, fetch: fetcher,
-            ...(options.onProgress ? { onProgress: progress => options.onProgress({ artifact, ...progress }) } : {})
-        }));
-    }
-    return { envelope, authenticated, canonArchive: archives[0], engineArchive: archives[1] };
-}
-/** One source selector for setup/update; local bundles remain fully offline. */
-export async function readReleaseBundle(source, producers, compatibility, options = {}) {
-    if (/^https?:\/\//i.test(source))
-        return readRemoteReleaseBundle(source, producers, compatibility, options);
-    return readLocalReleaseBundle(source, producers, compatibility);
-}

package/dist/services/setup.js

@@ -1,377 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { createHash, randomUUID } from "node:crypto";
-import { AppError } from "../shared/errors.js";
-import { hybridDigest, validateHybridShape } from "./hybrid-contracts.js";
-import { admitReleaseManifest } from "./release-manifest.js";
-import { validateReleasePayloadIdentity } from "./release-payload.js";
-import { publishReleaseCache, verifyPublishedReleaseCache } from "./release-cache.js";
-import { acquireInstallationLock } from "./installation-lock.js";
-import { authenticateReleaseEnvelope } from "./release-envelope.js";
-import { prepareOperatorProfile, validateProfileCreationIntent, commitProfileCreation, readOperatorProfiles } from "./operator-profiles.js";
-/** Production ingress authenticates the source before constructing any installation authority. */
-export function installAuthenticatedRelease(home, input) {
-    const authenticated = authenticateReleaseEnvelope(input.envelope, input.trustedProducers, input.compatibility);
-    return installRelease(home, { requestId: input.requestId, action: input.action,
-        manifest: authenticated.manifest, manifestBytes: authenticated.manifestBytes, authority: authenticated.authority,
-        canonArchive: input.canonArchive, engineArchive: input.engineArchive,
-        ...(input.executor !== undefined ? { executor: input.executor } : {}),
-        ...(input.profileCreation !== undefined ? { profileCreation: input.profileCreation } : {}),
-        ...(input.deferredOnboarding ? { deferredOnboarding: true } : {}),
-        ...(input.onCheckpoint ? { onCheckpoint: input.onCheckpoint } : {}) });
-}
-function refuse(reason, effect = "no_effect") {
-    throw new AppError("setup_conflict", "Setup request cannot proceed", 1, { reason, phase: "setup", effect, help: "setup", next_action: "dd-flow setup status --json" });
-}
-const bytesDigest = (bytes) => createHash("sha256").update(bytes).digest("hex");
-function manifestFromBytes(bytes) {
-    try {
-        return JSON.parse(bytes.toString("utf8"));
-    }
-    catch {
-        return refuse("invalid_manifest_bytes");
-    }
-}
-function regularJson(file) {
-    if (!fs.lstatSync(file).isFile())
-        refuse("unsafe_setup_file");
-    try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
-    }
-    catch {
-        return refuse("invalid_setup_file");
-    }
-}
-function atomicJson(file, value) {
-    const temporary = `${file}.${randomUUID()}.tmp`;
-    const fd = fs.openSync(temporary, "wx", 0o600);
-    try {
-        try {
-            fs.writeFileSync(fd, JSON.stringify(value));
-            fs.fsyncSync(fd);
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-        fs.renameSync(temporary, file);
-    }
-    finally {
-        if (fs.existsSync(temporary))
-            fs.unlinkSync(temporary);
-    }
-}
-function readSetupRequest(file) {
-    const value = regularJson(file);
-    const required = ["schema_id", "request_id", "identity", "previous_selection", "phase", "installation"];
-    if (!value || typeof value !== "object" || Array.isArray(value)
-        || required.some(key => !Object.hasOwn(value, key))
-        || Object.keys(value).some(key => ![...required, "executor", "profileCreation", "deferredOnboarding"].includes(key)))
-        refuse("invalid_request_record");
-    const request = value;
-    if (Object.hasOwn(request, "deferredOnboarding") && (request.deferredOnboarding !== true || Object.hasOwn(request, "executor") || Object.hasOwn(request, "profileCreation")))
-        refuse("invalid_deferred_onboarding");
-    if (request.schema_id !== "dd-flow/setup-request@1"
-        || typeof request.request_id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(request.request_id)
-        || typeof request.identity !== "string" || !/^[a-f0-9]{64}$/.test(request.identity)
-        || request.previous_selection !== null && (typeof request.previous_selection !== "string" || !/^[a-f0-9]{64}$/.test(request.previous_selection))
-        || !["prepared", "canon_cached", "engine_cached", "profiles_saved", "committed"].includes(request.phase)
-        || !request.installation || typeof request.installation !== "object" || Array.isArray(request.installation))
-        refuse("invalid_request_record");
-    if (Object.hasOwn(request, "executor") && request.executor !== null) {
-        try {
-            prepareOperatorProfile(request.executor);
-        }
-        catch {
-            refuse("invalid_request_executor");
-        }
-    }
-    if (Object.hasOwn(request, "profileCreation")) {
-        try {
-            validateProfileCreationIntent(request.profileCreation);
-        }
-        catch {
-            refuse("invalid_request_profile_creation");
-        }
-        if (!request.executor || hybridDigest(request.executor) !== hybridDigest(request.profileCreation.profile))
-            refuse("request_profile_executor_mismatch");
-    }
-    return request;
-}
-/** Read retained executor consent for an exact retry, without installation or profile effects.
- * Full source/installation request identity is still checked by installRelease.
- */
-export function readRetainedSetupExecutor(home, requestId) {
-    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId))
-        refuse("invalid_request");
-    const root = path.resolve(home), directory = path.join(root, "setup-requests");
-    for (const candidate of [root, directory])
-        if (fs.existsSync(candidate) && !fs.lstatSync(candidate).isDirectory())
-            refuse("unsafe_setup_directory");
-    const file = path.join(directory, `${requestId}.json`);
-    if (!fs.existsSync(file))
-        return null;
-    const request = readSetupRequest(file);
-    if (request.request_id !== requestId)
-        refuse("request_identity_conflict");
-    if (!Object.hasOwn(request, "executor"))
-        return null;
-    return { executor: structuredClone(request.executor ?? null),
-        ...(request.profileCreation ? { profileCreation: structuredClone(request.profileCreation) } : {}) };
-}
-/** A deferred request is immutable installation consent, not an implicit skip. */
-export function hasDeferredSetupOnboarding(home, requestId) {
-    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId))
-        refuse("invalid_request");
-    const root = path.resolve(home), directory = path.join(root, "setup-requests");
-    for (const candidate of [root, directory])
-        if (fs.existsSync(candidate) && !fs.lstatSync(candidate).isDirectory())
-            refuse("unsafe_setup_directory");
-    const file = path.join(directory, `${requestId}.json`);
-    if (!fs.existsSync(file))
-        return false;
-    const request = readSetupRequest(file);
-    if (request.request_id !== requestId)
-        refuse("request_identity_conflict");
-    return request.deferredOnboarding === true;
-}
-function deferredRequest(home, requestId) {
-    if (!hasDeferredSetupOnboarding(home, requestId))
-        refuse("onboarding_not_deferred");
-    const request = readSetupRequest(path.join(path.resolve(home), "setup-requests", `${requestId}.json`));
-    if (request.phase !== "committed")
-        refuse("installation_not_committed");
-    return request;
-}
-/** Retained consent allows recovery without asking again or importing current defaults. */
-export function readSetupOnboarding(home, requestId) {
-    const request = deferredRequest(home, requestId);
-    const directory = path.join(path.resolve(home), "setup-onboarding");
-    if (fs.existsSync(directory) && !fs.lstatSync(directory).isDirectory())
-        refuse("unsafe_onboarding_directory");
-    const file = path.join(directory, `${requestId}.json`);
-    if (!fs.existsSync(file))
-        return null;
-    const receipt = regularJson(file);
-    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)
-        || Object.keys(receipt).some(key => !["schema_id", "request_id", "installation_identity", "phase", "executor", "profileCreation"].includes(key))
-        || receipt.schema_id !== "dd-flow/setup-onboarding@1" || receipt.request_id !== requestId
-        || receipt.installation_identity !== request.identity || !["selected", "committed"].includes(receipt.phase)
-        || !Object.hasOwn(receipt, "executor"))
-        refuse("invalid_onboarding_receipt");
-    try {
-        if (receipt.executor !== null)
-            prepareOperatorProfile(receipt.executor);
-        if (receipt.profileCreation !== undefined) {
-            validateProfileCreationIntent(receipt.profileCreation);
-            if (!receipt.executor || hybridDigest(receipt.executor) !== hybridDigest(receipt.profileCreation.profile))
-                refuse("onboarding_profile_mismatch");
-        }
-    }
-    catch {
-        refuse("invalid_onboarding_receipt");
-    }
-    return structuredClone(receipt);
-}
-/** Persist human consent before profile effects; replay never restores later profile edits. */
-export function commitSetupOnboarding(home, requestId, selection) {
-    const request = deferredRequest(home, requestId), root = path.resolve(home);
-    const executor = selection.executor === null ? null : prepareOperatorProfile(selection.executor);
-    if (selection.profileCreation) {
-        validateProfileCreationIntent(selection.profileCreation);
-        if (!executor || hybridDigest(executor) !== hybridDigest(selection.profileCreation.profile))
-            refuse("onboarding_profile_mismatch");
-    }
-    const candidate = { schema_id: "dd-flow/setup-onboarding@1", request_id: requestId,
-        installation_identity: request.identity, phase: "selected", executor,
-        ...(selection.profileCreation ? { profileCreation: selection.profileCreation } : {}) };
-    const lease = acquireInstallationLock(path.join(root, "setup.lock"), hybridDigest({ request_id: requestId, identity: request.identity }));
-    let failure, result;
-    try {
-        const retained = readSetupOnboarding(root, requestId);
-        if (retained && hybridDigest({ ...retained, phase: "selected" }) !== hybridDigest(candidate))
-            refuse("onboarding_selection_conflict");
-        if (retained?.phase === "committed")
-            result = retained;
-        else {
-            if (hybridDigest(readSetupStatus(root).installation) !== hybridDigest(request.installation))
-                refuse("onboarding_installation_changed");
-            const directory = path.join(root, "setup-onboarding");
-            fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
-            const file = path.join(directory, `${requestId}.json`);
-            if (!retained)
-                atomicJson(file, candidate);
-            if (candidate.profileCreation)
-                commitProfileCreation(root, candidate.profileCreation);
-            result = { ...candidate, phase: "committed" };
-            atomicJson(file, result);
-        }
-    }
-    catch (error) {
-        failure = error instanceof AppError ? error : new AppError("setup_onboarding_interrupted", "Installed release is retained; executor onboarding requires reconciliation", 1, { phase: "executor_onboarding", effect: "unknown", request_id: requestId, help: "setup", next_action: "Replay the exact setup request" });
-    }
-    finally {
-        try {
-            lease.release();
-        }
-        catch {
-            if (failure)
-                failure.details.cleanup = "not_confirmed";
-            else
-                failure = new AppError("setup_cleanup_failed", "Onboarding owner cleanup requires reconciliation", 1, { effect: "unknown", cleanup: "not_confirmed", request_id: requestId, help: "setup" });
-        }
-    }
-    if (failure)
-        throw failure;
-    return result;
-}
-/** Read-only global readiness. No SQLite connection, migration, project registration or probes. */
-export function readSetupStatus(home) {
-    const root = path.resolve(home);
-    if (fs.existsSync(root) && !fs.lstatSync(root).isDirectory())
-        refuse("unsafe_setup_home");
-    const file = path.join(root, "installation.json");
-    const installation = fs.existsSync(file) ? regularJson(file) : null;
-    if (installation) {
-        if (!installation.manifest || typeof installation.manifest_bytes_base64 !== "string" || validateHybridShape("release-manifest", installation.manifest).length ||
-            installation.canon_root !== path.join(root, "release-cache", "canon", installation.manifest.canon.version, "payload") ||
-            installation.engine_root !== path.join(root, "release-cache", "engine", installation.manifest.engine.version, "payload"))
-            refuse("invalid_installation_selection");
-        const bytes = Buffer.from(installation.manifest_bytes_base64, "base64");
-        if (bytes.toString("base64") !== installation.manifest_bytes_base64 || bytesDigest(bytes) !== installation.manifest_sha256 ||
-            hybridDigest(manifestFromBytes(bytes)) !== hybridDigest(installation.manifest))
-            refuse("invalid_installation_selection");
-    }
-    let readiness = installation ? "installed" : "not_installed";
-    if (installation) {
-        try {
-            verifyPublishedReleaseCache(path.dirname(installation.canon_root), installation.manifest.canon.archive);
-            verifyPublishedReleaseCache(path.dirname(installation.engine_root), installation.manifest.engine.archive);
-        }
-        catch {
-            readiness = "degraded";
-        }
-    }
-    const existingStorage = fs.existsSync(path.join(root, "db.sqlite"));
-    return { installation, installation_readiness: readiness,
-        storage_readiness: existingStorage ? "unknown_requires_diagnostic" : "not_initialized",
-        runtime_readiness: "unknown_requires_qualification",
-        next_action: !installation ? "dd-flow setup --help" : existingStorage ? "dd-flow migration plan --help" : "dd-flow engine doctor --json",
-        ...(existingStorage ? { storage_continuation: { kind: "storage_admission",
-                status: "requires_diagnostic", reason: "existing_storage_not_inspected",
-                help_command: "dd-flow migration plan --help", automatic_migration: false } } : {}) };
-}
-/** Exact-request installation transaction. Selected immutable caches do not affect existing RUNs. */
-export function installRelease(home, input) {
-    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(input.requestId) || !["install", "update"].includes(input.action))
-        refuse("invalid_request");
-    const executor = input.executor === undefined ? undefined : input.executor === null ? null : prepareOperatorProfile(input.executor);
-    const executorBinding = executor === undefined ? {} : { executor: structuredClone(executor) };
-    if (input.deferredOnboarding !== undefined && (input.deferredOnboarding !== true || executor !== undefined || input.profileCreation !== undefined))
-        refuse("invalid_deferred_onboarding");
-    const onboardingBinding = input.deferredOnboarding ? { deferredOnboarding: true } : {};
-    if (input.profileCreation !== undefined) {
-        validateProfileCreationIntent(input.profileCreation);
-        if (!executor || hybridDigest(executor) !== hybridDigest(input.profileCreation.profile))
-            refuse("profile_executor_mismatch");
-    }
-    const profileBinding = input.profileCreation === undefined ? {} : { profileCreation: structuredClone(input.profileCreation) };
-    const manifest = admitReleaseManifest(input.manifest, input.authority);
-    if (!Buffer.isBuffer(input.manifestBytes) || hybridDigest(manifestFromBytes(input.manifestBytes)) !== hybridDigest(manifest))
-        refuse("manifest_bytes_mismatch");
-    // Both archives must be valid before even creating the home or publishing the first cache.
-    validateReleasePayloadIdentity(manifest, input.canonArchive, input.engineArchive);
-    const root = path.resolve(home), requests = path.join(root, "setup-requests"), lock = path.join(root, "setup.lock");
-    const installation = { manifest, manifest_sha256: bytesDigest(input.manifestBytes), manifest_bytes_base64: input.manifestBytes.toString("base64"),
-        canon_root: path.join(root, "release-cache", "canon", manifest.canon.version, "payload"),
-        engine_root: path.join(root, "release-cache", "engine", manifest.engine.version, "payload") };
-    const identity = hybridDigest({ action: input.action, installation, ...executorBinding, ...profileBinding, ...onboardingBinding });
-    readSetupStatus(root);
-    for (const directory of [root, requests]) {
-        if (fs.existsSync(directory) && !fs.lstatSync(directory).isDirectory())
-            refuse("unsafe_setup_directory");
-    }
-    if (input.profileCreation) {
-        const existingFile = path.join(requests, `${input.requestId}.json`);
-        const retained = fs.existsSync(existingFile) ? readSetupRequest(existingFile) : null;
-        if (retained?.phase !== "committed") {
-            const revision = readOperatorProfiles(root).revision;
-            if (revision !== input.profileCreation.before.revision && revision !== input.profileCreation.after.revision)
-                refuse("profile_selection_changed");
-        }
-    }
-    fs.mkdirSync(requests, { recursive: true, mode: 0o700 });
-    const lease = acquireInstallationLock(lock, hybridDigest({ request_id: input.requestId, identity }));
-    let failure;
-    const perform = () => {
-        const file = path.join(requests, `${input.requestId}.json`);
-        const current = readSetupStatus(root).installation;
-        let request = { schema_id: "dd-flow/setup-request@1", request_id: input.requestId, identity,
-            previous_selection: current ? hybridDigest(current) : null, phase: "prepared", installation, ...executorBinding, ...profileBinding, ...onboardingBinding };
-        if (fs.existsSync(file)) {
-            request = readSetupRequest(file);
-            if (request.schema_id !== "dd-flow/setup-request@1" || request.request_id !== input.requestId || request.identity !== identity || hybridDigest(request.installation) !== hybridDigest(installation))
-                refuse("request_identity_conflict");
-            if (request.deferredOnboarding !== input.deferredOnboarding)
-                refuse("request_onboarding_conflict");
-            if (hybridDigest({ executor: request.executor ?? null, present: Object.hasOwn(request, "executor") }) !==
-                hybridDigest({ executor: executor ?? null, present: executor !== undefined }))
-                refuse("request_executor_conflict");
-            if (hybridDigest({ profileCreation: request.profileCreation ?? null }) !== hybridDigest({ profileCreation: input.profileCreation ?? null }))
-                refuse("request_profile_creation_conflict");
-            if (!["prepared", "canon_cached", "engine_cached", "profiles_saved", "committed"].includes(request.phase))
-                refuse("invalid_request_phase");
-        }
-        // Replay still revalidates retained payload bytes; it never reactivates an older selection.
-        if (request.phase === "committed") {
-            publishReleaseCache(root, "canon", manifest.canon.version, manifest.canon.archive, input.canonArchive);
-            publishReleaseCache(root, "engine", manifest.engine.version, manifest.engine.archive, input.engineArchive);
-            return { ok: true, replayed: true, installation: request.installation, ...executorBinding };
-        }
-        const selectedDigest = current ? hybridDigest(current) : null;
-        if (selectedDigest !== request.previous_selection && selectedDigest !== hybridDigest(installation))
-            refuse("selection_changed_since_request");
-        if (input.action === "install" && current && selectedDigest !== hybridDigest(installation))
-            refuse("existing_installation_requires_update");
-        const checkpoint = (phase) => {
-            request.phase = phase;
-            atomicJson(file, request);
-            input.onCheckpoint?.(phase);
-        };
-        checkpoint("prepared");
-        publishReleaseCache(root, "canon", manifest.canon.version, manifest.canon.archive, input.canonArchive);
-        checkpoint("canon_cached");
-        publishReleaseCache(root, "engine", manifest.engine.version, manifest.engine.archive, input.engineArchive);
-        checkpoint("engine_cached");
-        if (request.profileCreation) {
-            commitProfileCreation(root, request.profileCreation);
-            checkpoint("profiles_saved");
-        }
-        atomicJson(path.join(root, "installation.json"), installation);
-        checkpoint("committed");
-        return { ok: true, replayed: false, installation, ...executorBinding };
-    };
-    let result;
-    try {
-        result = perform();
-    }
-    catch (error) {
-        failure = error instanceof AppError ? error : new AppError("setup_interrupted", "Setup request requires reconciliation", 1, { phase: "setup", effect: "unknown", request_id: input.requestId, next_action: "Replay the exact setup request", help: "setup" });
-    }
-    finally {
-        try {
-            lease.release();
-        }
-        catch {
-            // Cleanup is secondary to the retained operation result. Never leak a
-            // raw filesystem cause or erase the original failure with an unlink error.
-            if (failure)
-                failure.details.cleanup = "not_confirmed";
-            else
-                failure = new AppError("setup_cleanup_failed", "Setup owner cleanup requires reconciliation", 1, { phase: "setup", effect: "unknown", cleanup: "not_confirmed", request_id: input.requestId,
-                    next_action: "Inspect dd-flow setup status --json; replay the exact request after its owner exits", help: "setup" });
-        }
-    }
-    if (failure)
-        throw failure;
-    return result;
-}