@maiaos/node 0.1.0-canary.44938d4.manual.1

package/dist/configuration/writer.js

@@ -0,0 +1,789 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, opendir, realpath, rename, rmdir, unlink, } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { configProfileNameSchema, MAIA_CONFIG_VERSION } from "@maiaos/protocol";
+import { DateTime, Effect, Schema } from "effect";
+import { asNodeRuntimeError, makeNodeRuntimeError, NodeRuntimeError, } from "../runtime/errors.js";
+import { acquireProcessOwnedLock, } from "../runtime/instance-lock.js";
+import { verifyConfigurationDocumentRole, } from "./document-role.js";
+import { discoverUserConfigurationRoot, preparePrivateConfigurationDirectory, prepareUserConfigurationRoot, readConfigurationFile, readConfigurationFileHandle, sameConfigurationFile, sameConfigurationFileSnapshot, } from "./filesystem.js";
+import { parseConfigurationDocument } from "./parser.js";
+import { configurationPolicy } from "./policy.js";
+const BACKUP_DOCUMENT_NAME = "document.jsonc";
+const BACKUP_PROVENANCE_NAME = "provenance.json";
+const BACKUP_CLAIM_PREFIX = ".claim-";
+const TEMPORARY_FILE_PREFIX = ".maia-config-write-";
+const WRITE_LOCK_NAME = ".configuration-write.lock";
+const digestPattern = /^[a-f0-9]{64}$/u;
+const backupIdPattern = /^\d{8}T\d{9}Z-[a-f0-9]{64}-[a-f0-9]{32}$/u;
+const backupClaimPattern = /^\.claim-[a-f0-9]{32}$/u;
+const backupCreatedAtPattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+const configurationRelativePathPattern = /^(?:config\.jsonc|profiles\/([A-Za-z0-9][A-Za-z0-9._-]{0,63})\.jsonc)$/u;
+const temporaryFilePattern = /^\.maia-config-write-[a-f0-9]{32}\.tmp$/u;
+const openReadFlags = constants.O_RDONLY |
+    (process.platform === "win32" ? 0 : constants.O_NOFOLLOW);
+const backupManifestSchema = Schema.Struct({
+    bytes: Schema.Int.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(configurationPolicy.maximumFileBytes)),
+    createdAt: Schema.String.check(Schema.isPattern(backupCreatedAtPattern)),
+    digest: Schema.String.check(Schema.isPattern(digestPattern)),
+    relativePath: Schema.String.check(Schema.isPattern(configurationRelativePathPattern)),
+    version: Schema.Literal(MAIA_CONFIG_VERSION),
+});
+const decodeBackupManifest = Schema.decodeUnknownSync(Schema.fromJsonString(backupManifestSchema), { onExcessProperty: "error" });
+const isNodeErrorCode = (error, code) => error instanceof Error && "code" in error && error.code === code;
+const digestBytes = (contents) => createHash("sha256").update(contents).digest("hex");
+const compactUuid = () => randomUUID().replaceAll("-", "");
+const formatBackupTimestamp = (createdAt) => createdAt.replaceAll(/[-:.]/gu, "");
+const destinationDetails = (destination) => {
+    if (destination.kind === "base") {
+        return { relativePath: "config.jsonc", role: "user-base" };
+    }
+    const profile = configProfileNameSchema.safeParse(destination.profile);
+    if (!profile.success) {
+        throw makeNodeRuntimeError("configuration_invalid", "The Maia configuration destination profile is invalid.");
+    }
+    return {
+        relativePath: `profiles/${profile.data}.jsonc`,
+        role: "user-profile",
+    };
+};
+const validateExpectedDigest = (digest) => {
+    if (digest !== undefined &&
+        (digest.length !== 64 || !digestPattern.test(digest))) {
+        throw makeNodeRuntimeError("configuration_invalid", "The expected Maia configuration digest is invalid.");
+    }
+};
+const prepareContents = (text, role) => {
+    if (text.length > configurationPolicy.maximumFileBytes ||
+        Buffer.byteLength(text, "utf8") > configurationPolicy.maximumFileBytes) {
+        throw makeNodeRuntimeError("configuration_invalid", "The Maia configuration contents exceed their byte limit.");
+    }
+    const bytes = Buffer.from(text, "utf8");
+    if (new TextDecoder("utf-8", { fatal: true }).decode(bytes) !== text) {
+        throw makeNodeRuntimeError("configuration_invalid", "The Maia configuration contents exceed their bounds or are not valid UTF-8.");
+    }
+    const document = parseConfigurationDocument(text);
+    verifyConfigurationDocumentRole(document, role);
+    return { bytes, digest: digestBytes(bytes), text };
+};
+const toWriteError = (error, code = "configuration_write_failed", message = "The Maia configuration could not be written safely.") => asNodeRuntimeError(error, code, message);
+const toRecoveryError = (error, message) => error instanceof NodeRuntimeError &&
+    error.code === "configuration_recovery_required"
+    ? error
+    : makeNodeRuntimeError("configuration_recovery_required", message);
+const ensureExpectedState = (current, expectedDigest) => {
+    const matches = expectedDigest === undefined
+        ? current === undefined
+        : current?.digest === expectedDigest;
+    if (!matches) {
+        throw makeNodeRuntimeError("configuration_conflict", "The Maia configuration changed after it was read.", true);
+    }
+};
+const ensureOwnedPrivateFile = (metadata) => {
+    const owned = typeof process.getuid !== "function" || metadata.uid === process.getuid();
+    const privateMode = process.platform === "win32" || (metadata.mode & 0o077) === 0;
+    if (!metadata.isFile() ||
+        metadata.isSymbolicLink() ||
+        metadata.nlink !== 1 ||
+        !owned ||
+        !privateMode) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "A Maia configuration recovery file is unsafe.");
+    }
+};
+const ensureOwnedPrivateDirectory = async (path) => {
+    const metadata = await lstat(path);
+    const owned = typeof process.getuid !== "function" || metadata.uid === process.getuid();
+    const privateMode = process.platform === "win32" || (metadata.mode & 0o077) === 0;
+    if (!metadata.isDirectory() ||
+        metadata.isSymbolicLink() ||
+        !owned ||
+        !privateMode ||
+        (await realpath(path)) !== path) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "A Maia configuration recovery directory is unsafe.");
+    }
+    return metadata;
+};
+const ensureFileWithinBounds = (metadata, maximumBytes) => {
+    ensureOwnedPrivateFile(metadata);
+    if (metadata.size > maximumBytes) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "A Maia configuration recovery file exceeds its byte limit.");
+    }
+};
+const verifyStableFileRead = (read) => {
+    if (read.contents.byteLength > read.maximumBytes ||
+        read.canonical !== read.path ||
+        !sameConfigurationFileSnapshot(read.before, read.after) ||
+        !sameConfigurationFileSnapshot(read.before, read.current)) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "A Maia configuration recovery file changed while it was read.");
+    }
+    return read.contents;
+};
+const readBoundedRecoveryContents = async (handle, maximumBytes) => {
+    try {
+        return await readConfigurationFileHandle(handle, maximumBytes);
+    }
+    catch (error) {
+        throw toRecoveryError(error, "A Maia configuration recovery file exceeds its byte limit.");
+    }
+};
+const readBoundedOwnedFile = async (path, maximumBytes) => {
+    const handle = await open(path, openReadFlags);
+    try {
+        const before = await handle.stat();
+        ensureFileWithinBounds(before, maximumBytes);
+        const contents = await readBoundedRecoveryContents(handle, maximumBytes);
+        const [after, current, canonical] = await Promise.all([
+            handle.stat(),
+            lstat(path),
+            realpath(path),
+        ]);
+        return verifyStableFileRead({
+            after,
+            before,
+            canonical,
+            contents,
+            current,
+            maximumBytes,
+            path,
+        });
+    }
+    finally {
+        await handle.close();
+    }
+};
+const writeExclusiveAndSync = async (path, contents) => {
+    const flags = constants.O_WRONLY |
+        constants.O_CREAT |
+        constants.O_EXCL |
+        (process.platform === "win32" ? 0 : constants.O_NOFOLLOW);
+    const handle = await open(path, flags, 0o600);
+    let complete = false;
+    try {
+        await handle.writeFile(contents);
+        if (process.platform !== "win32")
+            await handle.chmod(0o600);
+        await handle.sync();
+        ensureOwnedPrivateFile(await handle.stat());
+        complete = true;
+    }
+    finally {
+        try {
+            await handle.close();
+        }
+        finally {
+            if (!complete) {
+                await unlink(path).catch((error) => {
+                    if (!isNodeErrorCode(error, "ENOENT"))
+                        throw error;
+                });
+            }
+        }
+    }
+};
+const syncDirectory = async (path) => {
+    if (process.platform === "win32")
+        return;
+    const handle = await open(path, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+};
+const closeDirectory = async (directory) => {
+    try {
+        await directory.close();
+    }
+    catch (error) {
+        if (!isNodeErrorCode(error, "ERR_DIR_CLOSED"))
+            throw error;
+    }
+};
+const readDirectoryNames = async (directory, maximum, names = []) => {
+    if (names.length > maximum)
+        return names;
+    const entry = await directory.read();
+    return entry === null
+        ? names
+        : readDirectoryNames(directory, maximum, [...names, entry.name]);
+};
+const readBoundedDirectoryNames = async (path, maximum) => {
+    const before = await ensureOwnedPrivateDirectory(path);
+    const directory = await opendir(path, { bufferSize: 1 });
+    let names;
+    try {
+        names = await readDirectoryNames(directory, maximum);
+    }
+    finally {
+        await closeDirectory(directory);
+    }
+    const after = await ensureOwnedPrivateDirectory(path);
+    if (!sameConfigurationFile(before, after) || names.length > maximum) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "The Maia configuration backup directory exceeds its entry limit or changed during inspection.");
+    }
+    return names;
+};
+const removeKnownEntries = async (directoryPath, entries) => {
+    await Promise.all(entries.map(async (entry) => {
+        const path = join(directoryPath, entry);
+        ensureOwnedPrivateFile(await lstat(path));
+        await unlink(path);
+    }));
+};
+const verifyKnownEntries = (entries, allowedEntries) => {
+    if (entries.some((entry) => !allowedEntries.includes(entry))) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "A Maia configuration recovery directory contains unexpected entries.");
+    }
+};
+const removeKnownDirectory = async (directoryPath, allowedEntries) => {
+    const generation = await ensureOwnedPrivateDirectory(directoryPath);
+    const entries = await readBoundedDirectoryNames(directoryPath, allowedEntries.length + 1);
+    verifyKnownEntries(entries, allowedEntries);
+    await removeKnownEntries(directoryPath, entries);
+    if (!sameConfigurationFile(generation, await ensureOwnedPrivateDirectory(directoryPath))) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "A Maia configuration recovery directory changed during cleanup.");
+    }
+    await rmdir(directoryPath);
+};
+const cleanBackupClaims = async (backupRoot, names) => {
+    const claims = names.filter((entry) => entry.startsWith("."));
+    if (claims.some((name) => !backupClaimPattern.test(name))) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "The Maia configuration backup directory contains an unknown recovery artifact.");
+    }
+    await Promise.all(claims.map((name) => removeKnownDirectory(join(backupRoot.path, name), [
+        BACKUP_DOCUMENT_NAME,
+        BACKUP_PROVENANCE_NAME,
+    ])));
+};
+const decodeManifestBytes = (manifestBytes) => {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(manifestBytes);
+    }
+    catch (error) {
+        throw toWriteError(error, "configuration_recovery_required", "A Maia configuration backup manifest is not valid UTF-8.");
+    }
+    let manifest;
+    try {
+        manifest = decodeBackupManifest(text);
+    }
+    catch (error) {
+        throw toWriteError(error, "configuration_recovery_required", "A Maia configuration backup manifest is invalid.");
+    }
+    return manifest;
+};
+const readManifest = async (backupPath) => {
+    const manifestBytes = await readBoundedOwnedFile(join(backupPath, BACKUP_PROVENANCE_NAME), configurationPolicy.maximumManifestBytes);
+    const manifest = decodeManifestBytes(manifestBytes);
+    const documentMetadata = await lstat(join(backupPath, BACKUP_DOCUMENT_NAME));
+    ensureOwnedPrivateFile(documentMetadata);
+    if (documentMetadata.size !== manifest.bytes) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "A Maia configuration backup size does not match its manifest.");
+    }
+    return {
+        manifest,
+        storedBytes: manifestBytes.byteLength + documentMetadata.size,
+    };
+};
+const validateBackupEntries = async (directoryPath) => {
+    await ensureOwnedPrivateDirectory(directoryPath);
+    const entries = await readBoundedDirectoryNames(directoryPath, 2);
+    if (entries.length !== 2 ||
+        !entries.includes(BACKUP_DOCUMENT_NAME) ||
+        !entries.includes(BACKUP_PROVENANCE_NAME)) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "A Maia configuration backup is incomplete.");
+    }
+};
+const verifyBackupIdentity = (id, manifest) => {
+    if (id.slice(20, 84) !== manifest.digest ||
+        formatBackupTimestamp(manifest.createdAt) !== id.slice(0, 19)) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "A Maia configuration backup identity is inconsistent.");
+    }
+};
+const inspectBackup = async (backupRoot, id) => {
+    if (!backupIdPattern.test(id)) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "The Maia configuration backup directory contains an unknown entry.");
+    }
+    const directoryPath = join(backupRoot.path, id);
+    await validateBackupEntries(directoryPath);
+    const inspected = await readManifest(directoryPath);
+    verifyBackupIdentity(id, inspected.manifest);
+    return {
+        ...inspected.manifest,
+        directoryPath,
+        id,
+        storedBytes: inspected.storedBytes,
+    };
+};
+const inspectBackups = async (backupRoot) => {
+    const initialNames = await readBoundedDirectoryNames(backupRoot.path, configurationPolicy.maximumBackupDirectoryEntries);
+    await cleanBackupClaims(backupRoot, initialNames);
+    const names = initialNames.filter((name) => !name.startsWith("."));
+    const backups = await Promise.all(names.map((id) => inspectBackup(backupRoot, id)));
+    return backups.toSorted((left, right) => left.createdAt.localeCompare(right.createdAt));
+};
+const prepareBackupRoot = async (root) => {
+    const backups = await preparePrivateConfigurationDirectory(root, join(root.path, "backups"));
+    return preparePrivateConfigurationDirectory(backups, join(backups.path, "config"));
+};
+const makeBackupId = (createdAt, digest) => `${formatBackupTimestamp(createdAt)}-${digest}-${compactUuid()}`;
+const persistBackupClaim = async (claim) => {
+    const writes = await Promise.allSettled([
+        writeExclusiveAndSync(join(claim.claimPath, BACKUP_DOCUMENT_NAME), Buffer.from(claim.previous.text, "utf8")),
+        writeExclusiveAndSync(join(claim.claimPath, BACKUP_PROVENANCE_NAME), claim.manifestBytes),
+    ]);
+    const failed = writes.find((write) => write.status === "rejected");
+    if (failed?.status === "rejected")
+        throw failed.reason;
+    await syncDirectory(claim.claimPath);
+    await rename(claim.claimPath, claim.destinationPath);
+};
+const removeBackupClaim = async (claimPath) => {
+    try {
+        await removeKnownDirectory(claimPath, [
+            BACKUP_DOCUMENT_NAME,
+            BACKUP_PROVENANCE_NAME,
+        ]);
+    }
+    catch (error) {
+        if (!isNodeErrorCode(error, "ENOENT")) {
+            throw makeNodeRuntimeError("configuration_recovery_required", "A failed Maia configuration backup requires recovery.");
+        }
+    }
+};
+const makeBackupManifest = (input) => ({
+    bytes: input.previous.bytes,
+    createdAt: input.createdAt,
+    digest: input.previous.digest,
+    relativePath: input.relativePath,
+    version: MAIA_CONFIG_VERSION,
+});
+const prepareBackupClaim = async (input, id) => {
+    const claimPath = join(input.backupRoot.path, `${BACKUP_CLAIM_PREFIX}${compactUuid()}`);
+    await mkdir(claimPath, { mode: 0o700 });
+    if (process.platform !== "win32")
+        await chmod(claimPath, 0o700);
+    await ensureOwnedPrivateDirectory(claimPath);
+    const manifestBytes = Buffer.from(`${JSON.stringify(makeBackupManifest(input))}\n`, "utf8");
+    return {
+        claimPath,
+        destinationPath: join(input.backupRoot.path, id),
+        manifestBytes,
+        previous: input.previous,
+    };
+};
+const createBackup = async (input) => {
+    const id = makeBackupId(input.createdAt, input.previous.digest);
+    const claim = await prepareBackupClaim(input, id);
+    try {
+        await persistBackupClaim(claim);
+        await syncDirectory(input.backupRoot.path);
+    }
+    catch (error) {
+        await removeBackupClaim(claim.claimPath);
+        throw error;
+    }
+    return {
+        ...makeBackupManifest(input),
+        directoryPath: claim.destinationPath,
+        id,
+        storedBytes: input.previous.bytes + claim.manifestBytes.byteLength,
+    };
+};
+const selectObsoleteBackups = (backups) => {
+    const totalBytes = backups.reduce((total, backup) => total + backup.storedBytes, 0);
+    const select = (remaining, bytes, obsolete = []) => {
+        const oldest = remaining[0];
+        if (oldest === undefined ||
+            (remaining.length <= configurationPolicy.maximumBackups &&
+                bytes <= configurationPolicy.maximumBackupBytes)) {
+            return obsolete;
+        }
+        return select(remaining.slice(1), bytes - oldest.storedBytes, [
+            ...obsolete,
+            oldest,
+        ]);
+    };
+    return select(backups, totalBytes);
+};
+const removeBackup = (backup) => removeKnownDirectory(backup.directoryPath, [
+    BACKUP_DOCUMENT_NAME,
+    BACKUP_PROVENANCE_NAME,
+]);
+const readCurrent = async (root, relativePath, role) => {
+    let current;
+    try {
+        current = await readConfigurationFile({
+            ...root,
+            filePath: join(root.path, relativePath),
+            optional: true,
+        });
+    }
+    catch (error) {
+        throw toWriteError(error, "configuration_invalid", "The Maia configuration destination is unsafe.");
+    }
+    if (current !== undefined) {
+        verifyConfigurationDocumentRole(parseConfigurationDocument(current.text), role);
+    }
+    return current;
+};
+const prepareDestinationDirectory = async (root, relativePath) => {
+    const path = dirname(join(root.path, relativePath));
+    return path === root.path
+        ? root
+        : preparePrivateConfigurationDirectory(root, path);
+};
+const runHook = async (hooks, phase) => {
+    await hooks.afterPhase?.(phase);
+};
+const removeTemporaryFile = async (path) => {
+    try {
+        const metadata = await lstat(path);
+        ensureOwnedPrivateFile(metadata);
+        await unlink(path);
+    }
+    catch (error) {
+        if (!isNodeErrorCode(error, "ENOENT"))
+            throw error;
+    }
+};
+const cleanTemporaryFiles = async (directory) => {
+    const entries = await readBoundedDirectoryNames(directory.path, configurationPolicy.maximumWritableDirectoryEntries);
+    const temporaryFiles = entries.filter((name) => name.startsWith(TEMPORARY_FILE_PREFIX));
+    if (temporaryFiles.some((entry) => !temporaryFilePattern.test(entry))) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "The Maia configuration directory contains an unknown write artifact.");
+    }
+    await Promise.all(temporaryFiles.map((entry) => removeTemporaryFile(join(directory.path, entry))));
+};
+const restorePreviousContents = async (context) => {
+    if (context.previous === undefined) {
+        await unlink(context.destinationPath);
+        return;
+    }
+    const rollbackPath = join(dirname(context.destinationPath), `${TEMPORARY_FILE_PREFIX}${compactUuid()}.tmp`);
+    try {
+        await writeExclusiveAndSync(rollbackPath, Buffer.from(context.previous.text, "utf8"));
+        await rename(rollbackPath, context.destinationPath);
+    }
+    finally {
+        await removeTemporaryFile(rollbackPath);
+    }
+};
+const verifyPreviousRestored = async (context) => {
+    const restored = await readConfigurationFile({
+        ...context.root,
+        filePath: context.destinationPath,
+        optional: true,
+    });
+    if (restored?.digest !== context.previous?.digest) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "The previous Maia configuration could not be restored.");
+    }
+};
+const rollbackReplacement = async (context) => {
+    const current = await readConfigurationFile({
+        ...context.root,
+        filePath: context.destinationPath,
+        optional: true,
+    });
+    if (current?.digest !== context.intended.digest) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "The Maia configuration changed while a failed commit was being recovered.");
+    }
+    await restorePreviousContents(context);
+    await syncDirectory(dirname(context.destinationPath));
+    await verifyPreviousRestored(context);
+};
+const verifyCommittedReplacement = async (context, hooks) => {
+    const verified = await readConfigurationFile({
+        ...context.root,
+        filePath: context.destinationPath,
+        optional: false,
+    });
+    if (verified?.digest !== context.intended.digest) {
+        throw makeNodeRuntimeError("configuration_write_failed", "The committed Maia configuration did not verify.");
+    }
+    parseConfigurationDocument(verified.text);
+    await runHook(hooks, "replacement_verified");
+};
+const recheckBeforeReplacement = async (context) => {
+    const immediatelyBefore = await readCurrent(context.root, context.relativePath, context.relativePath === "config.jsonc" ? "user-base" : "user-profile");
+    ensureExpectedState(immediatelyBefore, context.previous?.digest);
+};
+const recoverCommitFailure = async (context, error) => {
+    try {
+        await rollbackReplacement(context);
+    }
+    catch (rollbackError) {
+        return toRecoveryError(rollbackError, "The Maia configuration commit failed and could not be rolled back safely.");
+    }
+    return toWriteError(error);
+};
+const replaceDestination = async (context, temporaryPath) => {
+    try {
+        await rename(temporaryPath, context.destinationPath);
+    }
+    catch (error) {
+        let current;
+        try {
+            current = await readConfigurationFile({
+                ...context.root,
+                filePath: context.destinationPath,
+                optional: true,
+            });
+        }
+        catch (inspectionError) {
+            throw toRecoveryError(inspectionError, "The Maia configuration replacement outcome could not be verified.");
+        }
+        if (current?.digest === context.intended.digest)
+            return;
+        if (current?.digest === context.previous?.digest)
+            throw error;
+        throw makeNodeRuntimeError("configuration_recovery_required", "The Maia configuration replacement has an unknown outcome.");
+    }
+};
+const performReplacement = async (context, hooks, temporaryPath) => {
+    let destinationReplaced = false;
+    try {
+        await writeExclusiveAndSync(temporaryPath, context.intended.bytes);
+        await runHook(hooks, "temporary_file_synced");
+        await recheckBeforeReplacement(context);
+        await replaceDestination(context, temporaryPath);
+        destinationReplaced = true;
+        await syncDirectory(dirname(context.destinationPath));
+        await runHook(hooks, "destination_replaced");
+        await verifyCommittedReplacement(context, hooks);
+        return;
+    }
+    catch (error) {
+        return destinationReplaced
+            ? recoverCommitFailure(context, error)
+            : toWriteError(error);
+    }
+};
+const commitReplacement = async (context, hooks) => {
+    const temporaryPath = join(dirname(context.destinationPath), `${TEMPORARY_FILE_PREFIX}${compactUuid()}.tmp`);
+    const failure = await performReplacement(context, hooks, temporaryPath);
+    try {
+        await removeTemporaryFile(temporaryPath);
+    }
+    catch (cleanupError) {
+        throw toRecoveryError(cleanupError, "A Maia configuration temporary artifact requires recovery.");
+    }
+    if (failure !== undefined)
+        throw failure;
+};
+const makeLockMetadata = (startedAt) => ({
+    instanceId: compactUuid(),
+    pid: process.pid,
+    startedAt,
+});
+const acquireWriteLock = (root, startedAt) => acquireProcessOwnedLock(join(root.path, WRITE_LOCK_NAME), makeLockMetadata(startedAt)).pipe(Effect.mapError((error) => {
+    if (error.code === "already_running") {
+        return makeNodeRuntimeError("configuration_conflict", "Another Maia configuration writer owns this user root.", true);
+    }
+    if (error.code === "path_invalid") {
+        return toRecoveryError(error, "The Maia configuration write lock could not be acquired safely.");
+    }
+    return toWriteError(error, "configuration_write_failed", "The Maia configuration write lock could not be acquired safely.");
+}));
+const releaseWriteLock = (resource) => resource.release.pipe(Effect.mapError((error) => toRecoveryError(error, "The Maia configuration write completed but its lock could not be released safely.")));
+const prepareWrite = (input) => {
+    validateExpectedDigest(input.expectedDigest);
+    const destination = destinationDetails(input.destination);
+    return {
+        ...(input.expectedDigest === undefined
+            ? {}
+            : { expectedDigest: input.expectedDigest }),
+        intended: prepareContents(input.contents, destination.role),
+        ...destination,
+    };
+};
+const ensureBackupCapacity = (backups) => {
+    if (backups.length >= configurationPolicy.maximumBackupDirectoryEntries) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "The Maia configuration backup directory has no safe commit capacity.");
+    }
+};
+const prepareWriteBackup = async (input, previous) => {
+    if (previous === undefined)
+        return {};
+    const root = await prepareBackupRoot(input.root);
+    ensureBackupCapacity(await inspectBackups(root));
+    const backup = await createBackup({
+        backupRoot: root,
+        createdAt: input.committedAt,
+        previous,
+        relativePath: input.write.relativePath,
+    });
+    try {
+        await runHook(input.hooks, "backup_persisted");
+    }
+    catch (error) {
+        await removeFailedBackup(backup);
+        throw error;
+    }
+    return { backup, root };
+};
+const removeFailedBackup = async (backup) => {
+    try {
+        await removeBackup(backup);
+    }
+    catch (error) {
+        throw toRecoveryError(error, "A failed Maia configuration commit left a backup requiring recovery.");
+    }
+};
+const pruneBackups = async (root) => {
+    try {
+        const backups = await inspectBackups(root);
+        const obsolete = selectObsoleteBackups(backups);
+        if (obsolete.length === 0)
+            return;
+        await Promise.all(obsolete.map(removeBackup));
+        await syncDirectory(root.path);
+    }
+    catch (error) {
+        throw toRecoveryError(error, "The Maia configuration was committed but backup retention requires recovery.");
+    }
+};
+const makeWriteReceipt = (input, previous, backup) => ({
+    ...(backup === undefined ? {} : { backupId: backup.id }),
+    bytes: input.write.intended.bytes.byteLength,
+    committedAt: input.committedAt,
+    digest: input.write.intended.digest,
+    ...(previous === undefined ? {} : { previousDigest: previous.digest }),
+    relativePath: input.write.relativePath,
+    version: MAIA_CONFIG_VERSION,
+});
+const makeCommitContext = (input, previous) => ({
+    destinationPath: join(input.root.path, input.write.relativePath),
+    intended: input.write.intended,
+    ...(previous === undefined ? {} : { previous }),
+    relativePath: input.write.relativePath,
+    root: input.root,
+});
+const commitWithBackupCleanup = async (context, hooks, backup) => {
+    try {
+        await commitReplacement(context, hooks);
+    }
+    catch (error) {
+        if (backup !== undefined &&
+            !(error instanceof NodeRuntimeError &&
+                error.code === "configuration_recovery_required")) {
+            await removeFailedBackup(backup);
+        }
+        throw error;
+    }
+};
+const performWrite = async (input) => {
+    const destinationDirectory = await prepareDestinationDirectory(input.root, input.write.relativePath);
+    await cleanTemporaryFiles(destinationDirectory);
+    const previous = await readCurrent(input.root, input.write.relativePath, input.write.role);
+    ensureExpectedState(previous, input.write.expectedDigest);
+    const preparedBackup = await prepareWriteBackup(input, previous);
+    await commitWithBackupCleanup(makeCommitContext(input, previous), input.hooks, preparedBackup.backup);
+    if (preparedBackup.root !== undefined)
+        await pruneBackups(preparedBackup.root);
+    return makeWriteReceipt(input, previous, preparedBackup.backup);
+};
+const writeWithHooks = Effect.fn("NodeConfiguration.writeUser")(function* (input, hooks = {}) {
+    const write = yield* Effect.try({
+        catch: (error) => toWriteError(error, "configuration_invalid"),
+        try: () => prepareWrite(input),
+    });
+    const startedAt = DateTime.formatIso(yield* DateTime.now);
+    const root = yield* Effect.tryPromise({
+        catch: (error) => toWriteError(error, "configuration_invalid", "The Maia user configuration root could not be prepared safely."),
+        try: () => prepareUserConfigurationRoot(input.canonicalUserRoot),
+    });
+    return yield* Effect.acquireUseRelease(acquireWriteLock(root, startedAt), () => Effect.tryPromise({
+        catch: toWriteError,
+        try: () => performWrite({ committedAt: startedAt, hooks, root, write }),
+    }).pipe(Effect.uninterruptible), releaseWriteLock);
+});
+export const writeUserConfiguration = (input) => writeWithHooks(input);
+const readBackupDocument = async (backup) => {
+    const contents = await readBoundedOwnedFile(join(backup.directoryPath, BACKUP_DOCUMENT_NAME), configurationPolicy.maximumFileBytes);
+    if (contents.byteLength !== backup.bytes ||
+        digestBytes(contents) !== backup.digest) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "A Maia configuration backup does not match its recorded digest.");
+    }
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(contents);
+    }
+    catch (error) {
+        throw toWriteError(error, "configuration_recovery_required", "A Maia configuration backup is not valid UTF-8.");
+    }
+};
+const destinationFromRelativePath = (relativePath) => {
+    if (relativePath === "config.jsonc")
+        return { kind: "base" };
+    const match = configurationRelativePathPattern.exec(relativePath);
+    const profile = match?.[1];
+    if (profile === undefined) {
+        throw makeNodeRuntimeError("configuration_recovery_required", "A Maia configuration backup has an unsupported destination.");
+    }
+    return { kind: "profile", profile };
+};
+const validateRestoreInput = (input) => {
+    if (!backupIdPattern.test(input.backupId)) {
+        throw makeNodeRuntimeError("configuration_invalid", "The Maia configuration backup identifier is invalid.");
+    }
+    validateExpectedDigest(input.expectedDigest);
+};
+const discoverRequiredUserRoot = async (canonicalUserRoot) => {
+    const discovered = await discoverUserConfigurationRoot(canonicalUserRoot, []);
+    if (discovered === undefined) {
+        throw makeNodeRuntimeError("configuration_invalid", "The Maia user configuration root does not exist.");
+    }
+    return discovered;
+};
+const openRequiredUserRoot = (canonicalUserRoot) => Effect.tryPromise({
+    catch: (error) => toWriteError(error, "configuration_invalid", "The Maia user configuration root could not be opened safely."),
+    try: () => discoverRequiredUserRoot(canonicalUserRoot),
+});
+const requireBackup = (backups, id) => {
+    const backup = backups.find((candidate) => candidate.id === id);
+    if (backup === undefined) {
+        throw makeNodeRuntimeError("configuration_invalid", "The requested Maia configuration backup does not exist.");
+    }
+    return backup;
+};
+const restoreUnderLock = async (restore) => {
+    const backupRoot = await prepareBackupRoot(restore.root);
+    const backup = requireBackup(await inspectBackups(backupRoot), restore.input.backupId);
+    const contents = await readBackupDocument(backup);
+    const destination = destinationFromRelativePath(backup.relativePath);
+    const write = prepareWrite({
+        canonicalUserRoot: restore.root.path,
+        contents,
+        destination,
+        ...(restore.input.expectedDigest === undefined
+            ? {}
+            : { expectedDigest: restore.input.expectedDigest }),
+    });
+    return performWrite({
+        committedAt: restore.startedAt,
+        hooks: {},
+        root: restore.root,
+        write,
+    });
+};
+export const restoreUserConfiguration = Effect.fn("NodeConfiguration.restoreUser")(function* (input) {
+    yield* Effect.try({
+        catch: (error) => toWriteError(error, "configuration_invalid"),
+        try: () => {
+            validateRestoreInput(input);
+        },
+    });
+    const startedAt = DateTime.formatIso(yield* DateTime.now);
+    const root = yield* openRequiredUserRoot(input.canonicalUserRoot);
+    return yield* Effect.acquireUseRelease(acquireWriteLock(root, startedAt), () => Effect.tryPromise({
+        catch: toWriteError,
+        try: () => restoreUnderLock({ input, root, startedAt }),
+    }).pipe(Effect.uninterruptible), releaseWriteLock);
+});
+export const configurationWriterInternals = {
+    backupIdPattern,
+    writeWithHooks,
+};
+//# sourceMappingURL=writer.js.map