@cogcoin/client 1.1.4 → 1.1.6

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@1.1.4` is the reference Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
+`@cogcoin/client@1.1.6` is the reference Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
 
 Use Node 22 or newer.
 
@@ -131,21 +131,20 @@ Managed node subpath:
 The installed `cogcoin` command covers the first-party local wallet and node workflow:
 
 - update commands such as `update` to compare the current CLI version with the latest npm release and install it
-- wallet lifecycle commands such as `init`, `restore`, `wallet delete`, `wallet show-mnemonic`, and `repair`
+- wallet lifecycle commands such as `init`, `reset`, `wallet show-mnemonic`, and `repair`
 - sync and service commands such as `status`, `sync`, `follow`, `bitcoin start`, `bitcoin stop`, `bitcoin status`, `indexer start`, `indexer stop`, and `indexer status`
 - domain and field commands such as `register`, `anchor`, `show`, `domains`, `fields`, `buy`, `sell`, and `transfer`
 - COG and reputation commands such as `send`, `cog lock`, `claim`, `reclaim`, `rep give`, and `rep revoke`
 - mining commands such as `mine`, `mine start`, `mine stop`, `mine status`, `mine log`, `mine setup`, `mine prompt`, and `mine prompt list`
 
-The CLI also supports stable `--output json` and `--output preview-json` envelopes on the commands that advertise machine-readable output.
 Use `cogcoin mine prompt <domain>` to set or clear a per-domain mining prompt override for one anchored root domain, and `cogcoin mine prompt list` to inspect the current per-domain prompt state alongside the global fallback prompt.
 Interactive text invocations periodically check the npm registry for newer `@cogcoin/client` releases and print `npm install -g @cogcoin/client` when a newer version is available.
 Set `COGCOIN_DISABLE_UPDATE_CHECK=1` to disable the CLI update notice entirely.
 Ordinary `sync`, `follow`, and wallet-aware read/status flows detach from the managed Bitcoin and indexer services on exit instead of stopping them.
 Use the explicit `bitcoin ...` and `indexer ...` commands when you want direct service inspection or start/stop control.
 For provider-backed local wallets, normal reads, mutations, and mining setup flows load local wallet state on demand whenever the local secret provider is available.
-`cogcoin restore` and `cogcoin wallet restore` rebuild a fresh local wallet from a 24-word English BIP39 mnemonic and recreate the managed Core wallet replica.
-Run `cogcoin sync` afterward to bootstrap the managed Bitcoin/indexer state.
+When no wallet exists yet, `cogcoin init` interactively lets you either create a new wallet or restore an existing one from a 24-word English BIP39 mnemonic, then continues into sync.
+To replace an existing wallet with a different mnemonic, run `cogcoin reset`, choose `clear wallet entropy`, and then rerun `cogcoin init`.
 
 ## SQLite Store
 

package/dist/bitcoind/indexer-daemon.d.ts

@@ -1,5 +1,7 @@
+import type { ManagedIndexerDaemonProbeResult } from "./managed-runtime/types.js";
 import { type BootstrapPhase, type BootstrapProgress, type ManagedIndexerDaemonObservedStatus, type ManagedIndexerDaemonStatus } from "./types.js";
 import { resolveManagedServicePaths } from "./service-paths.js";
+export type { IndexerDaemonCompatibility } from "./managed-runtime/types.js";
 export declare const INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED = "indexer_daemon_background_follow_recovery_failed";
 interface DaemonRequest {
     id: string;
@@ -74,13 +76,7 @@ export interface IndexerDaemonClient {
     resumeBackgroundFollow(): Promise<void>;
     close(): Promise<void>;
 }
-export type IndexerDaemonCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "schema-mismatch" | "unreachable" | "protocol-error";
-export interface IndexerDaemonProbeResult {
-    compatibility: IndexerDaemonCompatibility;
-    status: ManagedIndexerDaemonObservedStatus | null;
-    client: IndexerDaemonClient | null;
-    error: string | null;
-}
+export type IndexerDaemonProbeResult = ManagedIndexerDaemonProbeResult<IndexerDaemonClient>;
 export interface IndexerDaemonStopResult {
     status: "stopped" | "not-running";
     walletRootId: string;

package/dist/bitcoind/indexer-daemon.js

@@ -1,12 +1,13 @@
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
-import { mkdir, readFile, rm } from "node:fs/promises";
+import { mkdir, rm } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import net from "node:net";
-import { compareSemver, parseSemver } from "../semver.js";
 import { acquireFileLock, FileLockBusyError } from "../wallet/fs/lock.js";
 import { writeRuntimeStatusFile } from "../wallet/fs/status-file.js";
-import { INDEXER_DAEMON_SCHEMA_VERSION, INDEXER_DAEMON_SERVICE_API_VERSION, } from "./types.js";
+import { buildManagedIndexerStatusFromSnapshotHandle, mapIndexerDaemonTransportError, mapIndexerDaemonValidationError, resolveIndexerDaemonProbeDecision, validateIndexerDaemonStatus, validateIndexerSnapshotHandle, validateIndexerSnapshotPayload, } from "./managed-runtime/indexer-policy.js";
+import { readJsonFileIfPresent } from "./managed-runtime/status.js";
+import {} from "./types.js";
 import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "./service-paths.js";
 const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000;
@@ -15,17 +16,6 @@ const INDEXER_DAEMON_REQUEST_TIMEOUT_MS = 15_000;
 const INDEXER_DAEMON_RESUME_BACKGROUND_FOLLOW_REQUEST_TIMEOUT_MS = 35_000;
 const INDEXER_DAEMON_BACKGROUND_FOLLOW_NOT_ACTIVE = "indexer_daemon_background_follow_not_active";
 export const INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED = "indexer_daemon_background_follow_recovery_failed";
-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 isProcessAlive(pid) {
     if (pid === null) {
         return false;
@@ -68,7 +58,7 @@ function ignoreProcessNotFound(error) {
 export async function stopIndexerDaemonServiceWithLockHeld(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = options.paths ?? resolveManagedServicePaths(options.dataDir, walletRootId);
-    const status = await readJsonFile(paths.indexerDaemonStatusPath);
+    const status = await readJsonFileIfPresent(paths.indexerDaemonStatusPath);
     const processId = options.processId ?? status?.processId ?? null;
     if (status === null || processId === null || !await isProcessAlive(processId)) {
         await clearIndexerDaemonRuntimeArtifacts(paths);
@@ -217,97 +207,6 @@ function createIndexerDaemonClient(socketPath, closeOptions = null) {
         },
     };
 }
-function validateIndexerRuntimeIdentity(identity, expectedWalletRootId) {
-    if (identity.serviceApiVersion !== INDEXER_DAEMON_SERVICE_API_VERSION) {
-        throw new Error("indexer_daemon_service_version_mismatch");
-    }
-    if (identity.schemaVersion !== INDEXER_DAEMON_SCHEMA_VERSION || identity.state === "schema-mismatch") {
-        throw new Error("indexer_daemon_schema_mismatch");
-    }
-}
-function validateIndexerDaemonStatus(status, expectedWalletRootId) {
-    validateIndexerRuntimeIdentity(status, expectedWalletRootId);
-}
-function validateIndexerSnapshotHandle(handle, expectedWalletRootId) {
-    validateIndexerRuntimeIdentity(handle, expectedWalletRootId);
-}
-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");
-    }
-}
-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;
-}
-function buildStatusFromSnapshotHandle(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,
-    };
-}
-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;
-}
 async function probeIndexerDaemonAtSocket(socketPath, expectedWalletRootId) {
     const client = createIndexerDaemonClient(socketPath);
     try {
@@ -323,30 +222,12 @@ async function probeIndexerDaemonAtSocket(socketPath, expectedWalletRootId) {
         }
         catch (error) {
             await client.close().catch(() => undefined);
-            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",
-            };
+            return mapIndexerDaemonValidationError(error, status);
         }
     }
     catch (error) {
         await client.close().catch(() => undefined);
-        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",
-        };
+        return mapIndexerDaemonTransportError(error);
     }
 }
 async function waitForIndexerDaemon(dataDir, walletRootId, timeoutMs) {
@@ -380,7 +261,7 @@ export async function readSnapshotWithRetry(daemon, expectedWalletRootId) {
             validateIndexerSnapshotPayload(payload, handle, expectedWalletRootId);
             return {
                 payload,
-                status: buildStatusFromSnapshotHandle(handle),
+                status: buildManagedIndexerStatusFromSnapshotHandle(handle),
             };
         }
         catch (error) {
@@ -400,7 +281,7 @@ export async function readSnapshotWithRetry(daemon, expectedWalletRootId) {
 export async function readObservedIndexerDaemonStatus(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
-    return readJsonFile(paths.indexerDaemonStatusPath);
+    return readJsonFileIfPresent(paths.indexerDaemonStatusPath);
 }
 export async function attachOrStartIndexerDaemon(options) {
     const requestBackgroundFollow = async (client, observedStatus = null) => {
@@ -467,21 +348,23 @@ export async function attachOrStartIndexerDaemon(options) {
         });
     };
     const existingProbe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
-    if (existingProbe.compatibility === "compatible" && existingProbe.client !== null) {
-        if (!isStaleIndexerDaemonVersion(existingProbe.status, expectedBinaryVersion)) {
-            try {
-                return await requestBackgroundFollow(existingProbe.client, existingProbe.status);
-            }
-            catch {
-                await existingProbe.client.close().catch(() => undefined);
-            }
+    const existingDecision = resolveIndexerDaemonProbeDecision({
+        probe: existingProbe,
+        expectedBinaryVersion,
+    });
+    if (existingDecision.action === "attach" && existingProbe.client !== null) {
+        try {
+            return await requestBackgroundFollow(existingProbe.client, existingProbe.status);
         }
-        else {
+        catch {
             await existingProbe.client.close().catch(() => undefined);
         }
     }
-    if (existingProbe.compatibility !== "unreachable" && existingProbe.compatibility !== "compatible") {
-        throw new Error(existingProbe.error ?? "indexer_daemon_protocol_error");
+    if (existingDecision.action === "replace" && existingProbe.client !== null) {
+        await existingProbe.client.close().catch(() => undefined);
+    }
+    if (existingDecision.action === "reject") {
+        throw new Error(existingDecision.error ?? "indexer_daemon_protocol_error");
     }
     try {
         const lock = await acquireFileLock(paths.indexerDaemonLockPath, {
@@ -492,23 +375,15 @@ export async function attachOrStartIndexerDaemon(options) {
         });
         try {
             const liveProbe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
-            if (liveProbe.compatibility === "compatible" && liveProbe.client !== null) {
-                if (!isStaleIndexerDaemonVersion(liveProbe.status, expectedBinaryVersion)) {
-                    try {
-                        return await requestBackgroundFollow(liveProbe.client, liveProbe.status);
-                    }
-                    catch {
-                        await liveProbe.client.close().catch(() => undefined);
-                        await stopIndexerDaemonServiceWithLockHeld({
-                            dataDir: options.dataDir,
-                            walletRootId,
-                            shutdownTimeoutMs: options.shutdownTimeoutMs,
-                            paths,
-                            processId: liveProbe.status?.processId ?? null,
-                        });
-                    }
+            const liveDecision = resolveIndexerDaemonProbeDecision({
+                probe: liveProbe,
+                expectedBinaryVersion,
+            });
+            if (liveDecision.action === "attach" && liveProbe.client !== null) {
+                try {
+                    return await requestBackgroundFollow(liveProbe.client, liveProbe.status);
                 }
-                else {
+                catch {
                     await liveProbe.client.close().catch(() => undefined);
                     await stopIndexerDaemonServiceWithLockHeld({
                         dataDir: options.dataDir,
@@ -519,8 +394,18 @@ export async function attachOrStartIndexerDaemon(options) {
                     });
                 }
             }
-            else if (liveProbe.compatibility !== "unreachable") {
-                throw new Error(liveProbe.error ?? "indexer_daemon_protocol_error");
+            else if (liveDecision.action === "replace" && liveProbe.client !== null) {
+                await liveProbe.client.close().catch(() => undefined);
+                await stopIndexerDaemonServiceWithLockHeld({
+                    dataDir: options.dataDir,
+                    walletRootId,
+                    shutdownTimeoutMs: options.shutdownTimeoutMs,
+                    paths,
+                    processId: liveProbe.status?.processId ?? null,
+                });
+            }
+            else if (liveDecision.action === "reject") {
+                throw new Error(liveDecision.error ?? "indexer_daemon_protocol_error");
             }
             const daemon = await startDaemon();
             try {
@@ -572,7 +457,7 @@ export async function shutdownIndexerDaemonForTesting(options) {
 export async function readIndexerDaemonStatusForTesting(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
-    return readJsonFile(paths.indexerDaemonStatusPath);
+    return readJsonFileIfPresent(paths.indexerDaemonStatusPath);
 }
 export async function writeIndexerDaemonStatusForTesting(options, status) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;

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

@@ -0,0 +1,16 @@
+import type { ManagedBitcoindObservedStatus } from "../types.js";
+import type { WalletBitcoindStatus, WalletNodeStatus } from "../../wallet/read/types.js";
+import type { ManagedBitcoindProbeDecision, ManagedBitcoindServiceProbeResult } from "./types.js";
+export declare function validateManagedBitcoindObservedStatus(status: ManagedBitcoindObservedStatus, options: {
+    chain: "main" | "regtest";
+    dataDir: string;
+    runtimeRoot: string;
+}): void;
+export declare function mapManagedBitcoindValidationError(error: unknown, status: ManagedBitcoindObservedStatus): ManagedBitcoindServiceProbeResult;
+export declare function mapManagedBitcoindRuntimeProbeFailure(error: unknown, status: ManagedBitcoindObservedStatus): ManagedBitcoindServiceProbeResult;
+export declare function resolveManagedBitcoindProbeDecision(probe: ManagedBitcoindServiceProbeResult): ManagedBitcoindProbeDecision;
+export declare function deriveManagedBitcoindWalletStatus(options: {
+    status: ManagedBitcoindObservedStatus | null;
+    nodeStatus: WalletNodeStatus | null;
+    startupError: string | null;
+}): WalletBitcoindStatus;

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

@@ -0,0 +1,177 @@
+import { join } from "node:path";
+import { resolveManagedServicePaths } from "../service-paths.js";
+import { MANAGED_BITCOIND_SERVICE_API_VERSION } from "../types.js";
+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;
+}
+export function validateManagedBitcoindObservedStatus(status, options) {
+    const legacyRuntimeRoot = join(resolveManagedServicePaths(options.dataDir, status.walletRootId).runtimeRoot, status.walletRootId);
+    if (status.serviceApiVersion !== MANAGED_BITCOIND_SERVICE_API_VERSION) {
+        throw new Error("managed_bitcoind_service_version_mismatch");
+    }
+    // Managed bitcoind runtimes are adopted across wallet roots when the live
+    // runtime still points at the expected data dir and chain.
+    if (status.chain !== options.chain
+        || status.dataDir !== options.dataDir
+        || (status.runtimeRoot !== options.runtimeRoot && status.runtimeRoot !== legacyRuntimeRoot)) {
+        throw new Error("managed_bitcoind_runtime_mismatch");
+    }
+}
+export function mapManagedBitcoindValidationError(error, status) {
+    return {
+        compatibility: error instanceof Error
+            ? error.message === "managed_bitcoind_service_version_mismatch"
+                ? "service-version-mismatch"
+                : "runtime-mismatch"
+            : "protocol-error",
+        status,
+        error: error instanceof Error ? error.message : "managed_bitcoind_protocol_error",
+    };
+}
+export function mapManagedBitcoindRuntimeProbeFailure(error, status) {
+    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",
+    };
+}
+export function resolveManagedBitcoindProbeDecision(probe) {
+    if (probe.compatibility === "compatible") {
+        return {
+            action: "attach",
+            error: null,
+        };
+    }
+    if (probe.compatibility === "unreachable") {
+        return {
+            action: "start",
+            error: null,
+        };
+    }
+    return {
+        action: "reject",
+        error: probe.error ?? "managed_bitcoind_protocol_error",
+    };
+}
+function mapManagedBitcoindStartupError(message) {
+    switch (message) {
+        case "managed_bitcoind_service_start_timeout":
+            return {
+                health: "starting",
+                status: null,
+                message: "Managed bitcoind service is still starting.",
+            };
+        case "managed_bitcoind_service_version_mismatch":
+            return {
+                health: "service-version-mismatch",
+                status: null,
+                message: "The live managed bitcoind service is running an incompatible service version.",
+            };
+        case "managed_bitcoind_wallet_root_mismatch":
+            return {
+                health: "wallet-root-mismatch",
+                status: null,
+                message: "The live managed bitcoind service belongs to a different wallet root.",
+            };
+        case "managed_bitcoind_runtime_mismatch":
+            return {
+                health: "runtime-mismatch",
+                status: null,
+                message: "The live managed bitcoind service runtime does not match this wallet's expected data directory or chain.",
+            };
+        case "managed_bitcoind_protocol_error":
+            return {
+                health: "unavailable",
+                status: null,
+                message: "The managed bitcoind runtime artifacts are invalid or incomplete.",
+            };
+        default:
+            return {
+                health: "unavailable",
+                status: null,
+                message,
+            };
+    }
+}
+export function deriveManagedBitcoindWalletStatus(options) {
+    if (options.startupError !== null) {
+        const mapped = mapManagedBitcoindStartupError(options.startupError);
+        return {
+            ...mapped,
+            status: options.status,
+        };
+    }
+    if (options.status === null) {
+        return {
+            health: "unavailable",
+            status: null,
+            message: "Managed bitcoind service is unavailable.",
+        };
+    }
+    if (options.status.state === "starting") {
+        return {
+            health: "starting",
+            status: options.status,
+            message: options.status.lastError ?? "Managed bitcoind service is still starting.",
+        };
+    }
+    if (options.status.state === "failed") {
+        return {
+            health: "failed",
+            status: options.status,
+            message: options.status.lastError ?? "Managed bitcoind service refresh failed.",
+        };
+    }
+    const proofStatus = options.nodeStatus?.walletReplica?.proofStatus;
+    if (proofStatus === "missing") {
+        return {
+            health: "replica-missing",
+            status: options.status,
+            message: options.nodeStatus?.walletReplicaMessage ?? "Managed Core wallet replica is missing.",
+        };
+    }
+    if (proofStatus === "mismatch") {
+        return {
+            health: "replica-mismatch",
+            status: options.status,
+            message: options.nodeStatus?.walletReplicaMessage ?? "Managed Core wallet replica does not match trusted wallet state.",
+        };
+    }
+    return {
+        health: "ready",
+        status: options.status,
+        message: options.nodeStatus?.walletReplicaMessage ?? options.status.lastError,
+    };
+}

package/dist/bitcoind/managed-runtime/indexer-policy.d.ts

@@ -0,0 +1,34 @@
+import type { WalletIndexerStatus } from "../../wallet/read/types.js";
+import type { IndexerSnapshotHandle, IndexerSnapshotPayload } from "../indexer-daemon.js";
+import { type ManagedIndexerDaemonObservedStatus, type ManagedIndexerDaemonStatus, type ManagedIndexerTruthSource } from "../types.js";
+import { buildManagedIndexerStatusFromSnapshotHandle } from "./status.js";
+import type { IndexerDaemonProbeDecision, ManagedIndexerDaemonProbeResult, ManagedIndexerSnapshotLike } from "./types.js";
+type IndexerRuntimeIdentityLike = {
+    serviceApiVersion: string;
+    schemaVersion: string;
+    walletRootId: string;
+    daemonInstanceId: string;
+    processId: number | null;
+    startedAtUnixMs: number;
+    state?: ManagedIndexerDaemonStatus["state"] | string;
+};
+export declare function validateIndexerRuntimeIdentity(identity: IndexerRuntimeIdentityLike, expectedWalletRootId: string): void;
+export declare function validateIndexerDaemonStatus(status: ManagedIndexerDaemonObservedStatus, expectedWalletRootId: string): void;
+export declare function validateIndexerSnapshotHandle(handle: IndexerSnapshotHandle, expectedWalletRootId: string): void;
+export declare function validateIndexerSnapshotPayload(payload: IndexerSnapshotPayload, handle: IndexerSnapshotHandle, expectedWalletRootId: string): void;
+export declare function mapIndexerDaemonValidationError<TClient>(error: unknown, status: ManagedIndexerDaemonObservedStatus): ManagedIndexerDaemonProbeResult<TClient>;
+export declare function mapIndexerDaemonTransportError<TClient>(error: unknown): ManagedIndexerDaemonProbeResult<TClient>;
+export declare function isStaleIndexerDaemonVersion(status: ManagedIndexerDaemonObservedStatus | null, expectedBinaryVersion: string | null | undefined): boolean;
+export declare function resolveIndexerDaemonProbeDecision<TClient>(options: {
+    probe: ManagedIndexerDaemonProbeResult<TClient>;
+    expectedBinaryVersion: string | null | undefined;
+}): IndexerDaemonProbeDecision;
+export declare function deriveManagedIndexerWalletStatus(options: {
+    daemonStatus: ManagedIndexerDaemonStatus | null;
+    observedStatus?: ManagedIndexerDaemonObservedStatus | null;
+    snapshot: ManagedIndexerSnapshotLike | null;
+    source: ManagedIndexerTruthSource;
+    now: number;
+    startupError: string | null;
+}): WalletIndexerStatus;
+export { buildManagedIndexerStatusFromSnapshotHandle };