@zktx.io/sui-mcp 0.5.0

package/dist/runtime/config.js

@@ -0,0 +1,97 @@
+import { resolveActivityDatabasePath } from "../core/activity/sqliteActivityStore.js";
+import { DEFAULT_SUI_GRAPHQL_URL, DEFAULT_SUI_GRPC_URL, SUI_MAINNET_CHAIN_IDENTIFIER, parseGraphqlUrl, parseGrpcUrl } from "./suiEndpoint.js";
+import { SETTINGS_APPLIES_AFTER_RESTART } from "../core/preferences/preferencesStore.js";
+export function loadBootConfig(env = process.env) {
+    const network = env.SUI_NETWORK ?? "mainnet";
+    if (network !== "mainnet") {
+        throw new Error("Sui MCP product runtime only supports mainnet");
+    }
+    if (env.SUI_RPC_URL) {
+        throw new Error("Sui JSON-RPC endpoint configuration is not supported; use local settings, SUI_GRPC_URL for gRPC, or SUI_GRAPHQL_URL for GraphQL");
+    }
+    return {
+        network: "mainnet",
+        expectedChainIdentifier: SUI_MAINNET_CHAIN_IDENTIFIER,
+        reviewHost: "127.0.0.1",
+        reviewPort: parseReviewPort(env.SUI_MCP_REVIEW_PORT),
+        activityDatabasePath: resolveActivityDatabasePath(env)
+    };
+}
+// Existing shared-backend port: clients using the same data directory must
+// agree on this port and configuration. It is not browser-wallet authority.
+export const DEFAULT_REVIEW_PORT = 8765;
+function parseReviewPort(value) {
+    if (value === undefined || value === "") {
+        return DEFAULT_REVIEW_PORT;
+    }
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`SUI_MCP_REVIEW_PORT must be an integer between 1 and 65535, got: ${value}`);
+    }
+    return port;
+}
+export function composeRuntimeConfig(input) {
+    const env = input.env ?? process.env;
+    const defaultSuiGrpcUrl = parseGrpcUrl(input.defaultSuiGrpcUrl ?? DEFAULT_SUI_GRPC_URL);
+    const defaultSuiGraphqlUrl = parseGraphqlUrl(input.defaultSuiGraphqlUrl ?? DEFAULT_SUI_GRAPHQL_URL);
+    const storedValue = parseGrpcUrl(input.storedSuiGrpcUrl ?? defaultSuiGrpcUrl);
+    const storedGraphqlValue = parseGraphqlUrl(input.storedSuiGraphqlUrl ?? defaultSuiGraphqlUrl);
+    const envValue = env.SUI_GRPC_URL === undefined ? undefined : parseGrpcUrl(env.SUI_GRPC_URL);
+    const envGraphqlValue = env.SUI_GRAPHQL_URL === undefined ? undefined : parseGraphqlUrl(env.SUI_GRAPHQL_URL);
+    const suiGrpcUrl = resolveSuiGrpcUrlView({
+        defaultSuiGrpcUrl,
+        storedValue,
+        envValue
+    });
+    const suiGraphqlUrl = resolveSuiGraphqlUrlView({
+        defaultSuiGraphqlUrl,
+        storedValue: storedGraphqlValue,
+        envValue: envGraphqlValue
+    });
+    return {
+        ...input.bootConfig,
+        grpcUrl: suiGrpcUrl.effectiveValue,
+        graphqlUrl: suiGraphqlUrl.effectiveValue,
+        suiGrpcUrl,
+        suiGraphqlUrl
+    };
+}
+export function resolveSuiGrpcUrlView(input) {
+    const defaultSuiGrpcUrl = parseGrpcUrl(input.defaultSuiGrpcUrl ?? DEFAULT_SUI_GRPC_URL);
+    const storedValue = parseGrpcUrl(input.storedValue ?? defaultSuiGrpcUrl);
+    if (input.envValue !== undefined) {
+        const effectiveValue = parseGrpcUrl(input.envValue);
+        return {
+            storedValue,
+            effectiveValue,
+            source: "environment",
+            pendingStoredValue: effectiveValue === storedValue ? undefined : storedValue,
+            appliesAfter: effectiveValue === storedValue ? undefined : SETTINGS_APPLIES_AFTER_RESTART
+        };
+    }
+    return {
+        storedValue,
+        effectiveValue: storedValue,
+        source: storedValue === defaultSuiGrpcUrl ? "builtin_default" : "local_db"
+    };
+}
+export function resolveSuiGraphqlUrlView(input) {
+    const defaultSuiGraphqlUrl = parseGraphqlUrl(input.defaultSuiGraphqlUrl ?? DEFAULT_SUI_GRAPHQL_URL);
+    const storedValue = parseGraphqlUrl(input.storedValue ?? defaultSuiGraphqlUrl);
+    if (input.envValue !== undefined) {
+        const effectiveValue = parseGraphqlUrl(input.envValue);
+        return {
+            storedValue,
+            effectiveValue,
+            source: "environment",
+            pendingStoredValue: effectiveValue === storedValue ? undefined : storedValue,
+            appliesAfter: effectiveValue === storedValue ? undefined : SETTINGS_APPLIES_AFTER_RESTART
+        };
+    }
+    return {
+        storedValue,
+        effectiveValue: storedValue,
+        source: storedValue === defaultSuiGraphqlUrl ? "builtin_default" : "local_db"
+    };
+}
+export { DEFAULT_SUI_GRAPHQL_URL, DEFAULT_SUI_GRPC_URL, SUI_MAINNET_CHAIN_IDENTIFIER };

package/dist/runtime/localSettingsService.js

@@ -0,0 +1,198 @@
+import { SETTINGS_APPLIES_AFTER_RESTART, LocalSettingsError } from "../core/preferences/preferencesStore.js";
+import { DEFAULT_SUI_GRAPHQL_ENDPOINT_VERIFY_TIMEOUT_MS, DEFAULT_SUI_GRAPHQL_URL, DEFAULT_SUI_GRPC_ENDPOINT_VERIFY_TIMEOUT_MS, DEFAULT_SUI_GRPC_URL, SUI_MAINNET_CHAIN_IDENTIFIER, SuiEndpointError, parseGraphqlUrl, parseGrpcUrl, verifyMainnetGraphqlEndpoint, verifyMainnetGrpcEndpoint } from "./suiEndpoint.js";
+import { resolveSuiGraphqlUrlView, resolveSuiGrpcUrlView } from "./config.js";
+export class RuntimeLocalSettingsService {
+    options;
+    env;
+    defaultSuiGrpcUrl;
+    defaultSuiGraphqlUrl;
+    bootSuiGrpcUrl;
+    bootSuiGraphqlUrl;
+    verifyGrpcEndpoint;
+    verifyGraphqlEndpoint;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.env = options.env ?? process.env;
+        this.defaultSuiGrpcUrl = parseGrpcUrl(options.defaultSuiGrpcUrl ?? DEFAULT_SUI_GRPC_URL);
+        this.defaultSuiGraphqlUrl = parseGraphqlUrl(options.defaultSuiGraphqlUrl ?? DEFAULT_SUI_GRAPHQL_URL);
+        this.bootSuiGrpcUrl = normalizeBootSuiGrpcUrlView(options.bootSuiGrpcUrl ??
+            resolveSuiGrpcUrlView({
+                defaultSuiGrpcUrl: this.defaultSuiGrpcUrl,
+                envValue: this.env.SUI_GRPC_URL
+            }));
+        this.bootSuiGraphqlUrl = normalizeBootSuiGraphqlUrlView(options.bootSuiGraphqlUrl ??
+            resolveSuiGraphqlUrlView({
+                defaultSuiGraphqlUrl: this.defaultSuiGraphqlUrl,
+                envValue: this.env.SUI_GRAPHQL_URL
+            }));
+        this.verifyGrpcEndpoint = options.verifyGrpcEndpoint ?? defaultGrpcEndpointVerifier;
+        this.verifyGraphqlEndpoint = options.verifyGraphqlEndpoint ?? defaultGraphqlEndpointVerifier;
+        this.now = options.now ?? (() => new Date());
+    }
+    async getLocalSettings() {
+        const stored = await this.options.preferencesRepository.getSuiGrpcUrl();
+        const storedGraphql = await this.options.preferencesRepository.getSuiGraphqlUrl();
+        const currentStoredView = resolveSuiGrpcUrlView({
+            defaultSuiGrpcUrl: this.defaultSuiGrpcUrl,
+            storedValue: stored?.value,
+            envValue: this.env.SUI_GRPC_URL
+        });
+        const currentStoredGraphqlView = resolveSuiGraphqlUrlView({
+            defaultSuiGraphqlUrl: this.defaultSuiGraphqlUrl,
+            storedValue: storedGraphql?.value,
+            envValue: this.env.SUI_GRAPHQL_URL
+        });
+        return {
+            suiGrpcUrl: withBootEffectiveEndpoint(currentStoredView, this.bootSuiGrpcUrl),
+            suiGraphqlUrl: withBootEffectiveEndpoint(currentStoredGraphqlView, this.bootSuiGraphqlUrl)
+        };
+    }
+    async setSuiGrpcUrl(url) {
+        const normalized = parseEndpointForTool(url);
+        await this.verifyEndpointForTool(normalized, "grpc");
+        const result = await this.options.preferencesRepository.setSuiGrpcUrl(normalized, this.now());
+        return {
+            status: "saved",
+            storedValue: result.storedValue,
+            previousStoredValue: result.previousStoredValue,
+            appliesAfter: SETTINGS_APPLIES_AFTER_RESTART
+        };
+    }
+    async setSuiGraphqlUrl(url) {
+        const normalized = parseGraphqlEndpointForTool(url);
+        await this.verifyEndpointForTool(normalized, "graphql");
+        const result = await this.options.preferencesRepository.setSuiGraphqlUrl(normalized, this.now());
+        return {
+            status: "saved",
+            storedValue: result.storedValue,
+            previousStoredValue: result.previousStoredValue,
+            appliesAfter: SETTINGS_APPLIES_AFTER_RESTART
+        };
+    }
+    async resetSuiGrpcUrl() {
+        const result = await this.options.preferencesRepository.resetSuiGrpcUrl(this.defaultSuiGrpcUrl, this.now());
+        return {
+            status: "reset",
+            storedValue: result.storedValue,
+            previousStoredValue: result.previousStoredValue,
+            appliesAfter: SETTINGS_APPLIES_AFTER_RESTART
+        };
+    }
+    async resetSuiGraphqlUrl() {
+        const result = await this.options.preferencesRepository.resetSuiGraphqlUrl(this.defaultSuiGraphqlUrl, this.now());
+        return {
+            status: "reset",
+            storedValue: result.storedValue,
+            previousStoredValue: result.previousStoredValue,
+            appliesAfter: SETTINGS_APPLIES_AFTER_RESTART
+        };
+    }
+    async verifyEndpointForTool(url, transport) {
+        try {
+            await (transport === "grpc" ? this.verifyGrpcEndpoint(url) : this.verifyGraphqlEndpoint(url));
+        }
+        catch (error) {
+            if (error instanceof LocalSettingsError) {
+                throw error;
+            }
+            if (error instanceof SuiEndpointError) {
+                throw endpointErrorForTool(error, transport);
+            }
+            const label = transport === "grpc" ? "gRPC" : "GraphQL";
+            throw new LocalSettingsError("internal_error", `Sui ${label} endpoint verification failed`, {
+                message: `Sui ${label} endpoint verification failed`
+            });
+        }
+    }
+}
+function normalizeBootSuiGrpcUrlView(view) {
+    return {
+        ...view,
+        storedValue: parseGrpcUrl(view.storedValue),
+        effectiveValue: parseGrpcUrl(view.effectiveValue)
+    };
+}
+function normalizeBootSuiGraphqlUrlView(view) {
+    return {
+        ...view,
+        storedValue: parseGraphqlUrl(view.storedValue),
+        effectiveValue: parseGraphqlUrl(view.effectiveValue)
+    };
+}
+function withBootEffectiveEndpoint(storedView, bootView) {
+    if (storedView.effectiveValue === bootView.effectiveValue) {
+        return storedView;
+    }
+    return {
+        storedValue: storedView.storedValue,
+        effectiveValue: bootView.effectiveValue,
+        source: bootView.source,
+        pendingStoredValue: storedView.storedValue === bootView.effectiveValue ? undefined : storedView.storedValue,
+        appliesAfter: SETTINGS_APPLIES_AFTER_RESTART
+    };
+}
+async function defaultGrpcEndpointVerifier(url) {
+    await verifyMainnetGrpcEndpoint({
+        url,
+        expectedChainIdentifier: SUI_MAINNET_CHAIN_IDENTIFIER,
+        timeoutMs: DEFAULT_SUI_GRPC_ENDPOINT_VERIFY_TIMEOUT_MS
+    });
+}
+async function defaultGraphqlEndpointVerifier(url) {
+    await verifyMainnetGraphqlEndpoint({
+        url,
+        expectedChainIdentifier: SUI_MAINNET_CHAIN_IDENTIFIER,
+        timeoutMs: DEFAULT_SUI_GRAPHQL_ENDPOINT_VERIFY_TIMEOUT_MS
+    });
+}
+function parseEndpointForTool(url) {
+    try {
+        return parseGrpcUrl(url);
+    }
+    catch (error) {
+        if (error instanceof SuiEndpointError) {
+            throw endpointErrorForTool(error, "grpc");
+        }
+        throw error;
+    }
+}
+function parseGraphqlEndpointForTool(url) {
+    try {
+        return parseGraphqlUrl(url);
+    }
+    catch (error) {
+        if (error instanceof SuiEndpointError) {
+            throw endpointErrorForTool(error, "graphql");
+        }
+        throw error;
+    }
+}
+function endpointErrorForTool(error, transport) {
+    const label = transport === "grpc" ? "gRPC" : "GraphQL";
+    if (error.kind === "chain_identifier_mismatch") {
+        return new LocalSettingsError("input_invalid", `Sui ${label} endpoint did not report the mainnet chain identifier`, {
+            reason: error.kind,
+            ...endpointErrorDetailsForTool(error, ["chainIdentifier", "expectedChainIdentifier"])
+        });
+    }
+    if (error.kind === "endpoint_timeout" || error.kind === "endpoint_unreachable") {
+        return new LocalSettingsError("input_invalid", `Sui ${label} endpoint could not be verified`, {
+            reason: error.kind,
+            ...endpointErrorDetailsForTool(error, error.kind === "endpoint_timeout" ? ["timeoutMs"] : [])
+        });
+    }
+    return new LocalSettingsError("input_invalid", error.message, {
+        reason: error.kind
+    });
+}
+function endpointErrorDetailsForTool(error, allowedKeys) {
+    const details = {};
+    for (const key of allowedKeys) {
+        const value = error.details[key];
+        if (value !== undefined) {
+            details[key] = value;
+        }
+    }
+    return details;
+}

package/dist/runtime/logger.js

@@ -0,0 +1,66 @@
+export function flushStderr() {
+    return new Promise((resolve, reject) => {
+        const failed = (error) => { process.stderr.off("error", failed); reject(error); };
+        process.stderr.once("error", failed);
+        process.stderr.write("", (error) => {
+            // A failed stream write also emits error; keep its handler through that
+            // event instead of allowing EPIPE to replace the intended exit code.
+            if (error) {
+                reject(error);
+                return;
+            }
+            process.stderr.off("error", failed);
+            resolve();
+        });
+    });
+}
+export function createStderrLogger(scope) {
+    const write = (level, message, meta) => {
+        const record = {
+            level,
+            scope,
+            message,
+            meta: meta ? redactMeta(meta) : undefined,
+            at: new Date().toISOString()
+        };
+        process.stderr.write(`${JSON.stringify(record)}\n`);
+    };
+    return {
+        info: (message, meta) => write("info", message, meta),
+        warn: (message, meta) => write("warn", message, meta),
+        error: (message, meta) => write("error", message, meta)
+    };
+}
+const REDACTED = "[redacted]";
+const CIRCULAR = "[circular]";
+const SENSITIVE_META_KEY = /token|secret|private|signature|bytes/i;
+export function redactMeta(meta) {
+    return redactRecord(meta, new WeakSet());
+}
+function redactRecord(record, seen) {
+    if (seen.has(record)) {
+        return { value: CIRCULAR };
+    }
+    seen.add(record);
+    const redacted = Object.fromEntries(Object.entries(record).map(([key, value]) => [
+        key,
+        SENSITIVE_META_KEY.test(key) ? REDACTED : redactValue(value, seen)
+    ]));
+    seen.delete(record);
+    return redacted;
+}
+function redactValue(value, seen) {
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            return CIRCULAR;
+        }
+        seen.add(value);
+        const redacted = value.map((item) => redactValue(item, seen));
+        seen.delete(value);
+        return redacted;
+    }
+    return redactRecord(value, seen);
+}

package/dist/runtime/reviewDependencies.js

@@ -0,0 +1,58 @@
+import { mainnetCoins } from "@mysten/deepbook-v3";
+import { buildSupportedReviewAdapters } from "../adapters/reviewAdapters.js";
+import { validateSupportedAdapterLifecycle } from "../adapters/adapterLifecycleValidators.js";
+import { createDeepbookSwapTransactionMaterialDigestProducer, createDeepbookSwapTransactionMaterialProducer } from "../adapters/deepbook/deepbookTransactionMaterialProducer.js";
+import { createDeepbookSwapHumanReadableReviewProducer } from "../adapters/deepbook/deepbookHumanReviewProducer.js";
+import { createTransactionObjectOwnershipProducer } from "../core/action/transactionObjectOwnershipProducer.js";
+import { createReviewTimeSimulationProducer } from "../core/action/reviewTimeSimulationEvidence.js";
+import { producePtbVisualizationArtifact } from "../core/action/ptbVisualizationProducer.js";
+export function createRuntimeReviewDependencies(options) {
+    const { client: suiClient, chainIdentifier, materialStore: transactionMaterialStore, readService } = options;
+    const config = { network: "mainnet", expectedChainIdentifier: options.expectedChainIdentifier };
+    return {
+        validateAdapterLifecycle: validateSupportedAdapterLifecycle,
+        adapters: buildSupportedReviewAdapters((() => {
+            const transactionObjectOwnershipProducer = createTransactionObjectOwnershipProducer({
+                materialStore: transactionMaterialStore,
+                objectSource: suiClient,
+                fundingSource: suiClient.core,
+                network: config.network,
+                chainIdentifier,
+                expectedChainIdentifier: config.expectedChainIdentifier
+            });
+            const reviewTimeSimulationProducer = createReviewTimeSimulationProducer({
+                client: suiClient,
+                materialStore: transactionMaterialStore,
+                network: config.network,
+                chainIdentifier,
+                expectedChainIdentifier: config.expectedChainIdentifier
+            });
+            return {
+                deepbook: {
+                    deepbookQuoteSource: readService,
+                    deepbookDeepBalanceSource: async (account) => {
+                        const balance = await suiClient.core.getBalance({
+                            owner: account,
+                            coinType: mainnetCoins.DEEP.type
+                        });
+                        return balance.balance.balance.toString();
+                    },
+                    deepbookTransactionMaterialProducer: createDeepbookSwapTransactionMaterialProducer({
+                        client: suiClient,
+                        network: config.network,
+                        chainIdentifier,
+                        expectedChainIdentifier: config.expectedChainIdentifier,
+                        materialStore: transactionMaterialStore
+                    }),
+                    deepbookTransactionMaterialDigestProducer: createDeepbookSwapTransactionMaterialDigestProducer({
+                        materialStore: transactionMaterialStore
+                    }),
+                    transactionObjectOwnershipProducer,
+                    deepbookHumanReadableReviewProducer: createDeepbookSwapHumanReadableReviewProducer(),
+                    reviewTimeSimulationProducer,
+                    ptbVisualizationProducer: (vizInput) => producePtbVisualizationArtifact({ materialStore: transactionMaterialStore, ...vizInput })
+                }
+            };
+        })())
+    };
+}

package/dist/runtime/reviewServerAcquire.js

@@ -0,0 +1,93 @@
+const DEFAULT_REACQUIRE_INTERVAL_MS = 3000;
+function errorCode(error) {
+    return typeof error === "object" && error !== null
+        ? error.code
+        : undefined;
+}
+// Bind the port: returns the server on success, undefined when the port is already
+// in use, and rethrows any other (non-EADDRINUSE) startup error.
+async function tryStart(start, port) {
+    try {
+        return await start(port);
+    }
+    catch (error) {
+        if (errorCode(error) === "EADDRINUSE") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * Bind the review server to its fixed port, or defer to a healthy peer already
+ * serving it.
+ *
+ * - Port free → bind and own the single review origin.
+ * - Port held by a separate healthy instance of our review server → defer (run no
+ *   local server; the peer serves the shared database for every client) and watch for
+ *   the owner to exit, then take the origin over. No peer process is signalled.
+ * - Port held by anything else (foreign, no identity answer, or our own pid) → clear
+ *   error; the origin is never silently reassigned.
+ */
+export async function startOrDeferReviewServer(start, port, deps) {
+    const owned = await tryStart(start, port);
+    if (owned) {
+        deps.logger.info("review server bound; owning the review origin", { port });
+        return { deferred: false, close: () => owned.close() };
+    }
+    const holder = await deps.probeIdentity(port);
+    if (!holder || holder.service !== deps.serviceName || holder.pid === deps.currentPid) {
+        throw Object.assign(new Error(`Review server port ${port} is already in use by a process that is not a separate ${deps.serviceName} review server. ` +
+            `Use the same current runtime and data directory for every client, or choose a different SUI_MCP_REVIEW_PORT. The listener is not replaced automatically.`), { code: "REVIEW_PORT_CONFLICT" });
+    }
+    deps.logger.info("review port owned by a healthy peer; deferring and watching for takeover", {
+        port,
+        ownerPid: holder.pid,
+        ...(holder.version ? { ownerVersion: holder.version } : {})
+    });
+    const reacquireIntervalMs = deps.reacquireIntervalMs ?? DEFAULT_REACQUIRE_INTERVAL_MS;
+    let stopped = false;
+    let acquired;
+    const watch = (async () => {
+        while (!stopped && !acquired) {
+            await deps.delay(reacquireIntervalMs);
+            if (stopped || acquired) {
+                break;
+            }
+            let next;
+            try {
+                next = await tryStart(start, port);
+            }
+            catch (error) {
+                // An authenticated prior owner may have closed its port while its SDK
+                // still owns private storage. Reuse the existing takeover observation.
+                if (typeof error === "object" && error !== null && "code" in error && error.code === "DATA_DIRECTORY_OWNED")
+                    continue;
+                throw error;
+            }
+            if (!next) {
+                continue; // a peer still owns the port; keep deferring
+            }
+            if (stopped) {
+                await next.close();
+                break;
+            }
+            acquired = next;
+            deps.logger.info("acquired review port after the previous owner exited", { port });
+        }
+    })();
+    watch.catch((error) => {
+        if (!stopped)
+            deps.onFailure?.(error instanceof Error ? error : new Error("Shared server acquisition failed."));
+    });
+    return {
+        deferred: true,
+        close: async () => {
+            // Stop watching; the loop's stopped-check closes any bind that lands in-flight,
+            // so we never await the (possibly mid-delay) watch loop here.
+            stopped = true;
+            if (acquired) {
+                await acquired.close();
+            }
+        }
+    };
+}

package/dist/runtime/runtimeTermination.js

@@ -0,0 +1,60 @@
+import { SuiEndpointError } from "../core/suiEndpoint.js";
+// Keep arbitrary SDK/server exception text, endpoint values and stacks private.
+export function runtimeFailureReason(error, stage) {
+    if (error instanceof SuiEndpointError)
+        return `Sui mainnet endpoint verification failed (${error.kind}). Check the configured endpoint.`;
+    const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : undefined;
+    if (code === "DATA_DIRECTORY_OWNED")
+        return "The private data directory is already owned by another wallet runtime.";
+    if (code === "REVIEW_PORT_CONFLICT")
+        return "The review port is held by a foreign or incompatible runtime. Use the same runtime, data directory and port for every client.";
+    if (code && /^(SQLITE_[A-Z_]+|EACCES|EPERM|ENOENT|ENOSPC|EADDRINUSE)$/.test(code))
+        return `Local runtime resource access failed (${code}). Check the data directory and listener configuration.`;
+    if (stage === "configuration")
+        return "Invalid runtime configuration. Check mainnet, endpoint settings and SUI_MCP_REVIEW_PORT.";
+    if (stage === "control_identity")
+        return "The private runtime control identity could not be loaded. Check data directory ownership and permissions.";
+    return "The local runtime could not complete this stage. Check local data permissions and runtime configuration.";
+}
+// Bootstrap alone decides exit intent. Cleanup-induced onclose notifications
+// join the same promise; they cannot replace a fatal or signal exit with EOF.
+export class RuntimeTermination {
+    options;
+    closing;
+    constructor(options) {
+        this.options = options;
+    }
+    get requested() { return this.closing !== undefined; }
+    request(cause) {
+        if (this.closing)
+            return this.closing;
+        this.closing = Promise.resolve().then(async () => {
+            let code = cause.kind === "signal" ? cause.code : cause.kind === "failure" ? 1 : 0;
+            const report = (message, stage, error) => {
+                try {
+                    this.options.logger.error(message, { stage, reason: runtimeFailureReason(error, stage) });
+                }
+                catch { /* Preserve failure intent even if stderr is unavailable. */ }
+            };
+            if (cause.kind === "failure")
+                report("fatal runtime error", cause.stage, cause.error);
+            try {
+                await this.options.close();
+            }
+            catch (error) {
+                if (cause.kind === "client")
+                    code = 1;
+                report("runtime shutdown failed", "runtime_close", error);
+            }
+            try {
+                await this.options.flush();
+            }
+            catch {
+                if (cause.kind === "client")
+                    code = 1;
+            }
+            this.options.exit(code);
+        });
+        return this.closing;
+    }
+}