@abot-ai/runtime 1.7.0 → 1.8.0

package/dist/src/web-ui/local-runtime/runtime-setup-connection-edit.js

@@ -1,3 +1,5 @@
+import { commitRuntimeSetupEdit } from "./runtime-setup-edit-transaction.js";
+import { withPlannedRuntimeSetupCredentials, } from "./runtime-setup-credentials.js";
 import { randomUUID } from "node:crypto";
 import { dirname, join, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
@@ -80,30 +82,41 @@ export async function editRuntimeSetupConnection(params) {
                 modelConfig,
                 ownedProviders: retained.ownedProviders,
             };
-            let modelWritten = false;
-            let configWritten = false;
-            try {
-                await modelTransaction.write(modelConfig, {
-                    expectedConfig: params.draft.modelConfig,
-                });
-                modelWritten = true;
-                await configTransaction.write(config, {
-                    expectedConfig: source.config,
-                });
-                configWritten = true;
-                await writeRuntimeSetupDraft(nextDraft);
-            }
-            catch (error) {
-                if (configWritten)
-                    await configTransaction.write(source.config, {
-                        expectedConfig: config,
+            await withPlannedRuntimeSetupCredentials(params.credentialWrite, async (credentials) => {
+                const json = (value) => JSON.stringify(value, null, 2) + "\n";
+                await commitRuntimeSetupEdit(params.rootDir, [
+                    {
+                        role: "model",
+                        path: modelTransaction.path,
+                        text: json(modelConfig),
+                    },
+                    {
+                        role: "config",
+                        path: configTransaction.path,
+                        text: json(config),
+                    },
+                    {
+                        role: "receipt",
+                        path: configTransaction.path + ".web-setup.json",
+                        text: json(nextDraft),
+                    },
+                    {
+                        role: "credentials",
+                        path: credentials.path,
+                        text: credentials.text,
+                        mode: 0o600,
+                    },
+                ], async () => {
+                    await modelTransaction.write(modelConfig, {
+                        expectedConfig: params.draft.modelConfig,
                     });
-                if (modelWritten)
-                    await modelTransaction.write(params.draft.modelConfig, {
-                        expectedConfig: modelConfig,
+                    await configTransaction.write(config, {
+                        expectedConfig: source.config,
                     });
-                throw error;
-            }
+                    await writeRuntimeSetupDraft(nextDraft);
+                    await credentials.write();
+                }, credentials.publish);
+            });
             return { draft: nextDraft, embeddingInvalidated };
         });
     });

package/dist/src/web-ui/local-runtime/runtime-setup-context-window.d.ts

@@ -1,14 +1,7 @@
 import type { ModelContextCapacityIssue } from "../../runtime/config/model-context-capacity.js";
 import { RuntimeSetupError } from "./runtime-setup-input.js";
-export type RuntimeSetupContextWindowIssue = Readonly<{
-    field: "contextWindowTokens";
-    declaredTokens: number;
-    effectiveTokens: number;
-    reservedTokens: number;
-    minimumTokens: number;
-    allocationTokens?: number;
-    environmentId?: string;
-}>;
+import { type PublicContextWindowIssue } from "./model-context-capacity-error.js";
+export type RuntimeSetupContextWindowIssue = PublicContextWindowIssue;
 export declare class RuntimeSetupContextWindowError extends RuntimeSetupError {
     readonly contextWindow: RuntimeSetupContextWindowIssue;
     constructor(issue: ModelContextCapacityIssue, environmentId?: string);

package/dist/src/web-ui/local-runtime/runtime-setup-context-window.js

@@ -1,38 +1,15 @@
-import { RuntimeConfigValidationError } from "../../runtime/config/validation.js";
 import { RuntimeSetupError } from "./runtime-setup-input.js";
-function setupContextWindowMessage(issue) {
-    const capacity = `The effective context window is ${issue.effectiveTokens} tokens, but the configured reserves require more than ${issue.reservedTokens} tokens. Use a model-supported context window of at least ${issue.minimumTokens} tokens or adjust the configured reserves.`;
-    if (issue.allocationTokens === undefined)
-        return capacity;
-    if (issue.allocationTokens >= issue.minimumTokens)
-        return capacity;
-    return `${capacity} The Ollama num_ctx allocation of ${issue.allocationTokens} tokens must also support that window.`;
-}
+import { modelContextCapacityMessage, publicContextWindowIssue, readModelContextCapacityIssue, } from "./model-context-capacity-error.js";
 export class RuntimeSetupContextWindowError extends RuntimeSetupError {
     contextWindow;
     constructor(issue, environmentId) {
-        super("context_window_too_small", setupContextWindowMessage(issue));
-        this.contextWindow = {
-            field: "contextWindowTokens",
-            declaredTokens: issue.declaredTokens,
-            effectiveTokens: issue.effectiveTokens,
-            reservedTokens: issue.reservedTokens,
-            minimumTokens: issue.minimumTokens,
-            ...(issue.allocationTokens === undefined
-                ? {}
-                : { allocationTokens: issue.allocationTokens }),
-            ...(environmentId === undefined ? {} : { environmentId }),
-        };
+        super("context_window_too_small", modelContextCapacityMessage(issue));
+        this.contextWindow = publicContextWindowIssue(issue, environmentId);
     }
 }
-function readSetupContextCapacityIssue(error) {
-    if (!(error instanceof RuntimeConfigValidationError))
-        return undefined;
-    return error.capacityIssues.find((issue) => issue.profileId === "default");
-}
 /** Project only known capacity evidence; other exceptions keep their redaction. */
 export function throwRuntimeSetupValidationError(error, environmentId) {
-    const issue = readSetupContextCapacityIssue(error);
+    const issue = readModelContextCapacityIssue(error, "default");
     if (!issue)
         throw error;
     throw new RuntimeSetupContextWindowError(issue, environmentId);

package/dist/src/web-ui/local-runtime/runtime-setup-credentials.d.ts

@@ -1,4 +1,8 @@
-type RuntimeSetupCredentialWrite = {
+type CredentialFileSnapshot = {
+    raw?: string;
+    mode: number;
+};
+export type RuntimeSetupCredentialWrite = {
     rootDir: string;
     configPath: string;
     apiKey?: string;
@@ -9,6 +13,16 @@ export declare function readRuntimeSetupCredential(rootDir: string, apiKeyEnv?:
 export declare function assertRuntimeSetupCredentialFile(rootDir: string): Promise<void>;
 export declare function hasRuntimeSetupCredential(rootDir: string, apiKeyEnv?: string): Promise<boolean>;
 export declare function persistRuntimeSetupCredentials(params: RuntimeSetupCredentialWrite): Promise<void>;
+export type RuntimeSetupCredentialPlan = Readonly<{
+    rootDir: string;
+    path: string;
+    text: string;
+    previous: CredentialFileSnapshot;
+    write: () => Promise<void>;
+    publish: () => void;
+}>;
+/** Publish process credentials only after the caller's complete transaction commits. */
+export declare function withPlannedRuntimeSetupCredentials<T>(params: RuntimeSetupCredentialWrite, operation: (plan: RuntimeSetupCredentialPlan) => Promise<T>): Promise<T>;
 /** Keep the credential private and locked until the related setup commit settles. */
 export declare function commitRuntimeSetupCredentials<T>(params: RuntimeSetupCredentialWrite, commit: () => Promise<T>): Promise<T>;
 export {};

package/dist/src/web-ui/local-runtime/runtime-setup-credentials.js

@@ -108,10 +108,36 @@ export async function hasRuntimeSetupCredential(rootDir, apiKeyEnv = "OPENAI_API
 export async function persistRuntimeSetupCredentials(params) {
     await commitRuntimeSetupCredentials(params, async () => undefined);
 }
+/** Publish process credentials only after the caller's complete transaction commits. */
+export async function withPlannedRuntimeSetupCredentials(params, operation) {
+    const rootDir = await realpath(params.rootDir);
+    return withFileLock(join(rootDir, ".env.credentials.lock"), async () => {
+        const plan = await planCredentialAssignments({ ...params, rootDir });
+        const publish = () => {
+            const key = params.apiKey ||
+                process.env[plan.apiKeyEnv] ||
+                readSavedApiKey(plan.previousFile.raw ?? "", plan.apiKeyEnv);
+            if (key)
+                process.env[plan.apiKeyEnv] = key;
+        };
+        const result = await operation({
+            rootDir,
+            path: join(rootDir, ".env"),
+            text: plan.next,
+            previous: plan.previousFile,
+            write: () => replaceCredentialFile(rootDir, plan.previousFile.raw, plan.next),
+            publish,
+        });
+        publish();
+        return result;
+    });
+}
 /** Keep the credential private and locked until the related setup commit settles. */
 export async function commitRuntimeSetupCredentials(params, commit) {
-    const rootDir = await realpath(params.rootDir);
-    return withFileLock(join(rootDir, ".env.credentials.lock"), () => saveCredentialAssignments({ ...params, rootDir }, commit));
+    return withPlannedRuntimeSetupCredentials(params, async (plan) => {
+        await plan.write();
+        return commitOrRestoreCredentials(plan.rootDir, plan.previous, plan.text, commit);
+    });
 }
 function wouldReplaceConfiguredCredential(preserveExistingCredential, incomingKey, configuredKeys) {
     if (!preserveExistingCredential)
@@ -124,7 +150,7 @@ function wouldReplaceConfiguredCredential(preserveExistingCredential, incomingKe
         return configuredKey !== incomingKey;
     });
 }
-async function saveCredentialAssignments(params, commit) {
+async function planCredentialAssignments(params) {
     const apiKeyEnv = params.apiKeyEnv ?? "OPENAI_API_KEY";
     const previousFile = await readCredentialFileSnapshot(params.rootDir);
     const previous = previousFile.raw ?? "";
@@ -137,12 +163,5 @@ async function saveCredentialAssignments(params, commit) {
     let next = replaceRuntimeSetupEnvironmentAssignment(previous, "LLM_RUNTIME_CONFIG_FILE", params.configPath);
     if (params.apiKey)
         next = replaceRuntimeSetupEnvironmentAssignment(next, apiKeyEnv, params.apiKey);
-    await replaceCredentialFile(params.rootDir, previousFile.raw, next);
-    const result = await commitOrRestoreCredentials(params.rootDir, previousFile, next, commit);
-    const key = params.apiKey ||
-        process.env[apiKeyEnv] ||
-        readSavedApiKey(previous, apiKeyEnv);
-    if (key)
-        process.env[apiKeyEnv] = key;
-    return result;
+    return { previousFile, next, apiKeyEnv };
 }

package/dist/src/web-ui/local-runtime/runtime-setup-edit-files.d.ts

@@ -0,0 +1,20 @@
+import { RuntimeSetupError } from "./runtime-setup-input.js";
+export type SetupEditFileSnapshot = Readonly<{
+    bytes: string | null;
+    mode: number;
+}>;
+export declare function setupEditRecoveryRequired(): RuntimeSetupError;
+export declare function isMissingSetupEditFile(error: unknown): boolean;
+/** Snapshots preserve bytes, existence and mode; linked or special targets are not owned. */
+export declare function readSetupEditFile(path: string): Promise<SetupEditFileSnapshot>;
+export declare function setupEditFileMatches(actual: SetupEditFileSnapshot, expected: SetupEditFileSnapshot): boolean;
+export declare function setupEditTextSnapshot(text: string, mode: number): SetupEditFileSnapshot;
+export declare function setupEditSnapshotText(snapshot: SetupEditFileSnapshot): string;
+/** Directory sync is available on Unix; Windows does not expose it through Node. */
+export declare function syncSetupEditDirectory(path: string): Promise<void>;
+export declare function syncSetupEditFile(path: string): Promise<void>;
+export declare function requireSetupEditFileSnapshot(path: string, expected: SetupEditFileSnapshot): Promise<void>;
+/** Cooperative locks are held by the caller; recheck immediately before replacement. */
+export declare function restoreSetupEditFile(path: string, expected: SetupEditFileSnapshot, replacement: SetupEditFileSnapshot): Promise<void>;
+/** Publish the marker itself atomically; private mode also protects credential snapshots. */
+export declare function publishSetupEditJournal(path: string, text: string, expected: SetupEditFileSnapshot): Promise<void>;

package/dist/src/web-ui/local-runtime/runtime-setup-edit-files.js

@@ -0,0 +1,104 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, open, readFile, rename, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import { canonicalConfigFilePath } from "../../runtime/adapters/config-file-transaction.js";
+import { RuntimeSetupError } from "./runtime-setup-input.js";
+export function setupEditRecoveryRequired() {
+    return new RuntimeSetupError("setup_edit_recovery_required", "An interrupted connection edit needs recovery. Restart this Runtime before applying configuration. If recovery reports a conflict, preserve the transaction and review the changed files.", 409);
+}
+export function isMissingSetupEditFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+/** Snapshots preserve bytes, existence and mode; linked or special targets are not owned. */
+export async function readSetupEditFile(path) {
+    if ((await canonicalConfigFilePath(path)) !== path)
+        throw setupEditRecoveryRequired();
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink())
+            throw setupEditRecoveryRequired();
+        return {
+            bytes: (await readFile(path)).toString("base64"),
+            mode: info.mode & 0o777,
+        };
+    }
+    catch (error) {
+        if (isMissingSetupEditFile(error))
+            return { bytes: null, mode: 0 };
+        throw error;
+    }
+}
+export function setupEditFileMatches(actual, expected) {
+    if (actual.bytes !== expected.bytes)
+        return false;
+    // Node's Windows chmod only implements the writable bit, unlike POSIX modes.
+    const mask = process.platform === "win32" ? 0o200 : 0o777;
+    return (actual.mode & mask) === (expected.mode & mask);
+}
+export function setupEditTextSnapshot(text, mode) {
+    return { bytes: Buffer.from(text, "utf8").toString("base64"), mode };
+}
+export function setupEditSnapshotText(snapshot) {
+    if (snapshot.bytes === null)
+        throw setupEditRecoveryRequired();
+    return Buffer.from(snapshot.bytes, "base64").toString("utf8");
+}
+/** Directory sync is available on Unix; Windows does not expose it through Node. */
+export async function syncSetupEditDirectory(path) {
+    if (process.platform === "win32")
+        return;
+    const handle = await open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function syncSetupEditFile(path) {
+    // Windows FlushFileBuffers requires a handle opened for writing.
+    const handle = await open(path, process.platform === "win32" ? "r+" : "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await syncSetupEditDirectory(dirname(path));
+}
+export async function requireSetupEditFileSnapshot(path, expected) {
+    if (!setupEditFileMatches(await readSetupEditFile(path), expected))
+        throw setupEditRecoveryRequired();
+}
+/** Cooperative locks are held by the caller; recheck immediately before replacement. */
+export async function restoreSetupEditFile(path, expected, replacement) {
+    await requireSetupEditFileSnapshot(path, expected);
+    if (replacement.bytes === null) {
+        await rm(path);
+        await syncSetupEditDirectory(dirname(path));
+        return;
+    }
+    const temporary = `${path}.${randomUUID()}.setup-edit.tmp`;
+    try {
+        const handle = await open(temporary, "wx", replacement.mode);
+        try {
+            await handle.writeFile(Buffer.from(replacement.bytes, "base64"));
+            await handle.chmod(replacement.mode);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await requireSetupEditFileSnapshot(path, expected);
+        await rename(temporary, path);
+        await syncSetupEditDirectory(dirname(path));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Publish the marker itself atomically; private mode also protects credential snapshots. */
+export async function publishSetupEditJournal(path, text, expected) {
+    await restoreSetupEditFile(path, expected, setupEditTextSnapshot(text, 0o600));
+    await chmod(path, 0o600);
+}

package/dist/src/web-ui/local-runtime/runtime-setup-edit-journal.d.ts

@@ -0,0 +1,29 @@
+import { type SetupEditFileSnapshot } from "./runtime-setup-edit-files.js";
+export declare const SETUP_EDIT_JOURNAL_NAME = ".runtime-setup-edit.json";
+declare const FILE_ROLES: readonly ["model", "config", "receipt", "credentials"];
+type SetupEditFileRole = (typeof FILE_ROLES)[number];
+export type SetupEditJournalFile = Readonly<{
+    role: SetupEditFileRole;
+    path: string;
+    before: SetupEditFileSnapshot;
+    after: SetupEditFileSnapshot;
+}>;
+export type SetupEditJournal = Readonly<{
+    version: 1;
+    id: string;
+    rootDir: string;
+    phase: "pending" | "committed";
+    files: readonly SetupEditJournalFile[];
+}>;
+export type SetupEditFilePlan = Readonly<{
+    role: SetupEditFileRole;
+    path: string;
+    text: string;
+    mode?: number;
+}>;
+export declare function setupEditJournalPath(rootDir: string): string;
+export declare function validateSetupEditJournal(value: unknown, rootDir: string): Promise<SetupEditJournal>;
+export declare function readSetupEditJournal(rootDir: string): Promise<SetupEditJournal | undefined>;
+export declare function createSetupEditJournal(rootDir: string, plans: readonly SetupEditFilePlan[]): Promise<SetupEditJournal>;
+export declare function writeSetupEditJournal(journal: SetupEditJournal, previous?: SetupEditJournal): Promise<void>;
+export {};

package/dist/src/web-ui/local-runtime/runtime-setup-edit-journal.js

@@ -0,0 +1,151 @@
+import { parse } from "dotenv";
+import { isDeepStrictEqual } from "node:util";
+import { randomUUID } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { isRecord } from "../../runtime/config/utils.js";
+import { canonicalConfigFilePath } from "../../runtime/adapters/config-file-transaction.js";
+import { readSetupEditFile, setupEditRecoveryRequired, setupEditSnapshotText, setupEditTextSnapshot, publishSetupEditJournal, } from "./runtime-setup-edit-files.js";
+export const SETUP_EDIT_JOURNAL_NAME = ".runtime-setup-edit.json";
+const FILE_ROLES = ["model", "config", "receipt", "credentials"];
+export function setupEditJournalPath(rootDir) {
+    return join(rootDir, SETUP_EDIT_JOURNAL_NAME);
+}
+function isSetupEditSnapshot(value) {
+    if (!isRecord(value))
+        return false;
+    if (!Number.isInteger(value.mode))
+        return false;
+    if (typeof value.mode !== "number" || value.mode < 0 || value.mode > 0o777)
+        return false;
+    if (value.bytes === null)
+        return value.mode === 0;
+    if (typeof value.bytes !== "string")
+        return false;
+    return Buffer.from(value.bytes, "base64").toString("base64") === value.bytes;
+}
+function isSetupEditJournalFile(value, index) {
+    if (!isRecord(value))
+        return false;
+    if (value.role !== FILE_ROLES[index])
+        return false;
+    if (typeof value.path !== "string" || value.path !== resolve(value.path))
+        return false;
+    if (!isSetupEditSnapshot(value.before))
+        return false;
+    if (!isSetupEditSnapshot(value.after))
+        return false;
+    if (value.after.bytes === null)
+        return false;
+    if (value.role !== "credentials" && value.before.bytes === null)
+        return false;
+    return true;
+}
+function parseSetupEditObject(snapshot) {
+    const value = JSON.parse(setupEditSnapshotText(snapshot));
+    if (!isRecord(value))
+        throw setupEditRecoveryRequired();
+    return value;
+}
+async function requireSetupEditFileBindings(journal) {
+    const [model, config, receipt, credentials] = journal.files;
+    if (receipt.path !== config.path + ".web-setup.json")
+        throw setupEditRecoveryRequired();
+    if (credentials.path !== join(journal.rootDir, ".env"))
+        throw setupEditRecoveryRequired();
+    if (new Set(journal.files.map((file) => file.path)).size !== FILE_ROLES.length)
+        throw setupEditRecoveryRequired();
+    for (const state of ["before", "after"]) {
+        const draft = parseSetupEditObject(receipt[state]);
+        if (draft.version !== 1 || typeof draft.revision !== "string")
+            throw setupEditRecoveryRequired();
+        if (draft.configPath !== config.path || draft.modelPath !== model.path)
+            throw setupEditRecoveryRequired();
+        if (!isDeepStrictEqual(draft.modelConfig, parseSetupEditObject(model[state])))
+            throw setupEditRecoveryRequired();
+        const saved = parseSetupEditObject(config[state]);
+        const models = isRecord(saved.models) ? saved.models : {};
+        const profiles = isRecord(models.profiles) ? models.profiles : {};
+        if (!isDeepStrictEqual(draft.profileReferences, profiles))
+            throw setupEditRecoveryRequired();
+        if (!isRecord(draft.ownedProviders))
+            throw setupEditRecoveryRequired();
+        const providers = isRecord(models.providers) ? models.providers : {};
+        for (const [id, provider] of Object.entries(draft.ownedProviders)) {
+            if (!isDeepStrictEqual(providers[id], provider))
+                throw setupEditRecoveryRequired();
+        }
+        const profile = isRecord(profiles.default) ? profiles.default : {};
+        if (typeof profile.configRef !== "string")
+            throw setupEditRecoveryRequired();
+        const referenced = await canonicalConfigFilePath(resolve(dirname(config.path), profile.configRef));
+        if (referenced !== model.path)
+            throw setupEditRecoveryRequired();
+    }
+    const env = parse(setupEditSnapshotText(credentials.after));
+    if (typeof env.LLM_RUNTIME_CONFIG_FILE !== "string")
+        throw setupEditRecoveryRequired();
+    const configured = await canonicalConfigFilePath(resolve(journal.rootDir, env.LLM_RUNTIME_CONFIG_FILE));
+    if (configured !== config.path)
+        throw setupEditRecoveryRequired();
+}
+export async function validateSetupEditJournal(value, rootDir) {
+    try {
+        if (!isRecord(value))
+            throw setupEditRecoveryRequired();
+        if (value.version !== 1 || typeof value.id !== "string")
+            throw setupEditRecoveryRequired();
+        if (value.rootDir !== rootDir)
+            throw setupEditRecoveryRequired();
+        if (value.phase !== "pending" && value.phase !== "committed")
+            throw setupEditRecoveryRequired();
+        if (!Array.isArray(value.files) || value.files.length !== FILE_ROLES.length)
+            throw setupEditRecoveryRequired();
+        if (!value.files.every(isSetupEditJournalFile))
+            throw setupEditRecoveryRequired();
+        const journal = value;
+        await requireSetupEditFileBindings(journal);
+        return journal;
+    }
+    catch {
+        throw setupEditRecoveryRequired();
+    }
+}
+export async function readSetupEditJournal(rootDir) {
+    const snapshot = await readSetupEditFile(setupEditJournalPath(rootDir));
+    if (snapshot.bytes === null)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(setupEditSnapshotText(snapshot));
+    }
+    catch {
+        throw setupEditRecoveryRequired();
+    }
+    return validateSetupEditJournal(value, rootDir);
+}
+export async function createSetupEditJournal(rootDir, plans) {
+    const files = [];
+    for (const plan of plans) {
+        const before = await readSetupEditFile(plan.path);
+        files.push({
+            role: plan.role,
+            path: plan.path,
+            before,
+            after: setupEditTextSnapshot(plan.text, plan.mode ?? before.mode),
+        });
+    }
+    return validateSetupEditJournal({
+        version: 1,
+        id: randomUUID(),
+        rootDir,
+        phase: "pending",
+        files,
+    }, rootDir);
+}
+export async function writeSetupEditJournal(journal, previous) {
+    const path = setupEditJournalPath(journal.rootDir);
+    const expected = previous
+        ? setupEditTextSnapshot(JSON.stringify(previous) + "\n", 0o600)
+        : { bytes: null, mode: 0 };
+    await publishSetupEditJournal(path, JSON.stringify(journal) + "\n", expected);
+}

package/dist/src/web-ui/local-runtime/runtime-setup-edit-recovery.d.ts

@@ -0,0 +1,7 @@
+import { type SetupEditJournal } from "./runtime-setup-edit-journal.js";
+/** Synchronous consumers must not observe any part of an unresolved edit. */
+export declare function requireRuntimeSetupEditSettled(rootDir: string): void;
+/** Caller holds every participant lock; repeatable after interruption at any restore. */
+export declare function reconcileSetupEditJournal(journal: SetupEditJournal): Promise<void>;
+/** Runs before dotenv/configuration loading. No journal means no speculative repair. */
+export declare function recoverRuntimeSetupEdit(rootDir: string): Promise<void>;

package/dist/src/web-ui/local-runtime/runtime-setup-edit-recovery.js

@@ -0,0 +1,87 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { realpath, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { withFileLock } from "../../runtime/adapters/long-term-memory/file-lock.js";
+import { CONFIG_FILE_LOCK_OPTIONS } from "../../runtime/adapters/config-file-transaction.js";
+import { isMissingSetupEditFile, readSetupEditFile, requireSetupEditFileSnapshot, restoreSetupEditFile, setupEditFileMatches, setupEditRecoveryRequired, setupEditTextSnapshot, syncSetupEditDirectory, } from "./runtime-setup-edit-files.js";
+import { readSetupEditJournal, setupEditJournalPath, } from "./runtime-setup-edit-journal.js";
+/** Synchronous consumers must not observe any part of an unresolved edit. */
+export function requireRuntimeSetupEditSettled(rootDir) {
+    let path = resolve(rootDir);
+    try {
+        path = realpathSync(path);
+        lstatSync(setupEditJournalPath(path));
+    }
+    catch (error) {
+        if (isMissingSetupEditFile(error))
+            return;
+        throw setupEditRecoveryRequired();
+    }
+    throw setupEditRecoveryRequired();
+}
+async function requireRecoverableSetupEditFiles(journal) {
+    for (const file of journal.files) {
+        const current = await readSetupEditFile(file.path);
+        if (setupEditFileMatches(current, file.after))
+            continue;
+        if (journal.phase === "pending" &&
+            setupEditFileMatches(current, file.before))
+            continue;
+        throw setupEditRecoveryRequired();
+    }
+}
+/** Caller holds every participant lock; repeatable after interruption at any restore. */
+export async function reconcileSetupEditJournal(journal) {
+    await requireRecoverableSetupEditFiles(journal);
+    if (journal.phase === "pending") {
+        for (const file of [...journal.files].reverse()) {
+            const current = await readSetupEditFile(file.path);
+            if (setupEditFileMatches(current, file.before))
+                continue;
+            if (!setupEditFileMatches(current, file.after))
+                throw setupEditRecoveryRequired();
+            await restoreSetupEditFile(file.path, file.after, file.before);
+        }
+    }
+    const path = setupEditJournalPath(journal.rootDir);
+    await requireSetupEditFileSnapshot(path, setupEditTextSnapshot(JSON.stringify(journal) + "\n", 0o600));
+    await rm(path);
+    await syncSetupEditDirectory(journal.rootDir);
+}
+async function withSetupEditRecoveryLocks(journal, operation) {
+    const [model, config, receipt] = journal.files;
+    const locks = [
+        config.path + ".config.lock",
+        model.path + ".config.lock",
+        join(journal.rootDir, ".env.credentials.lock"),
+        receipt.path + ".config.lock",
+    ];
+    const acquire = (index) => {
+        if (index === locks.length)
+            return operation();
+        return withFileLock(locks[index], () => acquire(index + 1), CONFIG_FILE_LOCK_OPTIONS);
+    };
+    return acquire(0);
+}
+/** Runs before dotenv/configuration loading. No journal means no speculative repair. */
+export async function recoverRuntimeSetupEdit(rootDir) {
+    try {
+        requireRuntimeSetupEditSettled(rootDir);
+        return;
+    }
+    catch {
+        // Parsing and lock acquisition below decide whether recovery is safe.
+    }
+    const root = await realpath(rootDir);
+    await withFileLock(join(root, ".runtime-setup.lock"), async () => {
+        const journal = await readSetupEditJournal(root);
+        if (!journal)
+            return;
+        await withSetupEditRecoveryLocks(journal, async () => {
+            const current = await readSetupEditJournal(root);
+            if (!current || JSON.stringify(current) !== JSON.stringify(journal))
+                throw setupEditRecoveryRequired();
+            await reconcileSetupEditJournal(journal);
+        });
+    }, CONFIG_FILE_LOCK_OPTIONS);
+}

package/dist/src/web-ui/local-runtime/runtime-setup-edit-transaction.d.ts

@@ -0,0 +1,3 @@
+import { type SetupEditFilePlan } from "./runtime-setup-edit-journal.js";
+/** Setup, config, model and credential locks enclose this complete transaction. */
+export declare function commitRuntimeSetupEdit(rootDir: string, files: readonly SetupEditFilePlan[], commit: () => Promise<void>, publishCommittedCredentials: () => void): Promise<void>;