dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/data/src/sources/solana-rpc.js

@@ -0,0 +1,299 @@
+// Solana JSON-RPC adapter (SPEC §3.1 S6). Keyless, read-only.
+// Default endpoint is the public mainnet RPC (heavily rate-limited: "use sparingly");
+// any RPC URL can be configured. Only the read methods in READ_METHODS are ever sent.
+//   getAccountInfo(mint, base64)          -> SPL / Token-2022 mint: authorities, supply,
+//                                            decimals, Token-2022 extension list
+//   getTokenLargestAccounts(mint)         -> top 20 token accounts (raw amounts)
+//   getMultipleAccounts(accounts, base64) -> token-account owners for those 20
+// We decode the binary layouts ourselves (no @solana/* dependency) and use base64,
+// which every RPC supports, rather than jsonParsed.
+//
+// Strict backoff: no retries here. A 429, or a JSON-RPC error that says "too many
+// requests" (some RPCs send it with HTTP 200), pauses the bucket with a pause that
+// doubles per consecutive 429 (HttpClient) and counts toward health demotion.
+export const SOLANA_PUBLIC_RPC = 'https://api.mainnet-beta.solana.com';
+export const READ_METHODS = new Set(['getAccountInfo', 'getMultipleAccounts', 'getTokenLargestAccounts', 'getTokenSupply']);
+export const TOKEN_PROGRAM = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
+export const TOKEN_2022_PROGRAM = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';
+const MINT_LEN = 82;
+const ACCOUNT_LEN = 165; // Token-2022 pads mints to the account size before the extension TLVs
+const ACCOUNT_TYPE_MINT = 1;
+/** Token-2022 ExtensionType ids (spl-token-2022 `extension/mod.rs`). */
+export const TOKEN_2022_EXTENSIONS = {
+    1: 'transferFeeConfig',
+    2: 'transferFeeAmount',
+    3: 'mintCloseAuthority',
+    4: 'confidentialTransferMint',
+    5: 'confidentialTransferAccount',
+    6: 'defaultAccountState',
+    7: 'immutableOwner',
+    8: 'memoTransfer',
+    9: 'nonTransferable',
+    10: 'interestBearingConfig',
+    11: 'cpiGuard',
+    12: 'permanentDelegate',
+    13: 'nonTransferableAccount',
+    14: 'transferHook',
+    15: 'transferHookAccount',
+    16: 'confidentialTransferFeeConfig',
+    17: 'confidentialTransferFeeAmount',
+    18: 'metadataPointer',
+    19: 'tokenMetadata',
+    20: 'groupPointer',
+    21: 'tokenGroup',
+    22: 'groupMemberPointer',
+    23: 'tokenGroupMember',
+    24: 'confidentialMintBurn',
+    25: 'scaledUiAmountConfig',
+    26: 'pausableConfig',
+    27: 'pausableAccount',
+};
+/** Extensions that let an issuer take, block, tax or hook transfers: shown as risk flags. */
+export const RISKY_EXTENSIONS = new Set([
+    'permanentDelegate',
+    'transferHook',
+    'transferFeeConfig',
+    'nonTransferable',
+    'defaultAccountState',
+    'pausableConfig',
+    'mintCloseAuthority',
+]);
+/**
+ * Owners whose token accounts are pool vaults, not holders (SPEC §3.6 allow-list seed).
+ * Only program authorities that own the vaults of every pool of that program are listed;
+ * PumpSwap / CLMM / Meteora vaults are owned by per-pool PDAs and need Tier 1 labelling.
+ */
+export const KNOWN_OWNERS = {
+    '5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1': 'LP', // Raydium AMM v4 authority
+    GpMZbSM2GgvTKHJirzeGfMFoaZ8UR2X7F4v8vHTvxFbL: 'LP', // Raydium CPMM authority
+};
+// ---------------------------------------------------------------- decoding
+const B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+/** Base58 (Bitcoin alphabet) encode, used for 32-byte public keys. */
+export function base58(bytes) {
+    const digits = [];
+    for (const byte of bytes) {
+        let carry = byte;
+        for (let i = 0; i < digits.length; i++) {
+            carry += digits[i] << 8;
+            digits[i] = carry % 58;
+            carry = (carry / 58) | 0;
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = (carry / 58) | 0;
+        }
+    }
+    let out = '';
+    for (const byte of bytes) {
+        if (byte !== 0)
+            break;
+        out += '1';
+    }
+    for (let i = digits.length - 1; i >= 0; i--)
+        out += B58[digits[i]];
+    return out;
+}
+function accountBytes(acc) {
+    const [data, enc] = Array.isArray(acc.data) ? acc.data : [acc.data, 'base58'];
+    if (enc !== 'base64')
+        throw new Error(`unexpected account encoding ${enc}`);
+    return Buffer.from(data, 'base64');
+}
+function optionPubkey(buf, at) {
+    return buf.readUInt32LE(at) === 1 ? base58(buf.subarray(at + 4, at + 36)) : null;
+}
+/** Decode an SPL Token / Token-2022 mint account (82-byte base layout + Token-2022 TLV extensions). */
+export function decodeMint(mint, data, programId, fetchedAt, source = 'solana-rpc') {
+    if (data.length < MINT_LEN)
+        throw new Error(`account ${mint} is not a mint (${data.length} bytes)`);
+    const program = programId === TOKEN_PROGRAM ? 'spl-token' : programId === TOKEN_2022_PROGRAM ? 'token-2022' : 'unknown';
+    const extensions = [];
+    if (data.length > ACCOUNT_LEN && data[ACCOUNT_LEN] === ACCOUNT_TYPE_MINT) {
+        let at = ACCOUNT_LEN + 1;
+        while (at + 4 <= data.length) {
+            const type = data.readUInt16LE(at);
+            const len = data.readUInt16LE(at + 2);
+            if (type === 0)
+                break; // Uninitialized: rest is padding
+            extensions.push(TOKEN_2022_EXTENSIONS[type] ?? `unknown(${type})`);
+            at += 4 + len;
+        }
+    }
+    return {
+        mint,
+        program,
+        programId,
+        mintAuthority: optionPubkey(data, 0),
+        supply: data.readBigUInt64LE(36).toString(),
+        decimals: data[44],
+        isInitialized: data[45] === 1,
+        freezeAuthority: optionPubkey(data, 46),
+        extensions,
+        riskyExtensions: extensions.filter((e) => RISKY_EXTENSIONS.has(e)),
+        source,
+        fetchedAt,
+    };
+}
+/** Token account (SPL and Token-2022 share the first 165 bytes): mint, owner, amount. */
+export function decodeTokenAccount(data) {
+    if (data.length < 72)
+        throw new Error(`not a token account (${data.length} bytes)`);
+    return { mint: base58(data.subarray(0, 32)), owner: base58(data.subarray(32, 64)), amount: data.readBigUInt64LE(64) };
+}
+/** Percent of supply, computed in bigint so 18-digit raw amounts keep their precision. */
+export function pctOf(amount, supply) {
+    if (supply <= 0n)
+        return 0;
+    return Number((amount * 10000000n) / supply) / 100_000;
+}
+/** Mint authorities as the shared Audit flags (true = still enabled). */
+export function auditFromMint(info, top10Pct = null) {
+    return {
+        mint: info.mint,
+        mintAuthority: info.mintAuthority !== null,
+        freezeAuthority: info.freezeAuthority !== null,
+        top10Pct,
+        devPct: null,
+        devMints: null,
+        lpLockedPct: null,
+        rugRisks: info.riskyExtensions.map((e) => `token-2022:${e}`),
+        rugScore: null,
+        source: info.source,
+        fetchedAt: info.fetchedAt,
+    };
+}
+/** JSON-RPC errors are failures; rate-limit errors count as 429s (some RPCs send them with HTTP 200). */
+export const rpcBodyCheck = (data) => {
+    const err = data?.error;
+    if (!err)
+        return null;
+    const message = `rpc error ${err.code ?? '?'}: ${err.message ?? 'unknown'}`;
+    const limited = err.code === 429 || /too many requests|rate limit/i.test(err.message ?? '');
+    return limited ? { status: 429, error: message } : { error: message };
+};
+// ---------------------------------------------------------------- adapter
+export class SolanaRpc {
+    http;
+    /** May carry an api-key: never print it (see rpc-config.ts redactSecrets). */
+    url;
+    source;
+    meta;
+    constructor(http, opts = {}) {
+        this.http = http;
+        this.url = opts.url ?? SOLANA_PUBLIC_RPC;
+        this.source = opts.source ?? 'solana-rpc';
+        // Each pool endpoint gets its own bucket (task-1309) so one endpoint's 429 does not pause the others.
+        this.meta = { source: this.source, bucket: opts.bucket ?? this.source };
+    }
+    async call(method, params) {
+        if (!READ_METHODS.has(method))
+            throw new Error(`refusing non-read RPC method ${method}`);
+        // Constant id: one request per HTTP call, and recorded fixtures match on replay.
+        const body = { jsonrpc: '2.0', id: 1, method, params };
+        const r = await this.http.postJson(this.url, body, this.meta, rpcBodyCheck);
+        if (r.data.result === undefined)
+            throw new Error(`rpc ${method}: no result`);
+        return { result: r.data.result, fetchedAt: r.fetchedAt };
+    }
+    /** Mint/freeze authority, supply, decimals and Token-2022 extensions. */
+    async mintInfo(mint) {
+        const { result, fetchedAt } = await this.call('getAccountInfo', [mint, { encoding: 'base64', commitment: 'confirmed' }]);
+        if (!result.value)
+            throw new Error(`mint ${mint} not found`);
+        return decodeMint(mint, accountBytes(result.value), result.value.owner, fetchedAt, this.source);
+    }
+    /** Top 20 token accounts; `pct` uses `supply` from mintInfo(). */
+    async largestAccounts(mint) {
+        const { result, fetchedAt } = await this.call('getTokenLargestAccounts', [mint, { commitment: 'confirmed' }]);
+        return { accounts: result.value.map((a) => ({ address: a.address, amount: BigInt(a.amount) })), fetchedAt };
+    }
+    /**
+     * Raw base64 account data for arbitrary accounts (one getMultipleAccounts call, ≤ 100). Used by the
+     * fast lane to seed a first on-chain price (e.g. a pump.fun bonding curve) before the first push.
+     * A missing account maps to null; the caller decodes the bytes itself.
+     */
+    async accountsRaw(accounts, commitment = 'processed') {
+        const out = new Map();
+        if (accounts.length === 0)
+            return { data: out, fetchedAt: Date.now() };
+        const slice = accounts.slice(0, 100);
+        const { result, fetchedAt } = await this.call('getMultipleAccounts', [slice, { encoding: 'base64', commitment }]);
+        result.value.forEach((acc, i) => {
+            const bytes = acc ? (Array.isArray(acc.data) ? acc.data[0] : null) : null;
+            out.set(slice[i], bytes ?? null);
+        });
+        return { data: out, fetchedAt };
+    }
+    /**
+     * Account META for arbitrary addresses (task-1340 wallet intel): the owning program (System = a wallet,
+     * anything else = program-owned vault / PDA), whether the account exists, lamports. One getMultipleAccounts
+     * with a zero-length data slice, so a 100-address call stays a few KB.
+     */
+    async accountMeta(accounts, commitment = 'confirmed') {
+        const out = new Map();
+        if (accounts.length === 0)
+            return out;
+        const slice = accounts.slice(0, 100);
+        const { result } = await this.call('getMultipleAccounts', [slice, { encoding: 'base64', commitment, dataSlice: { offset: 0, length: 0 } }]);
+        result.value.forEach((acc, i) => {
+            out.set(slice[i], acc ? { programOwner: acc.owner, exists: true, lamports: acc.lamports ?? 0 } : { programOwner: null, exists: false, lamports: 0 });
+        });
+        return out;
+    }
+    /** Owners of token accounts (one getMultipleAccounts call, ≤ 100 accounts). */
+    async tokenAccountOwners(accounts) {
+        const out = new Map();
+        if (accounts.length === 0)
+            return out;
+        const { result } = await this.call('getMultipleAccounts', [accounts.slice(0, 100), { encoding: 'base64', commitment: 'confirmed' }]);
+        result.value.forEach((acc, i) => {
+            if (acc)
+                out.set(accounts[i], decodeTokenAccount(accountBytes(acc)).owner);
+        });
+        return out;
+    }
+    /**
+     * Top-20 holders (SPEC §3.2 keyless): 2 requests (largest accounts + owners), plus
+     * getAccountInfo when `info` is not supplied. Owner lookup failing keeps the token
+     * accounts as addresses rather than failing the whole call.
+     */
+    async topHolders(mint, opts = {}) {
+        const info = opts.info ?? (await this.mintInfo(mint));
+        const { accounts: largest, fetchedAt } = await this.largestAccounts(mint);
+        let owners = new Map();
+        if (opts.resolveOwners ?? true) {
+            try {
+                owners = await this.tokenAccountOwners(largest.map((a) => a.address));
+            }
+            catch {
+                // keep token accounts; the caller still gets amounts and shares
+            }
+        }
+        const supply = BigInt(info.supply);
+        const scale = 10 ** info.decimals;
+        const holders = largest.map((a) => {
+            const owner = owners.get(a.address) ?? null;
+            const label = owner ? KNOWN_OWNERS[owner] : undefined;
+            return {
+                address: owner ?? a.address,
+                tokenAccount: a.address,
+                owner,
+                amount: Number(a.amount) / scale,
+                pct: pctOf(a.amount, supply),
+                ...(label ? { label } : {}),
+            };
+        });
+        const excluded = new Set(['LP', 'cex', 'bridge']);
+        const top10 = holders.filter((h) => !h.label || !excluded.has(h.label)).slice(0, 10);
+        return {
+            mint,
+            holders,
+            top10Pct: supply > 0n ? Math.round(top10.reduce((s, h) => s + h.pct, 0) * 1000) / 1000 : null,
+            supply: info.supply,
+            decimals: info.decimals,
+            source: this.source,
+            fetchedAt,
+        };
+    }
+}

package/dist/packages/data/src/sources/solana-ws.js

@@ -0,0 +1,287 @@
+// Solana JSON-RPC WebSocket subscription client (SPEC §3.9 fast lane, task-1312). Read-only.
+//   accountSubscribe(pubkey, { encoding: 'base64', commitment: 'processed' })
+//   -> accountNotification { params: { subscription, result: { context:{slot}, value:{ data:[b64,'base64'] } } } }
+//
+// One connection multiplexes every watched account's subscription (SPEC §3.9.4: "multiplex all watchlist
+// subs on one connection"). The price is computed on-chain from the account bytes by the caller (the
+// fast lane decodes a pump.fun bonding curve), so this client is a pure transport: it owns the socket,
+// the desired-subscription set, reconnect with doubling backoff, and resubscribe on reopen (a reconnect
+// resets the server's subscription ids). It reports health under `helius-ws` (keyed) or `solana-ws`
+// (keyless public RPC), meters streamed bytes for the Helius credit budget, and records/replays a session
+// through the same handler (tests, --replay). The URL may carry an api-key: it is never logged — every
+// error/health string goes through redactSecrets().
+import { systemClock } from "../clock.js";
+import { redactSecrets } from "../rpc-config.js";
+export class SolanaWsClient {
+    url;
+    source;
+    make;
+    clock;
+    health;
+    opts;
+    commitment;
+    ws = null;
+    /** Accounts the caller wants (persists across reconnects). */
+    desired = new Set();
+    /** server subId -> account (active subscriptions on the current socket). */
+    bySubId = new Map();
+    /** request id -> account (subscribe acks still pending on the current socket). */
+    pending = new Map();
+    nextReqId = 1;
+    status = { state: 'idle', attempts: 0, failures: 0, desired: 0, active: 0, messages: 0, notifications: 0, bytes: 0, connectedAt: null, lastMessageAt: null, lastError: null, nextRetryMs: null };
+    stopped = false;
+    startedAt = 0;
+    /** Aborts a pending reconnect-backoff sleep so stop() never leaves a timer holding the loop (task-1311). */
+    retryAbort = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.url = opts.url;
+        this.source = opts.source ?? 'solana-ws';
+        this.clock = opts.clock ?? systemClock;
+        this.health = opts.health;
+        this.commitment = opts.commitment ?? 'processed';
+        const g = globalThis;
+        this.make = opts.ws ?? ((url) => {
+            if (!g.WebSocket)
+                throw new Error('WebSocket is not available in this runtime (Node 22+ required)');
+            return new g.WebSocket(url);
+        });
+    }
+    getStatus() {
+        return { ...this.status, desired: this.desired.size, active: this.bySubId.size };
+    }
+    /** Number of accounts with a live server subscription right now. */
+    get activeCount() {
+        return this.bySubId.size;
+    }
+    /** True when this specific account has an acked server subscription on the current socket. */
+    isActive(account) {
+        if (this.status.state !== 'open')
+            return false;
+        for (const acct of this.bySubId.values())
+            if (acct === account)
+                return true;
+        return false;
+    }
+    /** Accounts the caller wants subscribed (the cap the fast lane enforces applies to this set). */
+    get desiredCount() {
+        return this.desired.size;
+    }
+    start() {
+        if (this.status.state !== 'idle' && this.status.state !== 'stopped')
+            return;
+        this.stopped = false;
+        this.startedAt = this.clock.now();
+        if (this.opts.record)
+            this.opts.record.startedAt = new Date(this.startedAt).toISOString();
+        void this.connect();
+    }
+    stop() {
+        this.stopped = true;
+        this.retryAbort?.abort(); // cancel a pending backoff sleep so the process can exit at once (task-1311)
+        this.set({ state: 'stopped', nextRetryMs: null });
+        this.bySubId.clear();
+        this.pending.clear();
+        const ws = this.ws;
+        this.ws = null;
+        try {
+            ws?.close(1000, 'dexterm stop');
+        }
+        catch { /* already closed */ }
+    }
+    /** Add an account to the desired set and subscribe it now if the socket is open. Idempotent. */
+    subscribe(account) {
+        if (this.desired.has(account))
+            return;
+        this.desired.add(account);
+        this.set({});
+        if (this.ws && this.status.state === 'open')
+            this.sendSubscribe(this.ws, account);
+    }
+    /** Remove an account; unsubscribe it on the server if it has a live id. Idempotent. */
+    unsubscribe(account) {
+        if (!this.desired.delete(account))
+            return;
+        for (const [subId, acct] of this.bySubId) {
+            if (acct !== account)
+                continue;
+            this.bySubId.delete(subId);
+            if (this.ws && this.status.state === 'open') {
+                try {
+                    this.ws.send(JSON.stringify({ jsonrpc: '2.0', id: this.nextReqId++, method: 'accountUnsubscribe', params: [subId] }));
+                }
+                catch { /* socket will drop */ }
+            }
+        }
+        for (const [id, acct] of this.pending)
+            if (acct === account)
+                this.pending.delete(id);
+        this.set({});
+    }
+    /** Replace the desired set wholesale (add new, drop missing). */
+    setAccounts(accounts) {
+        const next = new Set(accounts);
+        for (const a of [...this.desired])
+            if (!next.has(a))
+                this.unsubscribe(a);
+        for (const a of next)
+            this.subscribe(a);
+    }
+    set(patch) {
+        this.status = { ...this.status, ...patch, desired: this.desired.size, active: this.bySubId.size };
+        this.opts.onStatus?.(this.getStatus());
+    }
+    sendSubscribe(ws, account) {
+        const id = this.nextReqId++;
+        this.pending.set(id, account);
+        const text = JSON.stringify({ jsonrpc: '2.0', id, method: 'accountSubscribe', params: [account, { encoding: 'base64', commitment: this.commitment }] });
+        try {
+            ws.send(text);
+        }
+        catch {
+            this.pending.delete(id);
+        }
+        this.opts.record?.sent.push(text);
+    }
+    async connect() {
+        if (this.stopped)
+            return;
+        this.set({ state: this.status.attempts === 0 ? 'connecting' : 'reconnecting', attempts: this.status.attempts + 1, nextRetryMs: null });
+        this.bySubId.clear();
+        this.pending.clear();
+        let ws;
+        try {
+            ws = this.make(this.url);
+        }
+        catch (err) {
+            this.fail(err instanceof Error ? err.message : String(err));
+            return this.retry();
+        }
+        this.ws = ws;
+        let opened = false;
+        ws.addEventListener('open', () => {
+            if (this.ws !== ws)
+                return;
+            opened = true;
+            this.set({ state: 'open', failures: 0, connectedAt: this.clock.now(), lastError: null });
+            // Resubscribe every desired account: a reconnect reset the server's subscription ids.
+            for (const account of this.desired)
+                this.sendSubscribe(ws, account);
+        });
+        ws.addEventListener('message', (ev) => {
+            if (this.ws !== ws)
+                return;
+            const text = typeof ev.data === 'string' ? ev.data : ev.data instanceof ArrayBuffer ? Buffer.from(ev.data).toString('utf8') : String(ev.data ?? '');
+            this.handle(text);
+        });
+        ws.addEventListener('error', (ev) => {
+            if (this.ws !== ws)
+                return;
+            this.set({ lastError: redactSecrets(ev.message ?? 'websocket error') });
+        });
+        ws.addEventListener('close', (ev) => {
+            if (this.ws !== ws)
+                return;
+            this.ws = null;
+            this.bySubId.clear();
+            this.pending.clear();
+            if (this.stopped)
+                return;
+            const reason = `closed ${ev.code ?? '?'}${ev.reason ? ` ${ev.reason}` : ''}${opened ? '' : ' before open'}`;
+            this.fail(reason);
+            void this.retry();
+        });
+    }
+    fail(message) {
+        const msg = redactSecrets(message);
+        this.health?.record(this.source, { ok: false, error: msg });
+        this.set({ failures: this.status.failures + 1, lastError: msg });
+    }
+    async retry() {
+        if (this.stopped)
+            return;
+        const base = this.opts.baseBackoffMs ?? 1_000;
+        const max = this.opts.maxBackoffMs ?? 30_000;
+        const wait = Math.min(max, base * 2 ** Math.max(0, this.status.failures - 1));
+        this.set({ state: 'reconnecting', nextRetryMs: wait });
+        this.retryAbort = new AbortController();
+        await this.clock.sleep(wait, this.retryAbort.signal);
+        if (this.stopped)
+            return; // stop() fired during the backoff: do not reconnect
+        await this.connect();
+    }
+    /** Parse one frame: subscribe ack, account notification, or ignorable. Shared by live and replay. */
+    handle(text, receivedAt = this.clock.now()) {
+        const bytes = Buffer.byteLength(text, 'utf8');
+        this.opts.record?.messages.push({ tMs: Math.max(0, receivedAt - this.startedAt), text });
+        this.status.messages += 1;
+        this.status.bytes += bytes;
+        this.status.lastMessageAt = receivedAt;
+        if (bytes > 0)
+            this.opts.onBytes?.(bytes);
+        let j;
+        try {
+            j = JSON.parse(text);
+        }
+        catch {
+            this.set({});
+            return null;
+        }
+        if (!j || typeof j !== 'object') {
+            this.set({});
+            return null;
+        }
+        const o = j;
+        // subscribe ack: { id, result: <subId number> }
+        if (typeof o.id === 'number' && typeof o.result === 'number' && this.pending.has(o.id)) {
+            const account = this.pending.get(o.id);
+            this.pending.delete(o.id);
+            if (this.desired.has(account))
+                this.bySubId.set(o.result, account);
+            this.set({});
+            return null;
+        }
+        if (o.method === 'accountNotification' && o.params) {
+            const account = typeof o.params.subscription === 'number' ? this.bySubId.get(o.params.subscription) : undefined;
+            const data = o.params.result?.value?.data;
+            const base64 = Array.isArray(data) ? data[0] : typeof data === 'string' ? data : null;
+            if (account && base64) {
+                const slot = typeof o.params.result?.context?.slot === 'number' ? o.params.result.context.slot : null;
+                const update = { account, slot, base64, receivedAt, bytes };
+                this.status.notifications += 1;
+                this.health?.record(this.source, { ok: true, latencyMs: 0 });
+                this.set({});
+                this.opts.onAccount?.(update);
+                return update;
+            }
+        }
+        this.set({});
+        return null;
+    }
+    /** Replay a recorded session through the same handler. `speed` 0 = instant, 1 = recorded gaps. */
+    async replay(rec, speed = 0) {
+        this.startedAt = this.clock.now();
+        // Seed the subscription map from the recorded subscribe frames so notifications resolve.
+        for (const sent of rec.sent) {
+            try {
+                const m = JSON.parse(sent);
+                if (typeof m.id === 'number' && Array.isArray(m.params) && typeof m.params[0] === 'string') {
+                    this.desired.add(m.params[0]);
+                    this.pending.set(m.id, m.params[0]);
+                }
+            }
+            catch { /* ignore */ }
+        }
+        this.set({ state: 'open', connectedAt: this.startedAt, attempts: 1 });
+        let last = 0;
+        for (const m of rec.messages) {
+            if (this.stopped)
+                break;
+            if (speed > 0 && m.tMs > last)
+                await this.clock.sleep((m.tMs - last) / speed);
+            last = m.tMs;
+            this.handle(m.text, this.clock.now());
+        }
+        return rec.messages.length;
+    }
+}