@cogcoin/client 1.1.5 → 1.1.6

package/dist/bitcoind/managed-runtime/indexer-policy.js

@@ -0,0 +1,200 @@
+import { compareSemver, parseSemver } from "../../semver.js";
+import { INDEXER_DAEMON_SCHEMA_VERSION, INDEXER_DAEMON_SERVICE_API_VERSION, } from "../types.js";
+import { buildManagedIndexerStatusFromSnapshotHandle, resolveManagedIndexerStatusProjection } from "./status.js";
+const STALE_HEARTBEAT_THRESHOLD_MS = 15_000;
+function isUnreachableIndexerDaemonError(error) {
+    if (error instanceof Error) {
+        if (error.message === "indexer_daemon_connection_closed"
+            || error.message === "indexer_daemon_request_timeout"
+            || error.message === "indexer_daemon_protocol_error") {
+            return false;
+        }
+        if ("code" in error) {
+            const code = error.code;
+            return code === "ENOENT" || code === "ECONNREFUSED" || code === "ECONNRESET";
+        }
+    }
+    return false;
+}
+export function validateIndexerRuntimeIdentity(identity, expectedWalletRootId) {
+    void expectedWalletRootId;
+    if (identity.serviceApiVersion !== INDEXER_DAEMON_SERVICE_API_VERSION) {
+        throw new Error("indexer_daemon_service_version_mismatch");
+    }
+    // Managed indexer daemons are adopted across wallet roots when the runtime
+    // is otherwise compatible. Wallet-root ownership remains advisory here.
+    if (identity.schemaVersion !== INDEXER_DAEMON_SCHEMA_VERSION || identity.state === "schema-mismatch") {
+        throw new Error("indexer_daemon_schema_mismatch");
+    }
+}
+export function validateIndexerDaemonStatus(status, expectedWalletRootId) {
+    validateIndexerRuntimeIdentity(status, expectedWalletRootId);
+}
+export function validateIndexerSnapshotHandle(handle, expectedWalletRootId) {
+    validateIndexerRuntimeIdentity(handle, expectedWalletRootId);
+}
+export function validateIndexerSnapshotPayload(payload, handle, expectedWalletRootId) {
+    validateIndexerRuntimeIdentity(payload, expectedWalletRootId);
+    if (payload.token !== handle.token
+        || payload.daemonInstanceId !== handle.daemonInstanceId
+        || payload.processId !== handle.processId
+        || payload.startedAtUnixMs !== handle.startedAtUnixMs
+        || payload.snapshotSeq !== handle.snapshotSeq
+        || payload.tipHeight !== handle.tipHeight
+        || payload.tipHash !== handle.tipHash
+        || payload.openedAtUnixMs !== handle.openedAtUnixMs) {
+        throw new Error("indexer_daemon_snapshot_identity_mismatch");
+    }
+    if (payload.tip === null) {
+        if (payload.tipHeight !== null || payload.tipHash !== null) {
+            throw new Error("indexer_daemon_snapshot_identity_mismatch");
+        }
+    }
+    else if (payload.tip.height !== payload.tipHeight || payload.tip.blockHashHex !== payload.tipHash) {
+        throw new Error("indexer_daemon_snapshot_identity_mismatch");
+    }
+}
+export function mapIndexerDaemonValidationError(error, status) {
+    return {
+        compatibility: error instanceof Error
+            ? error.message === "indexer_daemon_service_version_mismatch"
+                ? "service-version-mismatch"
+                : "schema-mismatch"
+            : "protocol-error",
+        status,
+        client: null,
+        error: error instanceof Error ? error.message : "indexer_daemon_protocol_error",
+    };
+}
+export function mapIndexerDaemonTransportError(error) {
+    return {
+        compatibility: isUnreachableIndexerDaemonError(error) ? "unreachable" : "protocol-error",
+        status: null,
+        client: null,
+        error: isUnreachableIndexerDaemonError(error)
+            ? null
+            : error instanceof Error
+                ? "indexer_daemon_protocol_error"
+                : "indexer_daemon_protocol_error",
+    };
+}
+export function isStaleIndexerDaemonVersion(status, expectedBinaryVersion) {
+    if (status === null || expectedBinaryVersion === null || expectedBinaryVersion === undefined) {
+        return false;
+    }
+    if (parseSemver(expectedBinaryVersion) === null) {
+        return false;
+    }
+    const comparison = compareSemver(status.binaryVersion, expectedBinaryVersion);
+    return comparison === null || comparison < 0;
+}
+export function resolveIndexerDaemonProbeDecision(options) {
+    if (options.probe.compatibility === "compatible") {
+        return {
+            action: isStaleIndexerDaemonVersion(options.probe.status, options.expectedBinaryVersion)
+                ? "replace"
+                : "attach",
+            error: null,
+        };
+    }
+    if (options.probe.compatibility === "unreachable") {
+        return {
+            action: "start",
+            error: null,
+        };
+    }
+    return {
+        action: "reject",
+        error: options.probe.error ?? "indexer_daemon_protocol_error",
+    };
+}
+function mapIndexerStartupError(message) {
+    switch (message) {
+        case "indexer_daemon_start_timeout":
+            return {
+                health: "starting",
+                message: "Indexer daemon is still starting.",
+            };
+        case "indexer_daemon_service_version_mismatch":
+            return {
+                health: "service-version-mismatch",
+                message: "The live indexer daemon is running an incompatible service API version.",
+            };
+        case "indexer_daemon_schema_mismatch":
+            return {
+                health: "schema-mismatch",
+                message: "The live indexer daemon is using an incompatible sqlite schema.",
+            };
+        case "indexer_daemon_wallet_root_mismatch":
+            return {
+                health: "wallet-root-mismatch",
+                message: "The live indexer daemon belongs to a different wallet root.",
+            };
+        case "indexer_daemon_protocol_error":
+            return {
+                health: "unavailable",
+                message: "The live indexer daemon socket responded with an invalid or incomplete protocol exchange.",
+            };
+        case "indexer_daemon_background_follow_recovery_failed":
+            return {
+                health: "failed",
+                message: "The managed indexer daemon could not recover automatic background follow.",
+            };
+        default:
+            return {
+                health: "unavailable",
+                message,
+            };
+    }
+}
+export function deriveManagedIndexerWalletStatus(options) {
+    const projection = resolveManagedIndexerStatusProjection({
+        daemonStatus: options.daemonStatus,
+        observedStatus: options.observedStatus,
+        snapshot: options.snapshot,
+        source: options.source,
+    });
+    const createResult = (health, message) => ({
+        health,
+        status: projection.status,
+        message,
+        snapshotTip: projection.snapshotTip,
+        source: projection.source,
+        daemonInstanceId: projection.daemonInstanceId,
+        snapshotSeq: projection.snapshotSeq,
+        openedAtUnixMs: projection.openedAtUnixMs,
+    });
+    if (options.startupError !== null) {
+        const mapped = mapIndexerStartupError(options.startupError);
+        return createResult(mapped.health, mapped.message);
+    }
+    if (projection.status === null) {
+        return createResult("unavailable", "Indexer daemon is unavailable.");
+    }
+    if ((options.now - projection.status.heartbeatAtUnixMs) > STALE_HEARTBEAT_THRESHOLD_MS) {
+        return createResult("stale-heartbeat", "Indexer daemon heartbeat is stale.");
+    }
+    if (projection.status.state === "schema-mismatch") {
+        return createResult("schema-mismatch", projection.status.lastError ?? "Indexer daemon sqlite schema is incompatible.");
+    }
+    if (projection.status.state === "failed") {
+        return createResult("failed", projection.status.lastError ?? "Indexer daemon refresh failed.");
+    }
+    if (projection.status.state === "service-version-mismatch") {
+        return createResult("service-version-mismatch", "Indexer daemon service API is incompatible.");
+    }
+    if (options.snapshot === null) {
+        if (projection.status.state === "reorging") {
+            return createResult("reorging", "Indexer daemon is replaying a reorg and refreshing the coherent snapshot.");
+        }
+        return createResult(projection.status.state === "catching-up" ? "catching-up" : "starting", "Indexer snapshot is not ready yet.");
+    }
+    if (projection.status.state === "catching-up") {
+        return createResult("catching-up", "Indexer daemon is still catching up to the managed Bitcoin tip.");
+    }
+    if (projection.status.state === "reorging") {
+        return createResult("reorging", "Indexer daemon is replaying a reorg and refreshing the coherent snapshot.");
+    }
+    return createResult("synced", null);
+}
+export { buildManagedIndexerStatusFromSnapshotHandle };

package/dist/bitcoind/managed-runtime/status.d.ts

@@ -0,0 +1,11 @@
+import type { IndexerSnapshotHandle } from "../indexer-daemon.js";
+import { type ManagedIndexerDaemonObservedStatus, type ManagedIndexerDaemonStatus, type ManagedIndexerTruthSource } from "../types.js";
+import type { ManagedIndexerSnapshotLike, ManagedIndexerStatusProjection } from "./types.js";
+export declare function readJsonFileIfPresent<T>(filePath: string): Promise<T | null>;
+export declare function buildManagedIndexerStatusFromSnapshotHandle(handle: IndexerSnapshotHandle): ManagedIndexerDaemonStatus;
+export declare function resolveManagedIndexerStatusProjection(options: {
+    daemonStatus: ManagedIndexerDaemonStatus | null;
+    observedStatus?: ManagedIndexerDaemonObservedStatus | null;
+    snapshot: ManagedIndexerSnapshotLike | null;
+    source: ManagedIndexerTruthSource;
+}): ManagedIndexerStatusProjection;

package/dist/bitcoind/managed-runtime/status.js

@@ -0,0 +1,59 @@
+import { readFile } from "node:fs/promises";
+import { INDEXER_DAEMON_SCHEMA_VERSION, INDEXER_DAEMON_SERVICE_API_VERSION, } from "../types.js";
+export async function readJsonFileIfPresent(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export function buildManagedIndexerStatusFromSnapshotHandle(handle) {
+    return {
+        serviceApiVersion: INDEXER_DAEMON_SERVICE_API_VERSION,
+        binaryVersion: handle.binaryVersion,
+        buildId: handle.buildId,
+        updatedAtUnixMs: Math.max(handle.heartbeatAtUnixMs, handle.openedAtUnixMs),
+        walletRootId: handle.walletRootId,
+        daemonInstanceId: handle.daemonInstanceId,
+        schemaVersion: INDEXER_DAEMON_SCHEMA_VERSION,
+        state: handle.state,
+        processId: handle.processId,
+        startedAtUnixMs: handle.startedAtUnixMs,
+        heartbeatAtUnixMs: handle.heartbeatAtUnixMs,
+        ipcReady: true,
+        rpcReachable: handle.rpcReachable,
+        coreBestHeight: handle.coreBestHeight,
+        coreBestHash: handle.coreBestHash,
+        appliedTipHeight: handle.appliedTipHeight,
+        appliedTipHash: handle.appliedTipHash,
+        snapshotSeq: handle.snapshotSeq,
+        backlogBlocks: handle.backlogBlocks,
+        reorgDepth: handle.reorgDepth,
+        lastAppliedAtUnixMs: handle.lastAppliedAtUnixMs,
+        activeSnapshotCount: handle.activeSnapshotCount,
+        lastError: handle.lastError,
+        backgroundFollowActive: handle.backgroundFollowActive,
+        bootstrapPhase: handle.bootstrapPhase,
+        bootstrapProgress: handle.bootstrapProgress,
+        cogcoinSyncHeight: handle.cogcoinSyncHeight,
+        cogcoinSyncTargetHeight: handle.cogcoinSyncTargetHeight,
+    };
+}
+export function resolveManagedIndexerStatusProjection(options) {
+    const status = options.source === "lease"
+        ? options.daemonStatus
+        : options.observedStatus ?? options.daemonStatus;
+    const source = status === null && options.snapshot === null ? "none" : options.source;
+    return {
+        status,
+        source,
+        snapshotTip: options.snapshot?.tip ?? null,
+        daemonInstanceId: options.snapshot?.daemonInstanceId ?? status?.daemonInstanceId ?? null,
+        snapshotSeq: options.snapshot?.snapshotSeq ?? status?.snapshotSeq ?? null,
+        openedAtUnixMs: options.snapshot?.openedAtUnixMs ?? null,
+    };
+}

package/dist/bitcoind/managed-runtime/types.d.ts

@@ -0,0 +1,37 @@
+import type { ClientTip } from "../../types.js";
+import type { ManagedBitcoindObservedStatus, ManagedIndexerDaemonObservedStatus, ManagedIndexerTruthSource } from "../types.js";
+export type ManagedBitcoindServiceCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "unreachable" | "protocol-error";
+export interface ManagedBitcoindServiceProbeResult {
+    compatibility: ManagedBitcoindServiceCompatibility;
+    status: ManagedBitcoindObservedStatus | null;
+    error: string | null;
+}
+export type IndexerDaemonCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "schema-mismatch" | "unreachable" | "protocol-error";
+export interface ManagedIndexerDaemonProbeResult<TClient> {
+    compatibility: IndexerDaemonCompatibility;
+    status: ManagedIndexerDaemonObservedStatus | null;
+    client: TClient | null;
+    error: string | null;
+}
+export interface ManagedBitcoindProbeDecision {
+    action: "attach" | "start" | "reject";
+    error: string | null;
+}
+export interface IndexerDaemonProbeDecision {
+    action: "attach" | "replace" | "start" | "reject";
+    error: string | null;
+}
+export interface ManagedIndexerSnapshotLike {
+    tip: ClientTip | null;
+    daemonInstanceId?: string | null;
+    snapshotSeq?: string | null;
+    openedAtUnixMs?: number | null;
+}
+export interface ManagedIndexerStatusProjection {
+    status: ManagedIndexerDaemonObservedStatus | null;
+    source: ManagedIndexerTruthSource;
+    snapshotTip: ClientTip | null;
+    daemonInstanceId: string | null;
+    snapshotSeq: string | null;
+    openedAtUnixMs: number | null;
+}

package/dist/bitcoind/managed-runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/bitcoind/service.d.ts

@@ -1,5 +1,7 @@
+import type { ManagedBitcoindServiceProbeResult } from "./managed-runtime/types.js";
 import { resolveManagedServicePaths } from "./service-paths.js";
 import type { InternalManagedBitcoindOptions, ManagedBitcoindObservedStatus, ManagedBitcoindRuntimeConfig, ManagedBitcoindNodeHandle, ManagedCoreWalletReplicaStatus } from "./types.js";
+export type { ManagedBitcoindServiceCompatibility, ManagedBitcoindServiceProbeResult, } from "./managed-runtime/types.js";
 export declare function resolveManagedBitcoindDbcacheMiB(totalRamBytes: number): number;
 interface ManagedWalletReplicaRpc {
     listWallets(): Promise<string[]>;
@@ -26,12 +28,6 @@ type ManagedBitcoindServiceOptions = Pick<InternalManagedBitcoindOptions, "dataD
     getblockArchiveSha256?: string | null;
     serviceLifetime?: "persistent" | "ephemeral";
 };
-export type ManagedBitcoindServiceCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "unreachable" | "protocol-error";
-export interface ManagedBitcoindServiceProbeResult {
-    compatibility: ManagedBitcoindServiceCompatibility;
-    status: ManagedBitcoindObservedStatus | null;
-    error: string | null;
-}
 export interface ManagedBitcoindServiceStopResult {
     status: "stopped" | "not-running";
     walletRootId: string;
@@ -66,4 +62,3 @@ export declare function shutdownManagedBitcoindServiceForTesting(options: {
     walletRootId?: string;
     shutdownTimeoutMs?: number;
 }): Promise<void>;
-export {};

package/dist/bitcoind/service.js

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { execFile, spawn } from "node:child_process";
 import { access, constants, mkdir, readFile, readdir, rm } from "node:fs/promises";
+import { totalmem } from "node:os";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 import net from "node:net";
@@ -9,6 +10,8 @@ import { acquireFileLock, FileLockBusyError } from "../wallet/fs/lock.js";
 import { writeFileAtomic } from "../wallet/fs/atomic.js";
 import { writeRuntimeStatusFile } from "../wallet/fs/status-file.js";
 import { stopIndexerDaemonServiceWithLockHeld } from "./indexer-daemon.js";
+import { mapManagedBitcoindRuntimeProbeFailure, mapManagedBitcoindValidationError, resolveManagedBitcoindProbeDecision, validateManagedBitcoindObservedStatus, } from "./managed-runtime/bitcoind-policy.js";
+import { readJsonFileIfPresent } from "./managed-runtime/status.js";
 import { createRpcClient, validateNodeConfigForTesting } from "./node.js";
 import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "./service-paths.js";
 import { DEFAULT_MANAGED_BITCOIND_FOLLOW_POLL_INTERVAL_MS, MANAGED_BITCOIND_SERVICE_API_VERSION as MANAGED_BITCOIND_SERVICE_API_VERSION_VALUE, } from "./types.js";
@@ -17,14 +20,31 @@ const LOCAL_HOST = "127.0.0.1";
 const SUPPORTED_BITCOIND_VERSION = "30.2.0";
 const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 15_000;
-const DEFAULT_DBCACHE_MIB = 2048;
+const DEFAULT_DBCACHE_MIB = 450;
 const claimedUninitializedRuntimeKeys = new Set();
+const GIB = 1024 ** 3;
 export function resolveManagedBitcoindDbcacheMiB(totalRamBytes) {
-    void totalRamBytes;
-    return DEFAULT_DBCACHE_MIB;
+    if (!Number.isFinite(totalRamBytes) || totalRamBytes <= 0) {
+        return DEFAULT_DBCACHE_MIB;
+    }
+    if (totalRamBytes < 8 * GIB) {
+        return 450;
+    }
+    if (totalRamBytes < 16 * GIB) {
+        return 768;
+    }
+    if (totalRamBytes < 32 * GIB) {
+        return 1024;
+    }
+    return 2048;
 }
 function detectManagedBitcoindDbcacheMiB() {
-    return DEFAULT_DBCACHE_MIB;
+    try {
+        return resolveManagedBitcoindDbcacheMiB(totalmem());
+    }
+    catch {
+        return DEFAULT_DBCACHE_MIB;
+    }
 }
 function sleep(ms) {
     return new Promise((resolve) => {
@@ -58,21 +78,10 @@ async function acquireFileLockWithRetry(lockPath, metadata, timeoutMs) {
 function getWalletReplicaName(walletRootId) {
     return `cogcoin-${walletRootId}`.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 63);
 }
-async function readJsonFile(filePath) {
-    try {
-        return JSON.parse(await readFile(filePath, "utf8"));
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-            return null;
-        }
-        throw error;
-    }
-}
 async function listManagedBitcoindStatusCandidates(options) {
     const candidates = new Map();
     const addCandidate = async (statusPath, allowDataDirMismatch = false) => {
-        const status = await readJsonFile(statusPath);
+        const status = await readJsonFileIfPresent(statusPath);
         if (status === null) {
             return;
         }
@@ -207,38 +216,6 @@ async function waitForRpcReady(rpc, cookieFile, expectedChain, timeoutMs) {
     }
     throw lastError instanceof Error ? lastError : new Error("bitcoind_rpc_timeout");
 }
-function validateManagedBitcoindStatus(status, options, runtimeRoot) {
-    const legacyRuntimeRoot = join(resolveManagedServicePaths(options.dataDir ?? "", options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID).runtimeRoot, status.walletRootId);
-    if (status.serviceApiVersion !== MANAGED_BITCOIND_SERVICE_API_VERSION_VALUE) {
-        throw new Error("managed_bitcoind_service_version_mismatch");
-    }
-    if (status.chain !== options.chain
-        || status.dataDir !== (options.dataDir ?? "")
-        || (status.runtimeRoot !== runtimeRoot && status.runtimeRoot !== legacyRuntimeRoot)) {
-        throw new Error("managed_bitcoind_runtime_mismatch");
-    }
-}
-function isRuntimeMismatchError(error) {
-    if (!(error instanceof Error)) {
-        return false;
-    }
-    return error.message.startsWith("bitcoind_chain_expected_")
-        || error.message === "managed_bitcoind_runtime_mismatch";
-}
-function isUnreachableManagedBitcoindError(error) {
-    if (error instanceof Error) {
-        if ("code" in error) {
-            const code = error.code;
-            return code === "ENOENT" || code === "ECONNREFUSED" || code === "ECONNRESET";
-        }
-        return error.message === "bitcoind_cookie_timeout"
-            || error.message.includes("cookie file is unavailable")
-            || error.message.includes("ECONNREFUSED")
-            || error.message.includes("ECONNRESET")
-            || error.message.includes("socket hang up");
-    }
-    return false;
-}
 function createBitcoindServiceStatus(options) {
     return {
         serviceApiVersion: MANAGED_BITCOIND_SERVICE_API_VERSION_VALUE,
@@ -264,27 +241,16 @@ function createBitcoindServiceStatus(options) {
         lastError: options.lastError,
     };
 }
-function mapManagedBitcoindValidationError(error) {
-    return {
-        compatibility: error instanceof Error
-            ? error.message === "managed_bitcoind_service_version_mismatch"
-                ? "service-version-mismatch"
-                : "runtime-mismatch"
-            : "protocol-error",
-        status: null,
-        error: error instanceof Error ? error.message : "managed_bitcoind_protocol_error",
-    };
-}
 async function probeManagedBitcoindStatusCandidate(status, options, runtimeRoot) {
     try {
-        validateManagedBitcoindStatus(status, options, runtimeRoot);
+        validateManagedBitcoindObservedStatus(status, {
+            chain: options.chain,
+            dataDir: options.dataDir ?? "",
+            runtimeRoot,
+        });
     }
     catch (error) {
-        const mapped = mapManagedBitcoindValidationError(error);
-        return {
-            ...mapped,
-            status,
-        };
+        return mapManagedBitcoindValidationError(error, status);
     }
     const rpc = createRpcClient(status.rpc);
     try {
@@ -297,30 +263,12 @@ async function probeManagedBitcoindStatusCandidate(status, options, runtimeRoot)
         };
     }
     catch (error) {
-        if (isRuntimeMismatchError(error)) {
-            return {
-                compatibility: "runtime-mismatch",
-                status,
-                error: "managed_bitcoind_runtime_mismatch",
-            };
-        }
-        if (isUnreachableManagedBitcoindError(error)) {
-            return {
-                compatibility: "unreachable",
-                status,
-                error: null,
-            };
-        }
-        return {
-            compatibility: "protocol-error",
-            status,
-            error: "managed_bitcoind_protocol_error",
-        };
+        return mapManagedBitcoindRuntimeProbeFailure(error, status);
     }
 }
 async function resolveRuntimeConfig(statusPath, configPath, options) {
-    const previousStatus = await readJsonFile(statusPath);
-    const previousConfig = await readJsonFile(configPath);
+    const previousStatus = await readJsonFileIfPresent(statusPath);
+    const previousConfig = await readJsonFileIfPresent(configPath);
     const reserved = new Set();
     const rpcPort = options.rpcPort
         ?? previousStatus?.rpc.port
@@ -545,7 +493,7 @@ async function clearManagedBitcoindRuntimeArtifacts(paths) {
 export async function stopManagedBitcoindServiceWithLockHeld(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = options.paths ?? resolveManagedServicePaths(options.dataDir, walletRootId);
-    const status = await readJsonFile(paths.bitcoindStatusPath);
+    const status = await readJsonFileIfPresent(paths.bitcoindStatusPath);
     const processId = status?.processId ?? null;
     if (status === null || processId === null || !await isProcessAlive(processId)) {
         await clearManagedBitcoindRuntimeArtifacts(paths);
@@ -769,14 +717,16 @@ export async function attachOrStartManagedBitcoindService(options) {
         shutdownTimeoutMs: resolvedOptions.shutdownTimeoutMs,
     }, async () => {
         const existingProbe = await probeManagedBitcoindService(resolvedOptions);
-        if (existingProbe.compatibility === "compatible") {
+        const existingDecision = resolveManagedBitcoindProbeDecision(existingProbe);
+        if (existingDecision.action === "attach") {
             const existing = await tryAttachExistingManagedBitcoindService(resolvedOptions);
             if (existing !== null) {
                 return existing;
             }
+            throw new Error("managed_bitcoind_protocol_error");
         }
-        if (existingProbe.compatibility !== "unreachable") {
-            throw new Error(existingProbe.error ?? "managed_bitcoind_protocol_error");
+        if (existingDecision.action === "reject") {
+            throw new Error(existingDecision.error ?? "managed_bitcoind_protocol_error");
         }
         const paths = resolveManagedServicePaths(resolvedOptions.dataDir ?? "", resolvedOptions.walletRootId);
         try {
@@ -787,14 +737,16 @@ export async function attachOrStartManagedBitcoindService(options) {
             });
             try {
                 const liveProbe = await probeManagedBitcoindService(resolvedOptions);
-                if (liveProbe.compatibility === "compatible") {
+                const liveDecision = resolveManagedBitcoindProbeDecision(liveProbe);
+                if (liveDecision.action === "attach") {
                     const reattached = await tryAttachExistingManagedBitcoindService(resolvedOptions);
                     if (reattached !== null) {
                         return reattached;
                     }
+                    throw new Error("managed_bitcoind_protocol_error");
                 }
-                if (liveProbe.compatibility !== "unreachable") {
-                    throw new Error(liveProbe.error ?? "managed_bitcoind_protocol_error");
+                if (liveDecision.action === "reject") {
+                    throw new Error(liveDecision.error ?? "managed_bitcoind_protocol_error");
                 }
                 const bitcoindPath = await getBitcoindPath();
                 await verifyBitcoindVersion(bitcoindPath);
@@ -915,7 +867,7 @@ export async function stopManagedBitcoindService(options) {
 }
 export async function readManagedBitcoindServiceStatusForTesting(dataDir, walletRootId = UNINITIALIZED_WALLET_ROOT_ID) {
     const paths = resolveManagedServicePaths(dataDir, walletRootId);
-    return readJsonFile(paths.bitcoindStatusPath);
+    return readJsonFileIfPresent(paths.bitcoindStatusPath);
 }
 export async function shutdownManagedBitcoindServiceForTesting(options) {
     await stopManagedBitcoindService({

package/dist/wallet/lifecycle/access.d.ts

@@ -0,0 +1,5 @@
+import type { WalletAccessContext, WalletLoadedState } from "./types.js";
+export declare function isWalletSecretAccessError(error: unknown): boolean;
+export declare function mapWalletReadAccessError(error: unknown): Error;
+export declare function normalizeLoadedWalletStateIfNeeded(options: WalletAccessContext & WalletLoadedState): Promise<WalletLoadedState>;
+export declare function loadWalletStateForAccess(options: WalletAccessContext): Promise<WalletLoadedState>;

package/dist/wallet/lifecycle/access.js

@@ -0,0 +1,79 @@
+import { normalizeWalletStateRecord, persistWalletCoinControlStateIfNeeded, } from "../coin-control.js";
+import { persistNormalizedWalletDescriptorStateIfNeeded } from "../descriptor-normalization.js";
+import { normalizeMiningStateRecord } from "../mining/state.js";
+import { createWalletSecretReference } from "../state/provider.js";
+import { loadWalletState } from "../state/storage.js";
+export function isWalletSecretAccessError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.startsWith("wallet_secret_missing_")
+        || message.startsWith("wallet_secret_provider_");
+}
+export function mapWalletReadAccessError(error) {
+    if (isWalletSecretAccessError(error)) {
+        return new Error("wallet_secret_provider_unavailable");
+    }
+    return new Error("local-state-corrupt");
+}
+export async function normalizeLoadedWalletStateIfNeeded(options) {
+    let state = options.state;
+    let source = options.source;
+    if (options.dataDir !== undefined) {
+        const node = await options.attachService({
+            dataDir: options.dataDir,
+            chain: "main",
+            startHeight: 0,
+            walletRootId: state.walletRootId,
+        });
+        try {
+            const normalizedDescriptorState = await persistNormalizedWalletDescriptorStateIfNeeded({
+                state,
+                access: {
+                    provider: options.provider,
+                    secretReference: createWalletSecretReference(state.walletRootId),
+                },
+                paths: options.paths,
+                nowUnixMs: options.nowUnixMs,
+                replacePrimary: source === "backup",
+                rpc: options.rpcFactory(node.rpc),
+            });
+            state = normalizedDescriptorState.state;
+            source = normalizedDescriptorState.changed ? "primary" : source;
+            const reconciledCoinControl = await persistWalletCoinControlStateIfNeeded({
+                state,
+                access: {
+                    provider: options.provider,
+                    secretReference: createWalletSecretReference(state.walletRootId),
+                },
+                paths: options.paths,
+                nowUnixMs: options.nowUnixMs,
+                replacePrimary: source === "backup",
+                rpc: options.rpcFactory(node.rpc),
+            });
+            state = reconciledCoinControl.state;
+            source = reconciledCoinControl.changed ? "primary" : source;
+        }
+        finally {
+            await node.stop?.().catch(() => undefined);
+        }
+    }
+    return {
+        state: normalizeWalletStateRecord({
+            ...state,
+            miningState: normalizeMiningStateRecord(state.miningState),
+        }),
+        source,
+    };
+}
+export async function loadWalletStateForAccess(options) {
+    const loaded = await loadWalletState({
+        primaryPath: options.paths.walletStatePath,
+        backupPath: options.paths.walletStateBackupPath,
+    }, {
+        provider: options.provider,
+    });
+    return await normalizeLoadedWalletStateIfNeeded({
+        ...options,
+        state: loaded.state,
+        source: loaded.source,
+    });
+}