@cogcoin/client 1.1.14 → 1.1.15

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@1.1.14` 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.15` 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.
 

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

@@ -1,5 +1,6 @@
 import type { ManagedIndexerDaemonProbeResult } from "../managed-runtime/types.js";
 import type { ManagedIndexerDaemonObservedStatus } from "../types.js";
+import { resolveManagedServicePaths } from "../service-paths.js";
 import type { CoherentIndexerSnapshotLease, IndexerDaemonClient, IndexerDaemonStopResult, ManagedIndexerDaemonServiceLifetime } from "./types.js";
 export type { IndexerDaemonCompatibility } from "../managed-runtime/types.js";
 export declare const INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED = "indexer_daemon_background_follow_recovery_failed";
@@ -8,6 +9,11 @@ export declare function probeIndexerDaemon(options: {
     dataDir: string;
     walletRootId?: string;
 }): Promise<IndexerDaemonProbeResult>;
+export declare function probeIndexerDaemonForStart(options: {
+    dataDir: string;
+    walletRootId: string;
+    paths?: ReturnType<typeof resolveManagedServicePaths>;
+}): Promise<IndexerDaemonProbeResult>;
 export declare function readSnapshotWithRetry(daemon: IndexerDaemonClient, expectedWalletRootId: string): Promise<CoherentIndexerSnapshotLease>;
 export declare function readObservedIndexerDaemonStatus(options: {
     dataDir: string;

package/dist/bitcoind/indexer-daemon/lifecycle.js

@@ -7,7 +7,8 @@ import { attachOrStartManagedIndexerRuntime } from "../managed-runtime/indexer-r
 import { readJsonFileIfPresent } from "../managed-runtime/status.js";
 import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "../service-paths.js";
 import { createIndexerDaemonClient, probeIndexerDaemonAtSocket, } from "./client.js";
-import { DEFAULT_INDEXER_DAEMON_SHUTDOWN_TIMEOUT_MS, DEFAULT_INDEXER_DAEMON_STARTUP_TIMEOUT_MS, sleep, stopIndexerDaemonService as stopIndexerDaemonServiceInternal, stopIndexerDaemonServiceWithLockHeld, waitForIndexerDaemon, } from "./process.js";
+import { DEFAULT_INDEXER_DAEMON_SHUTDOWN_TIMEOUT_MS, DEFAULT_INDEXER_DAEMON_STARTUP_TIMEOUT_MS, clearIndexerDaemonRuntimeArtifacts, isIndexerDaemonProcessAlive, sleep, stopIndexerDaemonService as stopIndexerDaemonServiceInternal, stopIndexerDaemonServiceWithLockHeld, waitForIndexerDaemon, } from "./process.js";
+import { openIndexerDaemonStartupLog, recordIndexerDaemonStartupFailure, waitForIndexerDaemonStartup, } from "./startup.js";
 export const INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED = "indexer_daemon_background_follow_recovery_failed";
 const INDEXER_DAEMON_BACKGROUND_FOLLOW_NOT_ACTIVE = "indexer_daemon_background_follow_not_active";
 export async function probeIndexerDaemon(options) {
@@ -15,6 +16,25 @@ export async function probeIndexerDaemon(options) {
     const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
     return probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
 }
+export async function probeIndexerDaemonForStart(options) {
+    const paths = options.paths ?? resolveManagedServicePaths(options.dataDir, options.walletRootId);
+    const probe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, options.walletRootId);
+    if (probe.compatibility === "compatible") {
+        return probe;
+    }
+    const status = await readJsonFileIfPresent(paths.indexerDaemonStatusPath).catch(() => null);
+    const processId = status?.processId ?? null;
+    if (processId !== null && !await isIndexerDaemonProcessAlive(processId)) {
+        await clearIndexerDaemonRuntimeArtifacts(paths);
+        return {
+            compatibility: "unreachable",
+            status: null,
+            client: null,
+            error: null,
+        };
+    }
+    return probe;
+}
 export async function readSnapshotWithRetry(daemon, expectedWalletRootId) {
     let lastError = null;
     for (let attempt = 0; attempt < 2; attempt += 1) {
@@ -69,14 +89,16 @@ export async function attachOrStartIndexerDaemon(options) {
     const expectedBinaryVersion = options.expectedBinaryVersion ?? null;
     const startDaemon = async () => {
         await mkdir(paths.indexerServiceRoot, { recursive: true });
+        const startupLog = await openIndexerDaemonStartupLog(paths);
         const daemonEntryPath = fileURLToPath(new URL("../indexer-daemon-main.js", import.meta.url));
+        const stdio = ["ignore", startupLog.fd, startupLog.fd];
         const spawnOptions = serviceLifetime === "ephemeral"
             ? {
-                stdio: "ignore",
+                stdio,
             }
             : {
                 detached: true,
-                stdio: "ignore",
+                stdio,
             };
         const child = spawn(process.execPath, [
             daemonEntryPath,
@@ -86,11 +108,16 @@ export async function attachOrStartIndexerDaemon(options) {
         ], {
             ...spawnOptions,
         });
+        await startupLog.close().catch(() => undefined);
         if (serviceLifetime !== "ephemeral") {
             child.unref();
         }
         try {
-            await waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
+            await waitForIndexerDaemonStartup({
+                child,
+                logPath: startupLog.logPath,
+                waitForReady: () => waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs),
+            });
         }
         catch (error) {
             if (child.pid !== undefined) {
@@ -101,6 +128,13 @@ export async function attachOrStartIndexerDaemon(options) {
                     // ignore shutdown failures while unwinding startup errors
                 }
             }
+            await recordIndexerDaemonStartupFailure({
+                paths,
+                walletRootId,
+                binaryVersion: expectedBinaryVersion ?? "0.0.0",
+                lastError: error instanceof Error ? error.message : String(error),
+                processId: child.pid ?? null,
+            }).catch(() => undefined);
             throw error;
         }
         return createIndexerDaemonClient(paths.indexerDaemonSocketPath, {
@@ -122,7 +156,11 @@ export async function attachOrStartIndexerDaemon(options) {
         expectedBinaryVersion,
     }, {
         getPaths: (runtimeOptions) => resolveManagedServicePaths(runtimeOptions.dataDir, runtimeOptions.walletRootId),
-        probeDaemon: async (runtimeOptions, runtimePaths) => probeIndexerDaemonAtSocket(runtimePaths.indexerDaemonSocketPath, runtimeOptions.walletRootId),
+        probeDaemon: async (runtimeOptions, runtimePaths) => probeIndexerDaemonForStart({
+            dataDir: runtimeOptions.dataDir,
+            walletRootId: runtimeOptions.walletRootId,
+            paths: runtimePaths,
+        }),
         requestBackgroundFollow,
         closeClient: async (client) => {
             await client.close();

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

@@ -0,0 +1,7 @@
+import { loadBetterSqlite3 } from "../../sqlite/better-sqlite3.js";
+export declare const SQLITE_NATIVE_MODULE_UNAVAILABLE = "sqlite_native_module_unavailable";
+type LoadBetterSqlite3 = typeof loadBetterSqlite3;
+export declare function isSqliteNativeModuleLoadFailure(error: unknown): boolean;
+export declare function createSqliteNativeModuleUnavailableError(error: unknown): Error;
+export declare function assertIndexerDaemonNativeDependencies(loadBetterSqlite3Impl?: LoadBetterSqlite3): Promise<void>;
+export {};

package/dist/bitcoind/indexer-daemon/native-dependencies.js

@@ -0,0 +1,27 @@
+import { loadBetterSqlite3 } from "../../sqlite/better-sqlite3.js";
+export const SQLITE_NATIVE_MODULE_UNAVAILABLE = "sqlite_native_module_unavailable";
+export function isSqliteNativeModuleLoadFailure(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const message = error.message;
+    return message.includes("NODE_MODULE_VERSION")
+        || message.includes("better_sqlite3.node")
+        || message.includes("Cannot find module 'better-sqlite3'")
+        || message.includes('Cannot find module "better-sqlite3"');
+}
+export function createSqliteNativeModuleUnavailableError(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return new Error(`${SQLITE_NATIVE_MODULE_UNAVAILABLE}: ${detail}`, { cause: error });
+}
+export async function assertIndexerDaemonNativeDependencies(loadBetterSqlite3Impl = loadBetterSqlite3) {
+    try {
+        await loadBetterSqlite3Impl();
+    }
+    catch (error) {
+        if (isSqliteNativeModuleLoadFailure(error)) {
+            throw createSqliteNativeModuleUnavailableError(error);
+        }
+        throw error;
+    }
+}

package/dist/bitcoind/indexer-daemon/runtime.js

@@ -5,6 +5,7 @@ import { createBootstrapProgress } from "../progress/formatting.js";
 import { resolveManagedServicePaths } from "../service-paths.js";
 import { UNINITIALIZED_WALLET_ROOT_ID } from "../service-paths.js";
 import { pauseBackgroundFollow, recordBackgroundFollowFailure, resumeBackgroundFollow, withTimeout, } from "./background-follow.js";
+import { assertIndexerDaemonNativeDependencies } from "./native-dependencies.js";
 import { createIndexerDaemonServer } from "./server.js";
 import { buildIndexerDaemonStatus, deriveIndexerDaemonLeaseState, observeIndexerAppliedTip, readCoreTipStatus, refreshIndexerDaemonStatus, writeIndexerDaemonStatus, } from "./status.js";
 import { closeSnapshotLease, createSnapshotHandle, loadSnapshotMaterial, pruneExpiredSnapshotLeases, readSnapshotLease, storeSnapshotLease, } from "./snapshot-leases.js";
@@ -152,6 +153,25 @@ export function createIndexerDaemonRuntime(options) {
                 return;
             }
             await mkdir(paths.indexerServiceRoot, { recursive: true });
+            try {
+                await assertIndexerDaemonNativeDependencies();
+            }
+            catch (error) {
+                const now = Date.now();
+                state.state = "failed";
+                state.lastError = error instanceof Error ? error.message : String(error);
+                state.heartbeatAtUnixMs = now;
+                state.updatedAtUnixMs = now;
+                state.bootstrapPhase = "error";
+                state.bootstrapProgress = {
+                    ...createBootstrapProgress("error", DEFAULT_SNAPSHOT_METADATA),
+                    message: state.lastError,
+                    lastError: state.lastError,
+                    updatedAt: now,
+                };
+                await writeStatus().catch(() => undefined);
+                throw error;
+            }
             await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
             server = createIndexerDaemonServer({
                 getStatus: () => buildIndexerDaemonStatus(state),

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

@@ -0,0 +1,44 @@
+import type { ManagedServicePaths } from "../service-paths.js";
+type ChildProcessLike = {
+    pid?: number;
+    once(event: "error", listener: (error: Error) => void): unknown;
+    once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    off(event: "error", listener: (error: Error) => void): unknown;
+    off(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+};
+export declare class IndexerDaemonStartupError extends Error {
+    readonly logPath: string;
+    readonly logTail: string | null;
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    constructor(message: string, options: {
+        logPath: string;
+        logTail?: string | null;
+        exitCode?: number | null;
+        signal?: NodeJS.Signals | null;
+        cause?: unknown;
+    });
+}
+export declare function getIndexerDaemonStartupLogPath(error: unknown): string | null;
+export declare function getIndexerDaemonStartupLogTail(error: unknown): string | null;
+export declare function openIndexerDaemonStartupLog(paths: ManagedServicePaths): Promise<{
+    fd: number;
+    logPath: string;
+    close(): Promise<void>;
+}>;
+export declare function readIndexerDaemonStartupLogTail(logPath: string, maxBytes?: number): Promise<string | null>;
+export declare function classifyIndexerDaemonStartupFailure(logTail: string | null): string;
+export declare function waitForIndexerDaemonStartup(options: {
+    child: ChildProcessLike;
+    logPath: string;
+    waitForReady(): Promise<void>;
+    readLogTail?: (logPath: string) => Promise<string | null>;
+}): Promise<void>;
+export declare function recordIndexerDaemonStartupFailure(options: {
+    paths: ManagedServicePaths;
+    walletRootId: string;
+    binaryVersion: string;
+    lastError: string;
+    processId?: number | null;
+}): Promise<void>;
+export {};

package/dist/bitcoind/indexer-daemon/startup.js

@@ -0,0 +1,152 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rm } from "node:fs/promises";
+import { writeRuntimeStatusFile } from "../../wallet/fs/status-file.js";
+import { readJsonFileIfPresent } from "../managed-runtime/status.js";
+import { SQLITE_NATIVE_MODULE_UNAVAILABLE } from "./native-dependencies.js";
+import { INDEXER_DAEMON_SCHEMA_VERSION, INDEXER_DAEMON_SERVICE_API_VERSION, } from "../types.js";
+const STARTUP_LOG_TAIL_BYTES = 4_096;
+export class IndexerDaemonStartupError extends Error {
+    logPath;
+    logTail;
+    exitCode;
+    signal;
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.name = "IndexerDaemonStartupError";
+        this.logPath = options.logPath;
+        this.logTail = options.logTail ?? null;
+        this.exitCode = options.exitCode ?? null;
+        this.signal = options.signal ?? null;
+    }
+}
+export function getIndexerDaemonStartupLogPath(error) {
+    return error instanceof IndexerDaemonStartupError ? error.logPath : null;
+}
+export function getIndexerDaemonStartupLogTail(error) {
+    return error instanceof IndexerDaemonStartupError ? error.logTail : null;
+}
+export async function openIndexerDaemonStartupLog(paths) {
+    await mkdir(paths.indexerServiceRoot, { recursive: true });
+    const handle = await open(paths.indexerDaemonLogPath, "w", 0o600);
+    await handle.writeFile([
+        `Cogcoin indexer daemon startup log`,
+        `pid=${process.pid}`,
+        `node=${process.version}`,
+        `time=${new Date().toISOString()}`,
+        "",
+    ].join("\n"));
+    return {
+        fd: handle.fd,
+        logPath: paths.indexerDaemonLogPath,
+        async close() {
+            await handle.close();
+        },
+    };
+}
+export async function readIndexerDaemonStartupLogTail(logPath, maxBytes = STARTUP_LOG_TAIL_BYTES) {
+    try {
+        const bytes = await readFile(logPath);
+        const tail = bytes.subarray(Math.max(0, bytes.byteLength - maxBytes));
+        const text = tail.toString("utf8").trim();
+        return text.length > 0 ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function classifyIndexerDaemonStartupFailure(logTail) {
+    return logTail?.includes(SQLITE_NATIVE_MODULE_UNAVAILABLE) === true
+        ? SQLITE_NATIVE_MODULE_UNAVAILABLE
+        : "indexer_daemon_start_failed";
+}
+export async function waitForIndexerDaemonStartup(options) {
+    const readLogTail = options.readLogTail ?? readIndexerDaemonStartupLogTail;
+    const ready = options.waitForReady();
+    const childFailure = new Promise((_, reject) => {
+        const onError = async (error) => {
+            const logTail = await readLogTail(options.logPath);
+            reject(new IndexerDaemonStartupError(classifyIndexerDaemonStartupFailure(logTail), {
+                logPath: options.logPath,
+                logTail,
+                cause: error,
+            }));
+        };
+        const onExit = async (code, signal) => {
+            const logTail = await readLogTail(options.logPath);
+            reject(new IndexerDaemonStartupError(classifyIndexerDaemonStartupFailure(logTail), {
+                logPath: options.logPath,
+                logTail,
+                exitCode: code,
+                signal,
+            }));
+        };
+        options.child.once("error", onError);
+        options.child.once("exit", onExit);
+        ready.then(() => {
+            options.child.off("error", onError);
+            options.child.off("exit", onExit);
+        }, () => {
+            options.child.off("error", onError);
+            options.child.off("exit", onExit);
+        });
+    });
+    try {
+        await Promise.race([
+            ready,
+            childFailure,
+        ]);
+    }
+    catch (error) {
+        if (error instanceof IndexerDaemonStartupError) {
+            throw error;
+        }
+        const logTail = await readLogTail(options.logPath);
+        throw new IndexerDaemonStartupError(error instanceof Error ? error.message : "indexer_daemon_start_timeout", {
+            logPath: options.logPath,
+            logTail,
+            cause: error,
+        });
+    }
+}
+export async function recordIndexerDaemonStartupFailure(options) {
+    await rm(options.paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
+    await mkdir(options.paths.indexerServiceRoot, { recursive: true });
+    const existing = await readJsonFileIfPresent(options.paths.indexerDaemonStatusPath).catch(() => null);
+    if (existing?.processId === (options.processId ?? null)
+        && (existing.state === "schema-mismatch"
+            || (existing.state === "failed" && existing.lastError !== null))) {
+        return;
+    }
+    const now = Date.now();
+    const status = {
+        serviceApiVersion: INDEXER_DAEMON_SERVICE_API_VERSION,
+        binaryVersion: options.binaryVersion,
+        buildId: null,
+        updatedAtUnixMs: now,
+        walletRootId: options.walletRootId,
+        daemonInstanceId: randomUUID(),
+        schemaVersion: INDEXER_DAEMON_SCHEMA_VERSION,
+        state: "failed",
+        processId: options.processId ?? null,
+        startedAtUnixMs: now,
+        heartbeatAtUnixMs: now,
+        ipcReady: false,
+        rpcReachable: false,
+        coreBestHeight: null,
+        coreBestHash: null,
+        appliedTipHeight: null,
+        appliedTipHash: null,
+        snapshotSeq: null,
+        backlogBlocks: null,
+        reorgDepth: null,
+        lastAppliedAtUnixMs: null,
+        activeSnapshotCount: 0,
+        lastError: options.lastError,
+        backgroundFollowActive: false,
+        bootstrapPhase: "error",
+        bootstrapProgress: null,
+        cogcoinSyncHeight: null,
+        cogcoinSyncTargetHeight: null,
+    };
+    await writeRuntimeStatusFile(options.paths.indexerDaemonStatusPath, status);
+}

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

@@ -115,6 +115,16 @@ function mapIndexerStartupError(message) {
                 health: "starting",
                 message: "Indexer daemon is still starting.",
             };
+        case "indexer_daemon_start_failed":
+            return {
+                health: "failed",
+                message: "The managed indexer daemon exited before it opened its local IPC socket.",
+            };
+        case "sqlite_native_module_unavailable":
+            return {
+                health: "failed",
+                message: "The managed indexer daemon could not load its SQLite native module.",
+            };
         case "indexer_daemon_service_version_mismatch":
             return {
                 health: "service-version-mismatch",

package/dist/bitcoind/service-paths.d.ts

@@ -15,5 +15,6 @@ export interface ManagedServicePaths {
     indexerDaemonLockPath: string;
     indexerDaemonStatusPath: string;
     indexerDaemonSocketPath: string;
+    indexerDaemonLogPath: string;
 }
 export declare function resolveManagedServicePaths(dataDir: string, walletRootId?: string): ManagedServicePaths;

package/dist/bitcoind/service-paths.js

@@ -41,5 +41,6 @@ export function resolveManagedServicePaths(dataDir, walletRootId = UNINITIALIZED
         indexerDaemonLockPath: join(walletRuntimeRoot, "indexer-daemon.lock"),
         indexerDaemonStatusPath: join(indexerServiceRoot, "status.json"),
         indexerDaemonSocketPath: resolveIndexerDaemonSocketPath(serviceRootId),
+        indexerDaemonLogPath: join(indexerServiceRoot, "daemon.log"),
     };
 }

package/dist/cli/output/rules/services.js

@@ -1,5 +1,19 @@
+import { getIndexerDaemonStartupLogPath, getIndexerDaemonStartupLogTail, } from "../../../bitcoind/indexer-daemon/startup.js";
+function formatIndexerStartupDetail(error) {
+    const logPath = getIndexerDaemonStartupLogPath(error);
+    const logTail = getIndexerDaemonStartupLogTail(error);
+    if (logPath === null && logTail === null) {
+        return null;
+    }
+    const tail = logTail === null
+        ? null
+        : logTail.replace(/\s+/g, " ").slice(0, 300);
+    return tail === null
+        ? `Startup log: ${logPath}.`
+        : `Startup log: ${logPath}. Last output: ${tail}`;
+}
 export const serviceErrorRules = [
-    ({ errorCode }) => {
+    ({ errorCode, error }) => {
         if (errorCode.endsWith("_requires_tty") && errorCode !== "cli_update_requires_tty") {
             return {
                 what: "Interactive terminal input is required.",
@@ -14,6 +28,30 @@ export const serviceErrorRules = [
                 next: "Check `cogcoin status`, wait for services to settle, and retry. If the state stays degraded, run `cogcoin repair`.",
             };
         }
+        if (errorCode === "sqlite_native_module_unavailable") {
+            const detail = formatIndexerStartupDetail(error);
+            return {
+                what: "The managed indexer daemon could not load its SQLite native module.",
+                why: `The active Node runtime is ${process.version}, but the installed native sqlite dependency appears to be missing or built for a different Node ABI.${detail === null ? "" : ` ${detail}`}`,
+                next: "Use the supported Node runtime for this checkout, then run `npm rebuild better-sqlite3 zeromq` or reinstall dependencies and retry.",
+            };
+        }
+        if (errorCode === "indexer_daemon_start_failed") {
+            const detail = formatIndexerStartupDetail(error);
+            return {
+                what: "The managed indexer daemon exited before it opened its local IPC socket.",
+                why: detail ?? "The daemon process died during startup before Cogcoin could read a service status.",
+                next: "Run `cogcoin repair` to clear stale managed indexer artifacts. If this was a local checkout, verify the Node version and rebuild native dependencies.",
+            };
+        }
+        if (errorCode === "indexer_daemon_start_timeout") {
+            const detail = formatIndexerStartupDetail(error);
+            return {
+                what: "The managed indexer daemon stayed alive but did not open its local IPC socket in time.",
+                why: detail ?? "Cogcoin could not attach to the daemon before the startup deadline.",
+                next: "Run `cogcoin repair` if this persists. If this was a local checkout, verify the Node version and rebuild native dependencies.",
+            };
+        }
         if (errorCode === "indexer_daemon_background_follow_recovery_failed") {
             return {
                 what: "The managed indexer daemon could not recover automatic background follow.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogcoin/client",
-  "version": "1.1.14",
+  "version": "1.1.15",
   "description": "Store-backed Cogcoin client with wallet flows, SQLite persistence, and managed Bitcoin Core integration.",
   "license": "MIT",
   "type": "module",