@lightninglabs/wavelength-core 0.1.0

package/dist/engine/engine.js

@@ -0,0 +1,548 @@
+import { toError } from "../errors.js";
+import { exitBatch as runExitBatch, } from "../exit.js";
+import { WalletState } from "../state.js";
+import { ActivityStream } from "./activity.js";
+import { ADOPT_INFO_RETRIES, ADOPT_INFO_RETRY_MS, BACKGROUND_REFRESH_FAILURE_LIMIT, MAX_LOGS, RESTORE_POLL_MS, SYNC_POLL_FAILURE_LIMIT, SYNC_POLL_MS, } from "./constants.js";
+import { transition } from "./machine.js";
+import { Poller } from "./poller.js";
+import { SettleReconciler } from "./reconcile.js";
+import { stabilize } from "./stabilize.js";
+import { SnapshotStore } from "./store.js";
+/** Creates a {@link WalletEngine} over any transport client. */
+export function createWalletEngine(options) {
+    return new WavelengthEngine(options);
+}
+class WavelengthEngine {
+    client;
+    #store = new SnapshotStore();
+    #config;
+    #disposed = false;
+    #unsubscribe;
+    // Background refreshes are serialized: two concurrent reads would race on
+    // the snapshot, and the slower one would win with the staler data.
+    #chain = Promise.resolve();
+    #refreshFailures = 0;
+    // The background processes the phase machine turns on and off; see #reconcileProcesses.
+    #stream;
+    #reconciler;
+    #syncPoller;
+    #restorePoller;
+    // The pending restore promise, settled exactly once at usability (resolve)
+    // or wallet-down failure (reject).
+    #restore;
+    constructor(options) {
+        this.client = options.client;
+        this.#config = options.config;
+        this.#stream = new ActivityStream({
+            client: this.client,
+            onActivity: () => this.#reconciler.trigger(),
+            onReconcile: () => this.#reconciler.trigger(),
+            onDead: (error) => {
+                // A stream death that lands after the phase has already left 'ready'
+                // (for example while stopping) would otherwise stamp a fatal error
+                // onto a snapshot the wallet is no longer claiming is live, so only
+                // dispatch while the phase is actually 'ready'.
+                if (this.getSnapshot().phase === 'ready') {
+                    this.#dispatch({ type: 'streamLost' }, { error });
+                }
+            },
+        });
+        this.#reconciler = new SettleReconciler({
+            refresh: () => this.#backgroundRefresh(),
+            baseline: () => this.getSnapshot().balance,
+        });
+        this.#syncPoller = new Poller({
+            intervalMs: SYNC_POLL_MS,
+            failureLimit: SYNC_POLL_FAILURE_LIMIT,
+            tick: () => this.refresh(),
+            onExhausted: (err) => {
+                // A poller tick already in flight when the poller stops can resolve
+                // after the phase has left 'syncing', so only dispatch while the
+                // phase is actually 'syncing'; otherwise this would stamp a fatal
+                // error onto a healthy or stopped snapshot.
+                if (this.getSnapshot().phase === 'syncing') {
+                    this.#dispatch({ type: 'syncPollExhausted' }, { error: toError(err) });
+                }
+            },
+        });
+        this.#restorePoller = new Poller({
+            intervalMs: RESTORE_POLL_MS,
+            immediate: true,
+            tick: () => this.#restoreTick(),
+        });
+        this.client.ready().then(() => {
+            if (this.#disposed) {
+                return;
+            }
+            this.#dispatch({ type: 'runtimeReady' });
+            if (options.autoStart && this.#config) {
+                // Failures surface through the startFailed transition; nothing to
+                // do with the rejection here.
+                void this.start().catch(() => undefined);
+            }
+        }, (err) => {
+            if (!this.#disposed) {
+                this.#dispatch({ type: 'runtimeFailed' }, { error: toError(err) });
+            }
+        });
+        this.#unsubscribe = this.client.subscribe((event) => this.#onClientEvent(event));
+    }
+    getSnapshot = () => this.#store.getSnapshot();
+    subscribe = (listener) => this.#store.subscribe(listener);
+    // Guards a public mutator against running after dispose(): a disposed
+    // engine has already torn down its subscriptions and background processes,
+    // so any RPC it kicks off would race a client no consumer can observe
+    // through the snapshot.
+    #assertNotDisposed() {
+        if (this.#disposed) {
+            throw new Error('the engine has been disposed');
+        }
+    }
+    async start(config) {
+        this.#assertNotDisposed();
+        const cfg = config ?? this.#config;
+        if (!cfg) {
+            throw new Error('start() needs a runtime config: pass one, or set config on the engine factory');
+        }
+        // The machine ignores startRequested while stopping, but without this
+        // guard the client RPC below would still fire mid-stop.
+        if (this.getSnapshot().phase === 'stopping') {
+            throw new Error('cannot start while the runtime is stopping');
+        }
+        this.#refreshFailures = 0;
+        this.#dispatch({ type: 'startRequested' }, { error: null });
+        try {
+            const info = await this.client.start(cfg);
+            this.#dispatch({ type: 'infoReceived', info }, { info });
+            try {
+                await this.refresh();
+            }
+            catch {
+                // A locked or empty wallet can fail balance/list until bootstrap.
+            }
+            return info;
+        }
+        catch (err) {
+            const error = toError(err);
+            this.#dispatch({ type: 'startFailed' }, { error });
+            throw error;
+        }
+    }
+    async stop() {
+        this.#assertNotDisposed();
+        this.#dispatch({ type: 'stopRequested' });
+        try {
+            await this.client.stop();
+            this.#dispatch({ type: 'stopCompleted' }, { info: null, balance: null, activity: [], error: null });
+            this.#rejectRestoreOnTeardown();
+        }
+        catch (err) {
+            const error = toError(err);
+            this.#dispatch({ type: 'stopFailed' }, { error });
+            throw error;
+        }
+    }
+    async refresh() {
+        this.#assertNotDisposed();
+        await this.#fetchAll();
+    }
+    async createWallet(req) {
+        this.#assertNotDisposed();
+        const result = await this.client.createWallet(req);
+        await this.#adoptInfo();
+        this.#kickRefresh();
+        return result;
+    }
+    restoreWallet(req) {
+        // A restore with server-assisted recovery blocks createWallet for the
+        // whole indexer scan, but the daemon marks the wallet ready before the
+        // scan runs. So kick createWallet off without awaiting it, resolve this
+        // promise as soon as the wallet is usable (the readiness poll below), and
+        // track the scan through snapshot.recovery when the caller opted in.
+        if (this.#disposed) {
+            return Promise.reject(new Error('the engine has been disposed'));
+        }
+        if (!req.mnemonic || req.mnemonic.length === 0) {
+            return Promise.reject(new Error('a restore needs a mnemonic'));
+        }
+        if (this.#restore && !this.#restore.settled) {
+            // A second concurrent restore would otherwise clobber #restore and
+            // strand the first caller's promise; reject the new call up front
+            // instead, before dispatching anything, so the first caller's promise
+            // stays valid.
+            return Promise.reject(new Error('a restore is already in flight'));
+        }
+        const tracking = Boolean(req.recoverState);
+        this.#dispatch({ type: 'restoreRequested' }, {
+            error: null,
+            recovery: tracking ? { status: 'restoring' } : { status: 'idle' },
+        });
+        const promise = new Promise((resolve, reject) => {
+            this.#restore = { resolve, reject, settled: false };
+        });
+        this.client.createWallet(req).then(async (result) => {
+            // dispose() already rejected #restore; a resolving createWallet must
+            // not dispatch, adopt info, or kick a refresh on a torn-down engine.
+            if (this.#disposed) {
+                return;
+            }
+            // The scan (or a plain restore) finished, so the wallet is up.
+            if (tracking) {
+                this.#store.update({ recovery: { status: 'done', result } });
+            }
+            const info = await this.#adoptWalletUp();
+            this.#settleRestore(info);
+            this.#kickRefresh();
+        }, async (err) => {
+            // dispose() already rejected #restore; a settling createWallet must
+            // not dispatch, adopt info, or kick a refresh on a torn-down engine.
+            if (this.#disposed) {
+                return;
+            }
+            const error = toError(err);
+            // Recovery runs after the wallet is created and unlocked, so a
+            // failure may leave a usable (if under-populated) wallet. Probe
+            // getInfo: if the wallet came up, keep the user in it and surface a
+            // failed banner; otherwise the create itself failed, so fall back to
+            // onboarding and reject.
+            let probe = null;
+            try {
+                probe = await this.client.getInfo();
+            }
+            catch {
+                // Treat an unreachable daemon as not-came-up.
+            }
+            const cameUp = Boolean(probe && (probe.walletReady || probe.walletState === WalletState.Ready));
+            if (cameUp && probe) {
+                this.#dispatch({ type: 'restoreFailedWalletUp' }, {
+                    info: probe,
+                    recovery: tracking
+                        ? { status: 'failed', error, walletUsable: true }
+                        : { status: 'idle' },
+                });
+                this.#settleRestore(probe);
+                this.#kickRefresh();
+            }
+            else {
+                // The wallet never came up, so the phase falls back to
+                // needsWallet, but recovery still records the failure: without
+                // this, a screen that unmounts on the rejection (returning to
+                // needsWallet) would lose the error the moment its hook-local
+                // state disappears with it. The snapshot survives that unmount.
+                this.#dispatch({ type: 'restoreFailedWalletDown' }, { recovery: { status: 'failed', error, walletUsable: false } });
+                this.#rejectRestore(error);
+            }
+        }).catch((err) => this.#rejectRestore(toError(err)));
+        return promise;
+    }
+    // A no-op while a scan is live: a stray banner dismiss must not wipe the
+    // in-progress restoring state out from under the poll that is tracking it.
+    acknowledgeRecovery() {
+        if (this.getSnapshot().recovery.status === 'restoring') {
+            return;
+        }
+        this.#store.update({ recovery: { status: 'idle' } });
+    }
+    async unlockWallet(req) {
+        this.#assertNotDisposed();
+        const result = await this.client.unlockWallet(req);
+        await this.#adoptInfo();
+        this.#kickRefresh();
+        return result;
+    }
+    async openWalletFromPasskey(req) {
+        this.#assertNotDisposed();
+        const result = await this.client.openWalletFromPasskey(req);
+        await this.#adoptInfo();
+        this.#kickRefresh();
+        return result;
+    }
+    async deposit(req = {}) {
+        this.#assertNotDisposed();
+        const result = await this.client.deposit(req);
+        this.#kickRefresh();
+        return result;
+    }
+    async receive(req) {
+        this.#assertNotDisposed();
+        const result = await this.client.receive(req);
+        this.#kickRefresh();
+        return result;
+    }
+    prepareSend(req) {
+        this.#assertNotDisposed();
+        // A quote moves no money, so nothing to refresh.
+        return this.client.prepareSend(req);
+    }
+    async sendPrepared(prepared) {
+        this.#assertNotDisposed();
+        const result = await this.client.sendPrepared(prepared);
+        this.#kickRefresh();
+        return result;
+    }
+    async send(req) {
+        this.#assertNotDisposed();
+        const result = await this.client.send(req);
+        this.#kickRefresh();
+        return result;
+    }
+    async exit(req) {
+        this.#assertNotDisposed();
+        const result = await this.client.exit(req);
+        this.#kickRefresh();
+        return result;
+    }
+    exitStatus(req) {
+        this.#assertNotDisposed();
+        // Reading status moves no money, so nothing to refresh.
+        return this.client.exitStatus(req);
+    }
+    exitSummary(req = {}) {
+        this.#assertNotDisposed();
+        return this.client.exitSummary(req);
+    }
+    getExitPlan(req) {
+        this.#assertNotDisposed();
+        // Previewing a plan moves no money, so nothing to refresh.
+        return this.client.getExitPlan(req);
+    }
+    async sweepWallet(req) {
+        this.#assertNotDisposed();
+        const result = await this.client.sweepWallet(req);
+        // A preview moves no money; only a broadcast does.
+        if (req.broadcast)
+            this.#kickRefresh();
+        return result;
+    }
+    async exitBatch(opts) {
+        this.#assertNotDisposed();
+        return runExitBatch({
+            ...opts,
+            client: this.client,
+            onEvent: (event) => {
+                // Each started exit moves money, so refresh as the batch progresses.
+                if (event.type === 'started')
+                    this.#kickRefresh();
+                opts.onEvent?.(event);
+            },
+        });
+    }
+    list(req) {
+        this.#assertNotDisposed();
+        // Listing reads state, so nothing to refresh.
+        return this.client.list(req);
+    }
+    clearLogs() {
+        this.#store.update({ logs: [] });
+    }
+    dispose() {
+        this.#disposed = true;
+        this.#unsubscribe?.();
+        this.#unsubscribe = undefined;
+        this.#stream.stop();
+        this.#reconciler.cancel();
+        this.#syncPoller.stop();
+        this.#restorePoller.stop();
+        this.#rejectRestore(new Error('the engine was disposed during the restore'));
+    }
+    // ----- internals -----
+    #onClientEvent(event) {
+        if (event.type === 'runtimeReady') {
+            this.#dispatch({ type: 'runtimeReady' });
+        }
+        else if (event.type === 'runtimeStopped') {
+            // A clean stop() or a runtime crash (the worker transport surfaces a
+            // fatal as runtimeStopped). Either way the engine below is gone.
+            this.#dispatch({ type: 'runtimeStopped' }, { info: null, balance: null, activity: [] });
+            this.#rejectRestoreOnTeardown();
+        }
+        else if (event.type === 'log') {
+            const logs = [...this.getSnapshot().logs, event.payload].slice(-MAX_LOGS);
+            this.#store.update({ logs });
+        }
+        else if (event.type === 'activity') {
+            this.#stream.noteActivity(event.payload);
+        }
+        else if (event.type === 'activityStream') {
+            this.#stream.noteStreamLost();
+        }
+    }
+    // The patch cannot touch phase: phase is derived solely from transition(),
+    // so no dispatch site can bypass the machine by smuggling a phase value in
+    // through the patch.
+    #dispatch(event, patch = {}) {
+        const prev = this.getSnapshot().phase;
+        const next = transition(prev, event);
+        this.#store.update({ ...patch, phase: next });
+        if (next !== prev) {
+            this.#reconcileProcesses(next);
+        }
+    }
+    // The process ownership table: which background process runs in which phase.
+    #reconcileProcesses(phase) {
+        if (phase === 'ready') {
+            this.#stream.start();
+        }
+        else {
+            this.#stream.stop();
+            this.#reconciler.cancel();
+        }
+        if (phase === 'syncing') {
+            this.#syncPoller.start();
+        }
+        else {
+            this.#syncPoller.stop();
+        }
+        if (phase === 'restoring') {
+            this.#restorePoller.start();
+        }
+        else {
+            this.#restorePoller.stop();
+        }
+    }
+    // Fetches info, balance, and activity concurrently, applies reference
+    // stabilization, and dispatches infoReceived so the phase re-derives.
+    async #fetchAll() {
+        const [info, balance, rows] = await Promise.all([
+            this.client.getInfo(),
+            this.client.balance(),
+            this.client.list({ view: 'activity', pendingOnly: false }),
+        ]);
+        const snap = this.getSnapshot();
+        // A refresh in flight when stop() lands resolves after the phase has
+        // already moved to stopping or stopped. Dispatching infoReceived here
+        // would ignore-transition through the phase machine but still apply the
+        // patch, repopulating info/balance/activity that stopCompleted just
+        // cleared. Bail out before dispatching so a late read cannot resurrect a
+        // snapshot the wallet promised was gone.
+        if (snap.phase === 'stopping' || snap.phase === 'stopped') {
+            return snap.balance;
+        }
+        const entries = rows.activity?.entries || [];
+        const nextInfo = stabilize(snap.info, info);
+        const nextBalance = stabilize(snap.balance, balance);
+        const nextActivity = stabilize(snap.activity, entries);
+        this.#dispatch({ type: 'infoReceived', info }, { info: nextInfo, balance: nextBalance, activity: nextActivity });
+        return nextBalance;
+    }
+    // Refetches complete info after a wallet came up (create/unlock/passkey),
+    // instead of fabricating a partial. A single failed attempt is transient
+    // (the daemon can take a beat to settle right after create/unlock), so this
+    // retries up to ADOPT_INFO_RETRIES times, ADOPT_INFO_RETRY_MS apart. If
+    // every attempt fails the daemon is presumed gone: escalate via
+    // walletAdoptionFailed rather than silently leaving the wallet stuck
+    // without info.
+    async #adoptInfo() {
+        for (let attempt = 0; attempt < ADOPT_INFO_RETRIES; attempt++) {
+            if (this.#disposed) {
+                return null;
+            }
+            try {
+                const info = await this.client.getInfo();
+                this.#dispatch({ type: 'infoReceived', info }, { info });
+                return info;
+            }
+            catch {
+                if (attempt < ADOPT_INFO_RETRIES - 1) {
+                    await new Promise((resolve) => {
+                        setTimeout(resolve, ADOPT_INFO_RETRY_MS);
+                    });
+                }
+            }
+        }
+        if (!this.#disposed) {
+            this.#dispatch({ type: 'walletAdoptionFailed' }, {
+                error: new Error('the wallet was created but the daemon stopped responding'),
+            });
+        }
+        return null;
+    }
+    // Serialized background refresh with a consecutive-failure budget. Below
+    // the limit failures stay engine-internal; at the limit the phase escalates
+    // so a dead daemon cannot hide behind a healthy-looking ready wallet.
+    async #backgroundRefresh() {
+        const run = () => this.#fetchAll();
+        const next = this.#chain.then(run, run);
+        this.#chain = next.then(() => undefined, () => undefined);
+        try {
+            const balance = await next;
+            this.#refreshFailures = 0;
+            return { ok: true, balance };
+        }
+        catch {
+            this.#refreshFailures += 1;
+            // backgroundRefreshExhausted only transitions the machine out of
+            // 'ready', so dispatching it from any other phase is an ignored
+            // transition that would still apply the error patch. That patch would
+            // then mislabel an unrelated failure (for example one surfacing while
+            // the runtime is stopping) as the wallet having gone unresponsive, so
+            // only dispatch it while the phase is actually 'ready'. The failure
+            // counter still increments either way.
+            if (this.#refreshFailures >= BACKGROUND_REFRESH_FAILURE_LIMIT &&
+                this.getSnapshot().phase === 'ready') {
+                this.#dispatch({ type: 'backgroundRefreshExhausted' }, { error: new Error('the wallet stopped responding to background refreshes') });
+            }
+            return { ok: false, balance: null };
+        }
+    }
+    #kickRefresh() {
+        void this.#backgroundRefresh();
+    }
+    // The readiness poll during a background restore: only a genuinely ready
+    // wallet advances; the transient locked-looking states InitWallet passes
+    // through are ignored (the machine has no infoReceived entry for
+    // 'restoring', and this tick never dispatches infoReceived).
+    #restoreTick = async () => {
+        let info;
+        try {
+            info = await this.client.getInfo();
+        }
+        catch {
+            // Transient while the wallet comes up; keep polling.
+            return;
+        }
+        if (info.walletReady || info.walletState === WalletState.Ready) {
+            this.#dispatch({ type: 'walletBecameReady' }, { info });
+            this.#settleRestore(info);
+            this.#kickRefresh();
+        }
+    };
+    // Adopts post-restore info when the scan finished: refetch, dispatch
+    // walletBecameReady (a no-op transition if the poll already won).
+    async #adoptWalletUp() {
+        let info = null;
+        try {
+            info = await this.client.getInfo();
+        }
+        catch {
+            // The background refresh converges the snapshot.
+        }
+        this.#dispatch({ type: 'walletBecameReady' }, info ? { info } : {});
+        return info;
+    }
+    #settleRestore(info) {
+        if (!this.#restore || this.#restore.settled) {
+            return;
+        }
+        const resolved = info ?? this.getSnapshot().info;
+        this.#restore.settled = true;
+        if (resolved === null) {
+            this.#restore.reject(new Error('the restored wallet came up but its info could not be read'));
+        }
+        else {
+            this.#restore.resolve(resolved);
+        }
+    }
+    #rejectRestore(error) {
+        if (this.#restore && !this.#restore.settled) {
+            this.#restore.settled = true;
+            this.#restore.reject(error);
+        }
+    }
+    // Mirrors dispose()'s pending-restore rejection: the runtime tearing down
+    // mid-restore (a clean stop() or a crash) leaves any in-flight restore
+    // promise stranded forever unless it is settled here too.
+    #rejectRestoreOnTeardown() {
+        this.#rejectRestore(new Error('the runtime stopped during the restore'));
+    }
+}

package/dist/engine/machine.d.ts

@@ -0,0 +1,50 @@
+import { type RuntimePhase, type WalletInfo } from '../state.ts';
+/**
+ * Events the engine dispatches into the phase machine. Events carry no
+ * behavior; the engine applies snapshot patches and process changes
+ * separately, so transition() stays a pure phase -> phase map.
+ */
+export type WalletEngineEvent = {
+    type: 'runtimeReady';
+} | {
+    type: 'runtimeFailed';
+} | {
+    type: 'runtimeStopped';
+} | {
+    type: 'startRequested';
+} | {
+    type: 'startFailed';
+} | {
+    type: 'infoReceived';
+    info: WalletInfo;
+} | {
+    type: 'restoreRequested';
+} | {
+    type: 'walletBecameReady';
+} | {
+    type: 'restoreFailedWalletUp';
+} | {
+    type: 'restoreFailedWalletDown';
+} | {
+    type: 'walletAdoptionFailed';
+} | {
+    type: 'streamLost';
+} | {
+    type: 'syncPollExhausted';
+} | {
+    type: 'backgroundRefreshExhausted';
+} | {
+    type: 'stopRequested';
+} | {
+    type: 'stopCompleted';
+} | {
+    type: 'stopFailed';
+};
+/**
+ * The pure phase transition table. Any (event, phase) pair without an entry is
+ * an identity transition: the event is ignored. Notably, infoReceived has no
+ * entry for 'restoring': during a restore the transient locked-looking
+ * states InitWallet passes through cannot leak into the UI.
+ */
+export declare function transition(phase: RuntimePhase, event: WalletEngineEvent): RuntimePhase;
+//# sourceMappingURL=machine.d.ts.map

package/dist/engine/machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../src/engine/machine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,uBAAuB,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,yBAAyB,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,sBAAsB,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,4BAA4B,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC;AAE3B;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,iBAAiB,GACvB,YAAY,CA+Dd"}

package/dist/engine/machine.js

@@ -0,0 +1,55 @@
+import { phaseFromInfo } from "../state.js";
+/**
+ * The pure phase transition table. Any (event, phase) pair without an entry is
+ * an identity transition: the event is ignored. Notably, infoReceived has no
+ * entry for 'restoring': during a restore the transient locked-looking
+ * states InitWallet passes through cannot leak into the UI.
+ */
+export function transition(phase, event) {
+    switch (event.type) {
+        case 'runtimeReady':
+            return phase === 'loading' ? 'runtimeReady' : phase;
+        case 'runtimeFailed':
+            return phase === 'loading' ? 'error' : phase;
+        case 'runtimeStopped':
+            // A clean stop or a runtime crash; either way the engine is gone, so
+            // this always wins.
+            return 'stopped';
+        case 'startRequested':
+            return phase === 'stopping' ? phase : 'starting';
+        case 'startFailed':
+            return phase === 'starting' ? 'error' : phase;
+        case 'infoReceived':
+            switch (phase) {
+                case 'starting':
+                case 'needsWallet':
+                case 'locked':
+                case 'syncing':
+                case 'ready':
+                    return phaseFromInfo(event.info);
+                default:
+                    return phase;
+            }
+        case 'restoreRequested':
+            return phase === 'needsWallet' || phase === 'locked' ? 'restoring' : phase;
+        case 'walletBecameReady':
+            return phase === 'restoring' || phase === 'syncing' ? 'ready' : phase;
+        case 'restoreFailedWalletUp':
+            return phase === 'restoring' ? 'ready' : phase;
+        case 'restoreFailedWalletDown':
+            return phase === 'restoring' ? 'needsWallet' : phase;
+        case 'walletAdoptionFailed':
+            return phase === 'needsWallet' || phase === 'locked' ? 'error' : phase;
+        case 'streamLost':
+        case 'backgroundRefreshExhausted':
+            return phase === 'ready' ? 'error' : phase;
+        case 'syncPollExhausted':
+            return phase === 'syncing' ? 'error' : phase;
+        case 'stopRequested':
+            return phase === 'stopping' || phase === 'stopped' ? phase : 'stopping';
+        case 'stopCompleted':
+            return phase === 'stopping' ? 'stopped' : phase;
+        case 'stopFailed':
+            return phase === 'stopping' ? 'error' : phase;
+    }
+}

package/dist/engine/optionsAssertions.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=optionsAssertions.d.ts.map

package/dist/engine/optionsAssertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optionsAssertions.d.ts","sourceRoot":"","sources":["../../src/engine/optionsAssertions.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAE,CAAC"}

package/dist/engine/optionsAssertions.js

@@ -0,0 +1,20 @@
+// Compile-time contract tests for WalletEngineOptions. This module has no
+// meaningful runtime behavior: it exists so `pnpm typecheck` enforces that
+// autoStart: true requires config, and that the other valid combinations
+// still compile. It is a plain .ts file under src/, so it is picked up by
+// tsconfig's "src" include (only src/**/*.test.ts and src/testing are
+// excluded) and typechecked on every run.
+// autoStart: true without config is rejected.
+// @ts-expect-error autoStart: true requires config.
+const missingConfig = { client, autoStart: true };
+// Valid combinations all compile.
+const withAutoStart = { client, config, autoStart: true };
+const configOnly = { client, config };
+const neither = { client };
+const autoStartFalseAlone = { client, autoStart: false };
+void missingConfig;
+void withAutoStart;
+void configOnly;
+void neither;
+void autoStartFalseAlone;
+export {};